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 (or inside <noinclude></noinclude> tags directly on the template page itself if it does not have a /doc subpage), like so:

<TemplateData>
TemplateData goes here
</TemplateData>

N.B. The preceding will throw a JSON error if used alone; see #Completing the TemplateData information below for more information.

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 (inside <noinclude></noinclude> tags), or the /doc documentation page. 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.

The TemplateData is placed 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.

If the template does not use names for its parameters but recognises them by their position, use numbers "1", "2" etc instead of names for the parameters.

Completing the TemplateData information

The first tag is a "description", which is fairly self-explanatory; it describes what the template does. You may use information that you glean from the top of the main or subpage of the template, which is then put in quotes {" "}.

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 "string"
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 "Alpha-numeric text".
- 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". It indicates if it's a number or a string.
- "default" contains the default value of this parameter (in quotes). The information can be skipped, if the parameter has no default value as in this example.
- "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.
- "aliases" (optional) List of aliases eg "aliases": [ "2", "Caption", "imagecaption" ]. An alias is an alternative name for the parameter that may be used instead of (not in addition to) the primary name. Aliases are not documented in a separate parameter object. If they need more information, they should be in their own property marked "deprecated".
- "deprecated" (optional) Tooltip for the user detailing the intent for the deprecated parameters, a boolean or string value.
- "inherits" (optional) Key to another parameter. The current parameter will inherit from that one, with local properties overriding the inherited ones.
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": {
  "string": {
    "label": "Alpha-numeric text",
    "description": "The string to be trimmed and counted",
    "type": "string",
    "default": "",
    "required": true
  },
  "count": {
    "label": "Quantity",
    "description": "Gives the <count> substring of characters from the start of the trimmed string",
    "type": "number",
    "default": "",
    "required": true
  }
}}</templatedata>

Minimal skeleton elements

This does not throw a JSON error.

<templatedata>{
  "description": "insert description here",
  "params": {
    "first parameter": {
      "label": "x",
      "description": "x",
      "type": "string",
      "default": "default value",
      "required": false
    }
  }
}</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 common things to look for are making sure that you have matched sets of quotes {""}, matched brackets ({}), and commas between multiple params sections. It may take up to 24 hours or more after saving for the TemplateData to be integrated into VisualEditor.

This would display in the template like so:

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

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

Perform a NULL edit on the template

Once saved it is advisable to perform a WP:NULL edit on the main template (not the documentation page). This is necessary to update the database so the information can be used in the VisualEditor. As many templates are protected you may need to request a null edit using {{editprotected}} or by leaving a note on this talkpage.

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.

Tools

Editor for TemplateData

TemplateDataEditor A user script that makes the process of adding TemplateData easier.
Yet another template data editor Template:Lang icon