FANDOM


For Sandstar12

This is a short tutorial on template coding. I know there is already an official Help article on it, but I'd like to keep this simple and with many examples, especially to help new users.

What is a Template?

A template is a piece of stored content (some text, a banner, a table, a userbox) that can be included in any article by simply referring to it. Its main advantages:

  • if you want to add a certain pre-formatted element to several articles, just create a template with the code, and refer to the template in the articles (instead of pasting the code itself into each article)
  • if you want to change something in that element, you have to change just the template (instead of changing all articles where the element was posted)
  • templates are flexible, and can process all kind of user input


Creating and Using a Template

Create a blank page with its name beginning with "Template:". For example, "Template:Hello". Write your code in that page, and save it. For instance, paste this code in Template:Hello:

Hello!


Now, whenever you put {{Hello}} in an article (this is called a transclusion), the following will appear...

You write this... This appears...
{{Hello}}
Hello!

Note: It is not necessary to create a template in the Template namespace to work. You can create a page f.i. in your own userspace, like User:MyName/MyTemplate, and transclude it to other pages as {{User:MyName/MyTemplate}}. It will work exactly as if it was in the Template namespace, including accepting parameters and running functions.

Now, let's see some more advanced usage.


Parameters

A handy feature of templates is that they can accept parameters; values that modify the displaying of the template, without you needing to modify the entire code every time. Let us modify the above template, so it will accept an user input.


Numbered Parameters

You can make the template to accept parameters by adding {{{1}}}, {{{2}}} etc to its code, values that will be read as user input. Modify the above code as follows:

Hello, {{{1}}}!


You can see that I added "{{{1}}}" there. The template will read a parameter (separated with a | from its name) and display it at that location.

You write this... This appears...
{{Hello|Peter}}
Hello, Peter!
{{Hello|Ann}}
Hello, Ann!
{{Hello}}
Hello, {{{1}}}!


The style problem you might observe: if you did not provide a parameter, the template displays {{{1}}}. You should add a default value that is displayed when no parameter is entered as {{{1|defaultvalue}}} (or you can just add {{{1|}}} if you want to have an empty default value):

Hello, {{{1|User}}}!


Now if no text is entered, "User" will be displayed (that is a default value I defined next to the "1").

You write this... This appears...
{{Hello}}
Hello, User!


You can add multiple parameters; for instance, let's add a second one for the time of day:

Good {{{2|afternoon}}}, {{{1|User}}}!


The template will read two parameters, separated with |, and display it at the indicated location. If no text is entered, the default values ("User" and "afternoon") will be displayed.

You write this... This appears...
{{Hello|Peter|morning}}
Good morning, Peter!
{{Hello|Ann|evening}}
Good evening, Ann!
{{Hello}}
Good afternoon, User!


Of course, the parameter given by the user can be used for anything, not just a piece of text to be displayed. For example, you can use it to set a color:

{|style="background:{{{2|#FFFFFF}}}"|Hello, {{{1|User}}}!|}


In this case, the second parameter is used to set a background color.

