Extensão: TemplateData

**Manual de extensões do MediaWiki**
TemplateData; Estado de lançamento: estável
Implementação	Etiqueta, API
Descrição	Permite guardar, recuperar e visualizar a informação sobre os modelos
Autor(es)	Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Parscal, Bartosz Dziewoński, Marielle Volz, ...
Última versão	0.2.0 (Atualizações contínuas)
Política de compatibilidade	Lançamentos de capturas de ecrã em conjunto com o MediaWiki. Original não é compatível com as versões anteriores.
PHP	5.4+
Alterações à base de dados	Não
Licença	GNU - Licença Pública Geral 2.0 ou superior
Transferência	Transferir extensão ; Git [?]: Explorar repositório (Phabricator · GitHub); Revisão de código Gerrit; Registo de implementação do Git; Transferir 'tarball' fonte;
	Parâmetros $wgTemplateDataMaxFavorites; $wgTemplateDataEnableFeaturedTemplates; $wgTemplateDataEnableDiscovery; $wgTemplateDataEnableCategoryBrowser; $wgTemplateDataCategoryBrowserItem; $wgTemplateDataEditorNamespaces; $wgTemplateDataUseGUI;
	Etiquetas ‎<templatedata>
	Hooks utilizados CommunityConfigurationProvider_initList; EditPage::showEditForm:initial; GetPreferences; MultiContentSave; OutputPageBeforeHTML; ParserFetchTemplateData; ParserFirstCallInit; ResourceLoaderRegisterModules; SaveUserOptions;
	Traduza a extensão TemplateData se esta estiver disponível em translatewiki.net
Problemas	Tarefas em aberto · Reportar um erro

This page is a translated version of the page Extension:TemplateData and the translation is 82% complete.

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

Instalação

This extension comes with MediaWiki 1.35 and later, so you do not need to download it. The remaining configuration instructions must still be followed.

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.

Editar dados

A extensão TemplateData funciona através da etiqueta ‎<templatedata> no texto wiki de uma página de modelo (opcionalmente, também pode ser movida de uma página diferente). Isto foi desenhado para ser compatível com a disposição comum que muitas wikis têm de mover a documentação do modelo de uma página separada (mas não é obrigatório). Este conteúdo da etiqueta ‎<templatedata> deve ser um JSON válido utilizando o formato descrito em baixo; note que todas as descrições devem estar em texto simples (nenhum texto wiki é aceite dentro dos dados do modelo).

Quando um bloco ‎<templatedata> é incluído numa página, a extensão TemplateData realiza as seguintes verificações quando a página está a ser guardada:

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

Se alguma destas verificações falhar, o servidor não será autorizado a guardar e será exibida uma mensagem de erro por cima da página de edição.

Para os itens de valor automático, T4700 impede que subst: funcione em qualquer modelo que é adicionado dentro de uma etiqueta, incluindo as etiquetas ‎<ref> e ‎<gallery>. O bloco de TemplateData será guardado corretamente, mas o texto wiki resultante não será analisado corretamente quando o modelo é utilizado.

