Jump to content

Manual:Desarrollo de extensiones

From mediawiki.org
This page is a translated version of the page Manual:Developing extensions and the translation is 99% complete.
Outdated translations are marked like this.
Languages:
Extensiones:
Extensiones de MediaWiki

Esta página es una guía para desarrollar extensiones para MediaWiki. Antes de comenzar, navegue por los complete list in: Category:Extensions by category es para ver si ya existe una extensión para su caso de uso.

El desarrollo de la extensión consta de estas partes:

  1. Configuración
  2. Implementación
  3. Localización
  4. Publicación

Configuración

Para configurar una nueva extensión, comience configurando un entorno de desarrollo local para MediaWiki y siga las instrucciones para instalar y copiar la extensión BoilerPlate .

Durante el desarrollo, es posible que deshabilite la caché estableciendo $wgMainCacheType = CACHE_NONE y $wgCacheDirectory = false, de lo contrario los mensajes del sistema y otros cambios pueden no aparecer.

Estructura

Una extensión mínima tiene la siguiente estructura:

MyExtension/extension.json
Almacena las instrucciones de configuración. El nombre del archivo debe ser extension.json. (En versiones anteriores a MediaWiki 1.25, las instrucciones de instalación estaban en un archivo MyExtension/MyExtension.php con el nombre de la extensión. Muchas extensiones tienen funcionalidades retrocompatibles en este archivo PHP.)
MyExtension/includes/ (or MyExtension/src/)
Almacena el código de ejecución PHP para la extensión.
MyExtension/resources/ (or MyExtension/modules/)
Almacena los recursos del lado del cliente, como JavaScript, CSS y LESS para la extensión.
MyExtension/i18n/*.json
Almacena información de localización de la extensión.
MyExtension/README.md
Una buena práctica es añadir un archivo README con información básica sobre cómo instalar y configurar la extensión. Utilice texto simple o Markdown. Para ver un ejemplo de texto simple, consulte la página de Phabricator Diffusion para el Extensión:Formas de página . Si se utiliza el marcado abajo, añadir la extensión de archivo .md. Por ejemplo, consulte el archivo README.md para Parsoid en Phabricator Diffusion.

Cuando desarrolles una extensión, reemplaza MyExtension en los nombres anteriores con el nombre de tu extensión. Usa nombres en UpperCamelCase para el directorio y el o los archivos PHP. Esta es la convención general de nombres de archivo.[1]

Registro

Versión de MediaWiki:
≥ 1.25

El archivo extension.json contiene los datos de configuración de la extensión. Aquí hay un ejemplo de un mínimo de extension.json: 

{
	"name": "MyExtension",
	"author": "John Doe",
	"url": "https://www.mediawiki.org/wiki/Extension:MyExtension",
	"description": "This extension is an example.",
	"version": "1.5",
	"license-name": "GPL-2.0-or-later",
	"type": "validextensiontype",
	"manifest_version": 2
}

Muchos de los campos son opcionales, pero aun así es una buena práctica completarlos. Para un ejemplo más completo de extension.json, vea la extensión de BoilerPlate.

manifest_version se refiere a la versión del esquema usado por el archivo extension.json . Consulte la documentación sobre esta función. A menos que necesite soportar una versión anterior de MediaWiki, elija la última versión.

Una vez que tenga un archivo extension.json configurado para su extensión, la extensión aparecerá en su página local Special:Version.

Licencia

MediaWiki is an open-source project and users are encouraged to make any MediaWiki extensions under an Open Source Initiative (OSI) approved license compatible with GPL-2.0-or-later (Wikimedia's standard software license).

We recommend adopting one of the following compatible licenses for your projects in Gerrit:

For extensions that have a compatible license, you can request developer access to the MediaWiki source repositories for extensions. To specify the licence in code and with "license-name" a key should be used to provide its short name, e.g. "GPL-2.0-or-later" or "MIT" adhering to the list of identifiers at spdx.org.

Hacer que su extensión sea configurable por el usuario

Lo ideal es que los usuarios puedan instalar su extensión añadiendo una sola línea a LocalSettings.php: 

wfLoadExtension( 'MyExtension' );

Si quieres hacer que tu extensión sea configurable, debes definir y documentar algunos parámetros de configuración. El código que los usuarios tendrán que introducir para instalar la extensión será algo así: 

wfLoadExtension( 'MyExtension' );
$wgMyExtensionConfigThis = 1;
$wgMyExtensionConfigThat = false;

Si desea que su usuario pueda configurar su extensión, tendrá que proporcionar una o más variables de configuración. Es una buena idea dar a esas variables un nombre único. También deben seguir las convenciones de nombres de MediaWiki (por ejemplo, las variables globales deben comenzar con $wg).

Por ejemplo, si su extensión se llama MyExtension, es posible que desee nombrar todas sus variables de configuración para comenzar con $wgMyExtension. Es importante que ninguno del núcleo de MediaWiki comience sus variables de esta manera y usted ha realizado un trabajo razonable de verificación para ver que ninguna de las extensiones publicadas comience sus variables de esta manera. Los usuarios no se sentirán amables al tener que elegir entre su extensión y algunas otras extensiones porque eligió nombres de variables superpuestas.

También es una buena idea incluir documentación extensa de cualquier variable de configuración en las notas de instalación.

A continuación se muestra un ejemplo de cómo configurar una variable de configuración en extension.json: 

{
	"config": {
		"BoilerPlateEnableFoo": {
			"value": true,
			"description": "Enables the foo functionality"
		}
	}
}

Tenga en cuenta que después de llamar a wfLoadExtension( 'BoilerPlate' );, la variable global $wgBoilerPlateEnableFoo no existe. Si establece la variable, por ejemplo en LocalSettings.php, no se utilizará el valor predeterminado dado en extension.json.

Para obtener más detalles sobre cómo utilizar variables globales dentro de extensiones personalizadas, consulte Configuration for developers .

Preparando clases para la carga automática

Si eliges usar clases para implementar tu extensión, MediaWiki proporciona un mecanismo simplificado para ayudar a PHP a encontrar el archivo fuente donde se encuentra tu clase. En la mayoría de los casos, esto debería eliminar la necesidad de escribir su propio método de carga automática.

Para utilizar el mecanismo de carga automática de MediaWiki, agregue entradas al campo AutoloadClasses . La clave de cada entrada es el nombre de la clase; el valor es el archivo que almacena la definición de la clase. Para una extensión de una clase simple, la clase suele tener el mismo nombre que la extensión, por lo que su sección de cargamento automático podría verse así (la extensión se llama MyExtension): 

{
	"AutoloadClasses": {
		"MyExtension": "includes/MyExtension.php"
	}
}

El nombre del archivo es relativo al directorio en donde se encuentra extension.json.

Para extensiones más complejas, se debe considerar namespaces. Véase Manual:Extension.json/Schema#AutoloadNamespaces para más detalles.

Manejo de dependencias

Supongamos que una extensión requiere la presencia de otra extensión, por ejemplo, porque se van a utilizar funcionalidades o tablas de base de datos y se quieren evitar mensajes de error en caso de no existencia.

Por ejemplo, la extensión CountingMarker requiere la presencia de la extensión HitCounters para ciertas funciones.

Una forma de especificar esto sería utilizando la clave requires en extension.json .

Otra opción es usar ExtensionRegistry (disponible desde MediaWiki 1.25): 

	if ( ExtensionRegistry::getInstance()->isLoaded( 'HitCounters', '>=1.1' ) ) {
		/* hacer algunas cosas adicionales, si la extensión HitCounters está presente en la versión 1.1 y superior */
	}

