Help:TemplateData/pt-br

 é uma extensão usada para armazenar informações sobre uma predefinição de wikitexto e seus parâmetros, de forma que o editor visual possa as recuperar e exibir esta informação em seu editor de predefinições, facilitando a edição de páginas que usam aquela predefinição.

Desde abril de 2019, TemplateData é parte da experiência padrão para todos os usuários em todas as wikis da Wikimedia, quando adicionam um modelo, incluindo usuários não registrados. Ambas os editores padrões visual e de código-fonte a incorporam de alguma maneira. Ela também é usada em outros lugares como em scripts, ferramentas e gadgets. Se você tem a sua própria wiki, terá de instalar a Extensão:Dados de Modelo.

Adicionando TemplateData a um modelo consiste essencialmente na inserção de um pequeno bloco de código JSON (explicado abaixo) na página de documentação do modelo. Há duas maneiras principais de fazer isso, tanto manualmente quanto usando o editor TemplateData, uma interface de usuário gráfico localizado nas páginas Editar/Editar código-fonte nas wikis com a extensão TemplateData instalada. JSON contém uma lista de parâmetros com informações sobre cada parâmetro do modelo bem como o modelo como um todo. Elas estão descritas abaixo.

Uma vez que um modelo tem TemplateData, esta informação irá mostrar na interface quando o usuário adicionar um modelo, às vezes no lugar da informação original e outras vezes como informação adicional. Em alguns casos, isso pode mudar como o editor comporta-se quando editando ou inserindo modelos. Isto pode facilitar muito para usuários identificarem o que precisam fazer no modelo ao adicioná-lo.

História
TemplateData foi originalmente desenvolvida no início de 2013 com em mente, que estava nos estágios de teste da MediaWiki na época. VisualEditor (trad.: Editor Visual) é a interface visual principal para wikis da Wikimedia, e TemplateData (Dados de Modelo) permitiu que uma interface mais útil surgisse ao adicionar modelos. Ela foi oficialmente apoiada pela VisualEditor imediatamente. Como a VisualEditor foi lançada para as várias wikis da Wikimedia como um recurso padrão de 2013 a 2016, TemplateData se tornou parte disso também.

Em março de 2018, Sam Wilson desenvolveu, uma extensão de edição de modelo GUI para o editor de código-fonte padrão da Wikimedia, (também conhecido como o editor de wikitexto de 2010), projetado para fazer o processo de adicionar modelos mais fácil a partir da utilização de informações da TemplateData. Em abril de 2019, TemplateWizard (trad.: Mago do Predefinição) foi feito parte padrão do editor de wikitexto de 2010 em todas as wikis da Wikimedia. Isto significa que a TemplateData era agora uma parte padrão de ambos os editores visuais e de código-fonte nas wikis da Wikimedia.

Editor TemplateData
O editor TemplateData é uma ferramenta incorporada na extensão TemplateData para adicionar e editar "Dados de Modelagem" usando uma interface gráfica para usuários.

Para acessar a ferramenta, vá em qualquer página de modelo (ou subpágina de documentação) e clique em Editar ou Editar código-fonte. Depois disso, você verá um botão acima da área de edição que diz "".



Clique nesse botão para entrar na interface gráfica de edição da TemplateData.

O editor permite-lhe adicionar parâmetros de predefinições e definir os atributos mais comuns. Se a página que você editou já contém um bloco de TemplateData, então a informação já documentada será mostrada automaticamente quando você abrir a página correta no editor de TemplateData. Na primeira caixa, pode adicionar ou atualizar uma breve descrição da predefinição em texto simples. Depois, você pode usar os botões Adicionar parâmetros sugeridos e Adicionar parâmetro para documentar os nomes e atributos dos parâmetros que a predefinição usa.

Você pode listar o nome do parâmetro, seus nomes alternativos, seu rótulo e a descrição que será exibida aos usuários. Você pode fornecer também um exemplo de como usar o parâmetro. O único campo obrigatório é Nome (o primeiro campo de cada linha), em que você pode guardar o nome exato do parâmetro, sensível a letras maiúsculas e minúsculas. No menu suspenso Tipo você poderá escolher o tipo de conteúdo que o parâmetro deverá receber, como uma string (para respostas em texto sem formatação), uma página (para ligações a outras páginas), ou datas. Caso a predefinição possa gerar um erro se o parâmetro for deixado em branco, marque como Obrigatório. Caso o parâmetro seja usado frequentemente ou seja recomendado, marque como Sugerido. O botão Remover informação do parâmetro deletará a entrada do parâmetro do TemplateData.



