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 actully 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. 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 unexpected results.

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, as in this example:

<includeonly>My_Template content goes here</includeonly><noinclude>
{{My_Template/doc}}</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"

Author Note: There is a way I could partly automate the creation of the documentation page and linking it to the Template page, but it requires the installation of a wiki extension that is not presently available on this site.

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.

For the more general case, where it may be necessary to include

http://assets.openuru.org/wiki/icons/wip_30x30.PNG

Content to be advised.