Actualmente (a partir de febrero de 2024, MediaWiki 1.41.0) el nombre de la extensión que se va a verificar debe coincidir exactamente con el nombre en su extension.json.[2][3]

Ejemplo: Si desea verificar el estado de carga de la extensión OpenIDConnect, debe usarla con un "espacio" (space). 

	if ( ExtensionRegistry::getInstance()->isLoaded( 'OpenID Connect' ) ) {
    ...
	}

Implementación

Para obtener una descripción general de la arquitectura, la estructura y las convenciones del código para las extensiones, consulte Buenas prácticas para las extensiones .

Puntos de extensión

El núcleo de MediaWiki proporciona varias formas para las extensiones para cambiar el comportamiento, la funcionalidad y la apariencia de una wiki. La mayoría de las extensiones utilizan más de uno de estos puntos de extensión. Para obtener una lista completa de los puntos de extensión admitidos en extension.json, consulte la referencia de esquema .

General

  • Enganches : Inyectar código personalizado en puntos clave del código central de MediaWiki, como cuando un usuario se inicia sesión o guarda una página. Las extensiones también pueden definir nuevos ganchos.
  • Domain events : Reaccionar a los cambios en el estado de la wiki, como cuando se edita una página. Las extensiones también pueden definir sus propios eventos. 1.44
  • Módulos de la API : Defina módulos API basados ​​en la API de acción o la API REST . Estos módulos pueden ser llamados por bots o clientes.
  • Trabajos : Añadir trabajos a la Cuenta de trabajos de MediaWiki para realizar tareas de proceso intensivo de manera sincrónica, como el envío de correos electrónicos de notificación.

