Guide/using templates

A Guide to Using Templates
__TOC__
===Purpose of this Guide===
I am going to explain to you, the eager, new, Retributions Blade™ contributor, how to use templates (not how to write them!) and, perhaps more importantly, how to interpret the arcane chicken scratches Councellor calls documentation.
What is a Template?
A template is just a wiki page, same as any other, but it lives in the Template: namespace so that the system knows that it can be transcluded in other pages. To make them more flexible and generally useful, there is a whole group of special commands that can be used to conditionally transclude the contents so that the template becomes aware of the context it finds itself in.
===What is transclusion?===
Transclusion is just a fancy word they came up with that means the template is semi-interpreted, or translated, then the result is included in the page that called it before that page is compiled.
===Why do I want to use Templates?===
Because templates make it possible for us to enforce certain style-guidelines across the entire Website, and allow us to group together content that needs to be used in many places so all we have to remember is the template name and not what all that stuff inside it means.
===Where can I find their names and what they do?===
Councellor has thoughtfully put together a set of guides, by game, that list all the templates he has created that pertain to that game, along with one for templates that apply to the entire Website.
*Global Template Users Guide
*EQ2 Template Users Guide for EverQuest II
===How do I call a Template?===
Very similar to the format for linking to a page, but template calls use curly braces instead of square brackets. Here is the general form of a template call, in what programmers call a syntax diagram:
{{TemplateName|value|value|name=value}}
Parameters being passed to a Template can be named or unnamed, and are separated with the pipe symbol, |. Unnamed parameters are numbered in the order they are encountered but named parameters use the name they are assigned. This is important because as a template designer, Councellor tries to mix and match named and unnamed parameters (or fields) in the most efficient way to make the template the easiest to use. If you see an equal sign, whatever is to the left is the parameter name and must not be changed! Whatever is to the right, up to the next pipe or the final curly braces, is the value.
Templates can also be called on multiple lines. The call starts with the double left curly braces, then has the name of the template, then the parameters and ends with a pipe and 2 right curly braces. Notice that a parameter does not have to have a value! It can be blank, or even undefined!
{{TemplateName|value
|name_1=value
|name_2=
|}}
Why the pipe before the ending braces, and why only on vertically-defined calls? - This is a little peccadillo of our wiki implementation. If you don't add the pipe the previous parameter will be passed with a linefeed on the end of it which seriously messes up most templates!
===Can you be less technical?===
Not very, so long as we are talking in generalities, so let's get specific. Here is a call with no named fields, just numbered ones. I will show you the usage diagram first, then the call with real values in it, then what it looks like when used on a page.
Usage: {{EQ2 Coin|gold|silver|copper}}
<nowiki>{{EQ2 Coin|1|2|3}}
This renders as: 1 2 3
===What does (list) and (comma list) mean in the Parameter descriptions?===
Frequently I will use a single field to hold a list of items, usually links to other records. In the past there was only one way to do this in the templates. The user had to build the list, with the full linking, and then I would just paste that to the output at the correct spot. The following is an example.
(list) method:
|relquests=
*[[FR Quest:Doohicky]]
*[[FR Quest:Thingamajig]]
*[[FR Quest:Just Another Quest]]
You can easily see that this would become a real pain when doing large amounts of data entry. But there is a better way. IF the parameter description says (comma list), then the field can be a comma-delimited list of items. The template recognizes the older format and uses it as-is when it sees one so no backtracking and conversion of existing pages is required. There is a limit to the number of items that can be handled in the comma-delimited style (10, at this time) and if the list is longer than it can handle the message "List Overflow" is displayed on the last line.
(comma list) method:
|relquests=Doohicky,Thingamajig, Just Another Quest
Notice that the list can handle a space after a comma, but does not require it.