Extensão:TemplateData

This extension comes with MediaWiki 1.35 and above. Assim, não precisa efetuar o download novamente. No entanto, ainda precisa seguir as outras instruções fornecidas.

Manual de extensões do MediaWiki

TemplateData Estado de lançamento: estável
Implementação	Etiqueta , API
Descrição	Permite armazenar, recuperar e visualizar informações sobre modelos
Autor(es)	Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Parscal, Bartosz Dziewoński, Marielle Volz, ...
Última versão	0.1.2 (Atualizações contínuas)
Política de compatibilidade	Lançamentos de capturas de ecrã junto com o MediaWiki. Original não é compatível com versões anteriores.
MediaWiki	>= 1.43
PHP	5.4+
Alterações à base de dados	Não
Licença	GNU - Licença Pública Geral 2.0 ou superior
Transferência	Download extension Git [?]: Download Git master browse repository (Phabricator · GitHub) commit history repository contributors (GitHub) code review
Parâmetros $wgTemplateDataUseGUI
Etiquetas ‎<templatedata>
Hooks utilizados EditPage::showEditForm:fields EditPage::showEditForm:initial MultiContentSave OutputPageBeforeHTML ParserFetchTemplateData ParserFirstCallInit ResourceLoaderRegisterModules
Quarterly downloads	277 (Ranked 19th)
Public wikis using	6,971 (Ranked 24th)
Traduza a extensão TemplateData se ela estiver disponível em translatewiki.net
Problemas	Tarefas em aberto · Reportar um erro

A extensão TemplateData introduz uma tag ‎<templatedata> e uma API que, juntas, permitem que os editores especifiquem como os modelos e seus parâmetros devem ser utilizados. Esta informação está disponível como uma tabela bem formatada para os usuários finais e como uma API JSON, que permite a outros sistemas (por exemplo, VisualEditor ) construir interfaces para trabalhar com modelos. Consulte Ajuda:TemplateData para obter ajuda detalhada.

Instalação

• Exporte e coloque o ficheiro, ou ficheiros, num diretório chamado TemplateData, na sua pasta 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
• Acrescente o seguinte código ao fundo do ficheiro $LocalSettings:

  wfLoadExtension( 'TemplateData' );
  

•  Pronto – Na página especial Special:Version da sua wiki verifique se a extensão foi instalada.

Editando dados

A extensão TemplateData funciona através da definição de uma tag ‎<templatedata> no Wiki Texto de uma página de modelo (opcionalmente, pode ser transcluída de uma página diferente também). Isto é projetado para ser compatível com o layout comum que muitas wikis têm de transcluir a documentação do modelo a partir de uma página separada (mas não é obrigatório). O conteúdo da tag ‎<templatedata> deve ser um JSON válido usando o formato descrito abaixo; note que todas as descrições devem estar em texto simples (nenhum Wiki Texto é aceito dentro dos dados do modelo).

Quando um bloco ‎<templatedata> é incluído em uma página, a extensão TemplateData realiza as seguintes verificações ao salvar a página:

1. O conteúdo deve ser um JSON válido;
2. Cada item dentro da estrutura JSON deve ser do tipo esperado conforme especificado abaixo (por exemplo, objeto, array ou um tipo primitivo); e
3. Para os itens que possuem uma lista especificada de valores possíveis (por exemplo, o type de um parâmetro), o valor no objeto JSON deve corresponder a um desses valores.

Se alguma dessas verificações falhar, o servidor não será autorizado a salvar e uma mensagem de erro será exibida acima da página de edição.

Para itens de autovalor, T4700 impede que subst: funcione em qualquer modelo adicionado dentro de uma tag, incluindo as tags ‎<ref> e ‎<gallery>. O bloco TemplateData será salvo corretamente, mas o Wiki Texto resultante não será interpretado corretamente quando o modelo for utilizado.

