Extensión:TemplateData

This extension comes with MediaWiki 1.35 and above. Thus you do not have to download it again. However, you still need to follow the other instructions provided.

Manual de extensiones de MediaWiki

TemplateData Estado de lanzamiento: estable
Implementación	Etiqueta , API
Descripción	Permite almacenar, recuperar y visualizar información sobre plantillas
Autor(es)	Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Parscal, Bartosz Dziewoński, Marielle Volz, ...
Última versión	0.1.2 (Actualizaciones continuas)
Política de compatibilidad	Lanzamientos de screenshots junto con MediaWiki. Master no es compatible con versiones anteriores.
PHP	5.4+
Cambios de la base de datos	No
Licencia	GNU Licencia Pública general 2.0 o posterior
Descarga	Descargar la extensión. Git [?]: Descargar desde master de Git Explorar el repositorio (Phabricator · GitHub) historial de cambios Colaboradores de repositorio (GitHub) revisión de código
Parámetros $wgTemplateDataEditorNamespaces $wgTemplateDataUseGUI
Etiquetas ‎<templatedata>
Hooks que usa EditPage::showEditForm:fields EditPage::showEditForm:initial MultiContentSave OutputPageBeforeHTML ParserFetchTemplateData ParserFirstCallInit ResourceLoaderRegisterModules
Descargas trimestrales	275 (Ranked 16th)
Wikis públicos que lo utilizan	6,971 (Ranked 24th)
Traduce la extensión TemplateData si está disponible en translatewiki.net
Asuntos	Tareas abiertas · Reportar un bug

La extensión TemplateData introduce una etiqueta ‎<templatedata> y una API que juntas permiten a los editores especificar cómo se deben usar las plantillas y sus parámetros. Esta información está disponible como una tabla bien formateada para los usuarios finales, y como una API JSON, que permite a otros sistemas (por ejemplo, VisualEditor ) construir interfaces para trabajar con plantillas. Véase Help:TemplateData para mayor ayuda.

Instalación

• Descarga y extrae los archivos en un directorio denominado «TemplateData» dentro de la carpeta extensions/.
  Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/TemplateData
• Añade el siguiente código en la parte final de tu archivo LocalSettings.php :

  wfLoadExtension( 'TemplateData' );
  

•  Hecho – Navega a Special:Version en el wiki para verificar que la extensión se haya instalado correctamente.

Editar datos

La extensión de TemplateData funciona al tener una etiqueta ‎<templatedata> definida en el wikitext de una página de plantilla (opcionalmente también puede ser transcluida desde una página diferente). Esta está diseñada para ser compatible con el diseño común que muchas wikis tienen de la transclusión de documentación de plantilla de una página separada (pero no es necesario). Este contenido de la etiqueta ‎<templatedata> debe ser JSON válido utilizando el formato descrito a continuación; tenga en cuenta que todas las descripciones deben estar en texto simple (no se acepta wikitexto dentro de los datos de la plantilla).

Cuando se incluye un bloque de ‎<templatedata> en una página, la extensión de TemplateData realiza las siguientes verificaciones cuando se guarda la página:

1. El contenido debe ser válido JSON;
2. Cada elemento dentro de la estructura JSON debe ser del tipo esperado como se especifica a continuación (por ejemplo, objeto, matriz o primitivo); y
3. Para aquellos elementos que tienen una lista específica de valores posibles (por ejemplo, el type de un parámetro), el valor en el objeto JSON debe coincidir con uno de esos valores.

Si alguna de estas comprobaciones falla, el servidor no podrá guardar y se mostrará un mensaje de error por encima de la página de edición.

Para los artículos autovalue , T4700 evita que subst: funcione en cualquier plantilla que se agregue dentro de una etiqueta, incluidas las etiquetas ‎<ref> y ‎<gallery>. El bloque de TemplateData se guardará correctamente, pero el texto de wiki resultante no se analizará correctamente cuando se usa la plantilla.