You write this... This appears...
{{Hello|Peter|#9AD0FF}}
Hello, Peter!
{{Hello|Ann|pink}}
Hello, Ann!


Named Parameters

Instead of numbers (1, 2 etc), you can use strings to refer to parameters. For instance, change the above code to:

Good {{{time|afternoon}}}, {{{name|User}}}!


Now, when calling the template, it is not enough to input parameters with pipes between them; we need to specify their names:

You write this... This appears...
{{Hello|name=Peter|time=morning}}
Good morning, Peter!
{{Hello|name=Ann|time=evening}}
Good evening, Ann!
{{Hello}}
Good afternoon, User!


The advantage of this method: when you have lots of input (such as in Template:Charcat), the named parameters give an easy and organized overview about which data is needed and where (on the other hand, numbered parameters are recommended if you have few elements).

You can use both numbered and named parameters in the same template.


Magic Parameters

These are parameters where the result is given by the system, not by the user - for example, the current time. A list of these is here. These are always written in uppercase. Now write this in the template:

Hello! Current time is {{CURRENTTIME}}. You are reading {{PAGENAME}} on {{SITENAME}}.


And the result:

You write this... This appears...
{{Hello}}
Hello! Current time is 03:58.
You are reading Waitingforspring/Templates
on Warriors Wiki.


Functions

Functions evaluate an input (compare a parameter against others, test if a parameter was entered etc). For a full list of functions, check here.


Testing for Input

You can use the #if function to test if a string (usually an user input) is present or not. The syntax is:

{{#if: string | result1 | result0 }}

If the string is present (not empty), this function will return result1; if it is not present (empty), it will return result0.


For example, consider the following code in Template:Hello:

{{#if: {{{1|}}} | Hello, {{{1}}}! | No name was given }}


And the result:

You write this... This appears...
{{Hello|Peter}}
Hello, Peter!
{{Hello|Ann}}
Hello, Ann!
{{Hello}}
No name was given

Note that capitalization of strings does matter when doing comparisons! For instance, "peter" is not the same as "Peter". If you want a workaround, use the lc function (see below) to convert the input to lowercase.


Comparison

You can compare a string (usually an user input) to another:

{{#ifeq: string | test | result1 | result0 }}

If the string is the same as test, this function will return result1; if it is not the same, it will return result0.

For example, consider Template:Hello that greets the user only if his name is Peter:

{{#ifeq: {{{1|}}} | Peter | Hello, {{{1}}}! | You are not Peter! }}


And it gives:

You write this... This appears...
{{Hello|Peter}}
Hello, Peter!
{{Hello|Ann}}
You are not Peter!
{{Hello}}
You are not Peter!


Switch

If you want to compare a string against several other ones, use the #switch function - it is much cleaner and faster than writing #ifeq rows for all possible cases.

{{#switch: string | test1=result1 | test2=result2 |...| default }}

If the string is the same as test1, the function returns result1; if it is the same as test2, the function returns result2 and so on. The last item is the default value, returned when the string does not match with any of the test cases.

For example, consider Template:Season that translates the name of season from humanspeak to catspeak. We need to compare the input against four strings:

{{#switch: {{{1|}}}
 | spring=It is newleaf
 | summer=It is greenleaf
 | autumn=It is leaf-fall
 | winter=It is leafbare
 | Unknown season}}


And it gives:

You write this... This appears...
{{Season|summer}}
It is greenleaf
{{Season|winter}}
It is leafbare
{{Season|whatever}}
Unknown season


Math Operations

The #expr function evaluates a mathematical expression and returns the result.

For example, {{#expr: 1 + 2 }} returns 3.

If you use arguments as input, don't forget to add "0" as a default value, or else you will get a "missing operand" error if the argument is empty.

For example, write {{#expr: 1 + {{{1|0}}} }} instead of {{#expr: 1 + {{{1|}}} }}


The #ifexpr function is similar to #ifeq, but instead of comparing two strings, it evaluates a mathematical expression to find if it is true or false, and returns one of the two predefined results (similar to combining #expr with #ifeq).

For example, {{#ifexpr: 8 + 6 > 10 | true | false }} returns true (as 8+6 is greater than 10),
but, {{#ifexpr: 2 + 5 > 10 | true | false }} returns false (as 2+5 is not greater than 10).


String Operations

There are functions that take a string (piece of text) as input and do various operations with them (finding a letter in it, selecting a portion of it, and so on). A full list of these functions can be found here, I just list the most common ones and their simple usage.

Function What Does It Do Example
{{lc: string }}
{{uc: string }}
Converts the input string to lower case
Converts the input string to upper case
{{lc:Sol}} gives sol
{{uc:Sol}} gives SOL
{{#len: string }} Calculates the length of the input string {{#len:Brambleclaw}} gives 11
{{#len: }} gives 0
{{#pos: string | term }} Returns the position (starting from 0) of the first occurrence of the search term in the input string {{#pos:Brambleclaw|m}} gives 3
{{#pos:Brambleclaw|claw}} gives 7
{{#sub: string | start | length }} Returns a sub-string starting at start with a defined length
A length of 0 means no truncation
{{#sub:Brambleclaw|5|3}} gives lec
{{#sub:Brambleclaw|5|0}} gives leclaw
{{#replace: string | term | new }} Searches for the given term in the string and replaces it with a new term {{#replace:Brambleclaw|r|w}} gives Bwambleclaw
{{#replace:Brambleclaw|claw|star}} gives Bramblestar
{{formatnum: number }}
{{formatnum: string | R }}
Converts a number into a string
Converts a string into a number
{{formatnum:1234}} gives 1,234
{{formatnum:1,234|R}} gives 1234


Here is an example of using these functions in a template. Let's write a Template:sc function that converts a string to small caps style (e.g. writes BRAMBLECLAW instead of Brambleclaw). How to do this?

  • Select the first letter with the #sub function
  • Capitalize it with uc
  • Select the other part of the string with the #sub function
  • Capitalize it with uc
  • Put it between the <small> and </small> tags

Put that together and get:

{{#sub:{{uc:{{{1|}}}}}|0|1}}<small>{{#sub:{{uc:{{{1|}}}}}|1|0}}</small>


And the result...

You write this... This appears...
{{sc|sunset}}
SUNSET
{{sc|Dark River}}
DARK RIVER
{{sc|Dark}} {{sc|River}}
DARK RIVER



And of course, you can combine all kinds of functions. For instance, here is a Template:Leader that tests if a cat is leader (has -star in their name) or not. First, combine #ifexpr and #len to find if the name is longer than 4 characters. If yes, use #pos to search for "star", and #if to process the result:

{{#ifexpr: {{#len: {{{1|}}} }} > 4 
 | {{{1|}}} is {{#if: {{#pos: {{{1|}}} | star }} | | not }} a leader
 | Name too short}}


And what it does...

You write this... This appears...
{{Leader|Firestar}}
Firestar is a leader
{{Leader|Graystripe}}
Graystripe is not a leader
{{Leader|Sol}}
Name too short


Other Tips

Some handy tips and workarounds for coding templates...

Tables in Functions

Just like templates, tables (and some other pieces of code) also use pipes as separators. Let's say you have the following table:

{| 
 | row 1, cell 1
 | row 1, cell 2
 |-
 | row 2, cell 1
 | row 2, cell 2
 |}

Now, let's say you wish to display the second row only if a parameter, like {{{1}}}, is present. Whatever table code is within the conditional, you must substitute all its pipes with {{!}}, to avoid them being "mistaken" for the separators of the conditional, getting:

{| 
 | row 1, cell 1
 | row 1, cell 2
 {{#if: {{{1|}}} |
  {{!}}-
  {{!}} row 2, cell 1
  {{!}} row 2, cell 2
  | }}
 |}

Functions in Tags

Sometimes, in a template you wish to wrap functions between HTML tags (such as "ref", "gallery" etc), for instance:

<ref>
 {{some functions here}}
</ref>

However, this will not always work, due to a limitation in the parser. You can fix this by using the #tag function instead of the regular tags:

{{#tag:ref|
 {{some functions here}}
}}


Organizing the Template Page

The above examples work when you insert the code in an article, such as {{Hello}}. However, if you check the template page itself (Template:Hello), it might be a mess, and users cannot figure out what is the template for, and how to use it.

The trick is to use "noinclude" and "includeonly" tags

  • Anything between "noinclude" tags will appear on the template page (Template:Hello), but not in transclusions ({{Hello}}) - use these to write explanations on the page
  • Anything between "includeonly" tags will appear only in transclusions, but not on the template page - use it to hide the template's code
  • Anything else appears both on the template page and in the transclusions

Consider the following code in Template:Hello:

<noinclude>This template greets the user</noinclude>
<includeonly>Hello, {{{1|User}}}!</includeonly>


And the result...

You do this... This appears...
view Template:Hello
This template greets the user
include {{Hello|Peter}} in an article
Hello, Peter!
include {{Hello}} in an article
Hello, User!


Further Advice

This tutorial should give you enough information to start writing your own simple templates - of course, you need some practice to get the hang of it. What you should do:

  • Experiment with template code in a sandbox - see what the different functions do and what can you use them for
  • Look at the code of existing templates, trying to figure out what they do
  • Feel free to ask for help if you are stuck


See Also

Community content is available under CC-BY-SA unless otherwise noted.