View source for Wikipedia:TemplateData/Tutorial

{{short description|Wikimedia project gadget tutorial}}
{{shortcut|WP:TDATA/T|WP:VE/TDT}}
{{VisualEditor navbox}}
[[Wikipedia:VisualEditor/TemplateData|Template data]] is a way of storing information about a template—such as parameter names, or a description of the template—so that the [[Wikipedia:VisualEditor|VisualEditor]] can retrieve it and populate the template editor with it.  It does ''not'' change anything about the actual ''template'' with which it appears, and nothing you can do with template data will affect the functionality of or "break" any existing Wikipedia template (though mistakes that appear in the template data might cause editors to use the associated template or its parameters incorrectly, so care is still needed). Template data is controlled by MediaWiki's [[mw:Extension:TemplateData|TemplateData extension]], which allows users to write small bits of structured data to a template page, or to be transcluded into that template page (such as on the standard documentation page). Once a template has this structured data, it can be displayed properly in the VisualEditor. While this may sound complex, it's actually very easy.

== How to use template data ==
===The structure of template data ===
{{see also|mw:Help:TemplateData|mw:Extension:TemplateData}}
Template data's central structure is encoded in [[JSON]] format, and the schema is fairly simple. The first thing to do is to type out a pair of <code><nowiki><templatedata></nowiki></code> tags directly on the template page itself inside {{tag|noinclude}} tags, or anywhere on the template's documentation sub-page if it has one, like so:

<syntaxhighlight lang="xml">
<templatedata>
TemplateData goes here
</templatedata>
</syntaxhighlight>

