MediaWiki

Extensão:TemplateData

This page is a translated version of the page Extension:TemplateData and the translation is 60% complete.
Outdated translations are marked like this.
Languages:
Esta extensão acompanha o MediaWiki 1.35 e superiores. 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 guardar, recuperar e visualizar a informação 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.42
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 262 (Ranked 25th)
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 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/.
    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.

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
  1. Para aqueles itens que possuem uma lista específica de valores possíveis (por exemplo, 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 $3, 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 Special:MyLanguage/Help:TemplateData#Template data editor method.

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 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 possivelmente até nos resultados de pesquisa quando os usuários escolhem um dentre muitos. A predefinição é null.

→ For more details see: description

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.

→ For more details see: params

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.

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

→ For more details see: label

description InterfaceText null Um breve descrição do parâmetro, para usuários saberem quais querem pegar de uma lista de opções.

→ For more details see: description

required booliano false Se o parâmetro é necessário para o modelo funcionar (verdadeiro se este parâmetro deve ser especificado).

→ For more details see: required

suggested booliano false Se o parâmetro é sugerido para o modelo ser ú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 sequência de instruções dando ao usuário orientações sobre o que pode ser feito, ou simplesmente true.

→ For more details see: deprecated

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

→ For more details see: aliases

default InterfaceText null O valor predefinido usado pelo modelo se nenhum valor é atribuído ao parâmetro, ou uma descrição do mesmo.

→ For more details see: default

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

→ For more details see: autovalue

example InterfaceText null Um texto de exemplo para o parâmetro, para ajudar usuários a preencher os valores adequados.

→ 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 milhares)

→ For more details see: value ‘number’

"string" Qualquer valor textual. Pode conter quebra de linha.

→ For more details see: value ‘string’

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

→ For more details see: value ‘line’

"boolean" um valor booleano ('1' para $v, '0' para false, $vazio para desconhecido), veja lógica de três valores.

→ For more details see: value ‘boolean’

"date" Uma data em 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 tem que existir, mas se não, 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 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").

→ 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 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").

→ 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 Array containing strings [] An optional parameter property. Creates a list of parameter values to help users select the desired value. For the suggested values to be displayed as a combo box in VisualEditor, the parameter’s type must be set to one of the following: content, line, string, number, unknown or unbalanced wikitext.

→ For more details see: suggestedvalues

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

Maps is a single data structure that goes multiple levels deep. It became common to call the second level a “map object”.

Chave Tipo Predefinição Descrição
nome do 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.

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 map objects. 

{
	"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:

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=6382612"