Help:Writing Templates

This article provides some basic information on how to start writing a template. The article Help:Templates should probably be read first to provide basic information on what a template is and how a template is used.

Any page that it is included/transcluded into another one can, at some level, be considered a template. However, the power of templates lies in the use of parameters and variables. Without parameters and variables, a template will look exactly the same everywhere it is used; with them, the appearance of the template can be customized, either based upon information provided by an editor (parameters), or based upon other information such as the page's name (variables).

The simplest way to use a parameter or variable is to simply display it as part of the template. This article will primarily describe this type of basic use. Many more advanced options become available when functions are added into the template. These start to allow the template to alter the contents of a parameter, or make choices based on the value of a parameter. Only a few basic examples of functions will be mentioned; the See Also section provides links to various Wikimedia articles with much more comprehensive information.

Types of Parameters

The term "parameter" is being used here to describe information that is provided by an editor when they add a template to a page. For example, if you want to write a template that formats some text, the text would be that template's parameter. Additional parameters might be used to specify the color or size of the text.

To use a parameter, first an editor needs to provide it when they use the template. Take the case of someone using the Example template:

{{Example|italic=Example with the italic parameter}}

Here "Example with the italic parameter" is the value being used, and it's being assigned to the parameter "italic". That parameter can then be displayed within the template. This is done using the code {{{italic}}}. Every time the code sees {{{italic}}}, it gets replaced by "Example with the italic parameter", in this case. In the editor, the example template looks like (simplified a bit here to show just what's relevant at this point):

This is an example of a template. ''{{{italic}}}''

So what ends up displayed on the page is:

First unnamed parameter:
Italic parameter: Example with the italic parameter

When writing a template, you can choose basically any name (containing any number of letters or numbers) for your parameters, or you can choose to use numbered parameters instead.

Named Parameters

The example above used a named parameter, in this case named "italic".

• The advantage of a named parameter is that it is easy to keep track of which parameter is which. Editors can provide the parameters in any order they like.
• The disadvantage of a named parameter is that it requires extra typing for editors.

As a result, named parameters are most useful in templates that have more than one or two parameters. For example, when creating a template to display a table (i.e., Place Summary), named parameters are used. Each parameter corresponds to an individual entry in the table.

Note that named parameters are case-sensitive. So "italic", "Italic", and "ITALIC" are treated as three different parameter names. It is best to stick with one style for your parameter names. Unfortunately, some templates on this site use all lowercase for parameter names, while other templates have implemented parameters where the first letter of the name is capitalized. At this point, trying to impose consistency would be more trouble than it's worth.

Numbered Parameters

Parameters can also be provided without providing any name, in which case they are assigned numbers based on their order in the template. So using the (non-existent) NumberTemplate in the following example:

{{NumberTemplate|first|second|another|more|many}}

"first" would be assigned to parameter {{{1}}}, "second" to {{{2}}}, "another" to {{{3}}}, "more" to {{{4}}}, and "many" to {{{5}}}.

• The advantage of a numbered parameter is that editors to need to do less typing to use it. The above example is much easier to enter than {{NumberTemplate|param1=first|param2=second|param3=another|param4=more|param5=many}}
• The disadvantage is that editors need to remember exactly which parameter goes in which order, and cannot easily skip parameters they don't want to use.

Therefore, numbered parameters are best in templates that only have one or two parameters. For example, the template FC, used to change a font's color, takes two numbered parameters. The first parameter is always the color; the second is always the text to be displayed, e.g.:

{{FC|red|red text}}

Mixing Names and Numbers

Both named and numbered parameters can be used within the same template, if desired. This is typically useful in a template that is normally used with a single parameter, but occasionally needs to have extra options specified.

For example, the Template:Place Link template is set up so that it can normally be used by just providing the place name, e.g.:

{{Place Link|Sancre Tor}}

But there are a couple of additional named parameters, allowing the template to also be used in any of the following ways:

{{Place Link|Sancre Tor|game=Oblivion}}

{{Place Link|Sancre Tor|altname=The Fortress of Sancre Tor}}

{{Place Link|Sancre Tor|game=Oblivion|altname=The Fortress of Sancre Tor}}

{{Place Link|Sancre Tor|altname=The Fortress of Sancre Tor|game=Oblivion}}

In all of these cases "Sancre Tor" is assigned to the parameter {{{1}}}, "Oblivion" is assigned to {{{game}}}, and "The Fortress of Sancre Tor" is assigned to {{{altname}}}.

As one final twist, it is even possible to make a parameter be either numbered or named. So the Place Link template will also accept the format:

{{Place Link|place=Sancre Tor}}

The internals of how to make either a number or a name work are explained in the next section

Displaying Parameters

The most straightforward way to display a parameter in your template is using the syntax

{{{parameter}}}

