User:Scartol/Scartol, on template use and design

Scartol, on template use and design

Welcome to my tutorial for making templates. Questions and comments are welcome, either here or on my talk page.

On Wikipedia, a template is a page that has the template prefix in front of its name, like this: Template:Example.

Templates are like any other page, except that they have a special feature built-in: whenever a template's name (without the prefix) appears {{within curly brackets just like this}}, in the source text of another page, it is automatically inserted at that spot when the other page is displayed. This feature is called transclusion.

Transclusion comes in handy when you want to display the same thing on multiple pages, whether it's a navigation box in an article, a menu at the top of your user pages, a task list displayed on the user pages of all the members of a WikiProject - pretty much anything! Another advantage of templates is that when you adjust your template (to update text, change the formatting, or add an announcement, for example), the adjustment appears on every page which includes the template.

Pages not in the template namespace can be transcluded too, but for those you have to include the namespace prefix of the page, like this: {{Wikipedia:Welcome}}. But if the page to be transcluded is in the main article space, you must put a colon (:) in front of the name, like this: {{:Humanism}}.

It's a good idea to have a sandbox open while you read this lesson, so that you can try things out for yourself as you go along. There are also some template sandboxes at {{X1}}, {{X2}} … {{X9}} which you may use – these are good places to start, to keep from adding dozens of never-to-be-used-again pages in the Wikipedia:Template namespace.

Basics

Templates can serve many, many functions from very basic to highly advanced. We'll start with the most simple elements and work our way up.

Basic linking

Let's start by linking to a sample template. This part is simple: In your sandbox, just type

[[Template:X9]]

and hit "Save page". You'll now have a link (Template:X9), which you can click to reach the page. It's just like linking to an article – the only difference is that you'll be working in the template namespace.

You can also add a link to a template by typing its name in braces, preceded by "tl|". In your sandbox, remove the first link you made and type:

{{tl|X9}}

and save. You'll get a link inside braces – {{X9}} – which looks a little different, but leads to the same place as the other one. (This format for listing the template is often used because the code looks different from other links, and it requires less typing.) We'll see why the "tl|" is necessary in a minute.

Note that if you create a link to a template which does not yet exist, you'll have a red link (just as with articles).

Basic editing

Click on the link for {{X9}} and select "Edit this page". (I usually do this in a new window or tab, so that I still have my sandbox open.) If there is already text on the {{X9}} page, delete it. Then type:

I'm learning how to make [[Wikipedia:Templates]].

Then include an edit summary ("Experimenting" is good) and hit "Save page". The {{X9}} page will look like any other page, with a link to this tutorial. Template pages can contain the same things as an article or userpage: text, links, pictures, even other templates. This can get confusing, but for now we'll keep it simple.

Basic transclusion

While it has a technical definition, in this case the basic idea behind transclusion is taking the data on a template and placing it within another page.

In your sandbox, underneath the {{tl|X9}} code, type:

{{X9}}

and save. You should see this:

{{X9}}

I'm learning how to make Wikipedia:Templates.

Hopefully you understand now why including the "tl|" code is important if you just want to create a link to the template – without those three characters, you're telling Wikipedia to transclude everything in the template.

Documentation

It's a good idea to include some sort of documentation (or "docs" as they're sometimes called) on how to use your template, in case someone else wants to use it too. The easiest way is to include the docs on the same page as your template, surrounded by <noinclude>…</noinclude> tags. (These will make sure your docs aren't included when the template is displayed.)

Go back to the {{X9}} template page and add the following at the bottom:

<noinclude>== Documentation ==
To add this template to a page, simply type the following code:

{{tl|X9}}

That's all there is to it!</noinclude>

and save. Now visitors to your template will be able to use it with ease.

The other way to provide docs is to make a separate page for them, and then include them in your template. The most common method is to make a subpage of your template called "/doc".

Go back to the {{X9}} template and remove the docs we just put in. Then type:

<noinclude>
{{template doc}}
</noinclude>

and save. You should get a box like this:

Documentation[create] [purge]

Editors can experiment in this template's sandbox (create | mirror) and testcases (create) pages.
Add categories to the /doc subpage. Subpages of this page.

Click on the "create" link – at the {{X9}} template, not here! – and you'll be taken to an editor for the page Template:X9/doc. Notice there is already some code on this page (this appears in every new template's docs); I guess editors want to limit uncategorized templates.

