Help:Template

A template is a page that is created to be included on other pages. This is usually done for material that needs to be displayed on multiple pages. Templates are usually used to display infoboxes, navboxes, and notice messages.

Templates are usually added to pages through a method called transclusion, where the contents of the template are added to a page by referencing the template in the wikitext of the page using a special syntax that causes the contents of the template to be added to the page. When a template is transcluded, any changes made to the template will be automatically propagated to all of the pages the template is transcluded on.

Templates are usually stored in the Template namespace. Pages are considered part of this namespace if their title begins with Template: (note the colon).

Using templates
Templates can be used on a page by editing the target page and typing in  where you want the template to appear. This will cause the contents of the page "Template:Name of template" to appear in that spot. This is known as transclusion, and is the typical way most templates are used. Like regular wikilinks, the first letter of the template name is not case-sensitive.

Templates in the Template namespace can be transcluded with or without the Template: prefix; it does not matter. Both  and   will both transclude the contents of "Template:Foo" onto the page. Templates that are stored in other namespaces need to have the namespace prefix attached. For example, a template that is being stored at "User:Foo/Template" must be called with. Typing in  will cause the contents of "Template:Foo/Template" to be used instead.

If you try to use a template that doesn't currently exist, the template will be displayed as a red link, just like links to any other non-existent page. Clicking on this link will take you to a page where you can create the template page in question.

Parameters
Many templates allow for the use of parameters that can, depending on the template, control different aspects of how the template is used, displayed, or functions on the page. The syntax for displaying parameters is, where   is the name of the template, and each parameter may contain just a value (known as unnamed parameters) or be in the form   (known as named parameters). Template parameters are dependent on the coding of the template and will usually differ between templates. A template's documentation may provide information on the parameters it offers and how to use them.

For example, the FontColor template uses two unnamed parameters to control its output. This template provides a simple way of changing the text's background and color. The template documentation explains how to use the template in more detail. The template can be used like the following:

If you type  on a page, it would produce the following:

And if you were to type, it would produce:

The first parameter sets the color of the text, while the second parameter is used for the text that should be colored. These two parameters normally need to be specified in the correct order in the wikitext for them to work. For example,  will not work correctly.

Unnamed parameters are technically given a cardinal number as a name, so in the above example, the actual names for the parameters above are  and. As such,  will work the same as. When using parameters like this, the ordering of the parameters in the wikitext does not matter, so  will work correctly.

Named parameters have a defined name and must be called by that name in order to work. The Metabox template, for instance, utilizes named parameters to control and display its output. If you were to type:

It would produce:

Parameters don't need to be in the same line; it is okay for them to be separated by line breaks. This is useful if there are a lot of named parameters, making it easier to read the wikitext later on.

As mentioned previously, it doesn't matter what order named parameters are listed in in the wikitext of the page.

Substitution
Most templates are used through transclusion, which is where the template's contents are automatically passed on to the page it is being used on. If the template is edited, the changes will be reflected on all pages that the template was transcluded on automatically, without any further edits necessary. For example, if "Template:XYZ" contained the text "The quick brown fox", and  was added to the page "Animals", then the page "Animals" would contain the text "The quick brown fox" where   was added. If "Template:XYZ" was edited to read "The quick brown fox jumps over the lazy dog", the "Animals" page would automatically update to read "The quick brown fox jumps over the lazy dog".

Substitution is an alternative method of using templates. When a template is substituted instead of being transcluded, the template's actual contents will be copied over to the page it is used on and will become a part of the page, and will no longer be automatically updated if the template is edited. In the above example, if  was used on the "Animals" page, when the edit is saved, the   code in the wikitext of the page will automatically change to "The quick brown fox", which is the contents of "Template:XYZ". If "Template:XYZ" is later edited to read "The quick brown fox jumps over the lazy dog", the "Animals" page will not reflect those changes because it no longer transcludes "Template:XYZ", and will continue to read "The quick brown fox".