Páginas 

  • Mostrar una página especial : Las páginas especiales proporcionan contenido generado dinámicamente, a menudo basado en el estado del sistema, consultas de base de datos y entradas de usuarios.
  • Ejecutar una acción de página : El parámetro URL action genera una página personalizada basada en la página actual, generalmente para proporcionar información (como el historial de la página) o para realizar una acción (como editar la página). Además de las acciones predeterminadas proporcionadas por el núcleo de MediaWiki, las extensiones pueden definir una nueva acción de página.
  • Agregar una categoría de seguimiento : Ayude a los usuarios a encontrar páginas con características similares agregando automáticamente páginas a categorías personalizadas.

Contenido

  • Extensión de marcado wiki : Las extensiones pueden agregar funcionalidad personalizada a la marcación de wikitext de MediaWiki utilizando la sintaxis de plantilla ({{...}}) o las etiquetas (‎<example />). Estas personalizaciones se utilizan para generar contenido e interactuar con MediaWiki durante la representación de la página.
  • Apoyo a un modelo de contenido : De forma predeterminada, las páginas wiki se pueden almacenar utilizando algunos modelos de contenido estándar, como wikitexto y JSON. Las extensiones pueden proporcionar soporte para nuevos modelos de contenido mediante la adición de un manipulador de contenido.
  • Apoyar un tipo de media : Las extensiones pueden agregar al conjunto predeterminado de tipos de archivos de medios soportados añadiendo un manipulador de medios.

Herramientas de moderación

  • Registrar una acción del usuario o del sistema : En wiki, se rastrean las acciones para la transparencia y la colaboración. Para respaldar esta función, las extensiones pueden agregar entradas y funcionalidades personalizadas a Special:Log.
  • Añadir una bandera de cambios recientes : Las extensiones pueden agregar banderas personalizadas a las siguientes páginas especiales para ayudar a los moderadores a rastrear los cambios de página: Special:RecentChanges, Special:Watchlist, Special:RecentChangesLinked
  • Agregar una etiqueta de revisión : Las extensiones pueden agregar anotaciones asociadas con una revisión o entrada de registro, como para las modificaciones realizadas utilizando la extensión VisualEditor.

Autenticación

  • Añadir un proveedor : Las extensiones pueden agregar soporte para nuevos mecanismos de inicio de sesión y métodos de gestión de sesión.

Agregando tablas de la base de datos

Asegúrese de que la extensión no modifique las tablas de la base de datos principal. En cambio, la extensión debería crear nuevas tablas con llaves extranjeras de las tablas pertinentes de MW.

Advertencia Advertencia: Si su extensión se utiliza en cualquier wiki de producción alojado en FWM, siga las guías para crear nuevas tablas y cambios de esquema.

Si su extensión necesita agregar sus propias tablas de base de datos, utilice el gancho LoadExtensionSchemaUpdates . Véase la página del manual para más información en uso.


Registro de atributos para otras extensiones