<small>N.B. The preceding is incorrect code if used as it is and will therefore throw a JSON error if used; see [[#Completing the template data information]] below for more information.</small>

This tells the software that everything between the two tags is template data, and should be referenced when the template is used. The template data itself follows a standard layout that identifies the parameters that may be set within the template.

On English Wikipedia, you can also use the {{tl|Format TemplateData}} template to generate a more "conventional" presentation of template data suitable for use in [[Wikipedia:Template documentation|Template documentation]]. Instead of the above, write this at the top of the documentation page:
<syntaxhighlight lang="xml">
{{Format TemplateData
|1=<templatedata>
TemplateData goes here
</templatedata>
|TOC=1
}}
</syntaxhighlight>

===Template data===
The template data is added to the template page itself inside <code><nowiki><noinclude></noinclude></nowiki></code> tags, or anywhere on the template's documentation page if it has one. In some cases, the main template page will be locked to prevent editing by unauthorized users. In that situation, the template data can only be added to the /doc page; the link to that page is at the bottom of the main page.

The template data is generally placed after the descriptive information about the template, and before the "See also" section.

'''Note''': You should add <nowiki>{{</nowiki>[[Template:TemplateData header|TemplateData header]]<nowiki>}}</nowiki> directly in front of the <code><nowiki><templatedata></nowiki></code> tag. This will categorize the page as template data documentation and allow later organization of templates and their documentations.

===Identifying the parameters===
If the template has no parameters, you can complete its template data block with a simple line of<code> "params": {}</code>. If you do not include this line, you will not be able to save the page. This completes the template data for the template. 

However, most templates have parameters, such as dates, URLs, article names, images, numbers or strings. Determine which parameters are or may be used in the template. Parameters may be passed by equal signs. For instance, the <code><nowiki>{{cite web}}</nowiki></code> template is passed values to complete a citation, such as <code>url=</code>, <code>title=</code>, <code>access-date=</code>, ''etc.'' Other parameters may be used by their position instead. In this case, use numbers "<code>1</code>", "<code>2</code>", ''etc.'' instead of names for the parameters. 

The [[Wikipedia:Template documentation|template documentation]] on the main or sub-page may summarize which parameters can be set on a template, and what each parameter must include. Also, template data must be included in the template documentation page.

===Completing the template data information===
Remember, template data information is both information ''about'' how a template is meant to be used by editors, and programming code that tells the VisualEditor how to help editors add a template to a page. Nothing you do here will affect the corresponding template, though creating a template data entry that contains errors may cause problems for editors trying to use that template in an article.

The first piece of information to fill out is a <code>"description"</code> for the overall template, which is fairly self-explanatory; it briefly describes what the template does and explains where and how the user might want to use it. If the template was created and given some kind of description by someone before you, you may use information that you glean from the top of the main or sub-page of the template, which you can copy and paste here.  Place it within quotes and follow it with a comma: <code>"description": "This template generates an information box for Croatian football players",</code>). Note that any wikitext typed anywhere in the template data table such as <code><nowiki>[[Croatian football]]</nowiki></code> will not retain any of its functions and will appear as plain unlinked text, character for character.

Next, you should create a <code>"params"</code> block, with braces (<code>{</code> and <code>}</code>). Inside this block, you need to create a sub-block for each parameter used by the template, with some of the following entries. Most of it is optional, but the more information you give the easier it will be for others to re-use the template.  
:* Create or use the short arbitrary <code>"name"</code> for the parameter that will be read by the Wikipedia template software.  If you use or the template has a parameter name containing more than one word, these must always be separated by an underscore: <code>_</code> like this: <code>ocean_size</code> (i.e., parameter names do not contain spaces).   Place it between double quotes, follow it with a colon, and create a block with some more single braces <code>{</code> and <code>}</code> like this: <code>"ocean_size": { }</code> or <code>"range_map": { }</code>.  Note that many templates like {{tl|Infobox Fabergé egg}} have a variable which is itself called "name", and therefore the JSON code for this parameter would be written <code>"name": { }</code>.  The following code now goes within these braces, separated by a comma at the end of each but none after the last, and with no additional braces (Note that the order of these entries is irrelevant: they will be ordered in a consistent pattern when the JSON template data code is read):
:** The <code>"'''label'''"</code> entry is a human-readable title for the parameter that will be displayed within the template editor. Capitalize the first character of the label (since it will be the leftmost value in the resulting table), and put it in quotes, like this: <code>"Ocean size":</code>.
:** Enter the parameter's <code>"'''description'''"</code> (i.e., a description of the specific parameter, not the template as a whole). This may already have been written on the template's main or documentation page, and can be copied and pasted into place. Put this information in quotes.  If you wish your description to also display a word or phrase in quotes, you must [[Escape character|escape]] the quotation marks by putting a backslash <code>\</code> directly ''before'' them like this: <code>"This parameter indicates the \"size\" of the ocean"</code>.  If you do not provide the backslash directly before the quotation mark, the JSON software will interpret the mark as the end of the parameter block— the backslash tells JSON, "Don't count the quotation mark directly following me— render it as a visible quotation mark and look for the end-of-parameter quotation mark further on".  If the word you wish to display in quotes is at the very end of your parameter description, you will just need to type <code>\""</code> like this: <code>"This parameter indicates the ocean \"size\""</code>  You may include any other punctuation (comma, semicolon, colon, brace, bracket, double bracket, etc.) between the two quotation marks as you like. Note, however, that should you need an actual backslash <code>\</code> as part of the text, you will have to escape that too with another backslash, like this: <code>\\</code>.
:**  You can optionally set a flag on the status of the parameter:
:*** <code>"'''required'''"</code> says that filling out the parameter is mandatory for that template. Only set this to <code>true</code> if the value is required for the template, and not setting a value will break the template (like the URL for [[Template:Cite web|Cite web]]).  Entries for this flag must be either the word <code>true</code> or <code>false</code>, with no quotation marks.
:*** <code>"'''suggested'''"</code> says this is one variable that most users of the template will probably want to fill in (like the source date for a citation). <mark>You should almost always have at least one suggested parameter on a template.</mark>  Like <code>required</code>, use either the word <code>true</code> or <code>false</code>, with no quotation marks.
:*** <code>"'''deprecated'''"</code> can be set to flag whether or not this parameter is in regular use – as well as setting to <code>true</code>, you can write a brief description about what users should do instead. Rare.
:**  The <code>"'''aliases'''"</code> group lets you list other names for this parameter which have been set to work equally well, and its entry is enclosed by a single bracket, i.e., <code>"aliases": [ "2", "Caption", "imagecaption" ]</code>.  An alias is an alternative name for the parameter that the template is willing to accept instead of (not in addition to) the primary name. Aliases are not documented in a separate parameter object.
:* The <code>"'''autovalue'''"</code> entry lets you tell VisualEditor and other tools to pre-fill this parameter with a standard value (in wikitext); this text will show up in the parameter box when users edit, and will be added to the template invocation when saved. This may be useful for cleanup templates to automatically set the date the user adds a template.  For example, add <code><nowiki>"autovalue": "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}"</nowiki></code> as the autovalue to have the relevant date, "{{CURRENTMONTHNAME}} {{CURRENTYEAR}}" automatically added when an editor uses the template([https://en.wikipedia.org/w/index.php?title=Template:Citation_needed/doc&diff=631687918&oldid=628385301 example edit]).  Autovalues may be changed by the editor simply by removing the supplied value in the template dialog.  Note that this subst-based method [[bugzilla:2700|does '''not''' work]] for any templates that are used inside <nowiki><ref></nowiki> tags, gallery tags, or other extension-specific tags.  Whether or not set by the person creating the template data code, this entry, whatever it is, will appear as an entry in the resulting template data table; if not created manually, it will be followed by the word "Empty".
:* The <code>"'''default'''"</code> setting lets you show what the template will do if this parameter is not set (or is set but left blank); this text will show up as light gray text in the parameter box when users edit, but will not add the value to the template invocation when saved unless the user manually overrides it. Rare. This entry will always appear in the resulting template data table, and if not manually created by the person writing the template data code, will be followed by the word "Empty".
:* The <code>"'''example'''"</code> entry allows you to display an example of an entry that a person might make for this variable, written exactly as a person might type it, character-for-character; if the type of entry has already been set with the  <code>"'''type'''"</code> parameter (see below), then the example should reflect this (i.e., if the type has been set to "wiki-page-name" then your example should ''not'' include a prefix like "File:" or "Image:").  Be sure to enclose the entire text of the example with quotes. Obviously, this means the actual example may not contain quotation marks itself.  If not created by the person writing the template data code, will be followed by the word "Empty".
:* The <code>"'''type'''"</code>, which controls how the template editor will interpret that parameter. This can be one of a few values, any of which used must be enclosed in double quotation marks:
{| class="wikitable"
!
String Value
!
Type of Parameter
|-
|<code>"unknown"</code>
|Assumed type if not set
|-
|<code>"number"</code>
|Any numerical value (without decimal points or thousand separators)
|-
|<code>"string"</code>
|Any textual value. May contain line breaks.
|-
|<code>"line"</code>
|Short text field – use for names, labels, and other short-form fields. This is supposed to be text that is not expected to contain line breaks.
|-
|<code>"wiki-page-name"</code>
|A valid MediaWiki page name for the current wiki. Doesn't have to exist, but if not, should be a valid page name which could be created.
|-
|<code>"wiki-file-name"</code>
|A valid MediaWiki file name for the current wiki. Doesn't have to exist, but if not, should be a valid file name which could be uploaded. Should not include the namespace (e.g. "Foo.svg" not "File:Foo.svg" or "Bild:Foo.svg").
|-
|<code>"wiki-user-name"</code>
|A valid MediaWiki user name for the current wiki. Doesn't have to exist, but if not, should be a valid user name which could be created. Should not include the namespace (e.g. "Foo" not "User:Foo" or "Usario:Foo").
|-
|<code>"content"</code>
|Page content in wikitext, such as text style, links, images, ''etc.''
|-
|<code>"unbalanced-wikitext"</code>
|Raw wikitext that should not be treated as standalone content because it is unbalanced – for example, templates concatenating incomplete wikitext as a bigger whole, such as<code><nowiki>{{echo|before=<u>|after=</u>}}</nowiki></code>
|-
|<code>"date"</code>
|A date in [[ISO 8601]] format, e.g. "2014-05-09" or "2014-05-09T16:01:12Z"
|}
:* The  <code>"'''suggestedvalues'''"</code> parameter property lets you define a list of parameter values to be shown to VisualEditor users for easy selection. Once the values have been added to TemplateData, the VisualEditor will display them in a combo box (a dropdown into which users can also enter a custom value). The user selects the desired value by clicking on it. For the suggested values to be displayed in the VisualEditor, the parameter’s type must be one of the following: content, line, string, number, unknown or unbalanced wikitext. Adding this parameter property can be done either in JSON or using the TemplateData Editor with no coding required. [[m:WMDE_Technical_Wishes/Suggested_values_for_template_parameters#TemplateData|Both methods are explained here.]]
:* <code>"inherits"</code>.  This is a key to another parameter. The current parameter will inherit from that one, with local properties overriding the inherited ones. Very rare. '''Currently, the inclusion of this parameter in a <code><nowiki><templatedata></nowiki></code> sub-block will cause the page to produce a ''Required property "params." not found.'' error and will fail to generate the expected table.'''
<nowiki>  </nowiki>Where more than one parameter sub-blocks is passed to the template, you must add a comma after the close brace, <code>},</code>, between the sub-blocks.  Do not place a comma after the last sub-block in your set, but do make sure that there is a final close brace, <code>}</code>.

A further option, <code>"format"</code>, determines how the wikitext code for the template will be formatted when it is saved by the VisualEditor. The primary options are <code>"format": "inline"</code> (the default) and  <code>"format": "block"</code>. With the inline option, the wikitext of the template will be formatted as single-line <code><nowiki>{{Sister project|project = commons|text = page in commons}}</nowiki></code> and with the block option, each parameter will be placed on a new line
<syntaxhighlight lang="wikitext">
{{Infobox television
| name  = Father Ted
| genre = Comedy
}}
</syntaxhighlight>
This option may be preferable for very complex templates like infoboxes which have multiple parameters. The documentation page indicated the format with the line {{small|"This template prefers inline formatting of parameters."}} or {{small|"This template prefers block formatting of parameters."}}

For more complex parameter formatting options, see [[:mw:Help:TemplateData#Custom_formats]]. 

==== Save ====
Once you're done, hit "save". If you've made errors, it will not let you save – which can be a little frustrating, as the resulting error message will not tell you where JSON encountered the first code error, but means you cannot "break" anything or put up a table that is accidentally malformed. If you find you are unable to save because of a code error, some common problems to look for include:
* Is every opening quote (<code>"</code>) matched with a closing quote in the correct place of the code?
* Does a string, such as a description of a parameter, contain a <code>"</code> that is not at the end of the entry? If so, consider replacing it with a <code>'</code>.
* Is every opening brace(<code>{</code>) matched with a closing brace(<code>}</code>) in the correct place?
* Are there commas between params blocks? (There should be one).

Manually searching through the program for these errors can be tiresome and difficult.  Fortunately, a number of program checking websites for JSON exist which will at least identify the line on which the program first encounters an error.  [http://jsonlint.com/] is one of these which seems to work quite well.  Simply copy and paste the problematic JSON code into the corresponding box on the website and ask it to check the code— it will not itemize every error in the document, but it ''will'' indicate the ''first'' error it encounters, if any, which should be immensely helpful in correcting your code.

Once you successfully save the page, it may take a few minutes after saving for the template data to be integrated into VisualEditor. If it doesn't come through after a few minutes, you can make a [[WP:null|null]] edit on the main template to fix this. As many templates are protected, you may need to request a null edit using {{tl|editprotected}} or leaving a note on [[Wikipedia talk:VisualEditor/TemplateData tutorial]].

=== Worked example ===
The {{tl|Str left}} template is a simple template used like <code><nowiki>{{Str left|<string>|<count>}}</nowiki></code> to show the first few characters of an input. It has two parameters, neither of which are named (they are only recognised by their position in the template), and both of which are required. Thus the template data for this template might be:
<syntaxhighlight lang="javascript">
<templatedata>
{
	"description": "Give the first few characters from the start of the input",
	"params": {
		"1": {
			"label": "Input",
			"description": "The string to be trimmed and counted",
			"required": true,
			"type": "string"
		},
		"2": {
			"label": "Length",
			"description": "How many characters of the input should be returned",
			"required": true,
			"type": "number"
		}
	}
}
</templatedata>
</syntaxhighlight>
... which would display in the template like so:
<templatedata>
{
	"description": "Give the first few characters from the start of the input",
	"params": {
		"1": {
			"label": "Input",
			"description": "The string to be trimmed and counted",
			"required": true,
			"type": "string"
		},
		"2": {
			"label": "Length",
			"description": "How many characters of the input should be returned",
			"required": true,
			"type": "number"
		}
	}
}
</templatedata>

Note: As explained above, the TemplateData block does not affect how the template works, but it does affect editors' use of the template in the VisualEditor. In the {{tl|Str left}} example above, parameter {{para|2}} is listed as "required", which means that the VisualEditor will require entry of a value, even though the template's actual code does not require parameter {{para|2}} to be present in transclusions of the template. This difference can be confusing to editors.

=== Complete empty template data block ===
You can just copy and paste this to use when creating your own.

<syntaxhighlight lang="javascript">
<templatedata>
{
	"description": "zzzzz",
	"params": {
		"first_parameter": {
			"label": "x",
			"description": "xxx",
			"required": false,
			"suggested": false,
			"example":"x",
			"deprecated": false,
			"aliases": [],
			"autovalue": "auto value",
			"default": "default value",
			"type": "string"
		},
		"second_parameter": {
			"label": "y",
			"description": "yyy",
			"required": false,
			"suggested": false,
			"example": "x",
			"deprecated": false,
			"aliases": [],
			"autovalue": "auto value",
			"default": "default value",
			"type": "number"
		}
	},
    "sets": { }
}
</templatedata>
</syntaxhighlight><!------------
Let's say that you have a template called "Commons" for linking to a commons category about an article. It has one parameter, and that is the name of the commons category. The TemplateData would look something like:

<pre>
<templatedata>
{
        "description": "A template for linking to a commons category about an article",
        "params": {
                "1": {
                        "label": "Commons category",
                        "description": "The commons category you want to link to.",
                        "type": "string",
                        "required": true
                     }
                }
}
</templatedata>
</pre>
This would display, in the template, like so:
<templatedata>
{
        "description": "A template for linking to a commons category about an article",
        "params": {
                "Category": {
                        "label": "Commons category",
                        "description": "The commons category you want to link to.",
                        "type": "string",
                        "required": true
                }
        }
}
</templatedata>
------>

===Shared documentation===
Many templates share the same documentation. Putting template data on a subpage has the advantage that the documentation page is generally not protected so all editors can update the documentation. However, if the template data is included in a shared documentation page then this will cause some of the templates to pick up the wrong template data section. 

This can be resolved by putting the template data in an individual subpage ([[Template:col-begin/doc]] uses [[Template:Col-begin/TemplateData]]) or in the template page itself (as in {{tl|collapse top}}). An alternative technique is to use [[Wikipedia:Switch|<code><nowiki>{{#switch: {{PAGENAME}} | ...}}</nowiki></code>]] in the document page with the different <code><nowiki><templatedata></nowiki></code> sections in each switch block.

===Help===
Should you run into errors, explain on the [[Wikipedia:VisualEditor/Feedback|feedback page]] what you were trying to do, and we'll be happy to help.

== Examples ==
A template which takes no parameters: {{tl|fixed}}. Note the params must be given as an empty list.
{{markup |
<nowiki>
<templatedata>{
  "description": "Displays a tick mark and the word fixed. It takes no parameters.",
  "params": { }
}</templatedata>
</nowiki>
|
<templatedata>{
  "description": "Displays a tick mark and the word fixed. It takes no parameters.",
  "params": { }
}</templatedata>
}}

A template with aliases {{tl|quote}}:
{{markup|
<nowiki>
<templatedata>{
  "description": "Adds a block quotation.",
  "params": {
    "text": {
      "label": "text",
      "description": "The text to quote",
      "type": "string",
      "required": false,
      "aliases": [ "1", "quote" ]
    },
    "sign": {
      "label": "sign",
      "description": "The person who quote it is",
      "type": "string",
      "required": false,
      "aliases": [ "2", "cite" ]
    },
    "source": {
      "label": "source",
      "description": "A source for the quote",
      "type": "string",
      "required": false,
      "aliases": [ "3" ]
    }
  }
}</templatedata></nowiki>
|
<templatedata>{
  "description": "Adds a block quotation.",
  "params": {
    "text": {
      "label": "text",
      "description": "The text to quote",
      "type": "string",
      "required": false,
      "aliases": [ "1", "quote" ]
    },
    "sign": {
      "label": "sign",
      "description": "The person who quote it is",
      "type": "string",
      "required": false,
      "aliases": [ "2", "cite" ]
    },
    "source": {
      "label": "source",
      "description": "A source for the quote",
      "type": "string",
      "required": false,
      "aliases": [ "3" ]
    }
  }
}</templatedata>
}}

A template with default values {{tl|col-6}}. Note default values are the values used by a template when the parameter is not specified. This example uses the <code>"format": "block"</code> option.
{{markup|
<nowiki><templatedata>
{
    "description": "Starts a new column, for use with {{col-begin}} when there are six columns.",
    "params": {
        "width": {
            "label": "width",
            "description": "Width of the column.",
            "type": "string",
            "default": "16.66%",
            "aliases": ["w"],
            "required": false
        },
        "align": {
            "label": "align",
            "description": "Horizontal alignment.",
            "type": "string",
            "default": "left",
            "required": false
        },
        "valign": {
            "label": "valign",
            "description": "Vertical alignment.",
            "default": "top",
            "type": "string",
            "required": false
        }
    },
    "format": "block"
}
</templatedata></nowiki>
|
<templatedata>
{
    "description": "Starts a new column, for use with {{col-begin}} when there are six columns.",
    "params": {
        "width": {
            "label": "width",
            "description": "Width of the column.",
            "type": "string",
            "default": "16.66%",
            "aliases": ["w"],
            "required": false
        },
        "align": {
            "label": "align",
            "description": "Horizontal alignment.",
            "type": "string",
            "default": "left",
            "required": false
        },
        "valign": {
            "label": "valign",
            "description": "Vertical alignment.",
            "default": "top",
            "type": "string",
            "required": false
        }
    },
    "format": "block"
}
</templatedata>
}}

== Limitations and questions ==
Template data is great for editing existing templates, but does not currently automatically pull in parameters when you create a new template. The ability to have it do that is being worked on now. There is some delay between the implementation and it showing up in existing templates – which makes debugging slightly difficult. There is also a slight delay after template data is created before it appears in the VisualEditor.

Template data was previously limited to 65,535 bytes (Phabricator: <s>{{phab|53740}}</s>). This limit could be exceeded for some templates which use many parameters, such as {{tl|Infobox officeholder}}, but the code is now compressed, increasing the limit.

== Tools ==
[[File:TemplateDataEditor.png|thumb|Editor for [[:en:Wikipedia:VisualEditor/TemplateData|template data]]]]
* [[User:NicoV/TemplateDataEditor|TemplateDataEditor]] A user script that makes the process of adding template data easier.
* [http://tools.wikimedia.pl/~mlazowik/templatedata/?lang=en Yet another template data editor]
* [[User:Salix alba/TDSkell|TemplateData Skeleton]] — Read the source of a template and tries to find all the parameters used and output a skeleton document with all the parameters listed. Javascript toolbox popup.
* [[Module:TemplateDataGenerator‎]] – Skeleton generator as a template to subst.
* {{tl|Format TemplateData}} (which uses [[Module:Format TemplateData]]) help format the appearance of template data sections on documentation pages.
* [[:ru:Модуль:TemplateDataDoc]] allows to create blank copy and usage example from template data. The module is in Russian.


== External links ==
{{MediaWiki|Extension:TemplateData#Defining a TemplateData block}}
*[http://jsonlint.com/ Jsonlint] a JSON validator to help spot errors in the template data syntax.
*[https://json-validate.com/ Json Validate] – A tool for not just identifying errors and validating JSON data but also converting it into different formats, ensuring data integrity. 

[[Category:TemplateData]]
[[Category:Wikipedia template help]]