Wikipedia:TemplateData/Tutorial

From Wikipedia, the free encyclopedia
Jump to: navigation, search
Shortcuts:

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[edit]

The structure of TemplateData[edit]

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 directly on the template page itself inside tags, or anywhere on the template's documentation sub-page if it has one, 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[edit]

The TemplateData is added to the template page itself inside 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 TemplateData can only be added to the /doc page; the link to that page is at the bottom of the main page.

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

Note: You should add {{TemplateDataHeader}} directly in front of the <templatedata> tag. This will categorize the page as TemplateData documentation and allow later organization of templates and their documentations.

Identifying the parameters[edit]

If the template has no parameters, you can complete its TemplateData block with a simple line of "params": {}. If you do not include this line, you will not be able to save the page. This completes the TemplateData 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 {{cite web}} template is passed values to complete a citation, such as url=, title=, accessdate=, etc. Other parameters may be used by their position instead. In this case, use numbers "1", "2", etc. instead of names for the parameters. The template documentation on the main or sub-page may summarize which parameters can be set on a template, and what each parameter must include.

Completing the TemplateData information[edit]

The first piece of information to fill out is a "description", which is fairly self-explanatory; it briefly describes what the template does and why the user should use it. You may use information that you glean from the top of the main or sub-page of the template, which is then put in double quotes (" "). Note that this cannot contain wikitext.

Then create a "params" block, with braces ({ and }). Inside this block, you need to create a block for each parameter used by the template, with some of the following information, Most of it is optional, but the more information you give the easier it is for you and others to re-use the template:

  • Enter the name of the parameter being used between double quotes, and create a block with some more braces ({ and }).
  • 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.
  • Enter the parameter's "description", of the specific parameter, not the template as a whole. This is also likely already written on the template's main or documentation page. Put the information in quotes.
  • You can optionally set a flag on the status of the parameter:
    • "required" says that filling out the parameter is mandatory for that template. Only set this to true if the value is required for the template, and not setting a value will break the template (like the URL for Cite web).
    • "suggested" says this parameter is one that most users of the template will want to fill in (like the source date for a citation). You should almost always have at least one suggested parameter on a template.
    • "deprecated" says this parameter isn't really used any more – as well as setting to "true", you can write a brief description about what users should do instead. Rare.
  • The "aliases" group lets you list other names for this parameter which work equally well e.g. "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.
  • The "autovalue" setting 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. Useful for cleanup templates to automatically set the date the user adds a template. For example, add "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}" as the autovalue to have "April 2015" automatically added (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 does not work for any templates that are used inside <ref> tags, gallery tags, or other extension-specific tags.
  • The "default" setting lets you show what the template will do if this parameter isn't set (or 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.
  • The "type", which controls how the template editor will interpret that parameter. This can be one of a few values:

String Value

Type of Parameter

"unknown" Assumed type if not set
"number" Any numerical value (without decimal points or thousand separators)
"string" Any textual value
"line" Short text field - use for names, labels, and other short-form fields
"wiki-page-name" 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.
"wiki-file-name" 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").
"wiki-user-name" 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").
"content" Page content in wikitext, such as text style, links, images, etc.
"unbalanced-wikitext" 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{{echo|before=<u>|after=</u>}}
  • "inherits" Key to another parameter. The current parameter will inherit from that one, with local properties overriding the inherited ones. Very rare.

Where there are more than one parameter passed to the template, add a comma after the close bracket, "},", between the params blocks.

Save[edit]

Once you're done, hit "save". If you've made errors, it will not let you save – which can be a little frustrating, but means you can't break anything. If you can't save, some common errors to look for include:

  • is every opening quote (") matched with a closing quote?
  • does a string, such as a description of a parameter, contain a (")? If so, replace it with a (').
  • is every opening bracket ({) matched with a closing bracket (})?
  • are there commas between params sections? (There should be one.)

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

Worked example[edit]

The {{Str left}} template is a simple template used like {{Str left|<string>|<count>}} 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 TemplateData for this template might be:

<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>

… which would display in the template like so:

Give the first few characters from the start of the input

Template parameters
Parameter Description Type Default Auto value Status
Input 1 The string to be trimmed and counted string empty empty required
Length 2 How many characters of the input should be returned number empty empty required

Complete empty TemplateData block[edit]

You can just copy and paste this to use when creating your own.

<templatedata>
{
	"description": "zzzzz",
	"params": {
		"first parameter": {
			"label": "x",
			"description": "xxx",
			"required": false,
			"suggested": false,
			"deprecated": false,
			"aliases": [],
			"autovalue": "auto value",
			"default": "default value",
			"type": "string",
			"inherits": ""
		},
		"second parameter": {
			"label": "y",
			"description": "yyy",
			"required": false,
			"suggested": false,
			"deprecated": false,
			"aliases": [],
			"autovalue": "auto value",
			"default": "default value",
			"type": "number",
			"inherits": ""
		}
	},
    "sets": { }
}
</templatedata>

Shared documentation[edit]

Many templates share the same documentation. For example {{multicol}}, {{multicol-break}} and {{multicol-end}} all use Template:Multicol/doc. If the TemplateData is included in the 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 TemplateData in an individual sub page, {{col-begin}} uses Template:Col-begin/TemplateData or in the template page itself as in {{top}}. An alternative technique is to use {{#switch: {{PAGENAME}} | ...}} in the document page with the different templatedata sections in each switch block. Template:Multicol/doc is an example of this. This has the advantage that the documentation page is generally not protected so all editors can update the documentation.

Help[edit]

Should you run into errors, explain on the feedback page what you were trying to do, and we'll be happy to help.

Examples[edit]

A template which takes no parameters: {{fixed}}. Note the params must be give as an empty list.

Markup Renders as
<templatedata>{
  "description": "Displays a tick mark and the word fixed. It takes no parameters.",
  "params": { }
}</templatedata>
 

Displays a tick mark and the word fixed. It takes no parameters.

Template parameters
Parameter Description Type Default Auto value Status
No parameters specified

A template with aliases {{quote}}:

Markup Renders as
<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> 

Adds a block quotation.

Template parameters
Parameter Description Type Default Auto value Status
text text1quote The text to quote string empty empty optional
sign sign2cite The person who quote it is string empty empty optional
source source3 A source for the quote string empty empty optional

A template with default values {{col-6}}. Note default values are the values used by a template when the parameter is not specified.

Markup Renders as
<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
        }
    }
}
</templatedata> 

Starts a new column, for use with {{col-begin}} when there are six columns.

Template parameters
Parameter Description Type Default Auto value Status
width widthw Width of the column. string 16.66% empty optional
align align Horizontal alignment. string left empty optional
valign valign Vertical alignment. string top empty optional

Limitations and questions[edit]

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.

Template data is limited to 65,535 bytes (bug 51740http://bugzilla.wikimedia.org/show_bug.cgi?id=51740). This limit can be exceeded for some templates which use many numbers parameters like {{Infobox officeholder}}.

Tools[edit]

Editor for TemplateData

External links[edit]

  • Jsonlint a JSON validator to help spot errors in the template data syntax.