Template:TemplateBox
 Warning: | This page is shared between multiple wikis. All changes to this page will be automatically copied to all wikis listed in the left side bar. To avoid unnecessary page regeneration and server load, changes should be tested on the page's sandbox. |
 | Uses Lua: |
 | This template uses TemplateStyles: |
This template ({{TemplateBox}}) eases documentation of (other) templates. Using it helps uniformizing template documentation pages. See: Commons:Template documentation and Commons:TemplateData.
Usage
{{TemplateBox
|x =
|xd =
|xlabel =
|xaliases =
|xtype =
|1set =
|xdef =
|xav =
|xsv =
|xstat =
|useTemplateData =
|name =
|desc =
|shorthand =
|usage-notes =
|namespace =
|usergroup =
|placement =
|type =
|example =
|example-value =
|i18n-method =
|i18n-desc =
|i18n-mediawiki-msg =
|i18n-subpage =
|i18n-data-file =
|seealso =
|setscats =
|print =
|relieson =
|mustbesubst =
|docsub-page =
}}
Usage notes: For a code template (for copy-pasting) with short parameter descriptions, see section Template to create a new template documentation page
 | This template ({{TemplateBox}}) allows to document different templates. To avoid confusion, when reading the following documentation, it is necessary to distinguish this template and its (meta-)parameters from the templates it documents and their parameters.
