Help:Templates

http://assets.openuru.org/wiki/icons/help-48x48.png

Templates

"Templates" may be a misleading term for many people, who may well be thinking of the document templates used by Microsoft Word or Open Office Writer. In the wiki context a template is a page that can be included within another page. The most common application is where a design element (such as graphic feature, a block of formatted text, etc.) is to be repeated on several pages. Instead of repeating the text and wiki markup on every page, you can place the common element in a page by itself (the template) and then at the point you wish that element to appear in your main article, you simply reference the template.

For example, to display the "?" icon that appears at the top of this page you need some wiki markup that looks like this:

<div style="float: left; padding-right: 20px">http://assets.openuru.org/wiki/icons/help-48x48.png</div>

It's not the easiest thing to remember, and if you use it on several pages and at some time find you want to change the icon or amend the spacing, then you'll need to find every page it's used on and edit each one. If you place that code on a template page, then you only ever need to apply edits in one place and you can vastly simplify using the icon.

If you're familiar with text macros, then you can think of templates in the same way.

Using Templates

Most people will only ever need to use a template that has already been created, so they never need to worry about the intricacies of making a "good template".

To use a template in your document, you simply give the template name inside double curly brackets at the point where you want the template contents to appear, e.g. the "?" icon on this page is placed there using {{help}}.

A list of the available templates for this wiki is given on the Page Creation Tools page: Many of these have some simple documentation on usage, to help you choose the correct one to use. As needs grow on this wiki then the list of templates will be expanded.

Creating Templates

Templates are all created within the Template namespace. This is necessary as the {{template_name}} notation actually assumes that the template's full page name is Template:template_name (but see Transclusion, below).

The best way start on a new template is to type Template:New_Template_Name into the Search box on the navigation panel at the left and then follow the "You can create this page" link.

Obviously, the key thing you need to do is put the content you want for your template into your template document. Remember that you can make use of HTML markup to apply formatting, such as controlling placement or changing colours. The following example comes from the template {{draft}}, which displays a banner showing that a page is an unfinished draft:

{{clear}}<div style="background-color: #ffe0e0; border: none; 
text-align: left; margin-right: 50px; margin-left: 50px; padding: 2px">
<div style="float: left; padding-left: 5px; padding-right: 10px;">
http://assets.openuru.org/wiki/icons/note-edit-48x48.png</div>'''This page 
contains draft content'''<br>The content of this page is a "work-in-progress" 
and is subject to change. Do not place undue reliance on the completeness or 
accuracy of the material presented here!{{clear}}</div>

You will see that this template code actually uses another template, {{clear}} to ensure that any previously set "floats" (e.g. images that have been floated to the left or right edge of the page) are cleared before inserting the banner.

This is as much as you need to do to create a working template. However, it is usually helpful to others to provide some form of documentation, and a bit more work is needed for this.

Template Documentation

If you view the template page itself, all you will see is the same content that would be included in a page that uses that template: We need to find a way around that, and there are two special "tags" that we can employ:

<includeonly> ... </includeonly>
<noinclude> ... </noinclude>

Anything enclosed inside the <includeonly> tags will only be used when the template is included in another page, i.e. it will not be shown when you view the template itself. Conversely, anything inside the <noinclude> tags will only appear when you view the template. Be careful not to overlap or nest these tags as the result is unpredictable.

This means you can now do something similar to this:

<includeonly>Template content goes here</includeonly><noinclude>
Description of template goes here</noinclude

Remember these tags effectively define three classes of content rather than two:

• Material that only appears when the Template is used in another page
• Material that only appears when the Template is viewed, and
• Material that can appear in both cases

Because of this, be careful of how you use "whitespace", like new lines outside of the <noinclude> tags as this will still be displayed when the template is used, and may well give undesired results.

Transcluded Documentation

By convention, the documentation for a template is normally held on a separate page with a "/doc" suffix and transcluded into the Template page. So, if a Template is named Template:My_Template then the documentation will be in Template:My_Template/doc, and this could be included as a template within your template as in this example:

<includeonly>My_Template content goes here</includeonly><noinclude>
{{My_Template/doc}}</noinclude

However, there is a special template, Template:Documentation that you should use instead as this simplifies maintaining consistent links between templates and their documentation. The Documentation template is aware of the page name where it is being used and automatically generates a link to a corresponding page_name/doc template. If page_name/doc does not exist, then a link is inserted to allow you to create the documentation page.

<includeonly>My_Template content goes here</includeonly><noinclude>
{{documentation}}</noinclude

You will see examples of this if you review the existing templates. The question may be "Why would you keep the documentation on a different page?" The answer is that you can then protect the template itself against edits, while leaving the description page open for users to add to or improve the documentation.

Transclusion

Transclusion is slightly overblown term to describe the process of including one document within another, and is the basic priciple by which Templates work.

It may sometimes be necessary to include project pages (rather than Template pages) within another document. This can come about for any of a number of reasons:

• The document is very large and breaking it up helps with managing the editing.
• It may be necessary to protect some sections against edits while leaving other parts open for edits.
• You may have a project specific index or similar that you want to appear in every document.

These cases don't really fall into the "global" scope that Templates are intended for, so placing these included (transcluded) documents in the Template namespace is inappropriate, and probably just creating these in the main namespace will be the more correct approach, although others namespaces could be used depending on the circumstances.

Referencing Namespaces

We've noted above that the {{...}} notation assumes the use of the Template namespace. Let's say you want to attach a section from your "User" page as a signature block on each of your pages: First, edit your "User" page (follow the link on your name at the very top of the wiki screen) and make sure the everything that you don't want to show in your signature block is wrapped inside <noinclude>...</noinclude> tags. Now include your "User" page in your articles using {{User:My_Username}}, remembering to include the User: namespace declaration.

Referencing the "Main" Namespace

Declaring the namespace works for all non-Template transclusions, but there is a slight complication when working with pages in the main (i.e. default) namespace, in that there is no assigned "name" for the namespace - it is a NULL. The answer here is actually quite simple: You include the colon in the page name, but omit the namespace name, e.g. {{:My_Included_Page}}.