Wikipedia:TemplateData/Tutorial

Main page
Feedback at MediaWiki
Sandbox (no account required)

About

Documentation:
Development:
- Roadmap up to 2017
- Updates (2013-2023)
- Weekly status reports (2015-2016)

Help out

Research

Main research page

Other

Why are the developers building this? (2013)
- User Test Data (2013)
Customization
Known problems
Requests for Comments (RfCs): Jul 2013 a, Jul 2013 b, Jul 2015, Sep 2015

As explained here, TemplateData is a way of storing information about a template - such as parameter names, or a description of the template - so that the VisualEditor can retrieve it and populate the template editor with it. TemplateData is controlled by MediaWiki's 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 TemplateData

The structure of TemplateData

TemplateData's structure is based around the "JSON" standard, and is fairly simple. The first thing to do is to type out a pair of <templatedata> tags, anywhere on the template's /doc subpage, like so:

<templatedata>
TemplateData goes here
</templatedata>

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

Templatedata

The templatedata is added to either the template itself, or the /doc documentation page - anywhere that is transcluded into the template will do. In some cases, the main template page will be locked to prevent editing by unauthorized users. In that situation, the templatedata may be added to the /doc page. The link to that page is at the bottom of the main page.

Although it may go anywhere on the template pages, some editors enter the data after the descriptive information about the template and before the "See also" section.

Identifying the parameters

Many templates have parameters, such as dates, urls, article names, numbers or strings.

Determine what parameters are or may be used in the template. In some cases, it's values within < >, (e.g., in "{{Str left|<string>|<count>}}", it's string and count.) It could also be parameters passed with equal signs. For instance, the {{cite web... template is passed values to complete a citation, such as url=, title=, accessdate=, etc. The template documentation may summarize what parameters are or may be set for the template.

Completing the templatedata information

The first value in the templatedata section is the description. Use information that you glean from the top of the main or subpage for the template to describe how the template is used and put that information in quotes {" "}.

Then, for each parameter used by the template, complete the following "params" information:

Enter the parameter being used. For example, per the Template:Str left information, {{Str left|<string>|<count>}}, the template has two parameters: string and count.
Enter the "params" value. In this example, the first parameter entered was "count"
Then add the information about each parameter. The label is the descriptive information for the value that should be entered for the value, capitalizing the first character of the label (since it will be the leftmost value in the resulting table). In this case, it is Quantity. Next, enter the description, which is also likely on the main or subpage. The type indicates if it's a number or a string. For required, enter "true" if the value is required for the template and "false" if it is not required. In this case, both count and sub_string are required values.
Where there are more than one parameter passed to the template, add a comma after the close bracket, "}," between the parms values.

<templatedata>
{
        "description": "A template to gives the <count> substring of characters from the start of the trimmed string ",
        "params": {
                "count": {
                        "label": "Quantity",
                        "description": "Gives the <count> substring of characters from the start of the trimmed string",
                        "type": "number",
                        "required": true
                },
                "string": {
                        "label": "Alpha-numeric text",
                        "description": "The string to be trimmed and counted",
                        "type": "string",
                        "required": true
                }
        }
}
</templatedata>

This would display in the template like so:

A template to gives the <count> substring of characters from the start of the trimmed string

Template parameters[Edit template data]
Parameter		Description	Type	Status
Quantity	`count`	Gives the <count> substring of characters from the start of the trimmed string	Number	required
Alpha-numeric text	`string`	The string to be trimmed and counted	String	required

What it all means

So let's break that down. The first tag is a "description", which is fairly self-explanatory; it describes what the template does. There is then a "params" tag, which indicates that subsequent sections cover each parameter in the template.

Within each subsection, the first tag is the name of the template parameter within the template - if the parameter is simply called "1", this tag would be "1". Next we have "label", in which you put a human-readable title for the parameter that will be displayed within the template editor. We then have "description" - this time a description of the parameter, not of the template as a whole. After that we have "type", which controls how the template editor will interpret that parameter. This can be "string" (a set of characters, like this sentence!), "number" (a set of digits), "string/wiki-user-name" or "string/wiki-page-name". We then have "required", which can be set to either true or false; this simply controls whether filling out the parameter is mandatory for that template.

If you have multiple parameters, just repeat each section (starting from the "Category" tag) and fill it out as you see fit. Once you're done, hit "save". If you've made errors, it will not let you save - which we appreciate 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'll be happy to help.

Limitations and questions

TemplateData 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 TemplateData is created before it appears in the VisualEditor.