Por favor, evite utilizar {{#tag:templatedata}}, pois isso impossibilita a utilização do editor de dados do modelo.

Formato

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

Objeto de TemplateData

O objeto de TemplateData é um "elemento raiz JSON" integrado num elemento ‎<templatedata> na página do modelo.

Chave	Tipo	Descrição
`description`	InterfaceText ou `null`	Uma breve descrição do modelo. Este deve estar em texto simples. Uma vez preenchido, este pode ser exibido como legenda quando editar um único modelo e, talvez, nos resultados de pesquisa quando os utilizadores escolherem um entre muitos. A predefinição é `null`. → For more details see: description
`params`	Objeto contendo objetos 'Param'	Um objeto que mapeia cada nome do parâmetro do modelo para um correspondente objeto 'Param' descrevendo as propriedades desse parâmetro. → For more details see: params
`paramOrder`	Matriz contendo string de nomes de parâmetro	A ordem lógica em que os parâmetros deverão ser exibidos. A matriz contém cada chave do 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 deverão ser utilizados em conjunto. A predefinição é []. Note que a funcionalidade `sets` ainda está em desenvolvimento.
`format`	string, tanto `inline` quanto `block`.	Como a representação no texto wiki do modelo DEVERIA ser estruturada. A predefinição é `inline`. Veja #Formatos_personalizados para outros formatos personalizados.
`maps`	Objeto contendo Objetos de mapa	Um objeto que interliga um nome simplificado de um terceiro consumidor dos dados do modelo (por exemplo, Citoid, Special:MyLanguage/Wikidata, etc.) para um objeto de mapa que, por sua vez, interliga 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 com menos de 20 carateres.

→ For more details see: label

description

InterfaceText

null

Uma breve descrição do parâmetro, para os utilizadores saberem qual escolher numa lista de opções.

→ For more details see: description

required

booliano

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

booliano

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

booliano ou string

false

Se o parâmetro está obsoleto. O valor pode ser uma string de instruções orientando o utilizador 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 utilizado em vez do nome principal (não em adição a ele). Aliases não são documentados num objeto de 'Parâmetro' separado. Se precisarem de mais informação, elas deverão estar na sua própria propriedade marcada como "obsoleto".

→ For more details see: aliases

default

InterfaceText

null

Um valor predefinido 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 predefinido gerado dinamicamente no texto wiki, como a data de hoje ou o nome de utilizador do editor; isso geralmente envolverá a substituição do texto wiki, 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 booliano ('1' para true, '0' para false, '' 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"	Um 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 Objeto do Parâmetro atual irá herdar as 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 predefinido para todos os campos do 'Texto da Interface' é null.

Tipo de string

Se é uma string, esta deve conter uma string não localizada na linguagem do conteúdo da wiki local.

Tipo de objeto

Se for um objeto, o objeto deve ter este mapeamento:

Chave	Tipo	Descrição
"Código do idioma da Wikipédia"	string	Uma string localizada para os utilizadores desse idioma da interface.

Exemplo de mapeamento de objetos:

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

Exemplo

Uma estrutura de TemplateData exemplo como especificada dentro do texto wiki numa página de modelo.

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

Em baixo mostra-se como o exemplo acima seria exibido na página do modelo:

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 a ajuda gerada em 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
Adições/alterações ao Objeto do 'Modelo de Dados' atual
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

Raiz de JSON
Chave	Tipo	Descrição
`pages`	Objeto da Página	O objeto Page (contém uma chave que é o número da página). Se fossem solicitadas várias páginas ao mesmo tempo existiriam múltiplo objetos Page.

Objeto da página
Chave	Tipo	Descrição
(número da página)	Objeto 'Dados do Modelo'	O Objeto 'Dados do Modelo' que contém a carga útil de informação. 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	O nome da página do modelo (por exemplo, "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`	booliano ou string	Se não definido, o valor predefinido de false adicionado.
`aliases`	Matriz de 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.

Texto da Interface (Objeto ou `null`):
An object containing strings keyed by language code.
Chave	Objeto ou tipo primitivo	Descrição
Objeto (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. A predefinição para todos os campos InterfaceText é `null`.
(código do idioma da Wiki)	string	AS cadeias de carateres traduzidas para os utilizadores desse idioma da interface.

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:

No formato HTML: 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
`$wgTemplateDataEditorNamespaces`	`[ 10 ]`	The namespaces in which the template data editor appears when creating or editing a page. (T189989)
`$wgTemplateDataMaxFavorites`	`50`	The maximum number of favorite templates that can be stored. (T377460)

Consultar também

Extensão: TemplateWizard – interface do utilizador para selecionar e inserir o texto wiki dos modelos, com base nos seus TemplateData.
GitHub: jeblad/TemplateData – versão alternativa com alguma funcionalidade Lua.
Modelo traduzível
Wikibase/Maps TemplateData

Este extensão está a ser utilizado em um ou mais projetos da Wikimedia. Isso provavelmente significa que a extensão é estável e funciona bem o suficiente para ser usada por esses sites de alto tráfego. Procure o nome desta extensão nos arquivos de configuração CommonSettings.php e InitialiseSettings.php da Wikimedia para ver onde está instalado. Uma lista completa das extensões instaladas em um determinado wiki pode ser vista na página Special:Version do wiki.

This extension is included in the following wiki farms/hosts and/or packages: