Extensão:TemplateData

This page is a translated version of the page Extension:TemplateData and the translation is 54% complete.
Other languages:
Deutsch • ‎English • ‎Türkçe • ‎dansk • ‎español • ‎français • ‎lietuvių • ‎português • ‎čeština • ‎русский • ‎українська • ‎अवधी • ‎বাংলা • ‎中文 • ‎日本語
Manual de extensões do MediaWiki
OOjs UI icon advanced.svg
TemplateData
Estado de lançamento: estável
Screenshot of TemplateData extension.png
Implementação Etiqueta , API
Descrição Permite guardar, recuperar e visualizar a informação sobre modelos
Autor(es) Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Pascal, Bartosz Dziewoński, Marielle Volz, ...
Última versão 0.1.2 (Atualizações contínuas)
Política de compatibilidade ramos de lançamento
MediaWiki 1.25+
PHP 5.4+
Alterações à base de dados Não
Licença GNU - Licença Pública Geral 2.0 ou superior
Transferência
  • $wgTemplateDataUseGUI
<templatedata>
Traduza a extensão TemplateData se ela estiver disponível em translatewiki.net
Verifique a utilização e a matriz de versões
Problemas Tarefas em aberto · Reportar um erro

A extensão TemplateData insere uma tag <templatedata> e uma API, que juntas, permite aos editores especificar como os modelos devem ser chamados. Esta informação está disponível como uma tabela bem formatada para os utilizadores finais, e como uma API JSON, que permite outros sistemas (por exemplo, o Editor Visual) para criar interfaces para trabalhar com modelos e os seus parâmetros. 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/.
  • Acrescente o seguinte código ao fundo do ficheiro LocalSettings.php:
    wfLoadExtension( 'TemplateData' );
    
  •   Pronto – Na página especial Special:Version da sua wiki verifique se a extensão foi instalada.

Para utilizadores que tenham o MediaWiki versão 1.24 ou anteriores:

As instruções acima descrevem a nova forma de instalar esta extensão, usando a extensão wfLoadExtension(). Se precisar de instalar esta extensão nestas versões anteriores (MediaWiki 1.24 e anteriores), em vez de wfLoadExtension( 'TemplateData' );, use:

require_once "$IP/extensions/TemplateData/TemplateData.php";

Edição de dados

A extensão TemplateData funciona com uma etiqueta definida <templatedata> no texto wiki de uma página de modelo (opcionalmente, este também pode ser transcrito de uma página diferente). Esta é projetada para ser compatível com o layout comum que muitas wikis têm de transcrever a documentação do modelo de uma página separada (mas não é obrigatório). O conteúdo da etiqueta <templatedata> deve ser um JSON válido utilziando o formato descrito em baixo; note que todas as descrições devem estar em texto não formatado (texto wiki não é permitido dentro dos dados do modelo).

Quando um bloco <templatedata> é incluído na página, a extensão DadosDeModelo executa as seguintes verificações quando a página está sendo salva:

  1. Os conteúdos devem ser um JSON válido;
  2. Cada item com da estrutura JSON devem ser do tipo esperado, conforme especificado abaixo (por exemplo, objeto, matriz ou primitivo); e
  3. Para aqueles itens que possuem uma lista específica de valores possíveis (por exemplo, params.yourParameterName.type), o valor no objeto JSON deve corresponder a um desses valores.

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

Para itens de autovalor, o bug 2700 impede subst: de trabalhar em qualquer modelo adicionado dentro de <tag>, incluindo as tags <ref> e <gallery>. O bloco DadosDeModelo salvará corretamente, mas o wikitexto de resultado não será analisado corretamente quando o modelo é usado.