Quando você terminar com a documentação de cada parâmetro, clique em Aplicar para inserir o TemplateData pré-formatado dentro da caixa de edição aberta. Você deve ainda salvar a página, usando o botão Salvar abaixo da janela de edição.

Atenção: O editor do TemplateData posicionará o TemplateData ou na página da predefinição ou na subpágina da documentação. Você poderá determinar onde o TemplateData será adicionado abrindo (editando) a página em que você deseja posicioná-lo. Todavia, se múltiplos blocos de TemplateData são posicionados na mesma predefinição, então apenas um desses blocos será utilizado. Caso já haja TemplateData numa página, então você deverá editar a página em que o TemplateData foi anteriormente colocado para evitar a criação acidental de múltiplos blocos de TemplateData.

Localização do TemplateData
TemplateData deve estar na página que descreve, ou deve estar transcluído nela. Numa predefinição, deve normalmente estar envolvida em tags(etiquetas). Durante a composição gráfica normal da página, ela apresenta documentação gerada automaticamente, como é mostrado em #Exemplo.

Estrutura do TemplateData
A estrutura do TemplateData é baseada no padrão JSON. Note que todas as descrições no TemplateData devem estar em texto sem formatação (sem wikitexto, sem links, etc.).

A primeira coisa a fazer é digitar um par de tags, em qualquer lugar da subpágina de documentação da predefinição, assim:

Isso diz ao programa que tudo que está entre as duas tags é TemplateData, e deve ser usado como referência quando a predefinição for empregada.

Exemplo
A descrição dentro do TemplateData segue um layout padrão; vamos dizer que você tem um template chamado Commons para vincular a uma categoria do Commons sobre um tópico. É necessário um parâmetro obrigatório: o nome da categoria no Commons. The TemplateData ficaria assim:

Isto seria apresentado, na predefinição, assim:

{   "description": "Um modelo para vincular a uma categoria da commons sobre um artigo", "params": { "1": {           "label": "Categoria do Commons", "description": "A categoria da commons à qual você deseja vincular.", "default": "Category:CommonsRoot", "type": "string", "required": true }   } }

Parâmetro da TemplateData
Cada parâmetro pata a TemplateData está listada abaixo com uma descrição e um exemplo. Eles também estão listados em Extension:TemplateData#Format.

A prdem de parâmetros não afeta sua funcionalidade, contanto que aqueles dentro, por exemplo, the objeto  é mantido dentro do objeto.

Within the parameter's name
Note: if neither "required", "suggested" nor "deprecated" are set as true for a parameter, its status will show as "optional" in the TemplateData documentation.

