Manual:Tag extensions/es

A menudo, será útil para un proyecto dado extender el marcado wiki predefinido con funcionalidades adicionales, sea un simple procesamiento de cadenas de texto o la recuperación de información. Las extensiones de etiquetas permiten crear etiquetas personalizadas precisamente para hacer eso. Por ejemplo, se podría usar una extensión de etiqueta para introducir una simple etiqueta, que inyecta un formulario de donación en la página. Por ejemplo, puede definir una extensión de etiqueta que permita a un usuario inyectar un formulario de contacto en su página de usuario, utilizando algo como $1. Por ejemplo, puede definir una extensión de etiqueta que permita a un usuario inyectar un formulario de contacto en su página de usuario, utilizando algo como $1.

Una extensión de etiqueta simple consiste en una función callback, que está enganchada al analizador sintáctico para que, cuando éste se ejecute, encuentre y reemplace todas las instancias de una etiqueta específica, llamando a la función callback correspondiente para renderizar el HTML real.

Ejemplo
In extension.json, set up the hooks:

And add the hook into a PHP file

Este ejemplo registra una función de devolución de llamada para la etiqueta. Cuando un usuario añade esta etiqueta a una página como esta:, el analizador sintáctico llamará a la función  , pasando cuatro argumentos:


 * $input : Entrada entre las etiquetas y, o null si la etiqueta está "cerrada", es decir,
 * $args : Argumentos de la etiqueta, que se introducen como los atributos de la etiqueta HTML; se trata de una matriz asociativa indexada por el nombre del atributo.
 * $parser : El parser padre (un objeto Parser); las extensiones más avanzadas lo utilizan para obtener el Título contextual, parsear el texto del wiki, expandir las llaves, registrar las relaciones y dependencias de los enlaces, etc.
 * $frame : El marco padre (un objeto PPFrame). Se utiliza junto con $parser para proporcionar al analizador una información más completa sobre el contexto en el que se llamó a la extensión.

Para un ejemplo más elaborado, véase Ejemplo de extensión de etiquetas

Atributos
Veamos otro ejemplo:

Este ejemplo vuelca los atributos que se han pasado a la etiqueta, junto con sus valores. Es bastante evidente que esto permite especificar de forma flexible nuevas etiquetas personalizadas. Por ejemplo, puede definir una extensión de etiqueta que permita a un usuario inyectar un formulario de contacto en su página de usuario, utilizando algo como.

Hay una verdadera plétora de extensiones de etiquetas disponibles para MediaWiki, algunas de las cuales se muestran en este sitio; otras se pueden encontrar mediante una búsqueda rápida en Internet. Aunque varias de estas extensiones están bastante especializadas para su caso de uso, también hay otras muy queridas y utilizadas que proporcionan varios grados de funcionalidad.

Convenciones
Véase para más información sobre el diseño general y la instalación de una extensión.

Publica tus propias extensiones
Las extensiones que crean nuevos hooks dentro del código de extensión debe registrarlos en hooks de extensión del registro.
 * 1) Crea una nueva página en este wiki llamada Extension: con información sobre tu extensión, cómo instalarla y capturas de pantallas de la extensión en uso. Disponemos de una plantilla útil para almacenar este tipo de información llamada . Para más información, véase la página de la plantilla. Asimismo, deberías añadir toda la información que sea posible al cuerpo de la página. Es conveniente volver a consultar la página de forma regular para responder a las preguntas que tengan otros usuarios en la página de discusión asociada. Además, asegúrate de que la página pertenezca a.
 * 1) Notificar a la lista de correo mediawiki-l.

Véase también publicar su extensión.

Cuestiones de seguridad
Podrás ver que los datos introducidos en los ejemplos mostrados arriba están escapados mediante  antes de ser devueltos. Es crucial que se trate cualquier entrada de datos de esta manera antes de devolverla a los clientes, con el fin de evitar introducir vectores de inyección HTML, que puede dar lugar a vulnerabilidades de tipo cross-site scripting.

