User:Anon126/How-to/Templates

The code that keeps Wikipedia running smoothly

If you've been editing Wikipedia, there's no doubt that you've seen this code: some text between double braces. These are templates. Knowing how to use templates is important for editing Wikipedia.

What are templates for?
Templates contain pieces of code that are used over and over again. It would be tedious to enter this every single time it was used, so a shorter bit of code that refers to the template is used instead.

The simplest case
The easiest (and probably most common) way to use a template is to add double braces around the template name, like so:

This produces:

As with articles on Wikipedia, the case of the first letter doesn't matter, so does the same thing.

Adding a template in this way has a technical name, transclusion. What this means is that the software automatically fetches the code for the template and displays it on the page. If the template is updated, then the page with the transcluded template will update as well.

Where is the template code?
You might think that the code for the template above would be fetched from Example. But that's an article about examples. So where did that box come from?

Answer: Template:Example. Pages starting with Template: are reserved for making templates.

The page should also have documentation, that is, information about how and when to use the template. So if you're ever curious about a template, add Template: to the beginning to check it out.

Non-Template: templates
It possible to transclude pages that don't start with Template:. Templates are not required to have such a name. It's also possible to transclude pages that aren't templates (the software makes no distinction), but this is not recommended.

To transclude an article (not recommended), add a colon inside the parentheses:

To transclude a non-article (including templates that don't start with Template:), use the full page name:

Parameters
Sometimes additional information is added to change how the template looks or acts. These are parameters, and the additional information provided is a parameter's value. They take the form:

Vertical bars (also called "pipes") are used to separate the name of the template and the parameters. The text of parameters can be displayed or used as an option to determine other aspects of appearance. The documentation on the template page should explain exactly what each parameter does.

Sometimes parameters have names. These look like:

Named parameters can be given in any order, while unnamed parameters must be given in a specific order. Unnamed parameters can also have "names," which are 1, 2, 3, and so on. So it is technically possible to use:

But this gets confusing, so please don't.

Special characters
If a parameter value has an equals sign, that becomes a problem for unnamed parameters. Take this example:

What you want is for the first unnamed parameter to have the value 1+1=2, but the software actually sees this as a parameter with the name 1+1 and the value 2.

There are two ways to fix this:


 * 1) Convert it into a named parameter with the number-name trick:
 * 2) Use the template, which is designed for equals signs in parameter values:

If a parameter value has a vertical bar, the way to get around it is to use. (That is an exclamation mark, not a literal vertical bar.)

Substitution
Substitution is the other way to include a template in a page, as opposed to transclusion. Instead of fetching the template code every time, the template code is actually in the page itself. This means that once a template is substituted onto the page, it will be updated if the template changes.

To do this, add subst: before the template name.

This achieves the same result:

But when the the page was saved, the template was replaced with its code. Again, the template code will not be updated, so if Template:Example is updated after this page was written, the first box (transcluded) will be updated, but the second one (substituted) will not. (For the record, this version was used.)

Transclusion versus substitution
Templates can change, and often they are improved. So why substitute a template? There are a few reasons:


 * Discussion messages: In a discussion (such as on a talk page), substituting templates allows for a static record. This ensures that when others look through the history or an archive, they will see exactly what the participants saw.
 * Exceptions are and a few others, which specifically say "you can remove the  template". Obviously if the template is substituted, then this note doesn't make sense, so these templates should be transcluded.
 * Technical purposes: Some templates must be substituted to take advantage of technical features. Such features are many, and beyond the scope of this page. The documentation for the template will state when a template must be substituted, so just check the template page for what to do.

If a template does not meet these conditions, it should be transcluded. Some templates even have to be for technical purposes. (Again, check the documentation.)