Help:Templates
A template is simply a page designed for inclusion on other pages. If a template is changed, this is usually reflected on every page that uses the template. As you might begin to imagine, templates are a powerful tool that when put to good use, can reduce work and increase maintainability. On this page you will learn how to use templates and how to make your own templates.
General
Templates may contain any desired wikitext, including calls to other templates. They have some limited programming capacities: customizable values (called parameters), calculation and branching (using parser functions), and access to wiki-specific variables, such as dates, times, and page names.
To use a template in a page, a template tag (in the form {{template name}}, which is the name of the template enclosed in doubled curled brackets) is added where you want the template to appear. When a reader wants to view the page, the servers fetch the contents of the template page, process any variables relevant to the page, and display the result in place of the template tag.
Templates are useful for any text for which one wants a copy in two or more pages, and there is no need for each copy to be edited independently, to adapt it to the page it is in. Since parameters can be used, versions may to that extent even be different, and parameter values can be edited independently for each. Templates are not only convenient, but they can also “force” a useful uniformity, e.g., a certain “style”.
Typical applications are:
- Messages for displaying information ({{split}})
- Navigation between a book's pages or chapters for easier reading online ({{chapter navigation}})
- Placeholders for displaying visual information. Like tables, figures, diagrams, illustrations, etc.
- Composites composed of a table of simple images which display more complex ideas ({{chess diagram}}
Template pages and namespaces
Templates have their own namespace which uses the prefix "Template:" (similar to the familiar "User:", "Help:", and "Talk:" namespaces).
Most templates exist in the template namespace, and can therefore be found on pages titled "Template:Template name". Sometimes, however, users create templates in other namespaces, such as the User: namespace. The normal use of a template (called transclusion) is possible from any namespace, but the advantage of the template namespace is that the "Template:" prefix is not needed when transcluding. By contrast, in order to transclude content from any other namespace excepting the main namespace (where books reside), the full name is needed, including the namespace prefix. If transcluding from the mainspace (which is rarely done) a colon must be prefixed inside the template syntax, or the software treats the code as an uncreated template. Thus:
| Namespaces | Coding example | Result |
|---|---|---|
| Template: | {{Name of template}} | Transclusion of template content |
| Outside template and mainspace | {{Wikibooks talk:name of page}} | Transclusion of page content |
| Mainspace | {{:Book title}} | Transclusion of book content |
| Mainspace without colon | {{Book title}} | Red-link to uncreated template |
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 within the curly brackets, then it and any characters that follow it are ignored.
Template pages, like most other pages, have talk pages associated with them, where editors can discuss any issues relating to the template. (For this reason, templates should not be placed in "Talk:" namespace, even if they are intended for use on talk pages; since talk pages do not have talk pages of their own, there would be no page for discussing the template.)
Template usage
To transclude a template into another page, use the following syntax (called a template tag):
- {{ template name | parameter | parameter | ... }}
This consists of the template name and various parameters that are passed to the template, where each parameter is separated by a vertical bar (or pipe), and the entirety is surrounded by doubled curly braces, {{...}}. The template tag should be placed in a page wherever the template is intended to appear. The "Template:" prefix is never needed for transclusion, only for finding and editing the template itself (though if the template is created in a different namespace that prefix is needed). Not all templates have parameters, and not all templates that have parameters need to have values provided, so sometimes {{template name}} is sufficient to use a template. If a parameter is needed, but a value is not provided by the user, the template may render with something like {{{...}}} in the text, where the '...' might be a number or a parameter name. This is to inform the user that a named or unnamed parameter is missing, and can be avoided by using default values for the parameter.
Parameters come in two basic forms:
- unnamed parameters (sometimes called 'positional' parameters): values that are put into the template in the order they appear
- {{template name|parameter1|parameter2|... }}
- named parameters: values associated with a particular named key in the template
- {{template name| parametername1 = parameter1 | parametername2 = parameter2 | ... }}
These may be mixed:
- {{template name|parameter1|parameter2| parametername1 = parameter3 | parametername2 = parameter4 | ... }}
By convention named parameters are listed last, though that is not a requirement. Whitespace characters (spaces, tabs, returns) are stripped from the beginnings and ends of named parameter values (unnamed parameters are unaffected), but not from the middle: thus {{ ... | myparam = this is a test }} will be treated as though the user had typed {{ ... |myparam=this is a test}}.
Template pages themselves may include material that is not transcluded with the template (such as documentation or categories that the template itself belongs to), or material that is only used when the page is transcluded (such as categories that apply to the transclusion page, but not the template). See the discussion of the includeonly and noinclude tags, below.
Attempting to transclude a template that does not exist produces a redlink, just like linking to any other nonexistent page. Following the link allows one to create that particular template.
Basic template usage examples
If you wish to experiment with any of these, please use the template sandbox.
Templates with no parameters
To see an example of a very simple template, look at Template:Tc. This template does nothing more than tranclude the letters "in" into other pages. For instance, editing the following phrases into any page will yield the associated results:
| Description | Text Entered | Result after Processing |
|---|---|---|
| {{Tc}} by itself | {{tc}} | in |
| Single use of {{tc}} | {{tc}} 2009, with Barack Obama settling into the White House, we find the beginning of... | in 2009, with Barack Obama settling into the White House, we find the beginning of... |
| Multiple uses of {{tc}} | {{tc}} 2009, with Barack Obama settl{{tc}}g {{tc}}to the White House, we f{{tc}}d the beg{{tc}}n{{tc}}g of... | in 2009, with Barack Obama settling into the White House, we find the beginning of... |
You'll notice that the template includes only the letters "in" when transcluded, despite the explanatory text on the template page ("This template is used..." click on the template link above to see). If you edit the template page, (click this link), you'll see that everything except the letters "in" is enclosed in 'noinclude' tags, discussed later.
Templates with unnamed parameters
Transclusion with parameters is only slightly more complicated. For a quick example, the famous dead man's hand can be reproduced by the following templates, using unnamed parameters:
| Description | Text Entered | Result after Processing |
|---|---|---|
| Using three templates (Template:Clubs, Template:Diamonds, and Template:Spades) | {{clubs|A}} {{clubs|8}} {{spades|A}} {{spades|8}} {{diamonds|9}} | A♣ 8♣ A♠ 8♠ 9♦ |
| Using (Template:BridgeHandInline); not quite as pretty, but just one template, with four parameters. | {{BridgeHandInline|A8||9|A8}} | ♠A8 ♥ ♦9 ♣A8 |
| Using (Template:BridgeHandInline), but with a missing pipe separator | {{BridgeHandInline|A8|9|A8}} | ♠A8 ♥9 ♦A8 ♣{{{4}}} |
In the second example, the position of the parameter in the template tag determines which suit it belongs to. Thus, the first A8 (first slot) goes to spades, the empty position (second slot) goes to hearts, the 9 (third slot) goes to diamonds, the second A8 (fourth slot) goes to clubs. Note that the empty parameter position is counted; if the extra pipe is forgotten, as in the third example, the result is that the cards end up in the wrong positions, and a {{{4}}} appears, meaning that the template was expecting a value for the fourth positional parameter but none was provided. See the section on parameters and default values, below.
Templates with named parameters
Using named parameters is similar to using unnamed parameters. For example, Template:Payoff matrix (which is used in some books on game theory) gives a simple 2-by-2 grid with adjustable values, using the names UL, UR, DL, and DR to refer to Up Left, Up Right, Down Left and Down Right, and a Name parameter to add a name to the bottom of the matrix.
| Description | Code | Result | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Payoff matrix | {{payoff matrix | UL = 5 | UR = 7 | DL = 2 | DR = 9 | Name = Example usage }} |
| ||||||||||||
| Payoff matrix showing a default value for a missing parameter, and different ordering for the others | {{payoff matrix | DR = 9 | Name = Example usage | DL = 2 | UR = 7 }} |
| ||||||||||||
In the second case, the order of the parameters has been altered without changing the result - one of the advantages that named parameters have over unnamed parameters - and one of the values (UL) has been removed entirely, allowing the template to insert the default value of "0, 0".
Parameter names are case sensitive, even in the first character. for example, using "dr = 9","Dr = 9" or "dR = 9" instead of "DR = 9" will cause the Down Right cell to display the default "0, 0". The alternate case versions are treated as different parameters and ignored by the template.
Substitution
Generally, templates are processed into readable text when a user browses a page. This is the normal intention of a template: since the template is reevaluated each time it's used, changes to the template can propagate across many pages quickly and effortlessly. Occasionally, however, this is not appropriate. For instance, a user may want a template which returns a date or time that remains fixed, rather than changing each time the page is browsed. For those cases there is substitution, which is done by adding subst: before the template name in the template tag. Substitution does exactly what its name suggests: rather than processing the template each time the page is browsed, substitution processes the template at the time the edit is saved, and replaces the template tag with the processed results.
For example, the template {{tc}} (as shown above) adds the letters "in" wherever it is placed. Thus, the wikitext bra{{tc}} will produce the word brain. The wikitext will always remain as bra{{tc}}, however, so if {{tc}} is changed so that it adds the letters "wn", the wikitext will produce brawn instead of brain. Substituting like so - bra{{subst:tc}} - will permanently change the wikitext to read brain, and later changes to the template {{tc}} will have no effect on the substituted text.
Common mistakes
URL problems
URLs can contain equals signs (=) e.g. http://some.page.org?key=value&key2=value2. However, the first equals sign in a template parameter listing is always treated as though it sets off a named template parameter. thus {{some template|http://some.page.org?key=value&key2=value2}} will act as though http://some.page.org?key is a parameter name, not the start of a URL. There are two workarounds for this problem:
- Use an explicit positional parameter reference: {{some template|1=http://some.page.org?key=value&key2=value2}}. the '1=' refers to the first positional parameter explicitly and will obviate the subsequent equals signs
- Use the special template {{=}}: {{some template|http://some.page.org?key{{=}}value&key{{=}}value2}}. This template returns an equals sign that is not parsed or interpreted by the wiki software.
Whitespace problems
Named parameters will automatically strip whitespace - spaces, tabs, carriage returns and line feeds, or other non-visible characters from a parameter. Unnamed parameters will retain all whitespace. This can cause odd formatting issues where the wrong behavior is expected.
Vertical pipe problems
The vertical pipe character (|) is used in templates (and parser functions) to separate parameters. If you need to provide a pipe character to a template parameter, then use the special template {{!}} which returns an unparsed pipe character, or use the HTML entity | for the pipe character.
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. The only real difference is that templates will normally be placed in the "Template:" namespace rather than the (unprefixed) main namespace. Anything that can be included on a normal page can be included on a template, including other templates. Beyond that, templates have access to programming features—parameters, parser functions, and variables—which allow for context-dependent use, and special tags that help control which information is transcluded and which is not.
When creating templates, it's best to follow a few simple principles:
- Choose a short, descriptive name. Some people suggest that generic template names be entirely in lowercase letters, and those for a specific book use the form Template:Book Name/Template Name, but there is currently no hard guideline.
- Make a quick search of template space or browse templates to make sure that the template you're creating hasn't already been done. It is sometimes easier and better to enhance an already existing template than to create a new template from scratch.
- Make sure your template is properly documented and included in the correct categories. (see below)
- Try to make your template modular: i.e. capable of standing on its own and in a variety of different page contexts, without breaking, producing poor output, or messing up a page's layout. In general, you want your template to be transparently useful to other editors—the more effort they have to put into understanding how your template is used, the less they will be willing to use it.
Template documentation
Categorizing your template and documenting it will make it easier for other editors to find and use.
- To add documentation, put the {{documentation}} template inside 'noinclude' tags on the template page. This will create a documentation subpage that you can edit
- Categories that apply to the template itself should be added to the template page (inside 'noinclude' tags, with the {{documentation}} template). Categories that are to be transcluded to the transclusion page should be placed on the template page inside 'includeonly' tags.
Parameters
Parameters are special codes that allow wikitext to be fed to a template; the template can be constructed to produce different outcomes depending on the values of the parameters it receives. Parameters may have names, or may be referenced by the position of values provided in the template tag (the order of the parameters in the template code is irrelevant). Parameters in a template take the form {{{...}}}, where the tripled curled-braces surround the name of a named parameter or the number of a positional parameter. Values entered for parameters can be quite long, and if needed the transclusion of an entire page may be used as the value for a parameter.
To see how parameters work, consider this example. Assume there is a template called 'peoplepets' that produces some text about people and their pets. A template tag for this template might look like the following:
- A. {{ peoplepets | John | Mary | age = 6 | Fido | small | kind = dog }}
- B. {{ peoplepets | Bill | Susan | age = 7 | Queenie | fat | kind = cat }}
The contents of the template itself, on the page Template:Peoplepets, looks as follows:
- {{{1}}} and {{{2}}} own a {{{4}}} {{{kind}}} named {{{3}}} who is {{{age}}} years old.
Thus, the two template tags above will transclude the following text, respectively:
- A. John and Mary own a small dog named Fido who is 6 years old.
- B. Bill and Susan own a fat cat named Queenie who is 7 years old.
Things to note:
- The numbering of positional parameters skips over named parameters (as with 'age' above)
- The leading and trailing spaces around the values of named parameters in the template tags are stripped by the template.
- This is not true for unnamed parameters, which preserve trailing and leading whitespace. However, browsers render multiple whitespace characters as a single space, so the extra spaces around 'Fido', 'fat' and the other unnamed parameter values aren't immediately visible. This can be confusing if unnamed parameters are used for something other than display, such as links.
- The order in which named parameter values are used in the template doesn't matter.
- The number of a positional parameter is treated as though it were a name: {{ peoplepets | John | ... }} could have been written {{ peoplepets | 1 = John | ... }}. This is useful when positional parameters need to be entered out of order, or when a position parameter value contains an equals sign.
- Values may be empty. Here the second positional parameter and the 'age' parameter have empty values:
- Template tag:{{ peoplepets | John || age = | Fido | small | kind = dog }}
- Produces (note the missing words): John and own a small dog named Fido who is years old.
- Values can remain unprovided. Here the 'kind' parameter has been omitted:
- Template tag: {{ peoplepets | John | Mary | age = 6 | Fido | small }}
- Produces (this displays the missing parameter): John and Mary own a small {{{kind}}} named Fido who is 6 years old.
Parameter defaults
Default values can be specified for parameters using the vertical pipe character: |. The above example template could be rewritten as follows (in which 'friend' is the default value for positional parameter 2, the 4th positional parameter defaults to emptiness, and the 'kind' of the pet defaults to 'dog'—see Template:Peoplepetsd):
- {{{1}}} and {{{2|friend}}} own a {{{4|}}} {{{kind|dog}}} named {{{3}}} who is {{{age}}} years old.
A template tag like the following: {{ peoplepetsd | Bill | age = 7 | 3=Queenie }} will then produce the phrase Bill and friend own a dog named Queenie who is 7 years old.
Note that the '3=' before the name of the dog is required, since the second positional parameter is not specified.
An empty value for a parameter will override a default value, producing an empty space. In other words, {{ peoplepetsd | Bill || kind=| age = 7 | 3=Queenie }} will then produce the phrase Bill and own a named Queenie who is 7 years old
Dummy parameters and tag layout
Parameters that are not used in the template are ignored if they are provided by the template tag. This was intended to prevent transclusions from breaking if a template is changed in a way that removes a parameter; there's no need to go to every page a template is transcluded onto and change the tags. This has an added benefit, however, of making some template tags more readable, through spacing, or by adding comments. Using {{t3d}}:
| Description | Text Entered | Result |
|---|---|---|
| Adding comments using template {{t3d}} | {{t3d |a|b|c| row 1
|d|e|f| row 2
|g|h|i| row 3
}}
|
a b c d e f |
Since {{t3d}} does not use parameters {{{4}}}, {{{8}}}, or {{{12}}} the 'row #' values have no effect on the produced wikitext. Dummy named parameters can be used in any template tag; simply choose an unused parameter name and add it into the tag as 'unusedname = value'. One special case of a named dummy parameter is to use an empty string as the parameter name.
Restrictions on parameters and parameter values
- Unnamed parameters cannot be assigned a value containing an equals sign (=); the parser will treat the equals sign as the assignment of a named parameter. There are several indirect means around this limitation:
- In the template, write the value as the default of an undefined parameter:
- {{{0}}}, where the ellipsis can be the number of an unused positional parameter, or can be a blank string (a null parameter).
- In the page, assign the values to the template parameters with one of the following methods:
- {{templatename| 1= a=b }}, where the '1=' notation explicitly names the first unnamed parameter.
- Use the special template {{=}}, e.g., {{template name| a{{=}}b }}
- Use the HTML entity for an equals sign: =. This is only useful for text representation; If the equals sign needs to be processed as an actual equals sign (as in another template) this approach won't work.
- In the template, write the value as the default of an undefined parameter:
- Parameter values cannot contain vertical pipe (|) characters; the parser will treat the pipe character as a separator rather than as text. Pipes are possible within wikilinks (country=[[United States|USA]]) or nested templates (e.g., volume= {{convert|30|acre.ft|m3}}). Indirect means around this limitation are as follows:
- Use the special template {{!}}, which returns a valid pipe character. Use this method if you need something that will be read as an actual pipe character (for instance, if you're using the parameter to modify the structure of a wikitext table)
- Use the HTML entity for a vertical pipe: |. This is only useful for text representation; If the pipe needs to be processed as an actual pipe, this approach won't work.
- Parameter values cannot contain unmatched sequential curled brackets - }} or {{. The parser will try to parse them as the beginning or ending of a template tag or parameter, and will throw errors somewhere. Parameters can, however, contain other parameters, magic words, or template tags.
- again, this can be circumvented using 'nowiki' tags or HTML entities.
Nesting templates
Templates may contain other templates – 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}}} }} jumped 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}}} jumped over...". As above, except the third positional parameter of Template:A is passed to the named parameter 'waldo' of Template:B.
A template can call itself, but will stop after one iteration to prevent an infinite loop.
Noinclude, includeonly, and onlyinclude
Several tags are available to control what does and doesn't get transcluded from a template. The three tags are noinclude, includeonly, and onlyinclude.
noinclude
The 'noinclude' tag is used to prevent text on the template page from being transcluded onto other pages. This is often used for:
- documentation
- categories that apply to the template itself
- interwiki links to related templates on other wikis.
Its use is straightforward:
- If this text were in a template page, this part would be transcluded
- <noinclude>but this text would not be transcluded</noinclude>
includeonly
The 'includeonly' tag is the opposite of the 'noinclude' tag. Text within an includeonly block is only included when the page is transcluded, it does not appear on the template page itself. This is frequently used for:
- categories that apply to the transcluding page
- hiding messy text or error messages that occur on the template page itself (often because parameters that need a value are undefined)
Its use is straightforward:
- If this text were in a template page, this part would appear on the template page and on the transclusion page
- <includeonly>but this text would only appear on the transclusion page</includeonly>
onlyinclude
The 'onlyinclude' tag literally only includes the material that is between the tags; anything else on the page - even text within 'includeonly' tags, will appear on the template page but will not be included. This is not frequently used, but might be useful when only a small bit of text in the middle of an otherwise large page is to be transcluded.
It is used like this:
- If this text were in a template page, this part would be visible there, but would not be transcluded
- <includeonly>This text would not be visible on the template page, nor would it be transcluded</includeonly>
- <onlyinclude>this text is all that would be transcluded</onlyinclude>
Variables
System variables take the format {{...}} where the enclosed text is always entirely capitalized. These provide information directly from the system itself: local dates and times, information about the current page, and even information about the wiki itself.
| 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}} | 3,482,088 |
| Timestamp of last revision | {{REVISIONTIMESTAMP}} | 20241027180451 |
The PAGENAME and NAMESPACE variables are particularly useful, and frequently used, to change template behavior based on context. For example, if the template includes a category (e.g. cleanup templates, which categorize 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.
Parser functions and modules
Parser functions are tools for performing simple branchings and text manipulation. They take one or more parameters and return a wikitext value based on the parameters. There are two basic forms for parser functions (distinguished by whether a pound sign follows the opening brackets):
- Core parser functions, of the form {{functionName: parameter | parameter | ... }}.
- Parser functions from an extension to the software, of the form {{#functionName: parameter | parameter | ... }}.
Parser functions are primarily used for the evaluation of parameters or variables, in order to produce different results in different contexts.
Core parser functions generally deal with text manipulation and specific project tasks.
| 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 Wikibooks URL | {{fullurl: pagename }} | //en.wikibooks.org/wiki/Pagename |
The extended features provide 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 | {{#expr: ( 27 * 46 / pi ) round 2 }} | 395.34 |
Other kinds of calculations and string manipulation functions, such as find and replace, can be performed by Module:String and other modules. Such modules similarly take one or more parameters.
| Description | Text Entered | Result |
|---|---|---|
| String replacement | {{#invoke:String|replace| 90 degrees | degrees | ° }} | 90 ° |
Other editing information
- If the first included character of a template is one of the Wiki markup characters :;*#, then it is processed as though it is at the beginning of a line (even when the template tag is not). This allows the creation of various kinds of lists in templates where the template may not always be in the correct place for a list. To avoid this effect use <nowiki>#</nowiki> or an HTML entity such as : for a colon. This is also useful in conjunction with definition lists.
- When a page called for transclusion is a redirect page, the redirect target is included instead.
Revision history of pages containing templates
Pages in the stored page history consist of wikitext with possible references to templates and images. When viewing an old version of a page, these refer to the current versions of the templates and images, if these still exist. Thus the former composite page is not reconstructed.
See also