Wikipedia:TemplateData/Tutorial: Difference between revisions

Revision as of 17:49, 9 June 2023

Latest revision as of 03:32, 20 April 2025

(11 intermediate revisions by 8 users not shown)

Line 44:

===Completing the template data information===

Remember, template data information is onlyboth information ''about'' how a template is meant to be used by editors., and programming code that tells the VisualEditor how to help editors add a template to a page. Nothing you do here will affect the corresponding template, though creating a template data 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 <code>"description"</code> 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: <code>"description": "This template generates an information box for Croatian football players",</code>). Note that any wikitext typed anywhere in the template data table such as <code><nowiki>[[Croatian football]]</nowiki></code> will not retain any of its functions and will appear as plain unlinked text, character for character.

Line 51:

:* Create or use the short arbitrary <code>"name"</code> for the parameter that will be read by the Wikipedia template software. If you use or the template has a parameter name containing more than one word, these must always be separated by an underscore: <code>_</code> like this: <code>ocean_size</code> (i.e., parameter names do not contain spaces). Place it between double quotes, follow it with a colon, and create a block with some more single braces <code>{</code> and <code>}</code> like this: <code>"ocean_size": { }</code> or <code>"range_map": { }</code>. Note that many templates like {{tl|Infobox Fabergé egg}} have a variable which is itself called "name", and therefore the JSON code for this parameter would be written <code>"name": { }</code>. The following code now goes within these braces, separated by a comma at the end of each but none after the last, and with no additional braces (Note that the order of these entries is irrelevant: they will be ordered in a consistent pattern when the JSON template data code is read):

:** The <code>"'''label'''"</code> entry 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, like this: <code>"Ocean size":</code>.

:** Enter the parameter's <code>"'''description'''"</code> (i.e., a description of the specific parameter, not the template as a whole). This may already have been written on the template's main or documentation page, and can be copied and pasted into place. Put this information in quotes. If you wish your description to also display a word or phrase in quotes, you must [[Escape character|escape]] the quotation marks by putting a backslash <code>\</code> directly ''before'' them like this: <code>"This parameter indicates the \"size\" of the ocean"</code>. If you do not provide the backslash directly before the quotation mark, the JSON software will interpret the mark as the end of the parameter block— the backslash tells JSON, "Don't count the quotation mark directly following me— render it as a visible quotation mark and look for the end-of-parameter quotation mark further on". If the word you wish to display in quotes is at the very end of your parameter description, you will just need to type <code>\""</code> like this: <code>"This parameter indicateindicates the ocean \"size\""</code> You may include any other punctuation (comma, semicolon, colon, brace, bracket, double bracket, etc.) between the two quotation marks as you like. Note, however, that should you need an actual backslash <code>\</code> as part of the text, you will have to escape that too with another backslash, like this: <code>\\</code>.

:** You can optionally set a flag on the status of the parameter:

:*** <code>"'''required'''"</code> says that filling out the parameter is mandatory for that template. Only set this to <code>true</code> if the value is required for the template, and not setting a value will break the template (like the URL for [[Template:Cite web|Cite web]]). Entries for this flag must be either the word <code>true</code> or <code>false</code>, with no quotation marks.

Line 101:

<nowiki> </nowiki>Where more than one parameter sub-blocks is passed to the template, you must add a comma after the close brace, <code>},</code>, 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, <code>}</code>.

A further option, <code>"format"</code>, determines how the wikitext code for the template will be formatted when it is saved by the VisualEditor. ThisThe canprimary haveoptions the optionsare <code>"format": "inline"</code> (the default) orand <code>"format": "block"</code>. With the inline option, the wikitext of the template will be formatted as single -line <code><nowiki>{{Sister project|project = commons|text = page in commons}}</nowiki></code> and with the block option, each parameter will takebe placed on a singlenew line

<syntaxhighlight lang="wikitext">

<pre>{{Infobox television

| show_namename = Father Ted

| genre = Comedy

}}</pre>

</syntaxhighlight>

This option may be preferable for very complex templates like infoboxes which have multiple parameters. The documentation page indicated the format with the line {{small|"This template prefers inline formatting of parameters."}} or {{small|"This template prefers block formatting of parameters."}}

For more complex parameter formatting options, see [[:mw:Help:TemplateData#Custom_formats]].

==== Save ====

Line 162 ⟶ 166:

}

</templatedata>

Note: As explained above, the TemplateData block does not affect how the template works, but it does affect editors' use of the template in the VisualEditor. In the {{tl|Str left}} example above, parameter {{para|2}} is listed as "required", which means that the VisualEditor will require entry of a value, even though the template's actual code does not require parameter {{para|2}} to be present in transclusions of the template. This difference can be confusing to editors.

=== Complete empty template data block ===

Line 171 ⟶ 177:

"description": "zzzzz",

"params": {

"first parameterfirst_parameter": {

"label": "x",

"description": "xxx",

Line 183 ⟶ 189:

"type": "string"

},

"second parametersecond_parameter": {

"label": "y",

"description": "yyy",

Line 393 ⟶ 399:

* {{tl|Format TemplateData}} (which uses [[Module:Format TemplateData]]) help format the appearance of template data sections on documentation pages.

* [[:ru:Модуль:TemplateDataDoc]] allows to create blank copy and usage example from template data. The module is in Russian.

== External links ==

{{MediaWiki|Extension:TemplateData#Defining a TemplateData block}}

*[http://jsonlint.com/ Jsonlint] a JSON validator to help spot errors in the template data syntax.

*[https://json-validate.com/ Json Validate] – A tool for not just identifying errors and validating JSON data but also converting it into different formats, ensuring data integrity.

[[Category:TemplateData]]