MediaWiki

Extensão:TemplateData

This page is a translated version of the page Extension:TemplateData and the translation is 69% complete.
Languages:
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 [?]:
Parâmetros
  • $wgTemplateDataUseGUI
Etiquetas
‎<templatedata>
Hooks utilizados
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

ParameterDescriptionTypeStatus
User's nameuser 1

User name of person who forgot to sign their comment.

Userrequired
Datedate 2

Timestamp of when the comment was posted, in YYYY-MM-DD format.

Auto value
{{subst:#time:Y-m-d}}
Unknownsuggested
Yearyear

no description

Numberoptional
Monthmonth

no description

Numberoptional
Dayday

no description

Numberoptional
commentcomment

no description

Unknownoptional

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:

    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:

Configuração

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

Consulte também

Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:TemplateData/pt&oldid=6766768"