Carga de módulos
La forma correcta de añadir módulos a tu extensión es conactarlos a ParserOutput en vez de a $wgOut. La lista de módulos se sacará automáticamente del objeto ParserOutput y se adjuntará a $wgOut incluso cuando la carga de la página está preguardada en caché. Si añades directamente los módulos a $wgOut, puede que no se guarden en caché en la salida del analizador sintáctico.

Sincronización y extensiones
Si cambias el código de una extensión, todas las páginas que utilicen la extensión, teóricamente, reflejarán de inmediato los resultados del nuevo código. Técnicamente hablando, esto significa de que tu código es ejecutado cada vez que en una página que contenga la extensión se renderice.

En práctica, esto a menudo no es el caso, dado al almacenamiento en caché de la página - ya sea por el software MediaWiki, el navegador o por un intermediario proxy o firewall.

Para evitar el caché del analizador de MediaWiki y asegurarse de que se genera una nueva versión de la página, haz clic en editar, sustituye "action=edit" en la URL que aparece en la barra de direcciones de tu navegador por "action=purge" y envía la nueva URL. La página y todas las plantillas a las que hace referencia se regenerarán, ignorando todos los datos almacenados en la caché. La acción de purga es necesaria si la página principal en sí no ha sido modificada, pero la forma en que debe ser renderizada ha cambiado (la extensión fue modificada, o sólo una plantilla referenciada fue modificada).

Si esto no basta para obtener una copia nueva de la página, normalmente puedes saltar cualquier caché intermedia añadiendo '&rand=algúntextoaleatorio' al final de la URL. Asegúrate de que 'algúntextoaleatorio' sea distinto cada vez.

¿Cómo puedo desactivar el almacenamiento en caché de las páginas que utilizan mi extensión?
Desde MediaWiki 1.5, el parser se pasa como tercer parámetro a una extensión. Este parser se puede utilizar para invalidar la caché de esta manera:

Regeneración de la página cuando se edita otra página
Tal vez no quieras deshabilitar la caché por completo, sólo quieres que la página se regenere cada vez que se edite otra página, de forma similar a como se manejan las transclusiones de plantillas. Esto se puede hacer utilizando el objeto parser que se pasa a su función hook. El siguiente método fue tomado de y parece funcionar para este propósito.

Ajuste de grano fino del comportamiento de la caché
Puede utilizar la caché de grano fino para su extensión mediante el uso de claves de caché para diferenciar entre las diferentes versiones de la salida de su extensión. Mientras se renderiza se pueden añadir claves de caché para cada función añadiendo un método addExtraKey a su función hook, por ejemplo

Sin embargo, modificar $parser->getOptions durante el parse significa que las claves de las opciones extra no se incluyen cuando se intenta obtener una página en caché, sólo cuando se renderiza una página para ir a la caché, por lo que se puede utilizar el hook PageRenderingHash para establecer opciones extra. PageRenderingHash se ejecuta tanto al poner una página en la caché, como al sacarla, por lo que es importante sólo añadir nuevas claves al hash si no están ya allí. p. ej.

Algunas notas importantes en esto:


 * Usar "!setting1=$value" en lugar de sólo "!$value" en el confstr asegura que la caché del parser no se desordene si se instalan diferentes extensiones o su orden de carga cambia. ! Se utiliza un separador para las diferentes opciones de representación
 * Algunas personas utilizan  en lugar de  . Ten en cuenta que addExtraKey no indica a la caché del analizador sintáctico que la clave extra está en uso, y por lo tanto puede resultar fácilmente en la ruptura de la caché si no tienes cuidado.

A partir de la versión 1.16
A las funciones hook del parser se les pasa una referencia al objeto parser y un objeto frame; estos deben ser usados para parsear el wikitexto.

existe desde la versión 1.8. Sus ventajas incluyen la simplicidad (sólo toma un argumento y devuelve una cadena) y el hecho de que analiza las etiquetas de extensión en, por lo que puede anidar las etiquetas de extensión.

El segundo parámetro de recursiveTagParse,, es un argumento opcional introducido en MW 1.16 alpha (r55682).


 * Si se proporciona  (usando el valor de   pasado a su extensión), entonces cualquier parámetro de plantilla en   será expandido.  En otras palabras, el contenido como   será reconocido y convertido en el valor apropiado.
 * Si no se proporciona  (por ejemplo,  ), o si   se establece como falso, los parámetros de la plantilla no se expandirán;   no se modificará. Although this unlikely to be the desired behavior, this was the only option available before MW 1.16.