Creating templates
Templates are created like any other page. Most templates are located in the Template namespace, so their page titles should begin with Template: (note the colon) in order to be organized correctly. Many users who create templates for their own personal use or for testing purposes may also create them in a subpage of their userpage. Templates can technically be created on any page, but in practice it is best to create templates only in the two locations mentioned above.

Basic content transclusion
The most basic template simply displays a prewritten or predefined text, image, table, or other form of page content, which can then be quickly used on multiple pages. This is as simple as writing the content you want the template to contain in the template page. For example, if we wanted to use the following text in our template... "Have you guessed the riddle yet?" the Hatter said, turning to Alice again. "No, I give it up," Alice replied: "what's the answer?" "I haven't the slightest idea," said the Hatter. "Nor I," said the March Hare. Alice sighed wearily. "I think you might do something better with the time," she said, "than wasting it in asking riddles that have no answers." ...this is as simple as creating a template containing that text. For example, we can create a page titled "Template:Alice in Wonderland pointless riddle" containing just the text above, and we have our first template. Whenever we type  onto a page, that text will appear.

Adding parameters
Template parameters are specified in the template code by using three curly braces instead of the usual two for calling templates.


 * Unnamed parameters are created by using the codes,  , and so forth. When the template is used, these parameters must either be used in order, or by using numbers as parameter names. For example, if "Template:Thank you" were to contain the code  , then typing   or   on a page would produce "Thank you for your effort. Sincerely, Your Boss."
 * Named parameters are created by using the code . For example, if "Template:Thank you" were to contain the code , then typing   on a page would produce "Thank you for your effort. Sincerely, Your Boss."

These parameter codes will be replaced by whatever value is given to them when the parameter is used, even if it is blank. If the parameter isn't called at all, no replacement will take place, and the templates will show the raw parameter code, which may be undesirable. For instance, in the above example, simply writing  will cause " Thank you for . Sincerely, . " or " Thank you for . Sincerely, . " to appear. You can rectify this in two ways:


 * You can specify a default parameter value that will be shown if the parameter isn't used or is left blank. You can do this by adding a pipe character (|) after the name of the parameter but before the closing curly braces. For example,  will produce "Thank you for your effort" if   is used on a page. You can also set it so that the parameter simply doesn't display anything when it isn't used by just providing a pipe character. For example,   will produce "Thank you for " if   is used on a page.
 * You can use the  parser function to either set a default value or don't produce any output if the parameter isn't used or is left blank. For example,   will produce "Thank you for your effort" if   or   is used on a page, and "Thank you for being awesome" if   is used.

Magic words and parser functions
Templates often make good use of magic words and parser functions, which are special features of wiki markup that can give instructions to the wiki software to perform certain basic tasks, such as checking to see if a parameter is filled or performing mathematical operations.

Nesting templates
Templates can be used in other templates; this is called "nesting". This is often used to build templates that are made out of other templates, and allows for the use of "meta" templates that power other templates. For example, Metabox is a "meta" template used to build other templates like Note and Info. Nested templates can accept parameters, but those parameters must be explicitly specified by the template that is being used on the page. For example, if "Template:A" contained the text " " and "Template:B" contained the text " ", then typing in  will not work properly, but   will.