Los atributos permiten que las extensiones registren algo, como un módulo, con otra extensión. Por ejemplo, las extensiones pueden usar atributos para registrar un módulo de plugin con la extensión VisualEditor. Para más información, véase Registro de extensiones .

Localización

Durante el desarrollo, es posible que deshabilite ambos caches estableciendo $wgMainCacheType = CACHE_NONE y $wgCacheDirectory = false, de lo contrario los cambios en el mensaje del sistema pueden no aparecer.

Si desea que su extensión se utilice en wikis que tengan un público de lectores multilingües, deberá agregar soporte de localización a su extensión.

Almacenar mensajes en <language-key>.json

Almacenar las definiciones de mensaje en un archivo JSON de localización, una para cada clave de idioma en la que se traduce la extensión. Los mensajes son guardados con una clave y el mensaje mismo usando el formato JSON estándar. Cada ID de mensaje debe estar en minúsculas y no puede contener espacios. Cada clave debe comenzar con el nombre de extensión de menor calificación. Un ejemplo se puede encontrar en la extensión de MobileFrontend. Aquí hay un ejemplo de un archivo JSON mínimo (en este caso, en.json):

en.json 

{
	"myextension-desc": "Adds the MyExtension great functionality.",
	"myextension-action-message": "This is a test message"
}

Almacenar la documentación del mensaje en qqq.json

La documentación de las claves de mensajes se puede almacenar en el archivo JSON para el pseudolenguaje con el código qqq. Una documentación del ejemplo puede ser:

qqq.json: 

{
	"myextension-desc": "The description of MyExtension used in Extension credits.",
	"myextension-action-message": "Adds 'message' after 'action' triggered by user."
}

Cargar el archivo de localización

En su extension.json, defina la ubicación de sus archivos de mensajes (por ejemplo, en el directorio i18n/): 

{
	"MessagesDirs": {
		"MyExtension": [
			"i18n"
		]
	}
}

Uso wfMessage en PHP

En su código de configuración e implementación, reemplace cada uso literal del mensaje con una llamada a wfMessage( $msgID, $param1, $param2, ... ). En las clases que implementan IContextSource (así como algunas otras como las subclases de SpecialPage), puede usar $this->msg( $msgID, $param1, $param2, ... ) en su lugar. Ejemplo: 

wfMessage( 'myextension-addition', '1', '2', '3' )->parse()

Uso de mw.message en JavaScript

También se pueden usar funciones de internacionalización en JavaScript. Véase Manual:API de mensajes para más información.


Publicación

Para autocategorizar y estandarizar la documentación de tu extensión existente, véase Plantilla:Extensión . Para añadir tu nueva extensión a esta Wiki:


A developer sharing their code in the MediaWiki code repository should expect:

Feedback / Criticism / Code reviews
Review and comments by other developers on things like framework use, security, efficiency and usability.
Developer tweaking
Other developers modifying your submission to improve or clean-up your code to meet new framework classes and methods, coding conventions and translations.
Improved access for wiki sysadmins
If you do decide to put your code on the wiki, another developer may decide to move it to the MediaWiki code repository for easier maintenance. You may then create a Cuenta de desarrollador to continue maintaining it.
Future versions by other developers
New branches of your code being created automatically as new versions of MediaWiki are released. You should backport to these branches if you want to support older versions.
Incorporation of your code into other extensions with duplicate or similar purposes — incorporating the best features from each extension.
Credit
Credit for your work being preserved in future versions — including any merged extensions.
Similarly, you should credit the developers of any extensions whose code you borrow from — especially when performing a merger.

Any developer who is uncomfortable with any of these actions occurring should not host in the code repository. You are still encouraged to create a summary page for your extension on the wiki to let people know about the extension, and where to download it.

Desplegando y registrando

Si tiene la intención de que su extensión se despliegue en los sitios de Wikimedia (incluyendo posiblemente Wikipedia), se justifica un escrutinio adicional en términos de rendimiento y seguridad. Consultar Writing an extension for deployment .