Evite usar {{#tag:templatedata}}, pois isso impossibilita o uso do editor de dados do modelo.

Formato

Abaixo está uma versão visualizada dos dados JSON conforme definido na página do modelo, delimitada por tags ‎<templatedata>‎</templatedata>. A especificação formal está disponível no repositório TemplateData. Consulte Specification.md para obter a versão mais recente.

Objeto TemplateData

O objeto TemplateData é um elemento raiz JSON encapsulado em um elemento ‎<templatedata> na página do modelo.

Chave	Tipo	Descrição
description	InterfaceText ou null	Uma breve descrição do modelo. Deve estar em texto não formatado. Uma vez preenchido, pode ser exibido como legenda ao editar um único modelo e, talvez, nos resultados de busca quando os usuários escolherem um entre muitos. A predefinição é null. → For more details see: description
params	Objeto contendo objetos Param	Um objeto que mapeia cada nome de parâmetro do modelo para um correspondente objeto Param descrevendo as propriedades desse parâmetro. → For more details see: params
paramOrder	Matriz contendo nomes de parâmetros em string	A ordem lógica em que os parâmetros devem ser exibidos. A matriz contém cada chave de parâmetro exatamente uma vez. Cada string deve ser uma chave válida no objeto params. → For more details see: paramOrder
sets	Matriz contendo Definir objetos	Uma matriz contendo especificações definidas. Uma definição é um grupo de parâmetros que devem ser usados em conjunto. A predefinição é []. Observe que a funcionalidade sets ainda está em desenvolvimento.
format	string, tanto inline quanto block.	Como a representação em wikitexto do modelo DEVE ser estruturada. A predefinição é inline. Veja #Formatos_personalizados para outros formatos personalizados.
maps	Objeto contendo Objetos de mapa	Um objeto que vincula um nome simplificado de um terceiro consumidor dos dados do modelo (por exemplo, Citoid, Special:MyLanguage/Wikidata, etc.) a um objeto de mapa que, por sua vez, vincula um nome de um parâmetro do consumidor a um ou mais nomes correspondentes de parâmetros do modelo.

Objeto de Param

Chave	Tipo	Predefinição	Descrição
label	InterfaceText	null	Um nome (muito) breve para o parâmetro. Tente manter menos de 20 caracteres. → For more details see: label
description	InterfaceText	null	Uma breve descrição do parâmetro, para que os usuários saibam qual escolher em uma lista de opções. → For more details see: description
required	booleano	false	Se o parâmetro é necessário para que o modelo funcione (verdadeiro se este parâmetro deve ser especificado). → For more details see: required
suggested	booleano	false	Se o parâmetro é sugerido para que o modelo seja útil (verdadeiro se este parâmetro deve ser especificado). → For more details see: suggested
deprecated	booleano ou string	false	Se o parâmetro está obsoleto. O valor pode ser uma string de instruções orientando o usuário sobre o que pode ser feito, ou simplesmente true. → For more details see: deprecated
aliases	Matriz contendo strings	[]	Lista de aliases. Um alias é um nome alternativo para o parâmetro que pode ser usado em vez do nome principal (não em adição a ele). Os aliases não são documentados em um objeto de Parâmetro separado. Se precisarem de mais informações, elas devem estar em sua própria propriedade marcada como "obsoleto". → For more details see: aliases
default	InterfaceText	null	Um valor padrão fixo utilizado pelo modelo se nenhum valor for atribuído ao parâmetro, ou uma descrição deste. → For more details see: default
autovalue	string	null	Um valor padrão gerado dinamicamente no wikitexto, como a data de hoje ou o nome de usuário do editor; isso geralmente envolverá substituição do wikitexto, como {{subst:CURRENTYEAR}}. → For more details see: autovalue
example	InterfaceText	null	Um texto de exemplo para o parâmetro, para ajudar os usuários a preencherem o valor correto. → For more details see: example
type	string	"unknown"	O tipo do parâmetro, para dicas (leves) do tipo. Um dos: Valor String Tipo de Parâmetro "unknown" Tipo assumido se não definido → For more details see: value ‘unknown’ "number" Qualquer valor numérico (sem pontos decimais ou separadores de milhar) → For more details see: value ‘number’ "string" Qualquer valor textual. Pode conter quebras de linha. → For more details see: value ‘string’ "line" Campo de texto curto – use para nomes, rótulos e outros campos de formato curto. Supõe-se que este seja um texto que não se espera conter quebras de linha. → For more details see: value ‘line’ "boolean" um valor booleano ('1' para true, '0' para false, $vazio para desconhecido), veja lógica de três valores. → For more details see: value ‘boolean’ "date" Uma data no formato ISO 8601, por exemplo "2014-05-09" ou "2014-05-09T16:01:12Z" → For more details see: value ‘date’ "url" Uma URL, incluindo protocolo, por exemplo "http://www.example.org", "https://example.org", ou "//example.org". → For more details see: value ‘url’ "wiki-page-name" Um nome de uma página MediaWiki válido para a wiki atual. Não precisa existir, mas, se não existir, deve ser um nome de página válido que possa ser criado. → For more details see: value ‘wiki-page-name’ "wiki-file-name" Um nome de arquivo MediaWiki válido para a wiki atual. Não precisa existir, mas, se não existir, deve ser um nome de arquivo válido que possa ser carregado. Não deve incluir o nome do lugar (por exemplo, "Foo.svg" e não "Arquivo:Foo.svg" ou "Imagem:Foo.svg"). → For more details see: value ‘wiki-file-name’ "wiki-template-name" Um nome de Modelo MediaWiki válido para a wiki atual. → For more details see: value ‘wiki-template-name’ "wiki-user-name" Um nome de usuário MediaWiki válido para a wiki atual. Não precisa existir, mas se não, deve ser um nome de usuário válido que possa ser criado. Não deve incluir o nome do lugar (por exemplo, "Foo" e não "User:Foo" ou "Usuário:Foo"). → For more details see: value ‘wiki-user-name’ "content" Conteúdo da página em wikitexto, como estilo do texto, links, imagens, etc. → For more details see: value ‘content’ "unbalanced-wikitext" Wikitexto bruto que não deve ser tratado como conteúdo a existir sozinho porque se torna desbalanceado - por exemplo, modelos concatenando wikitexto incompleto como um todo maior, como em {{echo|before=<u>|after=</u>}} → For more details see: value ‘unbalanced-wikitext’ → For more details see: type
inherits	string	nenhum substituído	O nome chave de outro parâmetro (deve ser uma chave válida no objeto params). O atual Objeto do Parâmetro vai herdar propriedades de um Objeto de Parâmetro específico, com propriedades locais substituindo as herdadas. → For more details see: inherits
suggestedvalues	Matriz contendo strings	[]	Uma propriedade opcional do parâmetro. Cria uma lista de valores de parâmetros para ajudar os usuários a selecionar o valor desejado. Para que os valores sugeridos sejam exibidos como caixa combinada no VisualEditor, o tipo do parâmetro deve ser definido em um dos seguintes: conteúdo, linha, string, número, wikitexto desconhecido ou desbalanceado. → For more details see: suggestedvalues

Definir objeto

Chave	Objeto ou tipo primitivo	Descrição
label	InterfaceText	Um nome (muito) breve para o conjunto de parâmetros. Tente manter menos de 20 caracteres.
params	Matriz de strings	Um ou mais nomes de parâmetros para incluir no conjunto (cada um deve ser uma chave válida no objeto params). Um parâmetro pode estar em múltiplas definições. Nem todo parâmetro deve estar em uma definição.

Estrutura dos mapas

Os mapas são uma estrutura de dados única que abrange vários níveis de profundidade. Tornou-se comum chamar o segundo nível de “objeto de mapa”.

Chave	Tipo	Predefinição	Descrição
nome do consumidor	objeto	{}	Um objeto que vincula um nome de um consumidor a um objeto de mapa que, por sua vez, vincula um nome de um parâmetro de consumidor a um ou mais nomes de parâmetros de modelo correspondentes. Os nomes dos parâmetros do modelo podem ser especificados como uma string (um nome), uma matriz de strings (vários nomes) ou uma matriz de matrizes de strings (vários conjuntos de nomes); cada uma dessas strings deve ser uma chave válida no objeto params em outro lugar no TemplateData do mesmo modelo. Um parâmetro de modelo específico pode estar em vários mapas e pode ser usado nos valores de várias chaves em um determinado mapa, mas nem todo parâmetro de modelo deve estar em um mapa. Um exemplo resumido do Template:Cite_news#TemplateData da Wikipédia em inglês ilustra a estrutura de 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 (string ou objeto)

Uma string de texto simples de formato livre (ou seja, sem wikitexto ou HTML) no idioma de conteúdo do wiki, ou um objeto contendo essas strings codificadas pelo código de idioma.

O valor padrão para todos os campos InterfaceText é null.

Tipo de string

If it is a string, it must contain a non-localized string in the content language of the local wiki.

Tipo de objeto

If it is an object, the object must have this mapping:

Chave	Tipo	Descrição
Wikipedia language code	string	Localized string for users of that interface language.

Example of object mapping:

Chave	Value
"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"	"Добро пожаловать в Википедию"

Exemplo

An example TemplateData structure as specified within wikitext on a template page.

<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>

Below is how the above example would be displayed on the template page:

Label unsigned comments in a conversation.

Template parameters

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

See the generated help at Special:ApiHelp/templatedata. A sample invocation (formatted for human readability) is:

api.php?action=templatedata&titles=Template:Cite%20web&format=json [teste na 'Área de Testes' da API (Sandbox)]

This returns the template data for Template:Cite web. The ‎<templatedata>...‎</templatedata> block for this template is on its transcluded template documentation page, en:Template:Cite web/doc.

Additions and changes to JSON as received from the API

The JSON structure provided in response to an API HTTP get request is significantly different than that which is defined in the ‎<templatedata>...‎</templatedata> block. In response to the API request, extension TemplateData makes the following changes to the JSON object:

• Adds two wrapping objects:

• 1. An overall Pages Object containing one or more Page Objects
  2. An object with a numeric key: a Page Object

• Additions/changes to the actual TemplateData Object

• 1. Add the title key with the name of the page from which the data was requested (e.g. "Template:Cite web").
  2. Add the sets key
  3. Change all TemplateText occurrences that are just strings to objects with a single key for the current wiki's Wikipedia language code
  4. Remove all inherits keys.
     • Add all properties from parameter from which an inheritance is defined which are not superseded by explicitly defined keys in the inheritor's Parameter Object.
  5. Add default values for all keys in each Parameter Object which have not been explicitly defined or inherited.

Visualised differences in a TemplateData JSON object delivered by the API

Wrapper objects added to JSON delivered by API
These are not defined in the JSON object enclosed by the ‎<templatedata> tags on the template page.

JSON Root Chave Tipo Descrição pages Page Object The Page object (contains one key which is the page number). If multiple pages were requested at one time there will be multiple Page Objects.

Page Object Chave Tipo Descrição {{{1}}} TemplateData Object The TemplateData Object containing the information payload. The key is a static page number for the template page from which the JSON data was requested.

TemplateData Object (added by API)
The following key is added to the root of the JSON object which is enclosed in ‎<templatedata> tags on the template page.

Chave	Tipo	Descrição
title	string	The page name of the template (e.g. "Template:Cite web"). This key is not contained in the JSON structure on the template page. It is added to the structure by the MediaWiki software in route to delivery via the API.
sets	Array containing Set Objects	An array containing set specifications. A set is a group of parameters that should be used together. If this does not exist on the template page it is added as an empty array to the structure provided by the API.

Parameter Objects from API

Chave	Tipo	Descrição
label	InterfaceText	translated to InterfaceText object, if not already in that format.
required	booliano	If not defined, default value of false added.
description	InterfaceText ou null	If defined as a string, converted to a InterfaceText object. If not defined, key is added with a null value.
deprecated	boolean or string	If not defined, default value of false added.
aliases	Array of strings	If not defined, a default empty array is assigned (i.e. [] ).
default	string	If not defined, default of "" is assigned.
type	string	If not defined, default of "unknown" is assigned.
inherits	(removed)	This key is removed and all inherited keys are added. Keys defined for the current parameter take precedence and any keys not defined on either the current param, or the one from which it inherits are given the default value.

InterfaceText (Object or null):
An object containing strings keyed by language code.

Key	Object or primitive type	Descrição
Object (containing localized strings by Wikipedia language code) If a TemplateData field on the template page contains a string, not an object with localized strings, MediaWiki translates it into an InterfaceText Object with a string assigned to the key name of the source Wikipedia Wikipedia language code. The default for all InterfaceText fields is null.
(Wiki language code)	string	Localized string for users of that interface language.

Example of JSON object provided by API

The response to an API request for the TemplateData structure in the Example section (above) can be seen:

• In HTML format: https://www.mediawiki.org/w/api.php?action=templatedata&titles=Extension:TemplateData&format=jsonfm

• As delivered by the API: https://www.mediawiki.org/w/api.php?action=templatedata&titles=Extension:TemplateData

Configuração

Variável	Predefinição	Descrição
$wgTemplateDataUseGUI	true	Interface da janela experimental para editar "templatedata" JSON

Consulte também

• Extensão:Assistente de Modelo  – user interface for selecting and inserting templates' wikitext, based on their TemplateData.
• GitHub: jeblad/TemplateData – alternate version with some Lua functionality.
• Translatable template
• Wikibase/Maps TemplateData