Under the "Usage" header, insert the following:

To add this template to a page, simply type the following code

{{tl|X9}}

That's all there is to it!

and save. Notice we don't have to use <noinclude>…</noinclude> tags here, since that's handled for us. Now when you reload the {{X9}} template, your doc page will be automatically included. (As you may have guessed, this is an example of a template within a template.)

Setting up a separate doc page makes the editing process easier in many cases. It also provides a good spot for "See also" links, as well as description of variables and/or examples. (We're coming to those.)

Images and tables

Templates can be useful for design purposes (especially on user pages and article infoboxes). Let's add a simple image to your sample template, just to see how it works. Along the way I'll show you some HTML code, which can be very handy.

Back at the {{X9}} template, type the following before the first line:

<table width=100% border=1><tr>
<td width=50%>[[Image:Maida arch.jpg|50px]]</td>
<td width=50%>

Then, after the line of text you wrote earlier ("I'm learning…"), add this code:

</td></tr></table>

and save. You should see the following:

I'm learning how to make Wikipedia:Templates.

The picture (which I took in the Italian village of Maida) and the text are now enclosed with the cells of a simple table. If you go back and reload your sandbox, the table should appear there as well.

In a nutshell, here's what the code does: The <table> tag is the beginning of the table. (Notice that at the end of the table there's a closing </table> tag – most HTML tags have a closing </whatever> counterpart.) Inside the <table> tag, we've included a width for the table (100% of the page) and a thickness for the border (1 pixel). After this, we need to indicate the start of a row (this is the <tr> tag). Then we use <td> for each cell of the table ("td" stands for Table Data cell).

Tables are good for layout because they are very easy to customize – you can learn all about tables at the wikibook. Notice that most tables used for layout have "border=0" in the code, so you can't see the structure behind it all.

CSS can also be used in template tables (using the format <td style="background:#CCCCCC">, for example).

Intermediate

Okay, let's knock it up a notch. Bam!

Parameters

In Wikipedia templates, a parameter is a variable, sort of like X in an algebra problem. Whatever you plug into the parameter spot is included when the template is rendered. Let's try it out.

Back in the {{X9}} template, delete the table code and add the following:

{{{1}}} is the best television show of all time.

The triple-braces around "1" make it a parameter. Now in your sandbox, underneath where you wrote {{X9}}, enter this code:

{{X9|The Simpsons}}

and save. You should see the following:

The Simpsons is the best television show of all time.

Wikipedia replaced the parameter from our template – {{{1}}} – with the information we included in the template name code. Try changing the code in your sandbox to:

