User:Happy-melon/Templates

The MediaWiki software includes the capacity to include the contents of one page in the display of another page - this process is known as transclusion. Since one page can be transcluded on many other pages, the most common use of transclusion is to create boilerplate text, which can be displayed on many pages but updated easily from one location. For this reason, pages which are created primarily for the purpose of being transcluded on other pages are known as templates. Most wikis include a "Template:" help:namespace to house these templates.

This page and its extension Help:Advanced templates form a reference manual for how to use templates and the associated wikimarkup on MediaWiki. Templates can also make use of other features of the MediaWiki software, such as ParserFunctions.

Note: The master version of this page is held at m:Help:Template on Meta-Wiki. All links and template examples work correctly there, but may not if you are viewing a copy of this page on another project.

Introduction
Most MediaWiki sites include a Template namespace which holds pages designed specifically for transclusion on other pages. While this namespace can be renamed, for instance if the project is in a language other than English, the canonical prefix Template: will always function as a shortcut to that namespace. So while the correct name of the Template: namespace on the German Wikipedia is Vorlage:, and so the correct link to the User en Babel box is w:de:Vorlage:User en, using w:de:Template:User en will also work.

A page within the Template: namespace is known as a template, although it is no different to any other page: the same wikimarkup can be used on templates as on any other page. However, many Wikipedias and other MediaWiki sites have policies to restrict the type of content that can appear in the Template: namespace. A page in the template namespace can be linked to like any other page: Template:TEx1 is a link to an example template that will be used later.

This example format will be used throughout this documentation page. If, instead of enclosing the link in square brackets, the link is enclosed in braces  , this is a signal to the MediaWiki parser to transclude the page at that point, rather than link to it. So:

Note that when using braces, the page to be transcluded defaults to the Template: namespace if no other namespace is specified. To transclude a page in another namespace, the full pagename must be specified. So to transclude this page's talk page, type. To transclude a page from the main namespace, use an 'empty' namespace field; to transclude the Main Page, you would need to type. Not all namespaces can necessarily be transcluded: this is a definable parameter of the MediaWiki software which is set in $wgNonincludableNamespaces. It is not possible to transclude pages across projects: trying to transclude w:de:Vorlage:User en anywhere but the German wikipedia outputs:.

The process of transcluding a template in the manner shown above has several synonyms, including: inclusion and embedding; however inclusion is sometimes used to mean substitution, which is entirely different. The code within the curly braces is often known as a template call.

Whatlinkshere
When viewing the Special:Whatlinkshere page for a page which transcludes templates, the pages which are transcluded are noted. This note is stored in MediaWiki:Istemplate, and defaults to "inclusion"; some projects (such as the English Wikipedia set this to "transclusion", and of course projects in other languages will use an appropriate translation. This list also appears at the bottom of the edit page.

Each page on a wiki is associated with several tables which store useful information; a list of all pages transcluded on the current version of the page is stored in the  table. When a page is edited, this table is used to create the list of transcluded pages. This has several caveats: Pressing the "show preview" button generates a new temporary  table, resulting in a correct display thereafter. Pages are also included on the  table if they are transcluded via conditional statements: if the code   were included on a page, both Template:TEx1 and Template:TEx2 will be marked as transcluded, even though the conditional statement will always display.
 * Editing an old version of the page will cause the current list of transcluded pages to be displayed, even if they are not transcluded in the old version
 * Editing a section of a page will display the full list, even if some of the pages are not transcluded in that section.

Passing parameters
While some templates simply include pure text, most include customisable values called parameters. Parameters are signified in the wikimarkup of the template page inside triple braces:  signifies that when the page is transcluded, the contents of the parameter name, if it exists, will be included in the text at that location.

By default, the parameters are numbered in order, starting from 1; there is no practical limit to the number of parameters that can be defined (at least 65536). However, named parameters may be added at any point without interrupting the numbering:

Some points to note from these examples:


 * If no parameter name is specified, the value is assigned to the first unused numbered parameter.
 * Parameters cannot be 'overloaded' - if a parameter is assigned a value more than once, only the last value is retained
 * Whitespace is always stripped from before and after named parameters, but not always from unnamed parameters.
 * It is possible to assign values to the 'null' parameter by using . These values will never be displayed

Based on these concepts, it is possible to develop some quite sophisticated template layouts. A good real example is w:en:Template:Chess position on the english wikipedia. This template takes 65 unnamed parameters, but to standardise the layout of the wikicode dummy parameters are used:

In this template call, the row numbers and column numbers are repeatedly assigned to the null parameter using the code. The template call is syntactically equivalent to, but is much easier to understand.

Equals signs
Unnamed parameter values cannot contain equals signs. Named parameters can contain equals signs. This is most commonly seen with User signatures containing HTML code. Imagine a signature:, which would display as Example. If this code were passed to a template as an unnamed parameter (eg, then when the template is parsed, the code is instead interpreted as assigning the value   to the named parameter  .  To prevent this, the value must be passed to a named parameter.  So   will work correctly (producing ).

It is sometimes easier to replace the equals sign with its HTML equivalent, which renders as. However this will not work if the equals sign is involved in another template call or HTML tag:  will display as Example.

Pipe character
The pipe character cannot appear in a parameter value unless it is a part of: This means that parameter values cannot contain raw wikitable code. However, the template  has been provided on most Wikis; this template contains only the raw pipe character, so it can be used in table code. It is also possible to use the HTML pipe character (&amp;#124;)unless the pipe is 'functional':
 * 1) Another template call
 * 2) A piped link
 * 3) An image tag