However, one step of parsing that is still skipped for tags, even when using recursiveTagParse, is Parser::preSaveTransform. preSaveTransform is the first step of parsing, responsible for making permanent changes to the about-to-be saved wikitext, such as:

(, ~ ,  )  Without this step, shorthand links such as Help:Contents are considered to be invalid, and are left in their wikitext form when parsed.
 * Converting signatures
 * Expanding link labels, also known as the pipe-trick (e.g., changing Help:Contents into Contents ).
 * Expanding templates.

The original call to preSaveTransform intentionally skips such conversions within all extension tags. If you need pre save transform to be done, you should consider using a parser function instead. All tag extensions can also be called as a parser function using  which will have pre save transform applied.

A partir de la versión 1.5
A partir de la versión 1.5, MediaWiki cuenta con soporte para parámetros (atributos de etiqueta) de tipo XML. The parameters are passed as the second parameter to the hook function, as an associative array. The value strings have already had HTML character entities decoded for you, so if you emit them back to HTML, don't forget to use, to avoid the risk of HTML injection.

¿Cómo puedo evitar la modificación de la salida HTML de mi extensión?
El valor devuelto por una extensión de etiqueta se considera casi texto analizado, que quiere decir que no se considerará HTML puro, sino ligeramente modificado. Hay dos cosas principales que se hacen a la salida de una extensión de etiqueta (junto con otras dos cosas menores):

Strip markers are certain items which are inserted at various stages of processing wikitext to act as a marker to re-insert removed content at a later time. This is not something extensions usually need to worry about. This can sometimes be an issue in some extensions.
 * Replace strip markers.
 * which turns *'s into lists, and turns any line starting with a leading space into a &lt;pre&gt; among other things.

Tag extensions also support returning an array instead of just a string (Much like parser functions) in order to change how the return value is interpreted. El valor de la posición 0 de la matriz debe ser el HTML. The "markerType" key can be set to  in order to stop further parsing. Doing something like  would ensure that the $html value is not further modified and treated as just plain html.

¿Cómo puedo hacer que se muestre mi extensión en Especial:Versión?
Para que tu extensión se muestre en la página de MediaWiki Especial:Versión, debes asignarle créditos de extensión en el código PHP.

To do this, add a  variable as the first executable line of code before the hook line or function definition.

Aquí se muestra un ejemplo de crédito de extensión:

Reemplaza  por una de las siguientes clases (a menos que tu extensión pertenezca a varias clases, en cuyo caso, deberás crear un crédito para cada clase):


 * 'specialpage'&mdash;reservada para añadir páginas especiales de MediaWiki;
 * 'parserhook'&mdash;si tu extensión modifica, complementa o reemplaza las funciones del analizador sintáctico de MediaWiki;
 * 'variable'&mdash;extensión que añade funcionalidades múltiples a MediaWiki;
 * 'media'&mdash;si tu extensión es un controlador de archivos multimedia
 * 'other'&mdash;cualquier otra extensión.

The  is the name of an interface/i18n message that describes your extension that will need to be defined in your extension's i18n.php file. If you omit this field, the  field will be used instead.

Retrieving the tag name inside of the callback
Suppose you have several tags and  that share the same callback, and inside the callback function, you want to obtain the name of the tag that invoked the callback.

The short answer is: the tag name ( or  ) is not present in any of the callback's arguments. But you can work around this by dynamically constructing a separate callback for each tag:

Toolbar buttons
provides an editing toolbar, allowing users to add tags into their editor by simply clicking a button. If you want a toolbar button for your new tag, create a file named something like  in your extension's   folder. The file should look like this:

Further details about customizing this file can be found here. Once you've created the file, you need to register it with so it will be delivered to visitors; this is done by editing your  :

Then, in your PHP file:

Véase también

 * – Lista de variables de etiqueta/especial como, , ...
 * – Lista de etiquetas del analizados en uso en los wikis de Wikimedia.