Evite utilizar {{#tag:templatedata}}, ya que hace imposible utilizar el editor de datos de plantilla.

Formato

A continuación se muestra una versión visualizada de los datos JSON definidos en la página de plantilla adjunta por las etiquetas ‎<templatedata>‎</templatedata>. La especificación formal está disponible en el repositorio de TemplateData. Consulte Specification.md para la última versión.

Objeto de TemplateData

El objeto TemplateData es un "elemento raíz JSON" incluido en un elemento ‎<templatedata> en la página de la plantilla.

Clave	Tipo	Descripción
description	InterfaceText o null	Una breve descripción de la plantilla. Debe estar en texto simple. Una vez llenado, puede mostrarse como leyenda cuando se edita una sola plantilla y tal vez en los resultados de búsqueda cuando los usuarios eligen una de muchas. El valor por defecto es null. → For more details see: description
params	Objeto que contiene Objetos Param	Un objeto que asigna cada nombre de parámetro de la plantilla a un objeto Param correspondiente que describe las propiedades de ese parámetro. → For more details see: params
paramOrder	Array que contiene cadenas de nombres de parámetros	El orden lógico en el que se deben mostrar los parámetros. El conjunto contiene cada clave de parámetro exactamente una vez. Cada cadena debe ser una clave válida en el objeto params. → For more details see: paramOrder
sets	Matriz que contiene Conjunto de objetos	Una matriz que contiene especificaciones de conjuntos. Un conjunto es un grupo de parámetros que deben usarse juntos. El valor predeterminado es []. Tenga en cuenta que la funcionalidad de sets está todavía en desarrollo.
format	cadena, ya sea inline o block	Cómo debe estar la representación del texto wiki de la plantilla. El valor predeterminado es inline. Consulte #Custom_formats para otros formatos personalizados.
maps	Object containing Map objects	Un objeto que vincula un nombre simplificado de un tercer consumidor de los datos de la plantilla (es decir, Citoid, Special:MyLanguage/Wikidata, etc.) a un objeto de mapa que a su vez vincula un nombre de un parámetro de consumidor a uno o más nombres correspondientes de parámetros de la planilla.

Objeto parámetro

Clave	Tipo	Por defecto	Descripción
label	InterfaceText	null	Un nombre (muy) breve para el parámetro. Trata de mantenerte bajo los 20 caracteres. → For more details see: label
description	InterfaceText	null	Una breve descripción del parámetro, para que los usuarios sepan cuál elegir de una lista de opciones. → For more details see: description
required	booleano	false	Si el parámetro es necesario para que la plantilla funcione (verdadero si este parámetro debe especificarse). → For more details see: required
suggested	booleano	false	Si se sugiere el parámetro para que la plantilla sea útil (verdadero si este parámetro debería especificarse). → For more details see: suggested
deprecated	booleano o cadena	false	Si el parámetro está desactualizado. El valor puede ser una serie de instrucciones que indican al usuario lo que se puede hacer en su lugar, o simplemente true. → For more details see: deprecated
aliases	Array que contiene cuerdas	[]	Lista de alias. Un alias es un nombre alternativo para el parámetro que puede usarse en lugar (no además) del nombre principal. Los alias no están documentados en un objeto Parámetro separado. Si necesitan más información, deben estar en su propia propiedad marcada "deprecada". → For more details see: aliases
default	InterfaceText	null	Un valor predeterminado fijo utilizado por la plantilla si no se asigna ningún valor al parámetro, o una descripción de este. → For more details see: default
autovalue	cadena	null	Un valor predeterminado generado dinámicamente en el texto de wikitext, como la fecha de hoy o el nombre del usuario de edición; esto a menudo implicará la sustitución del texto de wiketext, como {{subst:CURRENTYEAR}}. → For more details see: autovalue
example	InterfaceText	null	Un texto de ejemplo para el parámetro, para ayudar a los usuarios a llenar el valor correcto. → For more details see: example
type	cadena	"unknown"	El tipo del parámetro, para el tipo (suave) de sugerencia. Uno de los siguientes: Valor de cuerdas Tipo de parámetro "unknown" Tipo supuesto si no está establecido → For more details see: value ‘unknown’ "number" Cualquier valor numérico (sin puntos decimales o separadores de mil) → For more details see: value ‘number’ "string" Cualquier valor textual. Puede contener interrupciones de línea. → For more details see: value ‘string’ "line" Campo de texto corto - uso para nombres, etiquetas y otros campos de forma corta. Se supone que este es un texto que no se espera que contenga interrupciones de línea. → For more details see: value ‘line’ "boolean" Un valor booleano ('1' para true, '0' para false, $vacío para desconocido), consulte lógica de tres valores. → For more details see: value ‘boolean’ "date" Una fecha en formato ISO 8601, por ejemplo "2014-05-09" o "2014-05-09T16:01:12Z" → For more details see: value ‘date’ "url" Una URL, incluyendo el protocolo, por ejemplo "http://www.example.org", "https://example.org", o "//example.org". → For more details see: value ‘url’ "wiki-page-name" Un nombre válido de la página de MediaWiki para la wiki actual. No tiene que existir, pero si no, debería ser un nombre de página válido que podría ser creado. → For more details see: value ‘wiki-page-name’ "wiki-file-name" Un nombre de archivo de MediaWiki válido para la wiki actual. No tiene que existir, pero si no, debería ser un nombre de archivo válido que se pueda subir. No debe incluir el espacio de nombres (por ejemplo, "Foo.svg" no "File:Foo.svg" o "Bild:Foo.svg"). → For more details see: value ‘wiki-file-name’ "wiki-template-name" Un nombre válido de la plantilla de MediaWiki para la wiki actual. → For more details see: value ‘wiki-template-name’ "wiki-user-name" Un nombre de usuario de MediaWiki válido para la wiki actual. No tiene que existir, pero si no, debería ser un nombre de usuario válido que podría ser creado. No debe incluir el espacio de nombres (por ejemplo, "Foo.svg" no "File:Foo.svg" o "Bild:Foo.svg"). → For more details see: value ‘wiki-user-name’ "content" Contenido de la página en wikitexto, como estilo de texto, enlaces, imágenes, etc. → For more details see: value ‘content’ "unbalanced-wikitext" Técnico de wiki que no debe ser tratado como contenido independiente porque no está equilibrado, por ejemplo, plantillas que contienen un texto de wiki incompleto como un todo más grande, como {{echo|before=<u>|after=</u>}} → For more details see: value ‘unbalanced-wikitext’ → For more details see: type
inherits	cuerdas	Ninguno sustituidos	La clave de nombre de otro parámetro (debe ser una clave válida en el objeto params). El Objeto de parámetro actual heredará las propiedades del Objeto de parámetro especificado, y las propiedades locales anularán las heredadas. → For more details see: inherits
suggestedvalues	Array que contiene cuerdas	[]	Una propiedad de parámetro opcional. Crea una lista de valores de parámetros para ayudar a los usuarios a seleccionar el valor deseado. Para que los valores sugeridos se muestren como una caja combinada en VisualEditor, el tipo del parámetro debe ser establecido en uno de los siguientes: contenido, línea, cadena, número, wikitext desconocido o desequilibrado. → For more details see: suggestedvalues

Objeto URI

Clave	Tipo de objeto o tipo primitivo	Descripción
label	InterfaceText	Un nombre (muy) breve para el conjunto de parámetros. Trata de mantenerte bajo los 20 caracteres.
params	Array de cuerdas	Uno o más nombres de parámetros para incluir en el conjunto (cada uno debe ser una clave válida en el objeto params). Un parámetro puede estar en múltiples conjuntos. No todos los parámetros deben estar en un conjunto.

Maps structure

Los mapas son una estructura de datos única que va a múltiples niveles de profundidad. Se hizo común llamar al segundo nivel un “objeto de mapa”.

Clave	Tipo	Por defecto	Descripción
nombre del consumidor	objeto	{}	An object that links a name of a consumer to a map object that in turn links a name of a consumer parameter to one or more corresponding names of template parameters. Los "nombres de los parámetros de la plantilla" se pueden especificar como una cadena (un nombre), una matriz de cadenas (varios nombres) o una matriz de matrices de cadenas (varios conjuntos de nombres); cada una de estas cadenas debe ser una clave válida en el objeto params en otra parte del TemplateData de la misma plantilla. Un parámetro de plantilla específico puede estar en varios mapas y puede usarse en los valores de varias claves en un mapa determinado, pero no todos los parámetros de plantilla "deben" estar en un mapa. Un ejemplo abreviado de Template:Cite_news#TemplateData de la Wikipedia inglesa ilustra la estructura de los objetos de mapa. { "proveit": { "main": "title", "textarea": [ "quote" ] }, "citoid": { "title": "title", "url": "url", "publisher": "publisher", "publicationTitle": "work", "date": "date", "ISSN": [ "issn" ], "ISBN": [ "isbn" ], "contributor": "others", "author": [ [ "first", "last" ], [ "first2", "last2" ], [ "first9", "last9" ] ], "editor": [ [ "editor-first", "editor-last" ] ] } }

InterfaceText (cadena u objeto)

Una cadena de texto plano de forma libre (es decir, sin wikitext o HTML) en el lenguaje de contenido de la wiki, o un objeto que contiene esas cadenas tecladas por código de lenguaje.

El valor predeterminado para todos los campos de InterfaceText es null.

string

Si es una cadena, debe contener una cadena no localizada en el lenguaje de contenido de la wiki local.

Tipo de objeto

Si es un objeto, el objeto debe tener este mapa:

Clave	Tipo	Descripción
Código de idioma de Wikipedia	cuerdas	Una cadena localizada para los usuarios de ese lenguaje de interfaz.

Ejemplo de mapeo de objetos:

Clave	Valor
"en"	"Welcome to Wikipedia"
"de"	"Willkommen bei Wikipedia"
"fr"	"Bienvenue sur Wikipédia"
"nl"	"Welkom op Wikipedia"
"it"	"Benvenuti su Wikipedia"
"es"	"Bienvenidos a Wikipedia"
"ru"	"Добро пожаловать в Википедию"

Ejemplo

Un ejemplo TemplateData estructura tal como se especifica dentro del texto wiki en una página de plantilla.

<templatedata>
{
    "description": "Label unsigned comments in a conversation.",
    "params": {
        "user": {
            "label": "User's name",
            "type": "wiki-user-name",
            "required": true,
            "description": "User name of person who forgot to sign their comment.",
            "aliases": ["1"]
        },
        "date": {
            "label": "Date",
            "suggested": true,
            "description": {
                "en": "Timestamp of when the comment was posted, in YYYY-MM-DD format."
            },
            "aliases": ["2"],
            "autovalue": "{{subst:#time:Y-m-d}}"
        },
        "year": {
            "label": "Year",
            "type": "number"
        },
        "month": {
            "label": "Month",
            "inherits": "year"
        },
        "day": {
            "label": "Day",
            "inherits": "year"
        },
        "comment": {
            "required": false
        }
    },
    "sets": [
        {
            "label": "Date",
            "params": ["year", "month", "day"]
        }
    ],
    "maps": {
        "ExampleConsumer": {
            "foo": "user",
            "bar": ["year", "month", "day"],
            "quux": [
                "date",
                ["day", "month"],
                ["month", "year"],
                "year"
            ]
        }
    }
}
</templatedata>

A continuación se muestra cómo se mostraría el ejemplo anterior en la página de plantilla:

Label unsigned comments in a conversation.

Template parameters[Edit template data]

Parameter		Description	Type	Status
User's name	user 1	User name of person who forgot to sign their comment.	User	required
Date	date 2	Timestamp of when the comment was posted, in YYYY-MM-DD format. Auto value {{subst:#time:Y-m-d}}	Unknown	suggested
Year	year	no description	Number	optional
Month	month	no description	Number	optional
Day	day	no description	Number	optional
comment	comment	no description	Unknown	optional

API

Ver la ayuda generada en Special:ApiHelp/templatedata. Una invocación de muestra (formateada para su legibilidad por el hombre) es:

api.php?action=templatedata&titles=Template:Cite%20web&format=json [Prueba en ApiSandbox]

Esto devuelve los datos de la plantilla para Plantilla:Cite web. El bloque ‎<templatedata>...‎</templatedata> para esta plantilla se encuentra en su página de documentación de plantilla transcluida, es:Template:Cite web/doc.

Adiciones y cambios a JSON tal y como se reciben desde la API

La estructura JSON proporcionada en respuesta a una solicitud de API HTTP obtiene es significativamente diferente a la que se define en el bloque ‎<templatedata>...‎</templatedata>. En respuesta a la solicitud de API, la extensión TemplateData hace los siguientes cambios al objeto JSON:

• Agrega dos objetos envolventes:
  1. Un Objeto de páginas general que contiene uno o más Objeto de página
  2. Un objeto con una clave numérica: un Objeto de página
• Adiciones/cambios al Objeto TemplateData real
  1. Añadir la clave title con el nombre de la página desde la que se solicitaron los datos (por ejemplo, "Template:Cite web").
  2. Añadir la clave sets
  3. Cambiar todas las ocurrencias de TemplateText que sean simplemente cadenas a objetos con una clave única para el código de idioma de Wikipedia de la wiki actual
  4. Remove all inherits keys.
     • Agregue todas las propiedades del parámetro a partir del cual se define una herencia que no estén reemplazadas por claves definidas explícitamente en el Objeto de parámetro del heredero.
  5. Agregue valores predeterminados para todas las claves en cada Objeto de parámetro que no se hayan definido o heredado explícitamente.

Diferencias visualizadas en un objeto JSON de TemplateData proporcionado por la API

Objetos de envoltura añadidos a JSON entregados por API
Estos no se definen en el objeto JSON adjunto por las etiquetas ‎<templatedata> en la página de plantilla.

Raíz de JSON Clave Tipo Descripción pages Objeto de página El objeto Page (contiene una clave que es el número de página). Si se solicitan varias páginas a la vez habrá múltiples Page Objetos.

Objeto de la página Clave Tipo Descripción (número de página) Objeto TemplateData El Objeto TemplateData que contiene la carga útil de información. La clave es un número de página estática para la página de plantilla de la que se solicitaron los datos JSON.

Objeto de datos de plantilla (agregado por API)
Se agrega la siguiente clave a la raíz del objeto JSON que está encerrada en las etiquetas ‎<templatedata> en la página de plantilla.

Clave	Tipo	Descripción
title	cuerdas	El nombre de la página de la plantilla (por ejemplo, "Template:Cite web"). Esta clave "no" está contenida en la estructura JSON en la página de plantilla. Se agrega a la estructura por el software MediaWiki en camino a la entrega a través de la API.
sets	Matriz que contiene Conjunto de objetos	Una matriz que contiene especificaciones de conjuntos. Un conjunto es un grupo de parámetros que deben usarse juntos. Si no existe en la página de plantilla, se añade como matriz vacía a la estructura proporcionada por la API.

Objetos de parámetro de la API

Clave	Tipo	Descripción
label	InterfaceText	traducido a InterfaceText objeto, si no ya en ese formato.
required	booleano	Si no se define, valor predeterminado de false añadido.
description	InterfaceText o null	Si se define como una cadena, convertido en un objeto InterfaceText. Si no se define, se agrega la clave con un valor de null.
deprecated	booleano o cadena	Si no se define, valor predeterminado de false añadido.
aliases	Array of strings	Si no se define, se asigna una matriz vacía predeterminada (es decir, []).
default	cuerdas	Si no está definido, se asigna el valor por defecto de "".
type	cadena	Si no se define, se asigna el valor predeterminado de "unknown".
inherits	(eliminado)	Esta llave se elimina y se añaden todas las llaves heredadas. Las claves definidas para el parámetro actual tienen prioridad y las claves no definidas en el parámetru actual o en el que hereda se dan el valor predeterminado.

InterfaceText (objeto o null):
Un objeto que contiene cadenas tecladas por código de lenguaje.

Clave	Tipo de objeto o primitivo	Descripción
Objeto (que contiene cadenas localizadas por código de idioma de Wikipedia) Si un campo TemplateData en la página de plantilla contiene una cadena, no un objeto con cadenas localizadas, MediaWiki lo traduce en un objeto InterfaceText con una cadena asignada al nombre de clave de la fuente Wikipedia Código de idioma de Wikipedia. El valor predeterminado para todos los campos de InterfaceText es null.
(código de lenguaje de Wiki)	cadena	Una cadena localizada para los usuarios de ese lenguaje de interfaz.

Ejemplo de objeto JSON proporcionado por API

La respuesta a una solicitud de API para la estructura TemplateData en la sección Example (arriba) se puede ver:

• En formato HTML: https://www.mediawiki.org/w/api.php?action=templatedata&titles=Extension:TemplateData&format=jsonfm
• Como se entrega por la API: https://www.mediawiki.org/w/api.php?action=templatedata&titles=Extension:TemplateData

Configuración

Variable	Por defecto	Descripción
$wgTemplateDataUseGUI	true	Interfaz de diálogo experimental para editar modelos de datos JSON
$wgTemplateDataEditorNamespaces	[ 10 ]	The namespaces in which the template data editor appears when creating or editing a page. (task T189989)

Véase también

• Extensión:Mejor de diseño  – interfaz de usuario para seleccionar e insertar el texto de las plantillas, basado en sus datos $.
• GitHub: jeblad/TemplateData – una versión alternativa con alguna funcionalidad Lua.
• Template traducible
• Wikibase/Maps TemplateData