Braces and brackets
A parameter value cannot contain unmatched double brace characters  or   or square brackets   or. A parameter value can contain matched sets of braces, so template calls, parser functions, or other parameters can be included:

{{/T|temp=TEx2|text= {{TEx2|PQR}STU}} |out={{TEx2|PQR}STU}}|text2= STU}} |out2=STU|text3= {{TEx2|PQR{STU}} |out3={{TEx2|PQR{STU}}|text4=

Note that in the final example, the template call is not closed, probably resulting in unexpected formatting and/or template display. While matched sets of braces usually do not create a problem, care must be taken when large numbers of braces are nested together. Matched sets of braces are evaluated from the inside working outwards; if possible, the innermost three braces are interpreted as enclosing a parameter value, if there is a matching set of three braces to close the parameter. If this is not possible, then the innermost two braces are interpreted as enclosing a template call or parser function. Some examples:


 * Matched sets of four consecutive braces are interpreted as a parameter surrounded by single braces:  is equivalent to.
 * Unmatched sets of four braces are interpreted as nested template calls:  is parsed as a call to a template, the name of which is dependent on the output of  .  In this example,   results in, as the Hello world! template does not exist.
 * Matched sets of five consecutive braces are interpreted as a template call surrounding a parameter:  is equivalent to.
 * Unmatched sets of five braces are interpreted using the standard rules:  is interpreted as a named parameter with the name dependent on the result of Template:TEx1, which in this case is equivalent to.

In general, if unexpected results are obtained when using large numbers of nested braces, consider separating them into the correct groups of pairs and triplets using spaces. This will usually not have any adverse consequences.

XML
Parameters are not expanded when called from inside XML-style tags. This is a restriction not so much on what values can be passed to a parameter as to where those parameters can be used within the code in the template. This is most commonly encountered with the  tags that are provided by , and are the most popular citation form on many Wikis.

Note that while both the references appear to be correctly formatted, and parameter 2 has expanded correctly, parameter 1 has not (both references have the 'name' attribute, which is the HTML equivalent to  . This bug applies only to XML-style tags, not to basic HTML.  Using the code   in a template will still display correctly.

There are several other bugs associated with  tags, some of which can be found at the Mediawiki documentation page.

Default parameters

 * See also: Help:Parameter default

If a parameter is included in the template code, but is not defined in the template call, then it is not replaced when the template is transcluded, as shown in the last two examples above. To avoid this, default parameters can be specified. Default parameters are placed within the triple braces, after a pipe character, and can be another parameter:

There are no restrictions on default values other than those mentioned above which apply to normal parameter values.

Code on template pages
Template pages are in all respects identical to other Wiki pages - the same formatting will work in the same manner as it will anywhere else. However there are few pieces of wikimarkup which are designed primarily for use on template pages.

Any code placed between the XML tags  and   will not be included when a template is transcluded:

tags are most commonly used to include documentation or notes about a template on the template page, which will not appear when the template is transcluded. They may also be used to encapsulate a category tag, to enable the template page itself to be included in the category without also categorising every page the template is transcluded in.

Any code placed between the XML tags  and   will, as the name suggests, only be rendered when the template is transcluded. Any code placed between the tags will not appear or be parsed when the template page itself is displayed.

tags are often used to encapsulate category tags, to enable all pages on which the template is transcluded to be categorised, while the template itself is not. If the template code renders very messily when no parameters are specified, the entire template code can be encapsulated in  tags to prevent messy display.

Any code placed between the XML tags  is rendered normally when the template page itself is viewed. However, when the template is transcluded, only code encapsulated by  tags will be included.

Transclusion
A template can call another template without difficulty:

The set of parameter expressions are not automatically "passed through" the outer template to the inner template. However, it is easy to manually pass parameters through a template:

A template is permitted to transclude itself. However, the parser incldues protection against an infinite loop. When the template is transcluded for the second time, the template call within the template is replaced by a link to the template rather than a transclusion.

Parsing templates
When the MediaWiki parser encounters a template (defined as a matched pair of braces not inside  tags), the template is expanded using the following algorithm:


 * 1) The template call is divided into the template name and parameter expressions, by looking for pipe characters. Pipes contained within matched double braces or square brackets are ignored.
 * 2) *This division is performed purely based on pipe characters currently present in the template call, ignoring those potentially contained within templates. This is what permits the use of Template:!.
 * 3) *A potentially interesting feature is that characters including and following a hash  are stripped from the template name after this division.  So   will be parsed in exactly the same way as.
 * 4) The wikicode for the template name is evaluated, calling the template parser recursively if necessary.
 * 5) The wikicode for each parameter expression is evaluated, again using recursion if the wikicode contains another template.
 * 6) Any parameter expression now containing a raw equals sign is split around that equals sign into a parameter name and parameter value. If a parameter expression contains more than one equals sign, the division is done around the first (working left to right).
 * 7) Any remaining parameter expressions which do not contain equals signs are assigned as values to the implicit parameters, working left to right. So the first parameter expression which does not contain an equals sign is assigned as the value of parameter , the next parameter expression is assigned as the value of parameter  , etc.
 * 8) The wikicode of the template page is analysed and stripped around,   or   tags, if present.
 * 9) The template call is replaced by the analysed wikicode, replacing parameters by their values if possible.
 * 10) *Any parameters that do not appear in the analysed wikicode are discarded, and any parameters appearing in the wikicode which have not been assigned a value are replaced by their defaults (if defined) or left as they are.

