Help:Template: Difference between revisions

Revision as of 22:35, 7 November 2024

Latest revision as of 13:30, 30 August 2025

(30 intermediate revisions by 19 users not shown)

Line 1:

{{shortShort description|Main technical help page on templates}}

{{Redirect-multi|2|H:T|Wikipedia:Template|help regarding tables|Help:Table|content guidelines|Wikipedia:Template namespace}}

{{for|lists of commonly used templates|WP:Template index}}

{{For-multi|lists of commonly used templates|Wikipedia:Template index|a quick introduction to templates|Help:A quick guide to templates}}

{{Redirect|H:T|help regarding tables|Help:Table}}

{{Redirect|Wikipedia:Template|content guidelines|Wikipedia:Template namespace}}

{{Pp-semi-indef}}

{{Wikipedia how to|H:T|WP:TEMPLATE}}

{{beginner version|Help:A quick guide to templates}}

{{Wiki markup}}

A '''template''' is a Wikipedia page created to be included in other pages. Templates usually contain repetitive material that might need to show up on a larger number of articles or pages. They are commonly used for [[WP:Glossary#Boilerplate text|boilerplate]] messages, standardized warnings or notices, [[Help:Infobox|infoboxes]], [[WP:Navbox|navigational boxes]], and similar purposes. Templates can have parameters so that the same page generates different text on multiple pages that include it.

Line 11 ⟶ 10:

The most common method of inclusion is called [[Help:Transclusion|transclusion]], where the wiki source of the target page contains a reference to the template, using the {{tnull|{{var|Template name}}}} syntax. Another method is [[Help:Substitution|substitution]], where the content of the template is copied into the wiki source of the target page, just once, when it is saved.

[[Help:A quick guide to templates]] gives a brief introduction to the subject. There is further help from MediaWiki and Wikimedia at [[mw:Help:Templates]], [[m:Help:Template]], and [[mmw:HelpManual:Advanced templates]].

==General description==

Line 26 ⟶ 25:

==Using templates==

===General===

Using a template is similar to calling a [[Function (computer programming)|function]] in programming. When called, it returns a value. For a template, calling is (known as a ''template call''), itand returnsthe areturn result,value is known as the ''expansion'' of the template, which becomesis treated as part of the calling page's source. Like functions, some templates can take parameters that modifyaffect their output.

WhenCalling a template is called,causes it canto be either ''transcluded'' or ''substituted'' in the page that calls it (the ''target page'').

[[Wikipedia:Transclusion|TransclusionTranscluding]] a template means that when MediaWiki <em>displays</em> the page, it treats the template as if it were directly in the page’s source. This method[[Wikipedia:Substitution|Substituting]] ensuresa template differs in that updatesit toinserts the content of the template automaticallypermanently reflectinto inthe everytarget page wherewhen it’sit used.is <em>saved</em>

and subsequent editors cannot tell that it originated from a template.

When you update a template, every page that transcludes it automatically reflects the update when the page is displayed in the future, whereas updating a template has no effect on pages that have previously been saved with the template substituted.

[[Substitutionary atonement|Substitution]] differs in that it inserts the content of the template permanently into the target page when it is <em>saves</em>. This means subsequent editors cannot tell that it originated from a template.

To transclude a template, insert {{tnull|{{var|Template&nbsp;name}}}} at the point where it should appear in the page source. To substitute it, use {{tnull|subst:{{var|Template&nbsp;name}}}}. This wikitext is called a ''template call''.

In [[MediaWiki]], the [[wiki software]] that Wikipedia uses, [[Help:Magic words#Variables|variables]] are distinct from templates, butthough both are identifiedreferenced by double [[Curly brackets|curly braces]] <code>{{ }}</code>, butand they both return a value. These references differ: in that variables in MediaWiki are always uppercase, while template names follow the same conventions and have the same [[WP:NCHASHTAG|limitations]] as [[Help:Page names|page names]]. For example, includingthey are [[Case sensitivity|case-sensitivitysensitive]] (except for the first character);, [[underscore]]s are parsed as spaces;, and template names cannot contain certain characters: and limitedthe characters <code><nowiki># < > [ ] | { }</nowiki></code>. This is because thosethey are reserved for [[wiki markup]].

The [[number sign]] <code>#</code> is used as a [[URI fragment|fragment identifier]], which identifies a {{em|fragment}} or [[Help:Section|section]] of a page or Wikipedia article. Although you can use it in a [[WP:LINK|link]] to link to a section of a template page (e.g., [[Template:Portal#Example]]), fragment identifiers have no meaning in a template call and are ignored. For example, {{tnull|Portal{{var|#Location}}|Books}} is the same as {{tnull|Portal|Books}}.

The template namespace is the default, so you can leave out the namespace <code>Template:</code> in the template name, and it is conventional to do so. However, you must specify the namespace prefix for templates in other namespaces, such as <code>User:</code>. To transclude a page in [[WP:MAINSPACE|mainspace]], precede its page name with a colon, as <code>{<nowiki />{:{{var|Page name}}}}</code>.

{{A note}} Attempting to transclude a template that does not exist produces a [[WP:Red link|red link]], just like linking to any other nonexistent page. Following the link allows one to create that particular template. It is not possible to transclude templates between projects (such as different-language Wikipedias or MediaWiki) – to use a template on another language project, a copy of the template must be created in that project.

=== Parameters ===

Line 52:

The basic transclusion syntax for a template can be further controlled using [[parameters]], which allow you to customize a template’s output. The syntax is <code><nowiki>{{Template name|</nowiki>''parameter''<nowiki>|</nowiki>''parameter''<nowiki>|...}}</nowiki></code>, where <code>{{var|Template name}}</code> is the template’s name, and each <code>{{var|parameter}}</code> can be either a simple value (known as an ''{{dfn|unnamed parameter}}'') or in the form <code>{{var|name}}={{var|value}}</code> (known as a ''{{dfn|named parameter}}''). The first, second, third, etc., unnamed parameters are named <code>1</code>, <code>2</code>, <code>3</code>, etc., so using <code><nowiki>{{Template name|1=value1|2=value2}}</nowiki></code> is equivalent to <code><nowiki>{{Template name|value1|value2}}</nowiki></code>.

Each template has specific parameters it can accept, as defined within its code. You can list named parameters in any order in a template call. Extra or misnamed parameters arehave ignoredno effect, while missing parameters will usecause a default value to be used. If a parameter is repeated, the last defined parameter value will beis used.

[[Parameter|Parameters]] allow customization of a template’s output. The syntax is <code><nowiki><{{Template name|parameter|parameter|...}}</nowiki></code>, where <nowiki><code>Template name</code></nowiki> is the template’s name. Each <nowiki><code>parameter</code></nowiki> can be a simple value (an ''unnamed parameter'') or a <nowiki><code>name=value</code></nowiki> pair (a ''named parameter''). Unnamed parameters are referred to by numbers like 1, 2, 3, etc., so <nowiki><code>{{Template name|1=value1|2=value2}}</nowiki><nowiki></code></nowiki> is equivalent to <nowiki><code>{{Template name|value1|value2}}</nowiki><nowiki></code></nowiki>.

The value of a parameter can be an [[empty string]], such as when the pipe (<code>|</code>) or equals sign is followed immediately by the next pipe or the closing braces. For example, <code><nowiki>{{Template name|1=|2=test}}</nowiki></code> produces the same output as <code><nowiki>{{Template name||2=test}}</nowiki></code>. This is different from not specifying the parameter at all, which results in a default value, although templates are often coded so as to behave the same in both cases.

==== Whitespace handling ====

UnusedIf parametersa havetemplate call specifies a parameter which is not defined in the template, it has no impacteffect. SometimesEditors sometime specify a parameter they know is not defined in the template &mdash; for example, editors sometimes include a parameter like {{tag|reason|open}} to add a brief explanation within the source as a [[Wikipedia:Manual of Style/Hidden text|hidden comment.]]. However,(But some templates, likesuch as [[Template:Requested move|Requested move]], are programmed to show the reason parameter if provided). Certain templates, especially complex ones like [[Wikipedia:Infobox|infoboxes]], may use the check for [[Module:Check for unknown parameters|check for unknown parameters module]] to alert editors about any [[:Category:Unknown parameters|unrecognized parameters]] to helpthey avoidcode unintentionalby errorsmistake.

{{Nutshell|1=Leading and trailing [[Wikipedia:Whitespace|whitespace]] around {{em|named}} parameters and values is automatically removed, but spaces within the middle of the value are kept. For example, <code><nowiki>{{ ... | myparam = this is a test }}</nowiki></code> gives the same output as <code><nowiki>{{ ... |myparam=this is a test}}</nowiki></code>.|2=However, with {{em|unnamed}} parameters, all whitespace are preserved in the output.}}

==== Whitespace handling ====

<!-- Leading and trailing [[Wikipedia:Whitespace|whitespace]] around {{em|named}} parameters and values is trimmed and removed automatically, but spaces within the maddle of the value itself are kept. For instance, <code><nowiki>{{ ... | myparam = this is a test }}</nowiki></code> has the same output as <code><nowiki>{{ ... |myparam=this is a test}}</nowiki></code>. However, with {{em|unnamed}} parameters, all whitespace are retained as preserved in the output. -->

{{Nutshell|1=Leading and trailing [[Wikipedia:Whitespace|whitespace]] (including line breaks) around {{em|named}} parameters and values is automatically[[Whitespace removedcollapsing|collapsed]] automatically, but spaces withinin the middle of the value are kept. For exampleinstance, <code><nowiki>{{ ... | myparam = this is a test }}</nowiki></code> giveshas the same output as <code><nowiki>{{ ... |myparam=this is a test}}</nowiki></code>.|2= However, with {{em|unnamed}} parameters, all whitespace areis retained as preserved in the output.}}

Each template has specific parameters it can accept, as defined within its code. You can list named parameters in any order in a template call. Extra or misnamed parameters are ignored, while missing parameters will use a default value. If a parameter is repeated, the last defined parameter value will be used.

The value of a parameter can be an [[empty string]], such as when the pipe (<code>|</code>) or equals sign is followed immediately by the next pipe or the closing braces. For example, <code><nowiki>{{Template name|1=|2=test}}</nowiki></code> produces the same output as <code><nowiki>{{Template name||2=test}}</nowiki></code>. This is different from not specifying the parameter at all, which results in a default value, although templates are often coded so as to behave the same in both cases.

The collapsing of line breaks around parameters can be used to [[Wikipedia:Template namespace#Readability of the code|improve the readability of a template call]] with many parameters by placing each parameter specification in its own line.

Unused parameters have no impact. Sometimes, editors include a parameter like {{tag|reason|open}} to add a brief explanation within the source as a [[Wikipedia:Manual of Style/Hidden text|hidden comment.]] However, some templates, like [[Template:Requested move|Requested move]], are programmed to show the reason parameter if provided. Certain templates, especially complex ones like [[Wikipedia:Infobox|infoboxes]], may use the check for [[Module:Check for unknown parameters|unknown parameters module]] to alert editors about any [[:Category:Unknown parameters|unrecognized parameters]] to help avoid unintentional errors.

==== HandlingVariable variable-length variablesparameter lists ====

In MediaWiki, templates can’tcannot automatically handle an unknown or unlimited number of parameters. Each possible parameter usually has to be predefined in the template code. For example, a template might be set up to use three specific parameters, such as <code>1</code>, <code>2</code>, and <code>3</code>. If someone includes additional parameters beyond those, they wilwill not beaffect recognizedexpansion or processed byof the template.

However, there are some ways to work around this:

1. *Setting a limit: You can write the template to handle a fixed number of parameters by manually specifying each one (e.g., up to 10 or 20 parameters).

2. *Using templates or [[Wikipedia:Lua|modules]]: For cases needing a flexible number of inputs, templates can use Lua modules or helper templates (like <nowiki>{{mfl|separated entries|main}} or {{tl|separated entries}}</nowiki>). These helper tools provide more advanced handling, such as counting or iterating through parameters, enabling the use of multiple inputs without setting an exact number.

However, modules can bypass this limitation. For simpler cases, the separated entries module expands all sequential parameters and lets you set custom delimiters. For more advanced usage, the {{mfl|params}} module enables counting, listing, mapping, filtering, and handling a variable number of parameters without prior knowledge of the exact number.

Templates that accepts an open number of parameters are often collected under [[:Category:Variadic templates]].

This workaround allows templates to ''appear'' as if they handle a variable number of parameters by processing each one iteratively up to a certain point, but true infinite flexibility is not built into the core MediaWiki system.

If a parameter is intentionally left blank (e.g., {{para|1}|open}}}), it is treated as an empty string, which differs from leaving it out altogether (in which case the default value applies). However, templates are often coded to act the same in both cases.

Sometimes, editors may add parameters that aren't. not recognized by the template. This can be useful, for instance, when using reason to add a brief explanation directly in the source. Certain templates use [[:Category:Error-handling modules|error-checking modules]] like check for unknown parameters to notify the editor of any unrecognized parameters, mainly in complex templates like infoboxes, where such errors are common.

If a template call specifies a parameter which is not defined in the template, it has no effect. Sometimes editors do this on purpose: For example, {{para|reason}} is frequently used as a pseudo-parameter to explain briefly in the wiki source why the template call was put there (a form of a [[Wikipedia:Manual of Style/Hidden text|hidden comment]]).{{efn|Some templates, such as {{tlx|Requested move}}, have code to display {{para|reason}} as visible output; whether to do so is determined on a template-by-template basis.}} Some templates use {{mlx|check for unknown parameters|check|...}} to warn the editor if a parameter is being used that is not accounted for in the template's code; this is mostly used for [[Help:Infobox|infoboxes]] and other templates with a large number of complicated parameters, where the presence of an unknown one is usually an unintentional error. If you update such a template to define a new parameter, its call to the [[Wikipedia:Module|module]] must also be updated to include the new parameter.

Wikitext syntax has limits and does not natively support templates with an unlimited [[variadic template|variadic parameters]]. However, this restriction can be circumvented using dedicated Lua modules. For simpler cases, separated entries can handle {{mlx|separated entries|main}} and add custom delimiters. For more advanced use, {{mlx|[params}} can dynamically count, list, or map all provided parameters without needing to know their count in advance.

===Examples===

Line 169 ⟶ 157:

If a parameter is not specified in the template call, then the parameter reference is not replaced with anything -- it is expanded literally; this means that if the template call does not specify the parameter "xxx", the wikitext <code><nowiki>{{{xxx}}}</nowiki></code> inside the template expands to literally ''<nowiki>{{{xxx}}}</nowiki>'' (not the null string you may have expected). You can get a more useful behavior by specifying a default value in the parameter reference. Do this with the ''pipe syntax'': <code><nowiki>{{{xxx|dflt}}}</nowiki></code> specifies the default value <code>dflt</code> for the named parameter "xxx", and <code><nowiki>{{{1|dflt}}}</nowiki></code> specifies the default value <code>dflt</code> for the first unnamed parameter. Most often, one specifies a null default value, such as <code><nowiki>{{{1|}}}</nowiki></code> or <code><nowiki>{{{xxx|}}}</nowiki></code>.

If a call sets a parameter to the empty string like <code><nowiki>{{Template name|xxx=}}</nowiki></code> then <code><nowiki>{{{xxx|OK}}}</nowiki></code> will produce the empty string and not the default value "OK". Many users will expect that an empty parameter gives the same result as omitting the parameter. You can achieve this with: <code><nowiki>{{#if:{{{xxx|}}}|{{{xxx}}}|OK}}</nowiki></code>. This says: If <code>xxx</code> is assigned a non-empty value then use <code>xxx</code>, otherwise use "OK". If the default value is the empty string then you only have to write <code><nowiki>{{{xxx|}}}</nowiki></code>.

You can use default parameter values to effect a parameter alias:

Line 212 ⟶ 202:

===System variables and conditional logic===

Template code often makes use of the variables and parser functions described at [[Help:Magic words]] to make the template's behavior depend on the environment in which it is included (such as the current time or namespace). Parser functions can be used for some arithmetic calculations and string manipulations on variables and parameter values, but certain standard programming features such as loops and variable assignment are not available. Full string manipulation is not available; some templates providing such function have been created, but they are inefficient and imperfect.

Some of the most frequently used variables and functions are listed below. For more, see [[Help:Magic words]] and the fuller documentation at the MediaWiki pages [[mw:Help:Magic words]] and [[mw:Help:Extension:ParserFunctions]].

Line 243 ⟶ 233:

! width="30%" | Description !! width="40%" | Wiki source !! width="30%" | Displayed text

|-

| rowspan="2" | Testing for equality between two strings (or parameters). If the first two parameters are equal, the third parameter is returned, otherwise the fourth parameter is returned.

| <syntaxhighlight lang="wikitext" inline>{{#ifeq: yes | yes | Hooray...! | Darn...! }}</syntaxhighlight>

| {{#ifeq: yes | yes | Hooray...! | Darn...! }}

Line 250 ⟶ 240:

| {{#ifeq: yes | no | Hooray...! | Darn...! }}

|-

| Testing whether a string (or parameter) contains anything (other than whitespace). If it does, the second parameter is returned, otherwise the third parameter is returned.

| <syntaxhighlight lang="wikitext" inline>{{#if: {{{param|}}} | Hooray...! | Darn...! }}</syntaxhighlight>

| {{#if: {{{param|}}} | Hooray...! | Darn...! }}

Line 258 ⟶ 248:

| {{#expr: ( pi * 4 ^ 2 ) round 3 }}

|-

| [[Help:Calculation|Testing the result of a calculation]]. If the expression is true or non-zero, the second parameter is returned, otherwise the third parameter is returned.<br />[is 1230 even or odd?]

| <syntaxhighlight lang="wikitext" inline>{{#ifexpr: 1.23E+3 mod 2 | Odd | Even }}</syntaxhighlight>

| {{#ifexpr: 1.23E+3 mod 2 | Odd | Even }}

Line 290 ⟶ 280:

| {{CURRENTVERSION}}

|-

| Timestamp of last page revision

| <syntaxhighlight lang="wikitext" inline>{{REVISIONTIMESTAMP}}</syntaxhighlight>

| {{REVISIONTIMESTAMP}}

Line 303 ⟶ 293:

While fairly straightforward in application, it involves some noteworthy quirks and tricks.

To pass a parameter value from a template call to to a subtemplate, use a parameter reference in the template call to the subtemplate.

;Example{{colon}}

:Template:A contains <syntaxhighlight lang="wikitext" inline>"the quick brown {{B|{{{3}}} }} jumps over..."</syntaxhighlight>. Template:B (a subtemplate) contains <syntaxhighlight lang="moin" inline>'''{{{1}}}'''</syntaxhighlight>. Page X calls A with <syntaxhighlight lang="wikitext" inline>{{A|apple|pear|fox}}</syntaxhighlight> This expands to <syntaxhighlight lang="wikitext" inline>"the quick brown '''fox''' jumps over..."</syntaxhighlight>. The third unnamed parameter passed to Template:A gets passes as the first unnamed parameter to subtemplate B.

Line 316 ⟶ 306:

When a subtemplate contains unmatched braces—as in <syntaxhighlight lang="text" inline>{{lb}}}</syntaxhighlight>—the unmatched braces are treated as text during processing—they do not affect the parsing of braces in the calling template. But where the template is substituted, the unmatched braces will be parsed as braces when the page is subsequently displayed. This has little practical use, but can occasionally introduce unexpected errors.

See [[mmw:HelpManual:Advanced templates]] and [[mmw:HelpManual:Recursive conversion of wikitext]] for more information.

===<span id="Noinclude, includeonly, and onlyinclude"></span>Inclusion control: noinclude, includeonly, and onlyinclude===

Line 330 ⟶ 320:

! What is included {{em|there}} (calling page)

|-

|<code><nowiki><{{tag|noinclude> |content=&nbsp;{{bxt|text1 </noinclude> }}&nbsp;}}&nbsp;{{mxtn|text2</nowiki></code>}}

|<code>{{bxt|text1}} {{mxtn|text2</code>}}

|<code>{{mxtn|text2</code>}}

|-

|<code><nowiki>&lt;{{tag|onlyinclude|content=&gtnbsp; {{bxt|text1 }}&ltnbsp;/onlyinclude}}&gtnbsp; {{mxtn|text2</nowiki></code>}}

|<code>{{bxt|text1}} {{mxtn|text2</code>}}

|<code>{{bxt|text1</code>}}

|-

|<code><nowiki><{{tag|includeonly> |content=&nbsp;{{bxt|text1 </includeonly> }}&nbsp;}}&nbsp;{{mxtn|text2</nowiki></code>}}

|<code>{{mxtn|text2</code>}}

|<code>{{bxt|text1}} {{mxtn|text2</code>}}

|-

|{{tag|onlyinclude|content={{tag|includeonly|content=&nbsp;{{bxt|text1}}&nbsp;}} }}&nbsp;{{mxtn|text2}}

|<code><nowiki>&lt;onlyinclude&gt;<includeonly> text1 </includeonly>&lt;/onlyinclude&gt; text2</nowiki></code>

|<code>{{mxtn|text2</code>}}

|<code>{{bxt|text1</code>}}

|}

Line 375 ⟶ 365:

===Categorization===

{{See also|WPWikipedia:Categorization#Template categorizationTemplates}}

====Categorize pages by template inclusion====

Some templates generate category declarations in their expansion, since the template is intended to place calling pages in particular categories. This is often done with maintenance categories. Placing articles into ordinary content categories in this way is discouraged. When doing this, you may have to use {{tag|includeonly}} tags to keep the template itself out of the category. While developing, testing, sandboxing, or demonstrating a template intended to apply a category, either temporarily replace each category with a test category (starting with [[:Category:X1|X1]], [[:Category:X2|X2]], or [[:Category:X3|X3]]) or suppress categorization (see [[WP:CATSUP|category suppression in templates]]).

Line 433 ⟶ 423:

The displayed page content generated by a template call (which is the rendering of the expansion of the called template) is the ''template result''. The template result generated by the template call <syntaxhighlight lang="wikitext" inline>{{sic|constellation prize}}</syntaxhighlight> is "{{sic|constellation prize}}".

The ''name'' of a template is the name of the wikipediaWikipedia page (which is also the title of the page). The namespace is normally left off if it is "Template" (which it almost always is). Furthermore, it is customary to write the name with double braces, like a template call, to emphasize that it names a template. For example, "Use the {{tl|tm}} template to generate the trademark symbol." But don't go so far as to put a template name in the code font, to prevent confusion with an actual template call. {{tlf|tm}} is a template name, but {{tnull|tm}} is a template call.

Some template calls perform a tagging function; such a template call is often called a ''tag'', as in, "If you are in the middle of a major edit, place an {{tl|in use}} tag at the top of the page." This is one of many ways the term "tag" is used in Wikipedia.