Help:Templates
From WikiWOOD
If you have standard texts or formats you want to include on several pages, the template feature should be used. Doing so creates a standard 'look' to all pages on the wiki.
Templates are a useful and powerful tool, but can be confusing to new users, and even experienced users can have difficulty making sense of the more complex ones. Templates should therefore be accompanied by documentation to improve usability, and should not be edited without care.
Contents |
Using a template
Templates are wiki pages which can be used in other pages in three ways:
{{Name}}includes the content of Template:Name at the moment the page containing it is fetched.{{subst:Name}}inserts the content of Template:Name into the code of the page in a form that is editable normally after you have saved your text.{{msgnw:Name}}when the page containing it is fetched, includes Template:Name in a form that displays it as raw wiki syntax, like<nowiki>does.
Using parameters in templates
| Template with numbered parameters | |
'''A little thank you...'''<br>
<small>for {{{1}}}.<br>
hugs, {{{2}}}</small>
| |
| You type | You get |
{{Thankyou|all your hard work|Joe}}
| |
| with named parameters | |
'''A little thank you...'''<br>
<small>for {{{reason}}}.<br>
hugs, {{{signature}}}</small>
| |
| You type | You get |
{{Thankyou
|reason=all your hard work
|signature=Joe}}
| |
You can define parameters in templates either numbered as {{{1}}} or named {{{param}}}.
Example: You want a little thank you note you can put on the talk page of other users. It will contain a reason and your signature. You could create Template:Thankyou to enter your text, as in the example in the table.
When using the template on a page, you fill in the parameter values, separated by a pipe char (|): {{Thankyou|all your hard work|Joe}}. For named parameters use "name=value" pairs separated by a pipe char: {{Thankyou|reason=all your hard work|signature=Joe}}. The advantage of using named parameters in your template is that they are flexible in order. It also makes the template easier to understand if you have many parameters. If you want to change the order of numbered parameters, you have to mention them explicitly: {{Thankyou|2=Joe|1=all your hard work}}.
You can also provide default values for parameters, i.e. values that are going to be used if no value is provided for a parameter. For example, {{{reason|all your hard work}}} would result in "all your hard work" if no value was provided for the parameter reason.
Editing templates
Many templates employ intricate features of template syntax and parser functions[1]. You must therefore familiarise yourself with its setup before editing the template, and understand how the code works, and why it does it. If your edit causes unexpected problems, please undo it quickly, as the template may appear on a large number of pages. It is sometimes a good idea to discuss changes with previous editors of the template. You might also want to use 'What links here' to see how various pages are using the template.
Special Coding
Categories and interwiki links
- To place the template itself into a category, add the
[[Category:Category name]]code on the doc subpage inside an<includeonly>...</includeonly>section.
- To make the template place an article into a category (when the article includes the template), add the
[[Category:Category name]]code inside an<includeonly>...</includeonly>section on the template page. This is useful on things like maintenance templates to create a category of pages that need maintenance.
- To create an interwiki link for the template itself, add the
[[Languagecode:Template name]]code inside an<includeonly>...</includeonly>section on the doc subpage. (Multiple languages are not currently implemented on this wiki)
- To place the doc subpage into a category, add the
[[Category:Category name]]code inside a<noinclude>...</noinclude>section on the doc subpage.
Controlling template inclusion
You can control template inclusion by the use of <noinclude> and
<includeonly> tags.
Anything between <noinclude> and </noinclude> will be processed and displayed only when the page is being viewed directly, not included.
Possible applications are:
- Categorising templates
- Interlanguage links to similar templates in other languages
- Explanatory text about how to use the template
The converse is <includeonly>. Text between <includeonly> and
</includeonly> will be processed and displayed only when the page is
being included. The obvious application is to add all pages containing a given template to a category, without putting the template itself into that category.
Note: when you change the categories applied by a template, the categorization of the pages that use that template may not be updated until some time later: this is handled by the job queue.
Creating a template
Templates are just another wikipage and you create them like any other wiki page. They must be in the Template namespace, are therefore have to be prefixed with Template:
The template may be very simple, perhaps just a single line of text with some wiki markup. It might allow for some parameters to be passed to it as described above. More complex templates may include some Parser Functions[2].
Template documentation
Every template should be accompanied by documentation which should explain what a template does and how to use it. It should be simple enough that a user without complete knowledge of the intricacies of template syntax – which includes many experienced contributors who focus their attention elsewhere – can use it correctly. This is especially true in the case of very widely-used templates.
Template documentation is kept in a subpage of the template itself, Template:template_name/doc. This is then transcluded at the end of the template page. This separates the often complex template code from the documentation, making the documentation easier to edit. It also allows templates to be protected where necessary, while allowing anyone to edit the documentation.
We use a particular method to link the two pages properly. This automatically displays the documentation on the template page. The skeleton of a new documentation subpage can be automatically preloaded by following the method outlined below.
Linking to documentation from the template page
When the template itself has been created, place the following code immediately after the last line of your template code:
[--last line of your template code--]<noinclude>
{{Documentation}}
<!-- PLEASE ADD THIS TEMPLATE'S CATEGORIES AND INTERWIKIS TO THE /doc SUBPAGE, THANKS -->
</noinclude>
Important: Make sure the opening <noinclude> begins on the same line as the last character of the template code or text and not on a new line. Otherwise, extra space will be inserted below the template when it is used, which is usually not wanted.
This will transclude the documentation subpage at the bottom of the template page. When it is first saved, and you have not yet created the documentation subpage, it will display a 'create' link. This will open the documentation subpage in edit mode, with the skeleton of a documentation page which you can edit. It includes vital code described below:
Documentation subpage layout and code
The following code is automatically preloaded when you use the method described above.
{{Documentation subpage
|maintemplatename=Template:your_template_name
|documenttext={{communitybox|Templates}}
<!-- BEGIN TEMPLATE DOCUMENTATION HERE-->
__NOTOC__ <!-- delete this if page long and TOC needed-->
==Purpose==
(Mandatory)
==Parameters==
(Mandatory, or 'None')
==Usage examples==
(Mandatory)
==Related templates==
(optional)
==Full blank declaration==
(only where there are many parameters, such as infoboxes)
==Resources==
(mainly for infobox templates; sources for data)
==Future expansion==
(mainly for infobox templates; how to add more data fields)
<!-- END TEMPLATE DOCUMENTATION HERE-->
}}
<!-- CATEGORY FOR THIS /DOC PAGE. NO NEED TO CHANGE THIS!! -->
<noinclude>[[Category:Template documentation|{{PAGENAME}}]]</noinclude>
<includeonly>
<!-- PLEASE ADD CATEGORIES HERE, THANKS. -->
[[Category:Templates|{{PAGENAME}}]]
<!-- (CHANGE THIS TO A MORE SPECIFIC CATEGORY, THEN DELETE THIS COMMENT, THANKS)-->
<!-- PLEASE ADD INTERWIKIS HERE, THANKS -->
</includeonly>
This code uses template:Documentation subpage and two named parameters, maintemplatename and documenttext are passed to it.
Change your_template_name to the name of the template (two occurrences). Change the category name to a more appropriate subcategory of Category:Templates if possible.
Do not change Category:Template documentation. It is solely there to prevent the documentation pages being listed as uncategorized. It is unnecessary to create sub categories.
Add documentation between the BEGIN and END comments, under the appropriate subheadings:
What to include in documentation
- The basic purpose of the template: what it does and if it is not immediately obvious, why it needs to be done.
- The parameters of the template: whether they are numbered, named or optional, and if so, what the default values are and what effect they have. If a parameter can take only a limited set of values or is constrained in any way, for example, if it can only use: “yes”, “no” or a number, this should be clearly explained. If there are no parameters, just write None.
- Usage examples: specify the exact wikitext that should be used and the result that it produces. If the template can be used in several different ways, with or without optional parameters, for example, provide a range of examples. A good way to do so is to transclude the template itself into the documentation a few times (i.e., use live examples), with different parameters each time and list the parameters used in each case.
- Related templates: if the template is one of a series of templates, or if there are other templates with similar names or purposes, it's a good idea to link to them, in order to reduce the chance of the wrong one being used. If there are no related templates, just write None.
A good example to look at is Template:See also
Documenting Infoboxes
Infoboxes benefit from the use of other sections in their documentation. These include:
- Future expansion
- Infoboxes are likley to be expanded with new data fields, so it may be appropriate to explain how this may be done.
- Resources
- Where to find information to use in the Infobox.
- Full blank declaration
- The code that calls the template with all the parameter fields left blank.
Further assistance
If you need further assistance with using or creating templates, leave a note at the Help Desk or the talk page of WikiWOOD:WikiCommunity Templates.
See Also
- Help:Variables -- fancy stuff you may find in some templates
External links
http://en.wikibooks.org/wiki/Help:Template
| Help Page Navigation |
| Community Portal | Categories | Editing | Editing pages | External searches | Formatting | Help Desk | Images | Interwiki linking | Links | Managing files | Moving a page | Namespaces | Navigation | Patrolled edits | Preferences | Range blocks | Redirects | Searching | Skins | Special pages | Starting a new page | Subpages | Tables | Talk pages | Templates | Tracking changes | User page | Variables | WikiLinks |
