How Templates Work
Table of contents |
About Templates
Templates provide functionality for common tasks. Basically they allow including one page into another. They can also have parameters.
See also:
Using Templates
Syntax for calling a template from the current page:
- put the template's pagename into two curly braces like this: {{pagename}}
- the pagename can also be written like in bracket links, i.e. using spaces and other allowed other characters: {{ Page - Name }}
Template pages must have a name that ends in 'template', e.g. TestTemplate or "Player (Template)" (the name gets reduced to PlayerTemplate).
When calling the template the "Template" part has to be omitted. E.g. in order to call the above templates you would write {{Test}} and {{Player}}.
Template parameters
Parameters are set within the curly braces and are separated by a vertical bar '|'. Parameters can either have a name or be anonymous (in that case they are numbered starting at '1').
- Named parameters are of the form 'key = value'
- Example: {{ person | born=1829}}
- Explanation: call the template 'person' with parameter 'born' set to '1829'
- Anonymous parameters are of the form 'value'
- Example: {{ person | Shusaku}}
- Explanation: call the template 'person' with the first anonymous parameter (1) set to 'Shusaku'
- Mixing named and anonymous parameters is allowed.
- Example: {{ person | born = 1829 | Shusaku | died=1862 |Kuwahara Torajiro }}
- Explanation: call template 'person' with parameter 'born' set to '1829', parameter 'died' to '1862', first anonymous parameter (1) set to 'Shusaku', and second one (2) set to 'Kuwahara Torajiro'.
Unlike other wiki syntax the template call can be spread over several lines. The call is anything from the start '{{' to the end '}}'. When a template has several parameters it is encouraged and best practice to write each parameter on a line of its own like this:
{{ person | Shusaku | born = 1829 | died = 1862 }}
Defining Templates
Actually, any page can be used as template. There is no special page type or keyword associated with templates. Nonetheless it is suggested to:
- use designated pages as templates and not just any page.
- keep the content of the template page to the required minimum.
Defining the template's content
Within a page's content only the area marked by <template> ... </template> is treated as the template's content. I.e. anything outside this marked area is not included and can be used as documentation / description of the template.
Using parameters
In order to use parameters passed to the template, the parameter's name is written in triple curly braces like this '{{{parameter}}}'.
- Anonymous parameters are written with numbers like this: '{{{1}}}', '{{{2}}}', '{{{3}}}', ...
- Named parameters are written like this '{{{name}}}'.
- Valid parameter names may contain the characters a-z, 0-9, '-' and '_'. No other characters are allowed for parameter names (e.g. space).
Template logic
Within the template you can use simple if-else constructs.
- Syntax: <if parameter> .... <else> .... </if>
- The <else> is optional.
- parameter stands for the name of a parameter to the template (without ‘{{{’ and ‘}}}’).
- If the parameter is set, then the text after the <if> is used.
- If the parameter is not set, then the text after the <else> is used.
This syntax may be spread over several lines. IFs may be nested.
Templates within templates
Calling templates from within another template is allowed. Note that GoWiki enforces an arbitrary nesting limit.
Advanced template topics
How replacement / inclusion works
GoWiki performs all template inclusions and parameter substitutions before the wiki markup is transformed into an HTML page for the viewer.
GoWiki performs these steps:
- Find innermost template in page.
- For this template
- Handle template logic (if-else), i.e. only the proper text remains
- Substitute parameters
- Find innermost template (within template content)
- if a template is found, then continue with step 2
- Substitute result with template call in original page
- If there are still templates in the page, then continue with step 1
The substitution works exactly on the character bounderies. For example, assume that the original page content looks like this:
text before->>{{template | param=text}}<<-text after
And that the template looks like this:
<template>#Start# **{{{param}}}** #End#</template>
Then the result (before the transformation into HTML) looks like this:
text before->>#Start# **text** #End#<<-text after
Possible pitfalls
- Keep in mind that the text of the template is replaced verbatim. For example, if your template contains a newline (or you start a new line after the <template> definition,) then this new line is inserted into the resulting wiki markup. This may affect the page layout.
- As described in the chapter above, parameter substitution and template substitution (for recursive calls) are intertwined. Be aware of possible side-effects, when the template or parameter content contains chars like '{' or '|'.
See also: