Help:Templates
 | This article is a fledgling. Help BoyWiki grow by expanding it |
Templates are pages shown in Portal:Template index. This means any page whose name begins with "Template:", such as "Template:Documentation", can be used as a template. The content of a template can be added to a page by typing {{templatename}} while editing the page. When the page is later viewed, {{templatename}} is replaced by the content of the page "Template:templatename". If the page "Template:templatename" is later altered, all the pages with {{templatename}} in them will change automatically.
Amongst other things, templates are used to add recurring messages to pages in a consistent way, to add boilerplate such as template {{stub}} which indicates that the article is a fledgling.
When a template is automatically expanded and appears on a page, it is said to be "transcluded".
Templates are documented (or should be) at their pages. See Help:Template Documentation
General
Most templates are pages in Portal:Template index
Templates can contain any desired Wikitext, including calls to other templates. They have some limited programming capacities: customizable values (called parameters), calculation and branchings (using parser functions), and access to wiki-specific variables (magic words), such as dates, times, and page names. They may also contain tags which define which parts of the wikitext are to be included when the template is transcluded or substituted. This means that the appearance of the template page itself need not be the same as that of the transcluded content (for example, it can contain documentation, categories, etc. for the template).
How to do it: To transclude a template to an article or page, type {{template name}} in the wikitext at the place where the template is to appear. The prefix "Template:" need not be included, and an initial capital is not necessary.
Note: Attempting to transclude a template that does not exist produces a red link, just like linking to any other nonexistent page. Following the link allows one to create that particular template.
Also see: Help:Templates for beginners
Usage syntax
Parameters
The basic transclusion syntax given above can be extended by the addition of parameters, which are used to control the template's output. The syntax for this is
{{template name|parameter|parameter|...}}
where each "parameter" may either contain just a value (these are called unnamed parameters) or be of the form name=value (named parameters). The first, second, etc. unnamed parameters are equivalent to parameters named "1", "2", etc.
Whitespace characters (spaces, tabs, returns) are stripped from the beginnings and ends of named parameter names and values, but not from the middle: thus {{ ... | myparam = this is a test }} has the same effect as {{ ... |myparam=this is a test}}. This does not apply to unnamed parameters, where the whitespace characters are preserved.
What parameters (if any) can or should be passed to a template, and how they are to be named, depends on the coding of that template. Named parameters can be defined in any order. Superfluous or misnamed parameters will be ignored; undefined parameters will be assigned default values. If a parameter is defined more than once, the last value takes effect.
The value of a parameter can be the empty string (pipe or equals sign followed immediately by the next pipe or the closing braces). This is different from leaving the parameter undefined (although templates are often coded so as to behave the same in both cases).
Other details
Template names are exactly like other page names case-sensitive except for the first letter, with spaces indistinguishable from underscores. If the symbol # (normally used to link to a section of a page) appears in a transclusion, then it and any characters that follow it are ignored.
Notice that the same double-brace syntax is used for many MediaWiki variables and parser functions (see Help:Magic words). For example, the code {{NAMESPACE}} may look like a template call, but it is actually a variable whose value is the namespace prefix of the current page.
Usage hints and workarounds
The following points may be worth noting when using templates:
- An unnamed parameter cannot contain an ordinary equals sign, as this would be interpreted as setting off a named parameter. (This does not apply if the equals sign comes within another template call or other item which the parser handles separately.) To pass an equals sign in an unnamed parameter (for example in a URL with key/value pairs), replace the equals sign with the special template {{=}}, which returns an equals sign that will not be specially interpreted. Another method is to replace the unnamed parameter (and any subsequent unnamed parameters) with named parameters — the first unnamed parameter is equivalent to a named parameter with the name "1", and so on. So to call template
{{done}} with the parameter "a=b", type either {{done|a{{=}}b}} or {{done|1=a=b}}.
- Similarly, it is not possible to use an ordinary pipe character | in template parameters, as it will be interpreted as a separator. (Again, this does not apply if it comes within another separately parsed item, such as a piped wikilink.) This time the problem can be solved by using the special template {{!}} in place of the pipe, or (if the pipe is not intended to be parsed specially at a higher level) using the HTML entity |.
- Remember that whitespace characters (spaces, tabs, carriage returns and line feeds) are not automatically stripped from the start and end of unnamed parameters (as they are from named parameters). Including such characters (or any other non-visible characters in any parameters) may in some cases affect the template's behaviour in unexpected ways. (Template designers can use
{{StripWhitespace}} to remove unwanted whitespace in unnamed parameters.)
- In documentation and discussions it is often convenient to be able to produce the template call syntax, with a link to the template in question, but without actually calling the template. This can be done easily using the "
{{tl}}" template (the template link template). For example, using the text "{{tl|tc}}" produces " {{tc}}". There is an extended version, {{tlx}}, which also supports parameters.
- When a template is changed (when the template or one of its subtemplates is edited), the change will be reflected on all pages on which the template is transcluded. However the change may not become visible on all pages immediately — a previously cached version of a page, based on the previous version of the template, may continue to be displayed for some time. Use the purge function to force a page to be displayed using the latest versions of templates. (This includes the template page itself, if it contains usage examples.)
- When viewing old versions of pages, remember that templates will be transcluded as they are now, not necessarily as they were when the old page version was active.
- To list all pages onto which a template is transcluded, use What links here on the template page. (This will not include pages where the template has been substituted.)
- To get a list of templates transcluded on a page, click "Edit", and find the list below the edit window. This list also includes the sub-templates used by the templates that are directly transcluded. To get such a list for a page section, an old version of the page, or your newly edited version prior to saving, click "Show preview" on the appropriate edit page. (For an old version, the subtemplate tree will be constructed according to the templates' current state.)
- There are limits to the number and complexity of the templates that an article may have. See the "Expand limits" section for help in resolving this.
Creating and editing templates
Templates are created and edited in much the same way as any other page: choose an appropriate name, navigate to that page, then click the Edit tab or create a new page as needed. As mentioned above, templates are normally placed in the Template namespace, though templates intended for your own personal use or for experimentation can be created in your own user space. Anything that can be included on a normal page or article can be included on a template, including other templates (called subtemplates). Templates often make use of programming features — parameters, parser functions and other magic words — which allow the transcluded content to vary depending on context. There are also special tags to control which information is transcluded and which is not.
Before creating a template, do a quick search for existing templates (e.g. by exploring Portal:Template index) to see if there's already a template that does what you want, or a similar template whose code can be copied and modified (or left in place and expanded). Look for generic templates on which the new template can be based (for example, navbox templates can be easily created by calling the generic Template:Navbox).
There is no hard rule about what name to choose for a template — make it short but reasonably descriptive. If similar templates exist, try to follow a consistent naming pattern. Templates can be renamed without breaking existing transclusions, provided a redirect to the new template name is left behind.
Be extremely careful when editing existing templates — changes made can affect a large number of pages, often in ways you might not expect.
To propose the deletion of unused or inappropriate templates, or other changes in the way particular templates are used, go to Templates for discussion (TfD).
Handling parameters
The values of the parameters which can be fed to a template are represented in the template code by items enclosed between triple braces:
- the code
{{{xxx}}}will be replaced by the value of the parameter named xxx - the codes
{{{1}}},{{{2}}}etc. will be replaced by the first, second etc. unnamed parameter (or the value of a parameter named 1, 2, etc.); these are sometimes known as positional parameters
If a parameter is not assigned a value, then the above replacements will not take place — the form "{{{xxx}}}" will remain as the effective value of the parameter. To change this behaviour, define default values using the pipe syntax. For example, {{{1|default}}} will be replaced by the first unnamed parameter if there is one, or otherwise by the text "default". Similarly, {{{xxx|}}} will be replaced by the parameter named xxx if it exists, or otherwise will be left blank. Though if a template is called with the parameter specified as empty (e.g. {{Example|}}), the default for the parameter will be ignored; if that is undesired one can use {{#if:{{{1|}}}|{{{1}}}|default}} instead to get the text "default" even if the parameter is specified as empty.
Parameters do not get expanded when they are inside nowiki tags or XML-style extension tags. Thus, the following will not work within a template — <myextension xparam={{{tparam}}}> ... </myextension> — because the parameter is not expanded.
Because of the multiple uses of double-brace and triple-brace syntax, expressions can sometimes be ambiguous. It may be helpful or necessary to include spaces to resolve such ambiguity, for example by writing {{ {{{xxx}}} }} or {{{ {{xxx}} }}}, rather than typing five consecutive braces. However, watch out for unwanted whitespace appearing in template expansions.
System variables and conditional logic
Template code often makes use of the variables and parser functions described at Help:Magic words, in order to make the template's behaviour depend on the environment (such as the current time or namespace) or on the parameter values which are passed to it. They can also be used for arithmetical calculations. Notice that full string manipulation is not available (although templates have been created which provide such functionality, though very inefficiently and imperfectly), nor are certain standard programming features such as loops and variable assignment.
Some of the most often used variables and functions are listed hereafter. For more, see Help:Magic words.
| Description | Text entered | Result |
|---|---|---|
| Uppercasing text | {{uc: Heavens to BETSY! }} | HEAVENS TO BETSY! |
| Lowercasing text | {{lc: Heavens to BETSY! }} | heavens to betsy! |
| Getting a namespace name | {{NS: 1 }} | Talk |
| Getting a Wikipedia URL | {{fullurl: pagename }} | https://www.boywiki.org/en/Pagename |
The ParserFunctions extension gives more programming-oriented parser functions.
| Description | Text Entered | Result |
|---|---|---|
| Testing between options | {{#ifeq: yes | yes | Hooray...! | Darn...! }} {{#ifeq: yes | no | Hooray...! | Darn...! }} |
Hooray...! Darn...! |
| Testing if a parameter is set | {{#if: {{{param|}}} | Hooray...! | Darn...! }} | Darn...! |
| Making a calculation (mathematics) [area of circle of radius 4, to 3 decimal places] |
{{#expr: ( pi * 4 ^ 2 ) round 3 }} | 50.265 |
| Testing the result of a calculation [is 1230 even or odd?] |
{{#ifexpr: 1.23E+3 mod 2 | Odd | Even }} | Even |
| Description | Text Entered | Result (for this help page) |
|---|---|---|
| Page names | {{PAGENAME}} {{FULLPAGENAME}} |
Templates Help:Templates |
| Name of the current namespace | {{NAMESPACE}} | Help |
| Number of registered users | {{NUMBEROFUSERS}} | 225 |
| Number of pages in a given category | {{PAGESINCATEGORY:"Weird Al" Yankovic albums}} | 0 |
| Current software version | {{CURRENTVERSION}} | 1.42.1 |
| Timestamp of last revision | {{REVISIONTIMESTAMP}} | 20121224163637 |
The PAGENAME and NAMESPACE variables are particularly useful, and frequently used, to change template behavior based on context. For example, if the template transcludes a category link (e.g. cleanup templates, which transclude a link categorizing the page as a page which needs cleanup), it will often check the NAMESPACE variable to make sure that talk pages, user pages, or anywhere else the tag might incidentally be placed do not themselves get categorized as pages needing cleanup.
Nesting templates
Templates may contain other templates — this is usually called "nesting". As the template is processed, the wikitext produced by any nested templates is transcluded into the nesting template, so that the final product is essentially processed from the most deeply nested template out. While fairly straightforward in application, it involves some noteworthy quirks and tricks.
To pass a parameter value to a nested template, place a parameter tag as the value of one of the nested template's parameters.
- Examples:
- Template:A contains "the quick brown {{B|{{{3}}}}} jumps over...". This takes the value passed to the third positional parameter of Template:A and passes it as the first positional parameter of Template:B, then returns the wikitext produced by B as part of the phrase.
- Template:A contains "the quick brown {{B|waldo={{{3}}}}} jumps over...". As above, except the third positional parameter of Template:A is passed to the named parameter "waldo" of Template:B.
Template parameters themselves can be chosen conditionally.
- Example:
- Template:A contains "the quick brown {{B|{{{3}}}=fox}} jumps over...". Template:A passes the word "fox" to a parameter of Template:B that's named in A's third positional parameter.
A template can call itself, but will stop after one iteration to prevent an infinite loop.
When a nested template contains unmatched braces — as in {{lb}}} — the unmatched braces are treated as text during processing, and do not affect the parsing of braces in the nesting template. If the nested template is substituted, however, the substitution is processed first, and this will change how braces are parsed in the nesting template. This has little practical use, but can occasionally introduce unexpected errors.
See the meta:Help:Advanced templates and meta:Help:Recursive conversion of wikitext for more information. These pages also contain information on unusual calls such as {{template {{{parameter|}}} }}.
