en.m.wikipedia.org
Wikipedia:TemplateData/Tutorial
< Wikipedia:TemplateData  (Redirected from Wikipedia:VisualEditor/TemplateData/Tutorial​)
Shortcuts
About
Help out
Research
Main research page
Other
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. It does not change anything about the actual template with which it appears, and nothing you can do with TemplateData will affect the functionality of or "break" any existing Wikipedia template (though mistakes that appear in the TemplateData might cause editors to use the associated template or its parameters incorrectly, so care is still needed). 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
See also: mw:Help:TemplateData and mw:Extension:TemplateData
TemplateData'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 <TemplateData> tags directly on the template page itself inside <noinclude>...</noinclude> 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 is incorrect code if used as it is and will therefore throw a JSON error if used; 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.
On English Wikipedia, you can also use the {{Format TemplateData}} template to generate a more "conventional" presentation of TemplateData suitable for use in Template documentation. Instead of the above, write this at the top of the documentation page:
{{Format TemplateData​|1​=​<​TemplateData​>​TemplateData goes here​<​/TemplateData​>​|TOC​=​1​}}
TemplateData
The TemplateData is added to the template page itself inside <noinclude></noinclude> 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 {{TemplateData header}} 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
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. Also, TemplateDate must be included in the template documentation page.
Completing the TemplateData information
Remember, TemplateData information is only information about how a template is meant to be used by editors. Nothing you do here will affect the corresponding template, though creating a TemplateData entry that contains informational errors may cause problems for editors trying to use that template in an article.
The first piece of information to fill out is a "description" 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: "description": "This template generates an information box for Croatian football players",). Note that any wikitext typed anywhere in the TemplateData table such as [[Croatian football]] will not retain any of its functions and will appear as plain unlinked text, character for character.
Next, you should create a "params" block, with braces ({ and }). 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.
String ValueType of Parameter
"unknown"Assumed type if not set
"number"Any numerical value (without decimal points or thousand separators)
"string"Any textual value. May contain line breaks.
"line"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.
"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>}}
"date"A date in ISO 8601 format, e.g. "2014-05-09" or "2014-05-09T16:01:12Z"
"inherits". 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 templatedata sub-block will cause the page to produce a Required property "params." not found. error and will fail to generate the expected table.
Where more than one parameter sub-blocks is passed to the template, you must add a comma after the close brace, },, 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, }.
A further option "format" determines how the wikitext code for the template will be formatted when it is saved by the VisualEditor. This can have the options "format": "inline" (the default) or "format": "block". With the inline option the wikitext of the template will be formatted as single line {{Sister project|project = commons|text = page in commons}} with the block option each parameter will take a single line
{{Infobox television | show_name = Father Ted | genre = Comedy }}
This option may be preferable for very complex templates like infoboxes which have multiple parameters. The documentation page indicated the format with the line "This template prefers inline formatting of parameters." or "This template prefers block formatting of parameters."
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:
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. [1] 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 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
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
ParameterDescriptionTypeStatus
Input1The string to be trimmed and countedStringrequired
Length2How many characters of the input should be returnedNumberrequired
Complete empty TemplateData block
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, "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>
Shared documentation
Many templates share the same documentation. Putting TemplateData on a subpage has the advantage that the documentation page is generally not protected so all editors can update the documentation. However, if the TemplateData 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 TemplateData in an individual subpage (​Template:col-begin/doc uses Template:Col-begin/TemplateData​) or in the template page itself (as in {{collapse top}}). An alternative technique is to use {{#switch: {{PAGENAME}} | ...}} in the document page with the different templatedata sections in each switch block.
Help
Should you run into errors, explain on the feedback page what you were trying to do, and we'll be happy to help.
Examples
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
ParameterDescriptionTypeStatus
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
ParameterDescriptionTypeStatus
texttext1quoteThe text to quoteStringoptional
signsign2citeThe person who quote it isStringoptional
sourcesource3A source for the quoteStringoptional
A template with default values {{col-6}}. Note default values are the values used by a template when the parameter is not specified. This example uses the "format": "block" option.
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 } }, "format": "block" } </templatedata>
Starts a new column, for use with {{col-begin}} when there are six columns.
Template parameters
This template prefers block formatting of parameters.
ParameterDescriptionTypeStatus
widthwidthw
Width of the column.
Default
16.66%
Stringoptional
alignalign
Horizontal alignment.
Default
left
Stringoptional
valignvalign
Vertical alignment.
Default
top
Stringoptional
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.
Template data was previously limited to 65,535 bytes (Phabricator: T53740). This limit could be exceeded for some templates which use many parameters, such as {{Infobox officeholder}}, but the code is now compressed, increasing the limit.
Tools
Editor for TemplateData
External links
MediaWiki has documentation related to: Extension:TemplateData#Defining a TemplateData block
Jsonlint a JSON validator to help spot errors in the template data syntax.
Last edited on 30 August 2021, at 06:23
Content is available under CC BY-SA 3.0 unless otherwise noted.
Privacy policy
Terms of Use
Desktop
HomeRandomNearbyLog inSettingsDonateAbout WikipediaDisclaimers
LanguageWatchEdit