- Main page
- Feedback at MediaWiki
- Sandbox (no account required)
- Documentation:
- Development:
- Roadmap up to 2017
- Updates (2013-2023)
- Weekly status reports (2015-2016)
- 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 are provided between < >, (e.g., in "{{Str left|<string>|<count>}}", it's string and count.) Parameters may be passed by equal signs. For instance, the {{cite web}} template is passed values to complete a citation, such as url=, title=, accessdate=, etc. The template documentation on the main or subpage may summarize what parameters must or may be set for the template.
Completing the TemplateData information
The first tag is a "description", which is fairly self-explanatory; it describes what the template does. 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, the Template:Str left ({{Str left|<string>|<count>}}), 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 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. In this case, it is "Quantity".
- Enter the "description", this time a description of the parameter, not of the template as a whole. This is also likely on the main or subpage. Put the information in quotes.
- The "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".indicates if it's a number or a string.
- "Required" controls whether filling out the parameter is mandatory for that template. 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 give 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>
Save
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. Some commons things to look for are matched sets of quotes {""}, matched brackets ({}), and comma between multiple params sections.
This would display in the template like so:
A template to give the <count> substring of characters from the start of the trimmed string
| 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 |
Help
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.