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:.

Templates are like any other page, except that they have a special feature built-in: whenever a template's name (without the prefix) appears, 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:. 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:.

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 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: 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 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 X9 code, type: and save. You should see this:
 * I'm learning how to make Templates.
 * I'm learning how to make 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 … 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&#x003E; == Documentation == To add this template to a page, simply type the following code:

X9

That's all there is to it! </noinclude&#x003E; 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&#x003E;

</noinclude&#x003E; and save. You should get a box like this:

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

X9

That's all there is to it! and save. Notice we don't have to use … 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: and save. You should see the following:

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 tag – most HTML tags have a closing counterpart.) Inside the 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:

X9/countrycheck

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):

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

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

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

You should get the box we started with:

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

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.

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:

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

Thanks for your work on Wikipedia!

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