Wiki:Templates-How To
| ||||
|
First, let me say this here before rale does... wiki is not a programming language. It is a compiled markup language. That said, it has many, but not all, of the basic functions required of all programming languages.
Template Naming
All templates must be defined in the Template: namespace, and must conform to any other naming restrictions for any other wiki page.
Transclusion
When the wiki compiler encounters 2 left curly braces, like {{, it considers anything from there until it sees the closing braces, }}, as the definition and call for a template. The compiler then expands the named template while substituting any values defined within the call. This process is called transclusion. Pages that are not found in the Template: namespace are not eligible for transclusion.
To the template writer it is temping to think of the templates as functions or sub-routines that are being called, but this is not the case and thinking that it is can lead to errors. It is, literally, simply a fetch of the text on the named template page and it's inclusion in the current page at the place the template was named. The fields in the template definition are substituted, as text, as the page continues to expand until all such transclusions are completed and this takes place before any actual compilation occurs.
Actual functions are treated exactly the same, but rather than simply expanding the contents of the function, the function is evaluated and the return of the function is included in the page .
This is the generic syntax diagram for all Template definitions:
{{template name|value|value_n|name=value|name_n=value_n}}
Templates may also be referenced in a vertical format, which makes them easier to read, but the ending line must start with a pipe (|), thus:
{{template name
|value
|value_n
|name=value
|name_n=value_n
|}}
If there is no equals sign then it is a numbered value and the value will be substituted whenever that number is encountered in the expanding template. The markup for a value anchor is {{{n|default}}} where n is the number of the value. Values encountered this way are numbered in the sequence they appear in the definition regardless of any intervening named values.
The presence of an equals sign (=) signals that whatever is to the left is a label, or name, and whatever is to the right, until the next pipe (|) or the end of the definition (}}), is a value that will be substituted wherever the name is encountered. The markup for a named value's anchor is {{{name|default}}}.
Both of the above have a definable default value, which may be blank, that will be used if a value or named value is called for but the calling definition has no value matching that number or name.
It may be appropriate to think of these as constants, for the values cannot be modified inside of the template. They are merely substituted where the markup has identified their position.
Template Contents
A template may contain any combination of plain text, HTML, and Wiki markup, including transclusion definitions for other templates (called sub-templates).
Template Limitations
There are hard limits to the number of templates that can be called within a single page (about 7000), and the number of template calls that can be tracked on a single layer of the compilation. If you exceed these limits the system will tell you so. Go back and use direct wiki links when possible (rather than linkers). The counter of calls includes functions as well as actual templates. For this purpose #if and those like it count as calls so if a template has some decisions and calls other templates in some branches that inturn have other decisions, and if the base page has several of these the total template count can add up rather fast. This is the reason it is NOT recommended to use linkers on large Quest Series pages, or to use them very sparingly.
Best Practices
A well-built template page needs documentation. This should include a usage diagram to show how it should be called, a list of all the parameters with descriptions of their meanings, links to any categories created by the template, links to Images, or the categories the images can be found in (where appropriate), and a signature identifying the template author, how to contact him, and where others of his templates can be found.
Please remember that, in most cases, you are not the only person that will ever use your template, so be clear and remember you are talking to someone who does not know what you are thinking.
Gotchas
- It is inadvisable to use wiki table markup inside a template, as it can result in undesired results when a wiki table expands inside of another wiki table. Use HTML for all tables inside of a template.
- If a value being defined in a template call definition might contain another template call definition, it is inadvisable to use a numbered value, as this can result in the expanded text containing an equals sign which would cause the continuing expansion to mis-interpret the template in odd ways. Instead, always use named values if the value might contain another template call.
- If a value, named or numbered, might contain wiki formatting characters that require them to start the line, such as :, * or #, be sure that the value anchor begins in the first column of a new line.
 |
more to come |