Once you're done, hit "save". If you've made errors, it will not let you save (which is disruptive but means you can't break anything). Should you run into errors, explain on the feedback page what you were trying to do, and we will be happy to help.

Note that if you are abusing a hack template to dynamically generate TemplateData, it cannot be checked for errors before saving.

Note that each item of information is enclosed in quotation marks (except for  and  ) and separated from the next bit by a comma (unless it's the last one).

Effects of the type parameter
The  parameter can have multiple different effects or no effect depending on the value and depending on the template editor. Its effects are listed as follows.



The  value is intended for numerical values, including minus values and decimals.


 * In VisualEditor and the 2017 wikitext editor,  has no visible effect.
 * In the 2010 wikitext editor with TemplateWizard,,  causes the input box to display a "+" and "-" button on either side, which raise or lower a number value in the input box, respectively, and the user can only type numbers into the box. The buttons can also lower the number into negatives.



The  value is intended for any string of plain text.


 * In all main editors (VisualEditor, 2017 wikitext editor and the 2010 wikitext editor with TemplateWizard),  has no visible effect compared to.



The  value is intended for content that should be forced to stay on one line.


 * In VisualEditor and the 2017 wikitext editor,  prevents a parameter's input box from allowing new lines, which are usually possible in these editors.
 * In the 2010 wikitext editor with TemplateWizard,  has no visible effect (input boxes do not allow new lines by default in this editor).



The https:// value is intended for a URL, with Internet protocol (e.g., "https://") included.


 * In VisualEditor and the 2017 wikitext editor,  makes the input box display an external link icon (a square with arrow pointing out of it) in the left hand side of the box and makes the box glow red when the user clicks away without entering a URL value that includes a valid Internet protocol (e.g., "https://", "ftp://" or "//") followed by some text. This second effect is similar to that of the "required" setting, but it does not warn the user if they attempt to insert the template without a valid URL. It also occurs with any status setting (such as "suggested" or "deprecated").
 * In the 2010 wikitext editor with TemplateWizard,  has no visible effect.



The  value is intended for a page name on a wiki.


 * In all main editors (VisualEditor, 2017 wikitext editor and the 2010 wikitext editor with TemplateWizard),  makes the parameter input box show a suggestion dropdown menu containing a list of pages on the wiki, such as Wikipedia articles, which can be selected. Namespaces can also be defined in the search. Additionally, in VisualEditor and the 2017 wikitext editor, it forces the input box content to stay on one line. It has no other visible effect and doesn't prevent a non-page from being inputted.



The  value is intended for a file name hosted either locally on a wiki or on Wikimedia Commons.


 * In VisualEditor and the 2017 wikitext editor,  has no visible effect.
 * In the 2010 wikitext editor with TemplateWizard,  makes the parameter input box show a suggestion dropdown menu containing a list of files hosted both locally and on Wikimedia Commons, which can be selected. It also shows the thumbnail of the files. It has no other visible effect and doesn't prevent a non-file from being inputted.



The  value is intended for the name of a template.


 * In all main editors (VisualEditor, 2017 wikitext editor and the 2010 wikitext editor with TemplateWizard),  makes the parameter input box show a suggestion dropdown menu containing a list of templates, which can be selected. Additionally, in VisualEditor and the 2017 wikitext editor, it forces the input box content to stay on one line. It has no other visible effect and doesn't prevent a non-template from being inputted.



The  value is intended for a username on a wiki.


 * In all main editors (VisualEditor, 2017 wikitext editor and the 2010 wikitext editor with TemplateWizard),  makes the parameter input box show a suggestion dropdown menu containing a list of actual users' names, which can be selected. Additionally, in VisualEditor and the 2017 wikitext editor, it forces the input box content to stay on one line. It has no other visible effect and doesn't prevent a non-username from being inputted.



The  value is intended for wikitext of page content, for example, links, images or text formatting.


 * In VisualEditor and the 2017 wikitext editor,  has no visible effect.
 * In the 2010 wikitext editor with TemplateWizard,  makes the parameter input box one line taller and allows new lines, which regular input boxes in the 2010 wikitext editor do not.



The  value is intended for wikitext that cannot stand alone, i.e. it lacks an opening or closing tag or refers to other parts of wikitext.


 * In VisualEditor and the 2017 wikitext editor,  has no visible effect.
 * In the 2010 wikitext editor with TemplateWizard,  makes the parameter input box one line taller and allows new lines, which regular input boxes in the 2010 wikitext editor do not.

With other parameters


 * In VisualEditor and the 2017 wikitext editor,  overrides the visible effects of   - when both are set, the input box will not contain a URL icon nor glow red when the user clicks away without entering a valid URL.
 * In the 2010 wikitext editor with TemplateWizard,  overrides the effects of   - the value of "autovalue" will not be automatically placed in the input box if the parameter type is "number".

Formatos personalizados
When editing the  value, you create custom formats by inputting a set of wikitext symbols using some predefined rules.


 * - start of the template
 * - content (e.g., string, integer or parameter). This underscore serves to indicate the minimum length of a value in characters and can be repeated, like . If this length is not reached, it fills the remaining characters with spaces. This can be used to align all equals signs to a specific position after a parameter (if used with   for new lines).
 * - pipe (separates parameters)
 * - equals sign (precedes the value of a parameter)
 * or pressing the enter key - new line (this will display as  in the entry field)
 * - space (can be used with  to indent new lines)
 * - end of the template

The wikitext should at least meet the minimum of, otherwise there will be an invalid format string error.

Blank boilerplate
You can copy the blank boilerplate below to add new TemplateData to a template. Only the most common tags are included.

Syntax error in JSON / Bad JSON format
This error occurs if you attempt to save TemplateData that has certain types of invalid JSON code, such as duplicate keys (parameters) or trailing/missing commas, in VisualEditor or the 2017 wikitext editor (JavaScript-based editors).

"Syntax error in JSON" shows if you attempt to save such code in VisualEditor or the 2017 wikitext editor, while "Bad JSON format" shows if you attempt to open up such code in the TemplateData GUI editor, on template pages.

This error can come up quite frequently while editing a template's TemplateData. The most common mistakes that cause this error include excess commas (such as trailing commas), missing commas and missing quotation marks.


 * Examples of trailing commas:


 * Examples of missing commas:


 * Example of missing quotation marks:

To fix these errors, you can either look for the errors in the code yourself, or you can enter the JSON block into an external JSON validator, such as JSONLint, and it will highlight the problematic commas and keys that should be removed.

Due to a longstanding bug, users using the 2010 wikitext editor are able to save pages that have such invalid JSON (details: ), as the JavaScript parser is less strict and allows invalid JSON.

Required property "paramOrder(number)" not found.
This error occurs if you state a parameter in  that is not stated in  .The number in the square brackets refers to the parameter in   that is missing. It refers to its order in the sequence, but it is one less than its actual position, since  is an array; 0 is the first one, 1 is the second, etc.

To fix this, make sure all parameters stated in  are listed in  .Alternatively, you can remove the   object to remove this error.

Invalid value for property "paramOrder(number)".
This error occurs if you state a parameter in  that is not stated in  .The number in the square brackets refers to the parameter in   that shouldn't be there. It refers to its order in the sequence, but it is one less than its actual position, since  is an array; 0 is the first one, 1 is the second, etc.

To fix this, make sure all parameters stated in  are listed in  .Alternatively, you can remove the   object to remove this error.

Property "params.parametername.required" is expected to be of type "boolean".
This error occurs if you put quotation marks around the value of either  or.

These are boolean values, not strings, therefore they require no quotation marks. To fix this, remove any quotation marks around the values  or   for these parameters.

Property "format" is expected to be ...
If the  parameter exists but its value is not ,   or a valid format string, you will see the error message "Property "format" is expected to be "inline", "block", or a valid format string."

To fix this, make sure the value after  equals   or   and that there no spelling mistakes. Alternatively, if it's wikitext, make sure it contains a minimum of  and that there are no mistakes in the syntax that would normally cause a template to fail, such as duplicate equals signs or missing/duplicate curly brackets; see the section #Custom formats for the syntax for custom formats.Alternatively, you can remove the   parameter to remove this error.

Unexpected property "parametername".
This error occurs if you state a parameter in any object that is not a parameter of that object. This may be due to spelling mistakes, or you may have written the parameter of one object under another object that it doesn't belong to.

For example, you might have written the parameter  under the root TemplateData object instead of inside  :

Alternatively, if the unexpected parameter is under a template parameter inside, you'll see its name after "params.parametername." in the error.

To fix this, make sure your parameters are in their correct location, and make sure there aren't any spelling mistakes in the parameter names. Additionally, make sure you don't state any parameters that don't exist for an object. You can check which parameters exist for an object on this page, in the section.

Required property "params" not found.
This error occurs if there is no  object in the TemplateData.This is a necessary object, as it contains all the details of each parameter, so to fix this error, make sure it's added and that there are no spelling mistakes. See the section above on how to add the  parameter.

Limitações e questões

 * Funcionalidades ausentes — O TemplateData é um exemplo de ferramenta que foi disponibilizada com algumas funcionalidades, na esperança que usuários possam ajudar a guiar o desenvolvimento de funcionalidades desejadas por eles. Caso você queira requisitar novas funções para TemplateData, por favor avise-nos.
 * Demora para aparecer nas predefinições — Após adicionar TemplateData a uma predefinição, os metadados deverão ser visíveis imediatamente quando ela for aberta no Editor Visual. No entanto, é possível que levem horas para aparecerem. Você poderá forçar uma atualização fazendo uma edição vazia na própria página da predefinição (e não na subpágina da sua documentação). Para fazer uma edição vazia, abra a página de edição da predefinição, e salve-a sem fazer quaisquer mudanças.
 * Problemas atuais — Uma lista de bugs atuais e pedidos para funcionalidades está disponível no rastreador de bugs da Wikimedia.

Outras ferramentas

 * : A toolbar dialog window for entering template wikitext via an form built from TemplateData.
 * TemplateData Wizard: A tool that generates TemplateData through an interactive interface.
 * Skeleton TemplateData generator: A tool that reads the source wikicode of a template, tries to find all the parameters used and outputs a skeleton document with the parameters listed.
 * JSONLint: Uma ferramenta que permite validar o JSON escrito manualmente para ajudar a localizar erros na sintaxe.
 * List of all templates with TemplateData on this wiki
 * With dewiki template TemplateData template data is shown in a box, and the template is added to a category of templates with template data