This template is designed to document templates which support a fixed number of parameters. The Template parameters section is not designed to document those supporting an unlimited number of arguments, such as this one ({{TemplateBox}}) and {{Tle}}. The following table uses the variable x to reflect that templates can have any number of parameters. For example, the row about If there are no meta-parameters (parameters to {{TemplateBox}} beginning with a number), the usage notes of the template's documentation will state "The template takes no parameters." The following table does not represent parameter localization accurately. For example, the undocumented 1description-fr meta-parameter allows describing the documented template's first parameter in French. The 1description meta-parameter's row approximately documents 1description-fr and equivalent meta-parameters for other languages. The -langcode tag in the table below highlights the meta-parameters which have such undocumented equivalents. |
Template parameters
| Parameter | Description | Default | Status | |||
|---|---|---|---|---|---|---|
x | name (param) | Name of the documented template's xth parameter (1 names the first parameter, 2 the second, etc) | empty | optional | ||
xdxd-en xdescription xdescription-en | description (param) | Description of parameter x (1d describes the documented template's first parameter, 2d the second, etc) -langcode (→ see also on mediawiki: overview or details) | empty | optional | ||
xd-tdxd-td-en xdescription-td xdescription-td-en | TemplateData description (param) | Description of parameter x for Extension:TemplateData which does not accept Wiki-markup. If this parameter is omitted, xd is used. You can always override the defaults specifically for TemplateData by appending -td to the parameter-name. You can specify a language by appending your language-code. E.g. 3d-td-en would be the English translation of the description of parameter 3 which will be used in TemplateData. -langcode. 1d-td describes the documented template's first parameter, 2d-td the second, etc) | empty | optional | ||
xlabelxlabel-en xlabel-td xlabel-td-en | label (param) | A (very) brief name for parameter x. Try to keep under 20-ish characters. For example, 1label-de would be the German label of the documented template's first parameter. -langcode (→ see also on mediawiki: overview or details) | empty | optional | ||
xaliases | aliases (param) | An alias is an alternative name for the parameter that may be used instead of (not in addition to) the primary name. Name the aliases and separate them by "/"; e.g.d/desc/description. (→ see also on mediawiki: overview or details) | empty | optional | ||
xtype | type (param) | The type of the parameter, for (soft) type hinting. Please refer to the list of possible values. (→ see also on mediawiki: overview or details) | empty | optional | ||
1set | set (param) | Label and ID of a set in one.[clarification needed] Multiple parameters can be grouped in a set, if either none or all of them must be supplied. Try to keep under 20-ish characters. (→ see also on mediawiki: overview) | empty | optional | ||
xdefxdef-td xdefault | default (param) | Fixed default value for parameter x (1def is the value for the first parameter, 2def the value for the second, etc) -langcode (→ see also on mediawiki: overview or details) | empty | optional | ||
xav | autovalue (param) | Dynamically-generated default value in wikitext, such as today's date or the editing user's name; this will often involve wikitext substitution, such as {{subst:CURRENTYEAR}}. (→ see also on mediawiki: overview or details) | not specified | optional | ||
xsv | suggested (param) | Suggested values, separated by "/" (→ see also on mediawiki: overview or details) | not specified | optional | ||
xstatxstat-td xdeprecated xrequired | status (param) | Status of parameter x (1stat is the first parameter's status, 2stat the second's, etc); possible values:
| optional | optional | ||
useTemplateData | expose TemplateData | Whether the template should expose TemplateData - omitting means "false". Setting to 1, true, or yes means "true". Setting to only will suppress the house-made table.[clarification needed] Setting to export will turn TemplateBox into a preformatted Copy & Paste template. [clarification needed] | empty | suggested | ||
name | title (template) | name of the template (needed for viewing the documentation on another page than the template page, in particular for viewing the documentation page separately) | {{BASEPAGENAME}} | required | ||
descdesc-en description description-en desc-td description-td | description (template) | description of what the template does -langcode | empty | required | ||
shorthand | aliases | Aliases to ease invocation, separated by commas. Each alias must have a page which redirects to the template page. For example, if {{Catseealso}} and {{Csa}} are aliases for {{Cat see also}}, Template:Catseealso and Template:Csa are redirects to Template:Cat see also.
Aliases are listed on the documented template's page, in the Usage section (like the one on this page), directly under the synopsis (and above the Usage notes if there are some). See examples of lists of redirects here and with an additional searches-for-more-redirects here. | empty | optional | ||
usage-notes | usage notes | Notes about usage of the template which will be displayed in the Usage section (like the one in this page) under the invocation template (and any aliases) | empty | optional | ||
namespace | namespace | namespaces, the template is intended to be used in; possible values:
| no namespace specified | required | ||
usergroup | usergroup | usergroup that is meant to use the template; possible values:
| no user group specified | required | ||
placement | placement | placement on the page; possible values:
| empty | optional | ||
type | type (template) | what type is the template (infobox, formatting, licence tag, …) | empty | optional | ||
example | example call parameters | Example invocation (set of parameter values). A possible value (e.g. for {{Cat see also}}) can be: lakes. Multiple parameters can be separated with the {{!}} magic word; for example, 1=lakes{{!}}for=for more information sets 2 parameters (for the same template).There is also example2 for a second example.
| empty | optional | ||
example-value | example call result | Result of the invocation of the template with the values set in the example parameter. This parameter's value is almost always set by invoking the documented template with the values defined in example. In the example above, the value of example-value would be defined using {{ Cat see also | lakes }}; with two parameters it will be {{Cat see also|lakes|for=for more information}}. The documented template's page will show the result in a box separated from the example code by a "renders as:" line. See {{Own using}} for an example of a template which uses this parameter.There is also example2-value for a second example.
| {{TEMPLATENAME|<example>}} | optional | ||
i18n-method | translation method | method the localization is achieved by. Known values:
| empty | optional | ||
i18n-desc | translation info | additional info about the localization | empty | optional | ||
i18n-mediawiki-msg | mediawiki-message | When using “mediawiki-msg” as method, optionally put the name of the message here. Falls back to: | empty | optional | ||
i18n-subpage | translation subpage | When using “ext.translate” as method, optionally put the name of the sub-page here. A dot (.) means that the current template hosts the translation on its subpages directly. | i18n | optional | ||
i18n-data-file | I18n Data File | The tabular data file on Wikimedia Commons in the Data namespace. The I18n/ prefix and the .tab file extension are added automatically if its missing. | I18n/{{{name}}}.tab | optional | ||
seealso | see also | List of relevant links (each on a new code line; e.g. * [[Commons:TemplateData]]) | empty | optional | ||
setscats | categorizes into | List of categories which are automatically set by the template (each on a new code line; e.g. * [[:Category:Rivers]]) | empty | optional | ||
print | The way the parameters are typically arranged in the Usage-section; possible values:
|1def= |1stat= |useTemplateData=
|1def = |1stat = |useTemplateData =
|1def = |1stat = |useTemplateData = | one (if type parameter ≠ infoboxthis dependency is not working, everytime "one" by default) | optional | |||
lines | Deprecated! Use parameter print instead. | empty | deprecated | |||
relieson | relies on | List of templates on which the template's basic functionality relies (each on a new code line; e.g. * [[Module:TemplateBox]]) | empty | optional | ||
mustbesubst | must be subst | Set to yes (or any value) if the template must be substituted. This puts "subst:" into the template example under Usage-section. | empty | optional | ||
docsub-page | docsub-page | page parameter from {{Documentation subpage}} | {{NAMESPACE}}:{{BASEPAGENAME}} | optional | ||
|
<templatedata>JSON</templatedata> ./. {{TemplateBox}}
TemplateData is a way to store information about template parameters (the description of those and of the whole template) for both humans and machines. It is used by VisualEditor and possibly other tools like Upload Wizard. Existing template documentation Newly created template documentation and imports Wikipedia's help about TemplateData • Commons-specific information This template (<span style="white-space:nowrap;">{{TemplateBox}}</span>) eases documentation of (other) templates. Using it helps uniformizing template documentation pages. See: [[Commons:Template documentation]] and [[Commons:TemplateData]].
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Additional information
The template is intended to be used in the following namespaces: the Template namespace
The template is intended to be used by the following user groups: all users
Placement:
in the '/doc' subpage of a template
Relies on:
See also
Localization
This template makes use of {{Autotranslate}} and the translate extension. The layout of the template can be found under Template:TemplateBox/layout.
| This section is about localization of {{TemplateBox}}. Localizing the documentation of (other) templates is somewhat covered in the Template parameters section above and the TemplateData section below. |
Template to create a new template documentation page
The following code template contains brief descriptions for each parameter as well as space for categories and can be copy-pasted in new documentation pages. The meta-parameters are not internationalized (names have no language code).
{{TemplateBox
<!-- TEMPLATE PARAMETERS SECTION (for 2nd parameter, copy, paste & change "1" → "2") -->
|1 = <!-- 1st parameter: name of the first parameter the template takes-->
|1label = <!-- 1st parameter: label, very brief name, preferably less than 20 characters -->
|1d = <!-- 1st parameter: description (+LANGUAGE CODE) -->
|1d-td = <!-- 1st parameter: description for TemplateData without any wiki markup (+LANGUAGE CODE) -->
|1aliases = <!-- 1st parameter: alternative names that may be used, separated by "/" -->
|1type = <!-- 1st parameter: type (values: number, string, line, boolean, date, url, wiki-page-name, unknown/…) -->
|1set = <!-- 1st parameter: set ID / Label (to group multiple parameters in a set) -->
|1def = <!-- 1st parameter: fixed default value (+LANGUAGE CODE) -->
|1av = <!-- 1st parameter: autovalue, dynamically-generated default value, e.g. current year -->
|1sv = <!-- 1st parameter: suggested values to help users select the desired value, separated by "/" -->
|1stat = <!-- 1st parameter: status (values: required, optional, optional- or deprecated) -->
<!-- TEMPLATE SECTION -->
|useTemplateData = <!-- expose TemplateData (values: true, export; default: false) -->
|name = <!-- template title -->
|desc = <!-- template description (+LANGUAGE CODE) -->
|namespace = <!-- namespaces, the template is intended to be used (values: all, File, Category…) -->
|usergroup = <!-- usergroup that is meant to use the template (values: all, admin…) -->
|placement = <!-- placement on the page (values: top, bottom, licence or source) -->
|usage-notes = <!-- notes about the correct usage of the template -->
|type = <!-- template type (values: infobox, formatting, licence tag,…) -->
|example = <!-- example parameter values -->
|example-value = <!-- example invocation of the template with the values of the example parameter -->
|i18n-method = <!-- translation method (values: mediawiki-msg, ext.translate, autotranslate…) -->
|i18n-desc = <!-- translation info -->
|i18n-mediawiki-msg = <!-- name of the message when using “mediawiki-msg” as method -->
|i18n-subpage = <!-- translation subpage when using "ext.translate" as method -->
|i18n-data-file = <!-- tabular data file on Wikimedia Commons in the Data namespace -->
|seealso = <!-- relevant links (each of them on a new code line with * in the beginning) -->
|setscats = <!-- categories which are automatically set by the template -->
|print = <!-- template code layout in the Usage-section (values: one, multi, infobox) -->
|shorthand = <!-- redirects to the main template -->
|relieson = <!-- list of templates on which the template's basic functionality relies -->
|mustbesubst = <!-- set to yes (or any value) if the template must be substituted. -->
|docsub-page = <!-- page parameter from {{Documentation subpage}} -->
}}<includeonly>{{Sandbox other||
<!-- Categories below this line; interwikis at Wikidata -->
}}</includeonly>
TemplateData
{{TemplateBox}} supports every feature that is documented in TemplateData's technical documentation except inherits. Conversion to JSON is done by a Lua module. The Lua module automatically converts traditionally used parameters as well as the new ones to both, TemplateData, as well as the "historic table", on demand. The "historic table" is the table which was used to show parameter information at Wikimedia Commons before TemplateData's advent.[clarification needed]
- Required parameters
|desc=(or in its translated form), parameters and their description
- Translation
Avoid {{LangSwitch}} in TemplateData, which doesn't support it. Instead, append -langcode to the name of any translatable parameter, marked by -langcode in TemplateBox. For example, to describe the first parameter in French, write |1d-fr=Description pour le premier paramètre. Supplying only |1d-en=This is the description of parameter 1. instead of |1d=This is the description of parameter 1. will also work, but the -en is recommended because it clarifies for translators (they recognize the structure behind it without having to consult the documentation).
The language code must be the last element. Valid: |1d-td-en=. Invalid: |1d-en-td=
- Naming
- Both old names and new names are supported but treated differently if both of them are supplied. For example, while creating the "historic table", if both
1defand1defaultwere supplied, the value for1defwould be used. For generating TemplateData, the preference is the other way around.
- Overriding
- It's possible to override a specific entity, either for the "historic table" or for TemplateData.
- To override for TemplateData, append a
-tdto the parameter's default name. - On the other hand, if you coded something for TemplateData and want to use a link or other markup in the "historic table", use the parameter name without the
-tdor modify that, which should be only used for TemplateData appending-td.
- To override for TemplateData, append a
- Pay attention
- TemplateData does not parse Wiki-Markup. Think of it as if it would expand all templates and finally putting a nowiki around all this.
- When including templates, they must be wrapped in
<nowiki>tags, if they should not be expanded (it's, on the other hand, a geeky feature that you can use, if having the expanded content inside TemplateData is exactly what you want). - Even though some tags such as
<pre>seem to be rendered as expected, avoid them.
- Activation
- TemplateData can be activated setting the
useTemplateDataparameter to1or toonly. The former will add a collapsed version of the table; the latter replaces the "historic table" with the TemplateData table. In both cases, TemplateData is available through the API.
- Fetching TemplateData (e.g. for TemplateBox itself)
/w/api.php?action=templatedata&format=json&titles=Template%3ATemplateBox (raw result, pretty result)
- Advantages
- No type-mixture: Instead of inserting a new content-type, a template can be used.
- Syntax: Less error-prone compared to editing JSON (without a special editor).
- Schema: Always valid. TemplateBox always passes a structure matching the requested schema.
- Flat structure.
- Prepared for future changes. Adjustments to the LUA module can be made to support future changes. The power of control remains at Commons.
- Inserting redundant information can be avoided.
- Template traditionally used at Commons.
- Issues
- Grouping sets is currently not supported in the "historic table". Set labels are not supported to be multilingual (ideas how one could achieve this are truly welcome).
- Example
{{TemplateBox
| useTemplateData = 1
| 1 = artist
| 1aliases = Artist
| 1label-en = Artist
| 1type = string
<!-- used as the parameter description in the main parameter area of the documentation -->
<!-- and in the template data section unless overridden with 1d-td-langcode -->
| 1d-de = Künstler, der das ursprüngliche Kunstwerk geschaffen hat.<br/>Benutze möglichst immer {{Creator:Vorname Nachname}} mit der Vorlage {{Tl|Creator}}.
| 1d-en = Artist who created the original artwork.<br/>Use {{Creator:Name Surname}} with {{Tl|Creator}} template whenever possible.
| 1d-fr = Artiste ou artisan à l'origine de l'œuvre.<br/>Dans la mesure du possible, utiliser le modèle {{Tl|Creator}}.
| 1d-sv = Artist som skapade originalverket.<br/>Använd {{Creator:Förnamn Efternamn}} med {{Tl|Creator}}-mallen om detta är möjligt.
<!-- this overrides 1d-en in the Template data section -->
<!-- and all other translations unless each is provided as desc-td-langcode -->
| 1d-td-en = Artist who created the original artwork; this overrides "1d-en" in the Template data section; "1d-en" is used in the template "Parameter" section.
| 1def-de = Freifeld, angezeigt als: "{{int:wm-license-information-author}}".
| 1def-en = blank field presented as: "{{int:wm-license-information-author}}".
| 1def-fr = champ vide: « {{int:wm-license-information-author}} »
| 1def-sv = tomt fält, visas som: "{{int:wm-license-information-author}}"
<!-- used as the description of the template in the main documentation area -->
<!-- and in the Template data section unless overridden with desc-td-langcode -->
| desc-de = Deutsche Übersetzung der {{tl|Vorlagen}}beschreibung
| desc-en = English translation of the {{tl|template}} description
<!-- this overrides desc-en in the Template data section -->
<!-- and all other translations unless each is provided as desc-td-langcode -->
| desc-td-en = English translation that is used in the Template data section instead of "desc-en". This will also replace all desc-langcode translations, unless corresponding "desc-td-langcode" is provided.
}}
A live example is Template:Information/doc (edit that enabled TemplateData through TemplateBox, API-result showing the JSON generated by the Lua Module behind TemplateBox)
- Experimenting
You can use Special:ExpandTemplates to experiment with how the template will output the template documentation and the Template data section; e.g., copy the example above and paste it into the input text on the Special:ExpandTemplates page; then click on the ok button to see the result.
Disadvantage: section edition links
One issue caused by usage of this template is the loss of section editing links on the whole page of the documented template, and also on its documentation page, even for paragraphs outside the part produced by this template (TemplateBox).
This can be worked around by manually invoking {{Sed}} in each section to create an edit link anyway, but this technique is fragile since the first argument for {{Sed}} can change when the section structure changes, which quietly breaks such links. The link in this very section was broken for years, pointing to the wrong section, until the value was updated ({{Sed|1}} → {{Sed|3}}). Moreover, {{Sed}} wastes vertical space (standing on its own line).