Observe que você não pode usar {{#tag:templatedata}} no lugar de <templatedata>.

Formato

Abaixo está a versão visualizada dos dados JSON como definidas na página de modelo entre as tags <templatedata></templatedata>. A especificação formal está disponível no repositório TemplateData. Consulte Specification.md para a versão mais recente.

Objeto de TemplateData

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

Chave Tipo Descrição
description InterfaceText ou 2 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 possivelmente até nos resultados de pesquisa quando os usuários escolhem um dentre muitos. A predefinição é null.
params Objeto contendo objetos de Param Um objeto que mapeia cada nome de parâmetro do modelo para um objeto Param correspondente, descrevendo as propriedades daquele parâmetro.
paramOrder Matriz contendo nomes de parâmetros em string A ordem lógica na qual os parâmetros devem ser exibidos. A matriz contendo cada chave de parâmetro exatamente uma vez. Cada string deve ser uma chave válida no objeto params. Se esta chave não existir na estrutura <templatedata></templatedata> na página do modelo, é adicionada à estrutura fornecida pela API usando a ordem na qual os parâmetros ocorrem no objeto DadosDeModelo.
sets Matriz contendo
Definir objetos
Uma matriz contendo especificações definidas. Uma definição é um grupo de parâmetros que deveriam ser usados juntos. A predefinição é []. Note que a funcionalidade sets ainda está em desenvolvimento.
format string, tanto inline quanto block. Como a representação de wikitexto do modelo DEVERIA ser apresentada. A predefinição é inline. Veja #Formatos_personalizados para outros formatos personalizados.
maps Um objeto de Mapas Um objeto que mapeia um nome simplificado de um consumidor terceiro dos dados do modelo (ou seja, Citoid, Special:MyLanguage/Wikidata, etc.) para um objeto, que por sua vez, mapeia um nome de um parâmetro do consumidor para um ou mais nome correspondentes dos 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 em menos de 20 caracteres.
description InterfaceText null Um breve descrição do parâmetro, para usuários saberem quais querem pegar de uma lista de opções.
required booliano false Se o parâmetro é necessário para o modelo funcionar (verdadeiro se este parâmetro deve ser especificado).
suggested booliano false Se o parâmetro é sugerido para o modelo ser útil (verdadeiro se este parâmetro deve ser especificado).
deprecated booliano ou string false Se o parâmetro está obsoleto. O valor pode ser uma sequência de instruções dando ao usuário orientações sobre o que pode ser feito, ou simplesmente true.
aliases Matriz contendo cedeias [] Lista de apelidos. Um apelido é um nome alternativo para o parâmetro que pode ser usado ao invés do (não em adição ao) nome primário. Apelidos não são documentados em um objeto de Parâmetro separado. Se eles precisarem de mais informações, deverão estar em sua própria propriedade marcada como "obsoleta".
default InterfaceText null O valor predefinido usado pelo modelo se nenhum valor é atribuído ao parâmetro, ou uma descrição do mesmo.
autovalue string null Um valor dinamicamente-gerado no wikitexto, como a data de hoje ou o nome de usuário do editor; isto frequentemente envolve substituição de wikitexto, como {{subst:CURRENTYEAR}}.
example InterfaceText null Um texto de exemplo para o parâmetro, para ajudar usuários a preencher os valores adequados.
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
"number" Qualquer valor numérico (sem pontos decimais ou separadores de milhares)
"string" Qualquer valor textual. Pode conter quebra de linha.
"line" Espaço para 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.
"boolean" um valor booleano ('1' para $v, '0' para false, $vazio para desconhecido), veja lógica de três valores.
"date" Uma data em formato ISO 8601, por exemplo "2014-05-09" ou "2014-05-09T16:01:12Z"
"url" Uma URL, incluindo protocolo, por exemplo "http://www.example.org", "https://example.org", ou "//example.org".
"wiki-page-name" Um nome de uma página MediaWiki válido para a wiki atual. Não tem que existir, mas se não, deve ser um nome de página válido que possa ser criado.
"wiki-file-name" Um nome de arquivo MediaWiki válido para a wiki atual. Não tem que existir, mas se não, deve ser um nome de a 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").
"wiki-template-name" Um nome de Modelo MediaWiki válido para a wiki atual.
"wiki-user-name" Um nome de usuário MediaWiki válido para a wiki atual. Não tem que 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").
"content" Conteúdo da página em wikitexto, como estilo do texto, links, imagens, etc.
"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>}}
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.

Definir objeto

Chave Tipo Predefinição Descrição
Matriz de Matrizes [] O tipo do parâmetro, para dicas (leves) do tipo. Um de:
Definir Objeto

Chave

Objeto ou tipo primitivo

Descrição

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

Objeto de mapas

Chave Tipo Predefinição Descrição
nome do consumidor objeto {} An object that maps a name of a consumer to an object that in turn maps a name of a consumer parameter to one or more corresponding names of template parameters.

The names of the template parameters can be specified either as a string (one name), an array of strings (several names), or an array of arrays of strings (several sets of names); each of these strings must be a valid key in the params object elsewhere in the same template's TemplateData.

A specific template parameter may be in multiple maps, and it may be used in the values of multiple keys in a given map, but not every template parameter must be in a map.

A shortened example from English Wikipedia's Template:Cite_news#TemplateData illustrates the structure of a maps object.

{
	"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 or object)

A free-form plain-text string (i.e. no wikitext or HTML) in the content-language of the wiki, or an object containing those strings keyed by language code.

The default value for all InterfaceText fields is null.

Tipo de sttring

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:

Key Type Description
Wikipedia language code string Localized string for use on the Wikipedia corresponding to the given language code.

Example of object mapping:

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

Example

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:

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 paramOrder key and array using the order in which the parameters occur in the params key within the TemplateData Object on the template page.
    3. Add the sets key
    4. Change all TemplateText occurrences that are just strings to objects with a single key for the current wiki's Wikipedia language code
    5. 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.
    6. 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
Key Type Description
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
Key Type Description
(page number) 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.
Key Type Description
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.
paramOrder Array containing parameter name strings The logical order in which parameters should be displayed. The array contains each parameter key exactly once. Each string must be a valid key in the params object.
If this does not exist in the <templatedata></templatedata> structure on the template page, it is added to the structure as provided by the API using the order in which the parameters occur within the TemplateData object.
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
Key Type Description
label InterfaceText translated to InterfaceText object, if not already in that format.
required boolean If not defined, default value of false added.
description InterfaceText or 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
Description
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 use on the Wikipedia corresponding to the Wikipedia language code.

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