Manual:Desarrollo de extensiones

From MediaWiki.org
Jump to: navigation, search
This page is a translated version of the page Manual:Developing extensions and the translation is 50% complete.

Other languages:
العربية • ‎български • ‎Deutsch • ‎English • ‎español • ‎français • ‎Bahasa Indonesia • ‎italiano • ‎日本語 • ‎한국어 • ‎Nederlands • ‎polski • ‎português • ‎português do Brasil • ‎русский • ‎سنڌي • ‎中文
Gnome-preferences-other.svg Extensiones:Manual:Extensions DesarrolloManual:Developing extensions Tag extensionsManual:Tag extensions Parser functionsManual:Parser functions HooksManual:Hooks Páginas especialesManual:Special pages AparienciasManual:Skins Palabras mágicasManual:Magic words APIAPI:Extensions
Extensiones de MediaWiki

Cada extensión consta de tres partes:

  1. Configuración
  2. Ejecución
  3. Localización

Una extensión mínima constará de tres archivos, uno por cada parte:

MyExtension/extension.json
Almacena las instrucciones de instalació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/MyExtension_body.php
Almacena el código de ejecución de la extensión. Existe la convención de llamar a este archivo «MyExtension_body.php», pero no es obligatorio. If your extension is complex and involves multiple PHP files, you should follow the convention to put its implementation code in a subdirectory named MyExtension/includes (although the Example and BoilerPlate extensions do not follow this convention). For example, see the Semantic MediaWiki extension.
MyExtension/i18n/*.json
Almacena información de localización de la extensión.
En un principio, las extensiones eran archivos únicos. Es posible que aún encuentres algunos ejemplos de este estilo obsoleto.

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] (The BoilerPlate extension is a good starting point for your extension. Also check out the cookiecutter template for MediaWiki extensions on GitHub.)

The three parts of an extension, setup, execution, and, localisation as well as extension types and licensing and publishing your extension are described in the following sections of this page.

While developing, you may want to disable caching by setting $wgMainCacheTypeManual:$wgMainCacheType = CACHE_NONE and $wgCacheDirectoryManual:$wgCacheDirectory = false, otherwise system messages and other changes may not show up.

Configuración[edit]

Cuando programes la parte de la instación, tu objetivo es consolidar la instalación de modo que los usuarios que instalen la extensión solo tengan que incluir el archivo de instalación en su archivo LocalSettings.phpManual:LocalSettings.php, así:

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;

Para llegar a esta simplicidad, tu archivo de instalación debe cumplir una serie de tareas (que se describirán en detalle en las secciones siguientes):

  • register any media handler, parser function, special page, custom XML tag, and variable used by your extension.
  • define and/or validate any configuration variables you have defined for your extension.
  • prepare the classes used by your extension for autoloading
  • determine what parts of your setup should be done immediately and what needs to be deferred until the MediaWiki core has been initialized and configured
  • define any additional hooks needed by your extension
  • create or check any new database tables required by your extension.
  • set up localisation for your extension

Registrar funcionalidades con MediaWiki[edit]

MediaWiki enumera todas las extensiones que se han instalado en su página Special:Version. Por ejemplo, puedes ver todas las extensiones instaladas en este wiki en Special:Version. Es buena práctica asegurarse de que tu extensión también está presente en esta página. To do this, you will need to add an entry to $wgExtensionCreditsManual:$wgExtensionCredits for each media handler, parser function, special page, custom XML tag, and variable used by your extension. The entry will look something like this:

{
	"name": "Example",
	"author": "John Doe",
	"url": "https://www.mediawiki.org/wiki/Extension:Example",
	"description": "This extension is an example and performs no discernible function",
	"version": "1.5",
	"license-name": "GPL-2.0+",
	"type": "validextensionclass",
	"manifest_version": 1
}

See Manual:$wgExtensionCreditsManual:$wgExtensionCredits for full details on what these fields do. Many of the fields are optional, but it's still good practice to fill them out. manifest_version se refiere a la versión del esquema usado por el archivo extension.jsonextension.json. As of now the only supported version is 1 (MediaWiki 1.26.x and 1.27.x).

In addition to the above registration, you must also "hook" your feature into MediaWiki. The above only sets up the Special:Version page. The way you do this depends on the type of your extension. For details, please see the documentation for each type of extension:

Gnome-preferences-other.svg Extensiones:Manual:Extensions DesarrolloManual:Developing extensions Tag extensionsManual:Tag extensions Parser functionsManual:Parser functions HooksManual:Hooks Páginas especialesManual:Special pages AparienciasManual:Skins Palabras mágicasManual:Magic words APIAPI:Extensions

Making your extension user configurable[edit]

If you want your user to be able to configure your extension, you'll need to provide one or more configuration variables. It is a good idea to give those variables a unique name. They should also follow MediaWiki naming conventions (e.g. global variables should begin with $wg).

For example, if your extension is named "Very silly extension that does nothing", you might want to name all your configuration variables to begin $wgVsetdn or $wgVSETDN. It doesn't really matter what you choose so long as none of the MediaWiki core begins its variables this way and you have done a reasonable job of checking to see that none of the published extensions begin their variables this way. Users won't take kindly to having to choose between your extension and some other extensions because you chose overlapping variable names.

It is also a good idea to include extensive documentation of any configuration variables in your installation notes.

Advertencia Advertencia: To avoid register_globalsRegister globals vulnerabilities, ALWAYS explicitly set all your extension's configuration variables in extension setup file. Constructs like if ( !isset( $wgMyLeetOption ) ) $wgMyLeetOption = somevalue; do not safeguard against register_globals!

Here is an example boiler plate that can be used to get started:

{
	"name": "BoilerPlate",
	"version": "0.0.0",
	"author": [
		"Your Name"
	],
	"url": "https://www.mediawiki.org/wiki/Extension:BoilerPlate",
	"descriptionmsg": "boilerplate-desc",
	"license-name": "MIT",
	"type": "other",
	"AutoloadClasses": {
		"BoilerPlateHooks": "BoilerPlate.hooks.php",
		"SpecialHelloWorld": "specials/SpecialHelloWorld.php"
	},
	"config": {
		"BoilerPlateEnableFoo": true
	},
	"callback": "BoilerPlateHooks::onExtensionLoad",
	"ExtensionMessagesFiles": {
		"BoilerPlateAlias": "BoilerPlate.i18n.alias.php"
	},
	"Hooks": {
		"NameOfHook": [
			"BoilerPlateHooks::onNameOfHook"
		]
	},
	"MessagesDirs": {
		"BoilerPlate": [
			"i18n"
		]
	},
	"ResourceModules": {
		"ext.boilerPlate.foo": {
			"scripts": [
				"modules/ext.boilerPlate.js",
				"modules/ext.boilerPlate.foo.js"
			],
			"styles": [
				"modules/ext.boilerPlate.foo.css"
			]
		}
	},
	"ResourceFileModulePaths": {
		"localBasePath": "",
		"remoteExtPath": "BoilerPlate"
	},
	"SpecialPages": {
		"HelloWorld": "SpecialHelloWorld"
	},
	"manifest_version": 1
}

Preparing classes for autoloading[edit]

If you choose to use classes to implement your extension, MediaWiki provides a simplified mechanism for helping PHP find the source file where your class is located. In most cases this should eliminate the need to write your own __autoload($classname) method.

To use MediaWiki's autoloading mechanism, you add entries to the AutoloadClassesManual:$wgAutoloadClasses field. The key of each entry is the class name; the value is the file that stores the definition of the class. For a simple one class extension, the class is usually given the same name as the extension, so your autoloading section might look like this (extension is named MyExtension):

{
	"AutoloadClasses": {
		"MyExtension": "MyExtension_body.php"
	}
}

The filename is relative to the directory the extension.json file is in.

Defining additional hooks[edit]

Véase Manual:HooksManual:Hooks.

Adding database tables[edit]

Advertencia Advertencia: If your extension is used on any production WMF-hosted wiki please follow the Schema change guide.

If your extension needs to add its own database tables, use the LoadExtensionSchemaUpdatesManual:Hooks/LoadExtensionSchemaUpdates hook. Véase la página del manual para más información en uso.

Instalar localización[edit]

Véase:


Añadir registros[edit]

En MediaWiki, todas las acciones por los usuarios en wiki está seguido para transparencia y colaboración. Ver Manual:Logging to Special:LogManual:Logging to Special:Log para cómo hacerlo.

Ejecución[edit]

La técnica para escribir la porción de implementación depende de la parte del sistema de MediaWiki que desees extender:

Véase también Extensions FAQExtensions FAQ, Centro del desarrolladorDeveloper hub

Localización[edit]

While developing, you may want to disable both cache by setting $wgMainCacheType = CACHE_NONE and $wgCacheDirectory = false, otherwise your system message changes may not show up.

If you want your extension to be used on wikis that have a multi-lingual readership, you will need to add localisation support to your extension.

Store messages in <language-key>.json[edit]

Store message definitions in a localisation JSON-file, one for each language key your extension is translated in. The messages are saved with a message key and the message itself using standard JSON format. Each message id should be lowercase and may not contain spaces. An example you can find e.g. in extension MobileFrontend. Here is an example of a minimal JSON file (in this case en.json:

en.json

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

Store message documentation in qqq.json[edit]

The documentation for message keys can be stored in the JSON file for the pseudo language with code 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."
}

Definir mensajes[edit]

  • Asigna a cada mensaje un identificador de mensaje único, en minúsculas y sin espacios; p. ej.uploadwizard-desc
  • Para cada cadena de texto que se muestre al usuario, define un mensaje.
  • MediaWiki permite usar mensajes parametrizados. Esta característica debería utilizarse cuando un mensaje dependa de cierta información generada en tiempo de ejecución. Los marcadores de posición (placeholders) de los parámetros se indican con $n, donde n representa el índice del marcador; p. ej.
"mwe-upwiz-api-warning-was-deleted": "There was a file by this name, '$1', but it was deleted and you can not reupload the file. If your file is different, try renaming it."

Definir la documentación de los mensajes[edit]

Each message you define needs to have an associated message documentation entry Message documentation; in qqq.json e.g.

"uploadwizard-desc": "Description of extension. It refers to [//blog.wikimedia.org/blog/2009/07/02/ford-foundation-awards-300k-grant-for-wikimedia-commons/ this event], i.e. the development was paid with this $300,000 grant."

Cargar el archivo de localización[edit]

In your setup routine, define the location of your messages files (e.g. in directory i18n/):

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

Uso wfMessage en PHP[edit]

In your setup and implementation code, replace each literal use of the message with a call to wfMessage( $msgID, $param1, $param2, ... ). In classes that implement IContextSourceManual:RequestContext (as well as some others such as subclasses of SpecialPage), you can use $this->msg( $msgID, $param1, $param2, ... ) instead. Ejemplo:

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

Uso de mw.message en Javascript[edit]

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

Tipos de extensión[edit]

Gnome-preferences-other.svg Extensiones:Manual:Extensions DesarrolloManual:Developing extensions Tag extensionsManual:Tag extensions Parser functionsManual:Parser functions HooksManual:Hooks Páginas especialesManual:Special pages AparienciasManual:Skins Palabras mágicasManual:Magic words APIAPI:Extensions

Las extensiones pueden ser categorizadas en base de las técnicas de programación para conseguir su efecto. Extensiones más complejas que utilizan más de una de estas técnicas:

  • Subclasificar: MediaWiki expects certain kinds of extensions to be implemented as subclasses of a MediaWiki-provided base class:
    • Special pagesManual:Special pages – Subclases del SpecialPageManual:SpecialPage.php la clase suele páginas de complexión cuyo contenido es dinámicamente generado en una combinación del estado de sistema actual, parámetros de entrada del usuario, y consultas de base de datos. Ambos informes y formas de entrada del dato pueden ser generados. They are used for both reporting and administration purposes.
    • AparienciasManual:Skins – Skins change the look and feel of MediaWiki by altering the code that outputs pages by subclassing the MediaWiki class SkinTemplate.
  • HooksManual:Hooks – A technique for injecting custom php code at key points within MediaWiki processing. They are widely used by MediaWiki's parser, its localization engine, its extension management system, and its page maintenance system.
  • Tag-function associationsManual:Tag extensionsXML style tags that are associated with a php function that outputs HTML code. You do not need to limit yourself to formatting the text inside the tags. Ni siquiera necesitas mostrarlo. Many tag extensions use the text as parameters that guide the generation of HTML that embeds google objects, data entry forms, RSS feeds, excerpts from selected wiki articles.
  • Palabras mágicasManual:Magic words – A technique for mapping a variety of wiki text string to a single id that is associated with a function. Both variables and parser functions use this technique. All text mapped to that id will be replaced with the return value of the function. The mapping between the text strings and the id is stored in the array $magicWords. The interpretation of the id is a somewhat complex process – see Manual:Palabras mágicasManual:Magic words for more information.
    • VariableManual:Variable – Variables are something of a misnomer. They are bits of wikitext that look like templates but have no parameters and have been assigned hard-coded values. Standard wiki markup such as {{PAGENAME}}Help:Variables or {{SITENAME}}Help:Variables are examples of variables. They get their name from the source of their value: a php variable or something that could be assigned to a variable, e.g. a string, a number, an expression, or a function return value.
    • Parser functionsManual:Parser functions{{functionname: argument 1 | argument 2 | argument 3...}}. Similar to tag extensions, parser functions process arguments and returns a value. Las extensiones de las etiquetas son diferentes, el resultado de las funciones es el wikitexto.
  • Módulos de la APIAPI:Extensions – you can add custom modules to MediaWiki's "action" web API, that can be invoked by JavaScript, bots or third-party clients.

Apoyar otras versiones de núcleo[edit]

You can visit the extension support portal to keep on top of changes in future versions of MediaWiki and also add support for older versions that are still popular.

Licencia[edit]

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+ (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 it's short name, e.g. "GPL-2.0+" or "MIT" adhering to the list of identifiers at spdx.org.

Publicación[edit]

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


A developer sharing their code on the MediaWiki wiki or 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 request commit access to continue maintaining it.
Future versions by other developers
New branches of your code being created by other developers as new versions of MediaWiki are released.
Merger 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 their code directly on the MediaWiki wiki or 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. You may also add the {{Extension exception}} template to your extension requesting other developers refrain from modifying your code, although no guarantees can be made that an update will be made if deemed important for security or compatibility reasons. You may use the current issues noticeboard if you feel another developer has violated the spirit of these expectations in editing your extension.


Desplegando y registrando[edit]

Consultar Review queueReview queue. Si tu extensión añade espacio de nombres, puede que quieras registrar su espacio de nombres predeterminado; asimismo, si añade tablas o campos a la base de datos, puede que quieras registrarlos en database table and field registrationdatabase table and field registration.

Documentación de ayuda[edit]

You should provide public-domain help documentation for features provided by your extension. Help:CirrusSearchHelp:CirrusSearch es un buen ejemplo. You should give users a link to the documentation via the addHelpLink()Manual:Special pages#Help page function.

Proporcionando soporte / colaboración[edit]

Extension developers should open an account on Wikimedia's PhabricatorPhabricator, and request a new project for the extension. This provides a public venue where users can submit issues and suggestions, and you can collaborate with users and other developers to triage bugs and plan features of your extension.

Véase también[edit]

Referencias[edit]