Help:Templates
From Wikibooks, the open-content textbooks collection
- See also mw:Help:Templates and mw:Help:Extension:ParserFunctions for information about template syntax.
- See also Editing Wikitext/Templates for a gentler treatment of templates.
Contents |
[edit] Templates
A template is simply a page designed for inclusion on other pages. If a template is changed, this is usually reflected on every page that uses the template. As you might begin to imagine, templates are a powerful tool that when put to good use, can reduce work and increase maintainability. On this page you will learn how to use templates and how to make your own templates.
[edit] Using Templates
To use a page as a template simply use {{page name}} instead of [[page name]]. This causes the page's content to be processed and inserted onto a page rather than linked to. If the page does not exist yet, adding a template is the same as adding a link to the page — you will see a link that when clicked on will take you to the named page in edit mode.
People may sometimes refer to the process of using a template as inclusion, transclusion or template calling.
[edit] Inclusion vs Linking
When linking to pages, pages are assumed to be in the main namespace unless the namespace is also stated. For templates, pages are assumed to be in the template: namespace instead. To use a page from another namespace as a template you must also include the namespace the page belongs to. If you wanted to include this page from within Wikibooks:Sandbox you would add {{Help:Template}} for example. To use a page from the main namespace you use an empty namespace (e.g. {{:page name}}).
Using a page outside the template namespace as a template can be useful for:
- Quoting interface messages in the MediaWiki namespace
- Templates for personal use in subpages of one's userpage, e.g. for experimenting
- Including pages in other pages in the same namespace, e.g. having an extra page associated with each page, such as a to-do list, with a simple name correspondence; it can be created and included with
{{{{NAMESPACE}}:{{PAGENAME}}/todo}}.
[edit] Uses
Templates are useful for any text for which one wants a copy in two or more pages, and there is no need for each copy to be edited independently, to adapt it to the page it is in. Since parameters can be used, versions may to that extent even be different, and parameter values can be edited independently for each. Templates are not only convenient, but they can also “force” a useful uniformity, e.g., a certain “style”.
Typical applications are:
- Messages for displaying information ({{stub}}, {{message box}})
- Navigation between a book's pages or chapters for easier reading online ({{chapter navigation}})
- Placeholders for displaying visual information. Like tables, figures, diagrams, illustrations, etc.
- Composites composed of a table of simple images which display more complex ideas ({{chess position}}
[edit] Creating Templates
There is nothing special about creating templates. You create templates in the same way as you would create any page. Below you will learn about some of mediawiki's features that can be especially useful when used in templates.
[edit] noinclude and includeonly
Anything between <noinclude> and </noinclude> will be processed and displayed only when the page is being viewed directly, not included. Possible applications are:
- documentation that explains how to use the template.
- categorizing templates; lets you include templates without also categorizing all pages that include the template too.
- interlanguage links to similar templates in other languages without also doing the same for every page that includes the template.
- excluding any part of a page from the print version of a book, see Help:Print versions.
Conversely, anything between <includeonly> and </includeonly> will be processed and displayed only when the page has been included. Possible applications are:
- categorizing pages; lets you categorize all pages that include the template without using the same category for the template.
 |
If you change categories inside a template, categories may not update correctly until pages that include the template are editted. |
- hiding what the template actually does; can be useful in combination with documentation that already demonstrates how to use the template.
- including any part of a page only in the print version of a book.
You can also use these two tags in combination to make what is displayed depend on whether the page is viewed directly or included.
|
Content not inside either tag is processed and displayed both when viewed directly and when included, this includes newlines and spaces. If spaces or newlines are not desired, make sure the appropriate tag is used without any spaces or newlines in between. |
[edit] Substitution
Substitution can be useful with templates that are used to fill out information where the content shouldn't change if the template changes. Substitution causes almost any text to be processed and replaced with its expanded version upon saving a page. Substitution can also be used to include a copy of a page's content, leaving the copy untouched if the orginal page is changed. This is also a much quicker way to copy pages than copy+pasting.
Use {{subst:text or page name}} to invoke substitution. When the page is saved, subst is replaced with the text or page's content expanded. However replacement does not work recursively; if a template calls another template, the call to the second template is what gets saved.
Example: t2 (talk, backlinks, edit), containing:
start-{{{1}}}-middle-{{{2}}}-end
and called as {{subst:t2|[[a]]|[[image:tst.png]]}} gives the wikitext start-[[a]]-middle-[[image:tst.png]]-end
If you want to use a modified version of the resulting wikitext, you have to save the page with the unmodified wikitext first, then edit it, because when applying preview the subst code is not yet replaced in the edit box. In the edit summary of the temporary edit you can put "tmp" to indicate that you have not made an error but are still working on the page.
In the absence of parameters, an alternative that clutters the edit history less is, of course, copying the text from the edit box of the template page: then it can be edited before saving. Another method is using msgnw without saving, and copying the preview result into the edit box.
Applying subst to a variable works like applying it to a template. E.g. a timestamp:
{{subst:CURRENTDAY}} {{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}, {{subst:CURRENTTIME}} (UTC)
giving: 10 March 2005, 08:23 (UTC)
Applying subst to a template containing four tildes in nowiki tags, the latter are preserved but not applied, i.e., the wikitext of the link to the user name, as well as date and time, are rendered.
Usage of a template through subst: does not show up in page histories, backlinks, etc.
[edit] Parameters
See Help:Templates in the MediaWiki help.
[edit] Extensions
Some extensions extend the wiki syntax to provide new functionality and features. Typically the extended wiki syntax that extensions provide is hidden away in some template. You can always find the most up to date list of installed extensions that extend the wiki syntax by looking at the Parser hooks section of Special:Version.
- Extension:ParserFunctions includes if, switch, time, ifexist, expr and 5 others.
- Extension:ImageMap allows for the inclusion of image maps that link to one or more pages.
- Extension:EasyTimeline lets you create one or two dimensional graphs.
- Extension:SyntaxHighlight_GeSHi lets you include source code examples with syntax highlighting.
[edit] Pitfalls and Limitations
Pages in the stored page history consist of wikitext with possible references to templates and images. When viewing an old version of a page, these refer to the current versions of the templates and images, if these still exist. Thus the former composite page is not reconstructed.
Changes to templates don't affect the pages where they are included until the server cache has cleared. This is usually not a problem, but if you desperately need to view the update, you can purge the server cache (you'll need to change your preferences: this option is under the Gadgets tab). If you add or remove categories from a template that is heavily used, pages that include the template usually show the correct categories.
However, categories may not correctly update until some edit is made to the pages that use the template. Purging the page isn't usually enough. To refresh categories with respect to the listing of a particular page (adding or deleting the entry), a null edit can be applied to that page. See bug #5382. Alternatively, if you have editor or reviewer privileges, sighting a page, then going back and setting all the levels to "poor or unrated" again to de-sight the page will refresh the category in the same manner without leaving an edit trail.