In many situations this syntax is completely sufficient for what needs to be done, and the rest of this section can be skipped. However, this syntax does not work so well when you want to allow parameters to be optional. If an editor leaves out a parameter in a template using this syntax, the result is generally ugly: the original {{{parameter}}} text from the template is just left in place. So, for example,

{{{FC|red}}}

produces

{{{2}}}

The second required parameter, namely the text to display, was left out, so the parameter text from the template is just displayed as is.

To make a parameter optional the pipe symbol, |, is used to indicate "or," in the sense of "display parameter x if it was provided, or else ...." Some examples of how this can be used are:

• {{{text|}}}: If the parameter text was not provided, then nothing at all gets displayed.
• {{{1|Example text}}}: If one numbered parameter was provided, display the parameter; if not, display the text "Example text".
• {{{text|{{{Text}}}}}}: If the parameter text was not provided, then display the parameter Text. If Text was also not provided, then {{{Text}}} will be displayed.
• {{{text|{{{1}}}}}}: If the parameter text was not provided, then display the first numbered parameter. This is how templates like Template:Place Link can allow parameters to be provided either with or without their name.
• {{{namesp|{{NAMESPACE}}}}}. If the parameter namesp was not provided, then use the default value, which is the page's namespace (using the NAMESPACE variable, described in the next section)
• {{{text|{{{Text|{{{TEXT|{{{TexT|None}}}}}}}}}}}}: Check the parameters text, Text, TEXT, and TexT in order, and display the first one that was provided. If none were provided, then display "None".

As the last example clearly shows, this can start to get very ugly. You need to pay close attention to the number of braces to make sure that the template works properly. So even though it might be convenient for editors to be able to provide a parameter name typed any way they like, trying to add that type of flexibility to the template makes it much harder to write, read, and maintain it.

Variables

In addition to the custom parameters that you can add to your template, there are also multiple built-in variables. These variables are used just like parameters, except that they take only two pairs of braces, rather than the three used by parameters. (Inserting templates, adding built-in variables, and using functions all require just two braces; only parameters need three).

The most commonly used variables are:

• {{NAMESPACE}}: Inserts the namespace of the current page. Useful for creating automatic links in articles and templates that will be used by multiple games.
• {{PAGENAME}}: Inserts the name of the current page, without the namespace.

All variables are evaluated based upon the page on which the template has been used. So when the Template:Example is inserted onto this page, the namespace is "Help" and the page name is "Writing Templates".

Wikimedia provides a complete list of the available variables.

Functions

Adding functions to templates adds a lot of power, but also a fair bit of complexity. Functions provide ways to modify parameters and variables, and provide ways to make other parts of the template change depending upon parameters or other settings.

In some ways, functions look and act like mini-templates. In particular, the syntax of a typical function is {{#function: ... | ... | ...}}: two pairs of braces surround the function, and parameters are separated by "|" symbols. Function names always start with # (at least in all recent versions of the wiki software). A colon (:) follows the function name (not a pipe symbol) and separates the function name from the first parameter.

The most commonly used functions are:

• #if: used to make different text appear depending upon the situation. The official syntax is:

{{ #if: <condition string> | <then text> | <else text> }}

If <condition string> is not empty, <then text> is displayed; otherwise <else text> is displayed. The <else text> is optional, in which case the second pipe symbol can be dropped. The <condition string> here is simply checked to see whether or not the string is empty; advanced comparisons are not done using this function. An example of how it might be used is:

{{#if:{{{class|}}}|This NPC's class is {{{class}}}|This NPC does not have a class}}

If the parameter class has been provided and is not empty, then the first string will be displayed. If the template call either did not contain "|class=..." anywhere, or only provided an empty value, "|class=", then the second string is displayed.

• #ifeq: a more advanced if function, used when you need to check if two strings are the same. The official syntax is:

{{ #ifeq: <text 1> | <text 2> | <equal text> | <not equal text> }}

If <text 1> and <text 2> are identical (case and spelling), then the <equal text> is displayed, otherwise <not equal text> is displayed. Again, the <not equal text> and the final "|" symbol can be dropped if not needed. An example used of #ifeq is:

{{#ifeq:{{NAMESPACE}}|Shivering|This game is named Shivering Isles|This game is named {{NAMESPACE}}}}

• More advanced if functions are also available, namely #ifexist, #ifexpr, and #switch.

The See Also section provides links to various Wikimedia articles describing all of the available functions.

See Also

Wikimedia provides the most complete documentation available on wiki templates. Some of the Wikimedia articles are:

• Template help: Covers most of the same material as this article, but in more depth.
• Magic words: Summarizes of all the built-in variables, functions, and other useful miscellany.
• Parser functions: Documents the core wiki functions (limited in number, mainly for changing case, getting URLs).
• ParserFunctions: Documents add-on wiki functions, which include some of the most useful functions (if, ifeq, math, time).
• StringFunctions: Documents more add-on wiki functions, useful for altering text.
• Advanced templates: Advanced (and often esoteric) ways to use templates.