Wikimarkup
If the first character of a template page is,  ,   or  , then when the template is parsed, an HTML line break   is inserted immediately before the start of the template code. This ensures that these characters are at the beginning of a line, resulting in an indentation, bulleted or numbered list, etc. If this effect is not desired, use the HTML equivalents (such as &amp;#58; for a colon) or surround the first character with  tags.

Redirects
If a transcluded page is a redirect to another page, then the wikicode of the target page is transcluded instead. A double redirect does not work. Transcluding the target page onto the redirect page has a similar effect, but care must be taken to ensure that any named or unnamed parameter values are "passed through" to the target page - it is usually more convenient to use a redirect. Careful use of redirects permits a certain degree of recursion:

Where Template:TEx13b is a redirect to Template:TEx13a.

msgnw
An abbreviation for "message, nowiki",, like  , is a prefix which can be added to template calls to affect their display. When a template call including the msgnw prefix is encountered, it is simply replaced by the complete wikitext of the template page, surrounded by  tags. Parameters are not replaced by their values, and the text is not stripped around or tags.

History of templates on MediaWiki

 * MediaWiki 1.2.6

Pages in the MediaWiki namespace only could be transcluded with the code, to transclude the page MediaWiki:templatename. Parameters were not supported.


 * MediaWiki 1.3

Pages from all namespaces could be transcluded, with the  prefix now optional. Named and unnamed parameters were supported, but default values were not. An undefined parameter was interpreted as a template call surrounded by single braces, almost inevitably resulting in redlinks in the final render. Default values could be improvised by storing them as the wikitext of Template:parametername.


 * MediaWiki 1.4

Templates could be transcluded more than five times on the same page (previously this was not possible).


 * MediaWiki 1.5

No fundamental changes were made to the template mechanism itself, but the expansion of the collection of mw:Help:Magic words enabled greater flexibility in the use of templates.


 * MediaWiki 1.6

More magic words were added, and the current parameter default mechanism was implemented. ,  and   were also implemented.