UtterAccess HomeUtterAccess Wiki

Welcome Guest ( Log In | Register )

Custom Search
Edit Discussion
> Help:Templates    
Templates (Help)


Templates are a very powerful tool for wiki authoring purposes. They provide standardized, parameterized markup inclusion into our wiki pages. This helps greatly with uniform appearances and with simplifying many highly complex markup tasks. Templates are used widely throughout the UA Wiki - this article is intended to help familiarize with them.

This article mainly deals with calling conventions for existing templates. Template Authoring deserves it's own article.


Contents

Syntax

You may think of a Template as a VBA Function, where the call and it's parameters are wrapped in a set of of double curly braces.

The basic syntax for showing a template is by including the template keyword inside a set of double curly braces.

{{TemplateKeyword}}

The above example, when used in your page's markup, would process the text from the Template:TemplateKeyword page and put it into your page. Do note that there is a fair amount of specialized syntax in an actual template's page. If you navigate to a template's page and view the page, it likely will not represent the final result when the template is "brought in" to your page.

Template keywords are always the same as the template page title. If a template's page title is renamed, so is it's callable keyword.

Parameters

Templates accept parameters by delimiting them inside the curly braces, after the template keyword. The delimiter for parameters in template calls is the Pipe character: |

Examples of parameterized template calls:

{{TemplateKeyword|Param1|Param2|Param3}}
{{TemplateKeyword|Param1||Param3}}
{{TemplateKeyword|NamedParam=Value}}

The first example passes parameters 1, 2 and 3 as Param1, Param2 and Param3, respectively. The second example passes parameters 1, 2 and 3 as Param1, Null, Param3, repsectively. The third example shows passing the Named Parameter NamedParam with a value of Value.

Ordinal Parameters

Ordinal Parameters are parameters without names. They are specified by ordinal position and must be listed in the order expected by the template. Ordinal parameters are ideal where multiple parameters of the same type may be used. For example, for a template that displays a list, essentially each parameter is the same "object", thus an ordinal parameter may make more sense.

Ordinal parameters are generally easier from a calling convention standpoint as well, because there is no need to memorize the parameter name (and it's inherent case-sensitivity).

Variable Parameter Counts

Note that markup languages are incapable of running loops, and therefore it is not possible for a template call to accept a truely variant number of parameters. However, due to optional parameters and conditional checking within the template, many template parameters are simulated as such, usually with a an overflow limit set significantly higher than would ideally be used, and usually with a means to indentify that an overflow has been reached (red bold text stating so on the rendered page, for instance). Template Parameter limits can always be expanded to accept a higher count.

Named Parameters

Named Parameters are parameters which are specified by a name, rather than by ordinal position. Parameter names are case sensitive. To specify a named parameter in a template call, use the Parameter Name, followed by the Equals sign, followed by the value you want to specify. For example:

{{TemplateName|ThisParam=ThatValue}}

The order of parameters is irrelevant when using named parameters, with the exception that all parameters must follow the template keyword and initial delimiter.

Optional Parameters

Optional Parameters can be omitted from the call entirely (except a numbered parameter with trailing values required). The optional status of a given parameter is dictated only by the template itself. Technicallly, all parameters are optional - it is legal to omit all parameters, but the rendering that the template supplies may be unsightly at best if the template indeed required the parameter.

Optional parameters can be omitted completely or can be left blank. If the paramters are Ordinal (Numbered), and a parameter is required after the one in question, you must include a set of blank separators, as depicted in example 2 in the #Paramters section.


Calling Conventions

There's two ways to include template markup in your code: via inline calling and via the line-break method. One way is not better than the other, though each have their pros and cons, and many templates will require one calling method or the other for proper formatting (note that line breaks between the {{ }} are passed to the template and processed as well as any other text).

Inline Calling

The inline calling method is the one that's been shown in examples thus far. It is very common on short, simple calls that have no or few parameters. In many cases, the inline template call is included directly into a line of text:

...this is an example of {{MakeMeBold|Inline Calling}} of a template

While this method is commonly used for non-complex calls, in some cases it's required by the template for formatting purposes, as even line breaks are processed. More complex inline templates can be initially typed using the line-break method for ease of understanding, followed by a removal of the line breaks before saving.

Line-Break Calling

The Line-Break calling method is common for complex templates, either ones that contain many parameters, or ones whose parameters contains complex markup. The Line Break method is usually implemented by putting the opening braces and keyword on the first line, followed by each applicable parameter on it's own line after that, with the closing braces on the last line of the call. For example, the CoreNotificationBox template is much more easily implemented using this calling convention:

{{CoreNotificationBox
|FlagColor=red
|BackgroundColor=white
|Image=[[Image:WarningStrong.gif]]
|Text=
This is the notification text. Notice how it starts with a line break after the parameter = sign for readability.
}}

The above method can be used with Ordinal (Numbered) parameters as well, so long as the order of usage stays the same.

That same template call, when used inline, is not so easy to read:

{{CoreNotificationBox|FlagColor=red|BackgroundColo=white|Image=[[Image:WarningStrong.gif|Text=This is the notification text. Notice how it starts with a line break after the parameter = sign for readability.}}


Where to find Documentation

Template Documentation is at the mercy of the template author. However, most templates, when viewed directly through the Templates namespace, have provisions for documentation. Template documentation is shown in the aqua/green display area of the template page, and generally includes callable keywords, its general purpose, parameter listings, usage examples, related content and other pertinent information.

Commonly used templates may have additional and possibly more user-friendly documentation in the Help category's Template Help subcategory.

A list of all templates can be found here: Special Pages:All Templates Please be extremely careful while making changes to existing templates... some templates may be present on ever page in the wiki!

Edit Discussion
Custom Search
Thank you for your support!
This page has been accessed 3,942 times.  This page was last modified 15:06, 12 January 2012 by Jack Leach.   Disclaimers