You can use a template within itself (i.e. "Template:A" containing the text " ", but it will stop after one iteration to prevent an infinite loop.

Template nesting is a useful and powerful feature, but it can quickly increase the complexity of templates, as well as make it harder to diagnose issues. Nevertheless, nesting templates makes it easier to write new templates and update existing ones.

Noinclude, includeonly, and onlyinclude
By default, when a template is used, all of the text in it gets included in the target page. This can cause problems or unwanted behavior if the template page contains items that should normally only be seen on the template page itself, and not included with other pages. The following tags allow editors to control what gets shown when a template is used and what doesn't:


 * will not include any of the contents placed inside of them onto target pages when the template is used. This is typically used to surround template documentation, which should normally only be seen on the template page and not used on other pages.
 * will include any of the contents placed inside of them onto target pages when the template is used, but said content will not be shown on the template page.
 * will include any of the contents placed inside of them onto target pages and on the template page itself, but anything not placed between these tags are not included onto target pages.

Documentation
A template's documentation explains what the template does and how to use it. Documentation is a crucial part of developing templates and you should generally endeavour to write documentation for your templates as much as possible. Although documentation is not technically required for the template to work, not including documentation can be discourteous to other editors, as they will need to look at the wikitext of the template in order to figure out how to use it.

Documentation can be included on the template page by using the Documentation template. This template should be surrounded by  tags so it doesn't get transcluded into other pages. Ideally, this should be placed at the very bottom of the template, below the last line of code. For example:

Foo. Bar. Foo. Bar.

A template's documentation page is located at the /doc subpage of the template page. For example, the /doc subpage of "Template:A" would be "Template:A/doc". The Documentation template will automatically transclude the contents of the /doc subpage onto the main template page.

Categorizing templates
Templates should be categorized appropriately so other editors can easily find them. They should ideally be categorized in one of the sub-categories of the main template category. Categories added to a template should be located on its documentation subpage, wrapped in  tags, and not placed on the main template page. Placing categories on the documentation page allows them to be edited by non-administrators if the template is protected from editing, while the  tags prevent the documentation subpage itself from being categorized. Because the Documentation template is located between  tags, the categories will be added to the template page but not on the pages the template is used on.

Categorizing pages using templates
Templates can be configured to add pages to categories. This is often done for maintenance or tracking categories. When doing so, it is best to surround the categories with  tags to keep the template itself from being categorized. For example, a template can add a page to a maintenance category if it is being used incorrectly.

Categories added by a template will appear on pages like normal, but the categories will not appear in the wikitext of the page, which may confuse new editors. If the category added by the template is incorrect, and there are multiple templates in use on a page, it may take more experienced editors some time to be able to find the template adding the category. Note that the HotCat script will not be able to modify categories added to a page via templates.

Redirects
Template redirects will work properly, and will point to the destination page of the redirect. For example, if "Template:A" was redirected to "Template:Apple", typing  on a page will have the same effect as typing. This works for parameters and for substituted templates as well.

Template limits
When templates are expanded and rendered in HTML for viewing in your browser, they use up resources on the servers. To prevent excessively long and complex pages that take a long time to load, and to prevent denial-of-service attacks caused by the excessive use of complex templates, the MediaWiki software that powers is configured to stop expanding templates after the page they are used on exceeds certain pre-set limits. Once these limits are reached, any additional templates used on the page will not be expanded and will display incorrectly.

You can view the limits—and how far the current page has gone to reaching those limits—by doing one of the following:


 * 1) Edit the page using the source editor, then preview the page. The template limits will be shown at the bottom of the page under.
 * 2) Right-click on the page and select your browser's "View Source" option to view the HTML source of the page. The template limits and their current values will be shown under an HTML comment titled "NewPP limit report". For example:

In general, the higher the numbers, the longer it takes for the page to load, and the more complex the page is considered to be. Some level of complexity is to be expected on pages that use complex templates, but when creating templates it is often useful to keep speed and performance in mind. For example, consider keeping templates short and efficient, and avoid inserting redundant code. Editors can also help with these template limits by avoiding the excessive use of complex templates and consider using fewer templates, if possible. For example, typing  by hand is better for performance than using the Reflist template.

Lua-based templates
A growing number of templates on are being written in Lua rather than wikitext. Lua is a programming language that is designed to be simple to use and learn. This functionality is provided by the Scribunto extension.

Lua code is stored in the module namespace and not the template namespace. Templates will call these modules using the  parser function. For example, Module:Bananas can be used in a template by typing  on a template.