{{X9|Monty Python's Flying Circus}}

Now let's add another parameter. Go back to the {{X9}} template and change it to say:

{{{1}}} is the best television show of all time, and {{{2}}} is the best character on the show.

Then change your sandbox to read:

{{X9|The Simpsons|Lisa}}

You should get:

The Simpsons is the best television show of all time, and Lisa is the best character on the show.

There are two things to notice here:

1. Default parameters are the numbers 1, 2, 3, etc. The numbers correspond to the order of the items in the template name code (separated by | symbols) – here "The Simpsons" is 1 and "Lisa" is 2. You can use words instead of numbers, but this requires more work. If you want to make {{{1}}} into {{{show}}}, for example, you'd need to change the code for the template name to read: {{X9|show="The Simpsons"}}.
2. Parameters can be styled and/or linked and/or include other parameters. Let's see an example of this.

Change the code in your sandbox to say:

{{X9|''[[The Simpsons]]''|'''[[Lisa Simpson]]'''}}

Now the line of text should have links to both The Simpsons and Lisa Simpson – the show's name should be in italics, and Lisa's name should be in bold.

Magic words

This isn't specific to templates, but you can also include a variety of meta-information by using so-called "Magic words". See this page for more information.

Subst(itution)

When you transclude Template A onto Page X, Wikipedia just copies whatever is in Template A and puts it right into Page X. If someone comes along and changes the contents of Template A, then Page X (and every other page on which it appears) will automatically be changed. This is a good thing, most of the time – it's one of the main reasons templates are so useful.

But suppose you just want to stamp the information from Template A onto Page X once, and have it remain the same forever, regardless of how Template A is changed in the future? This is why the gods created substitution.

Go back to your sandbox and – below the code {{X9|''[[The Simpsons]]''|'''[[Lisa Simpson]]'''}}, enter the following:

{{subst:X9|''[[The Simpsons]]''|'''[[Lisa Simpson]]'''}}

and save. You get the exact same thing. But suppose some lost soul – for some sad reason – wishes to disparage The Simpsons. Go into the {{X9}} template and change it to say:

{{{1}}} is the ''worst show ever'', and {{{2}}} is the ''worst character ever''.

Now save and reload your sandbox. The first line should read:

The Simpsons is the worst show ever, and Lisa Simpson is the worst character ever.

The second line, however, remains unchanged. Behold the power of subst!

This technique is often used for distributing Wikipedia:Barnstars and vandal warning templates, among other things.

Advanced

We'll go over two more advanced techniques here. Please note that there are many sophisticated possibilities for using template code – you can find detailed information here.

#if

One of the most basic parser functions is #if. This is a simple function to allow an "if/then" routine, like the kind used in most computer programming.

Case Statement

Case statements can involve more complicated parameter passing, when they involve this extra step.

Let's say you want to make a template which would allow the user to specify their preferences, and get a box like this:

My favorite country is Italy. My favorite city is Venice.

You could do it with parameters, but the user would have to add the links to Italy and Venice, and specify which pictures to use. The case statement allows an easier (although more limiting) method.

Go to your sandbox and add the following code:

{{tl|X9/countrycheck}}

{{tl|X9/citycheck}}

Now click on the first link – {{X9/countrycheck}} – (it might be red) and in the countrycheck page, insert the following (it may already be there; if so, make sure it matches):

{{#switch:{{lc:{{{1|}}}}}
|ita=[[Italy]]. [[Image:Flag of Italy.svg|50px]]
|saf=[[South Africa]]. [[Image:Flag of South Africa.svg|50px]]
}}

Then click on the second link – {{X9/citycheck}} – and add to (or verify) the citycheck page:

{{#switch:{{lc:{{{1|}}}}}
|ven=[[Venice]]. [[Image:Venezia 2004.jpg|50px]]
|joh=[[Johannesburg]]. [[Image:Joburg top.jpg|50px]]
|None of the above.
}}

Hopefully you can see where this is going. Now on the {{X9}} template page, blank the page and insert this code:

<table width=50% align=center border=1><tr><td align="center">
My favorite country is {{X9/countrycheck|{{{country}}}}}
<br>My favorite city is {{X9/citycheck|{{{city}}}}}
</td></tr></table>

Finally, go back to your sandbox and clear out the previous text. Replace it with:

{{X9
|country=ita
|city=ven
}}

You should get the box we started with:

My favorite country is Italy. My favorite city is Venice.

Now return to your sandbox and replace "ita" with "saf" and switch "ven" to "joh". You should see the alternative:

My favorite country is South Africa. My favorite city is Johannesburg.

What we've done, basically, is created pages (countrycheck and citycheck) which list the possible variables and what they'll put into the table. Then we put the code for the table into our template, with triple-brackets to mark the spot where a check must be done. Finally, the code for naming the template includes the names of our favorite country and city (in the code we established on the check pages).

Note that we also indicated a default ("None of the above"). If the user doesn't specify – or uses any other code than what we've allowed – the default is listed. (The default is also what a user sees when s/he goes to the countrycheck or citycheck page.) For this reason, it's very important to include complete docs for your user with the available options. This is also where examples are handy.

The lc: stands for lowercase, and allows you to use VEN and Ven as well as ven.[1]

The end

Congratulations – you've made it through the entire tutorial! I've taught you (mostly) everything I know about how to make and use templates. Please note that there are many users more skilled than myself, and it's entirely possible that I've provided some bogus information. (If so, please let me know so I can fix it.)

Now that you've finished all of these steps, you are entitled to display the following badge on your userpage. Just copy and paste the following code:

{{subst:TempTutorialBadge}}

You'll have this spiffy box on your user page (and you'll know why it does what it does):

This user has completed the Template Tutorial.

Thanks for your work on Wikipedia!

This page created and maintained by Scartol. He is to blame for any misinformation, erroneous claims, and/or offensive heresy.

See also

• Wikipedia:Transclusion/How Transclusion Works