Template:TemplateBox/doc

Warning: Do not edit. This page is maintained by an automated tool. All edits should be done at mediawiki.org. (translate this warning)

This subpage contains documentation, categories, or other content that is not part of the template.
To view the template page itself, see Template:TemplateBox.

---

Tracked in Phabricator
Task T54966
RESOLVED

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 xdescription documents 1description, 2description, 3description, etc.

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
xd xd-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-td xd-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
xlabel xlabel-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.[Please clarify – October 2024] 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
xdef xdef-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
xstat xstat-td xdeprecated xrequired	status (param)	Status of parameter x (1stat is the first parameter's status, 2stat the second's, etc); possible values: required optional optional- optional and not present in the standard form deprecated	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.[Please clarify – October 2024] Setting to export will turn TemplateBox into a preformatted Copy & Paste template. Setting to TNT or TNT:template name will cause TemplateData to be handled handled by Module:TNT.[Please clarify – October 2024]	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
desc desc-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. Despite this parameter's name, an alias's length can be equal to or higher than the canonical name's (for example, {{Semicolon}} is an alias of {{;}}). Aliases are listed on the documented template's page, in the Usage section (like this one), 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 the correct usage of the template; will be listed in the Usage-section under the code example and the shorthands, if given.	empty	optional
namespace	namespace	namespaces, the template is intended to be used in; possible values: all talks contents Main Talk User User talk Commons Commons talk File File talk MediaWiki MediaWiki talk Template Template talk Help Help talk Category Category talk Creator Creator talk Special Any other values will show as “unknown”.	no namespace specified	required
usergroup	usergroup	usergroup that is meant to use the template; possible values: all bot administrator admin sysop bureaucrat crat checkuser licensereviewer vrt autoconfirmed autopatrolled filemover oversight patroller rollbacker steward upwizcampeditors	no user group specified	required
placement	placement	placement on the page; possible values: top bottom licence source	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. If this parameter is set to anything more than a single (anonymous) value for the first unnamed parameter, it is currently needed to set example-value too (as {{TemplateBox}} does not call itself properly).	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. If example is set, and not just a single parameter value, it is currently required to set this parameter (as {{TemplateBox}} does not call itself properly). Not doing so causes unspecified behavior. If example is not set, this parameter is ignored.	{{TEMPLATENAME|<example>}}	optional
i18n-method	translation method	method the localization is achieved by. Known values: autotranslate using {{Autotranslate}} or applying a similar method switch using {{LangSwitch}} in the template itself - no localization needed custommediawiki-msg using MediaWiki namespace messages mediawiki-msg using MediaWiki namespace messages, translated on translatewiki.net ext.translate using {{Autotranslate}} or applying a similar method on a subpage that is marked for translation using the translate extension TNT Using Module:TNT and a tabular translations file on Wikimedia Commons.	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	print	The way the parameters are typically arranged in the Usage-section; possible values: one - parameters arranged in one line (default): |1def= |1stat= |useTemplateData= multi - parameters arranged in multiple lines: |1def = |1stat = |useTemplateData = infobox - multiple lines, the equals signs are aligned with each other: |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

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:

• Module:Languages
• Module:TemplateBox
• Module:TNTTools
• {{Documentation subpage}}

See also

• Commons:Template documentation
• Commons:TemplateData
• {{Documentation}}
• {{Doc-inline}}, {{doc-end}}

Localization

العربية ∙ Boarisch ∙ беларуская (тарашкевіца) ∙ বাংলা ∙ català ∙ čeština ∙ dansk ∙ Deutsch ∙ Deutsch (Sie-Form) ∙ Zazaki ∙ English ∙ español ∙ eesti ∙ euskara ∙ فارسی ∙ suomi ∙ français ∙ galego ∙ ગુજરાતી ∙ עברית ∙ हिन्दी ∙ hrvatski ∙ magyar ∙ Bahasa Indonesia ∙ italiano ∙ 日本語 ∙ 한국어 ∙ Lëtzebuergesch ∙ latviešu ∙ македонски ∙ മലയാളം ∙ मराठी ∙ Bahasa Melayu ∙ မြန်မာဘာသာ ∙ norsk bokmål ∙ Plattdüütsch ∙ Nederlands ∙ norsk nynorsk ∙ polski ∙ português ∙ português do Brasil ∙ русский ∙ sicilianu ∙ slovenčina ∙ slovenščina ∙ српски / srpski ∙ svenska ∙ ไทย ∙ Türkçe ∙ українська ∙ Tiếng Việt ∙ 中文 ∙ 中文（简体） ∙ 中文（繁體）

This template makes use of {{Autotranslate}} and the translate extension. The layout of the template can be found under Template:TemplateBox/layout.

Translate this template now!

 Administrate translations.

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

{{Commons:TemplateData}}

Disadvantage: section edition links

edit

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