Si su extensión agrega espacios de nombres, es posible que desee registrar sus espacios de nombres predeterminados; asimismo, si agrega tablas o campos a la base de datos, es posible que desee registrarlos en database field prefixes .

Tenga en cuenta que la revisión y implementación de nuevas extensiones en los sitios de Wikimedia puede ser extremadamente lenta, y en algunos casos ha tomado más de dos años.[4]

Documentación de ayuda

Debe proporcionar documentación de ayuda de dominio público para las funciones proporcionadas por su extensión. La convención es que las extensiones tengan sus páginas de ayuda enfocadas en el usuario bajo un pseudo-espacio de nombres de Help:Extension:<ExtensionName>, con cualquier subpágina requerida (la página de nivel superior se vinculará automáticamente desde el cuadro de información de la extensión si existe). Help:CirrusSearch es un ejemplo de buena documentación. Tendrías que darles a los usuarios un enlace a la documentación mediante la función addHelpLink() .

Lanzamiento de actualizaciones

Hay una serie de enfoques comunes para liberar actualizaciones a las extensiones. Estos generalmente se definen de acuerdo con la política de compatibilidad de la extensión (master, rel o ltsrel):

  • master – Las versiones se pueden etiquetar con números de versión en la rama maestra y se puede proporcionar documentación en la página de inicio de la extensión que describe qué versiones de la extensión son compatibles con qué versiones principales. Las ramas de liberación se crearán automáticamente y es posible que desee eliminarlas si no están destinadas a ser utilizadas.
  • rel y ltsrel – Liberar mediante la incorporación de cambios a las ramas REL1_* (ya sea todos los cambios o solo los críticos). Los números de versión generalmente no son necesarios a menos que la extensión sea una dependencia de otra (el número de versión puede entonces proporcionarse en la configuración de la otra extensión para garantizar que no se instalen combinaciones incompatibles). Muchas extensiones permanecerán con el mismo número de versión durante años.

Apoyar otras versiones de núcleo

Hay dos convenciones generalizadas para apoyar versiones más antiguas del núcleo MediaWiki:

  • El eje principal de la extensión es compatible con la mayor cantidad de versiones antiguas del núcleo posible. Esto resulta en una carga de mantenimiento (los hacks de compatibilidad retroactiva deben mantenerse durante mucho tiempo, y los cambios en la extensión deben ser probados con varias versiones de MediaWiki), pero los sitios que ejecutan versiones antiguas de MediaWiki se benefician de la funcionalidad recientemente añadida a la extensión.
  • Ramos de liberación: las ramas de liberación de la extensión son compatibles con ramas de core correspondientes, por ejemplo, los sitios que usan MediaWiki 1.45 necesitan usar la rama de REL1_45 de la extención. (Para las extensiones alojadas en Gerrit, estas ramas se crean automáticamente cuando se lanzan nuevas versiones de MediaWiki). Esto da como resultado un código más limpio y un desarrollo más rápido, pero los usuarios que usan versiones antiguas del núcleo no se benefician de las correcciones de errores y las nuevas características a menos que las incorporen de nuevo manualmente.

Los mantenedores de extensiones deben declarar con el parámetro compatibility policy de la plantilla {{Extensión }} qué convención siguen.

Proporcionando soporte / colaboración

Los desarrolladores de extensiones deben abrir una cuenta en Phabricator de Wikimedia y solicitar un nuevo proyecto para la extensión. Esto proporciona un lugar público donde los usuarios pueden enviar problemas y sugerencias, y puede colaborar con los usuarios y otros desarrolladores para triaje de errores y planificar características de su extensión.


Véase también

Aprenda con el ejemplo

Referencias

  1. ↑ mailarchive:wikitech-l/2011-August/054839.html
  2. ↑ https://www.mediawiki.org/wiki/Project%3ASupport%20desk/Flow/2024/02#h-%5BDeveloper_question%5D_ExtensionRegistry%3A%3AgetInstance%28%29-%3EisLoaded%28_%27OpenIDConnect%27-20240204084500
  3. ↑ https://phabricator.wikimedia.org/T356596
  4. ↑ phabricator:T148848
Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:Developing_extensions/es&oldid=8195965"