Help:Templates

From Users Wiki
Jump to navigation Jump to search

This is a ShoutWiki help page, hosted at ShoutWiki Hub. If you want to suggest changes, leave a message on its talk page. If you want to replace this page with a custom help page for your wiki, click the create button above.

A template is a page created to be included in other pages. Templates typically contain repetitive material for many articles or pages. They reduce duplication and promote a uniform style among messages, information boxes (infoboxes), navigation boxes (navboxes), and similar purposes.

General

Templates usually (but not always) exist in the Template: namespace. They are created and edited like any other page.

The method to include templates in other pages is transclusion, where the wikitext of the pages contains a reference to the template. The syntax is {{Template name}}. Transclusion can be modified through the use of special magic words, one of which replaces (substitutes) the template reference with the literal wikitext of the template. Substitution is frequently considered separate from transclusion.

Parameters

Template with unnamed parameters
[[File:Example.png|left|80px|Example image]]
'''A little thank you...'''<br/>
<small>for {{{1}}}.<br/>
Hugs, {{{2}}}</small>
You type You get
{{Thankyou|all your hard work|Joe}}
Example image

A little thank you...
for all your hard work.
Hugs, Joe

Template with named parameters
[[File:Example.png|left|80px|Example image]]
'''A little thank you...'''<br/>
<small>for {{{reason}}}.<br/>
Hugs, {{{signature}}}</small>
You type You get
{{Thankyou
| reason = all your hard work
| signature = Joe
}}
Example image

A little thank you...
for all your hard work.
Hugs, Joe

Templates can have parameters, which alter the way the template is displayed, such as by including specific text or by altering the design, usually by parsing the parameters. The syntax is

{{Template name|parameter|parameter| ...}}

Parameters can be named or unnamed. Named parameters are referenced by their names in triple braces.

Template invoked as {{Template name|parameter name = parameter value|parameter name = parameter value| ...}}
Parameters referenced as {{{parameter name}}}

Named parameters can be specified in any order. Parameter names are case-sensitive, including the first character. Unnamed parameters are referenced by their positions in the template invocation.

Template invoked as {{Template name|parameter value|parameter value| ...}}
Parameters referenced as, e.g., {{{1}}}

The first unnamed parameter is parameter 1. Subsequent unnamed parameters are numbered sequentially. Numbering skips named parameters. Unnamed parameters may be reordered by explicitly referencing their indices.

e.g., {{Template name|2=parameter value|1=parameter value|...}}

Whitespace characters (spaces, tabs, returns) are stripped from the beginnings and ends of named parameter names and values, but not from the middle. Thus {{ ... | myparam = this is a test }} is the same as {{ ... |myparam=this is a test}}. All whitespace characters are preserved for unnamed parameters.

Parameters can be given default values within the template by specifying them with the parameter reference, separated with a vertical bar, e.g., {{{name|unknown}}}. In this example, if name is undefined, the value unknown is used. A parameter being undefined is different from a parameter being defined, but empty, e.g., if a template is invoked with {{Template|name=}} or {{Template|}}. Frequently parameters are given a default value of empty, e.g., {{{name|}}}, to prevent the template from using the literal template reference as the text.

To pass the vertical bar or equals sign as part of the parameter value, use either the HTML entity (&vert; or &equals;) or a magic word or template which expands to the character ({{!}} or {{=}}).

Transclusion

The syntax {{Template|optional parameters}} usually includes the contents of another page (transcludes a page) from the Template: namespace. To specify other namespaces, simply include them in the article name.

e.g., {{User:Page name|optional parameters}} would transclude a page from the User: namespace.

To transclude a page from the main namespace, use only :.

{{:Page name|optional parameters}}

To transclude a subpage of the current page, specify its relative path.

{{/Subpage name|optional parameters}}

To transclude a template from the ShoutWiki Hub Template: namespace from another ShoutWiki wiki, prepend the template name with s:. Transcluding a template directly from a remote wiki does not support parameters. In addition, transcluding from another wiki is expensive in terms of server resources, so it is enabled only from ShoutWiki Hub (and its language variants), not from any other ShoutWiki wikis. A template transcluded from a remote wiki is expanded on the remote wiki, therefore any resource references (e.g., files, links, other templates) in that template are relative to the remote wiki.

{{s:Template}}

To transclude a template from any other namespace on ShoutWiki Hub, prepend the template name with s:: and the namespace.

e.g., {{s::User:Page name}} would transclude a page from the User: namespace on ShoutWiki Hub.

There are a few magic words that modify the behavior of transclusion.

Wikitext
example
Description
{{int:xyz}} Apply standard message translation, depending on subpages and language, to MediaWiki:xyz and use it. Any template with this word does not appear under "Templates used on this page". Rendered as <xyz> if MediaWiki:xyz does not exist.
{{msg:xyz}} Use Template:xyz even if there is a magic word xyz. Equivalent to {{Template:xyz}}. Normally, magic words have priority if there is a conflict.
{{msgnw:xyz}} The word is short for "message, nowiki." Include the wikitext as if it were wrapped with <nowiki> ... </nowiki>.
{{raw:xyz}} Include the raw wikitext from xyz before rendering the current page. Normally the transcluded page would be expanded before including it in the current page. raw can be useful for remote transclusion, since the wikitext is copied first, then expanded, allowing parameters to be used in templates from remote wikis. In that case, resource references in the template are relative to the local wiki, not the remote wiki. raw is not the same as msg.
{{subst:xyz}} The word is short for "substitute." Upon saving the page, the template invocation is replaced with the wikitext of the template, expanded to one level of substitution. If a template contains subst:, subst: is not parsed on transclusion, but treated as literal text, which probably breaks the template. Substitution is frequently treated separately from transclusion.
{{safesubst:xyz}} Works the same as subst: when saving a page, but also allows transclusion and multi-level substitution of templates containing it. If a template contains safesubst:, safesubst: is parsed as subst: on transclusion, allowing multiple levels of substitution.

Inclusion tags

By default, invoking a template includes the entire wikitext of the template. However, it is possible to specify within the template that only a portion of the wikitext is to be included.

  • <noinclude> ... </noinclude>
    The wikitext between the tags is not rendered when the template is invoked. It is only rendered on the template page. Text wrapped with this tag is excluded even from raw: transclusions.
  • <includeonly> ... </includeonly>
    The wikitext between the tags is rendered only when the template is invoked. It is not rendered on the template page.
  • <onlyinclude> ... </onlyinclude>
    The wikitext between the tags is the only wikitext rendered when the template is invoked.
Wikitext example Rendered on
template page
Rendered on
invoking page
<noinclude> text1 </noinclude> text2 text1 text2 text2
<includeonly> text1 </includeonly> text2 text2 text1 text2
<onlyinclude> text1 </onlyinclude> text2 text1 text2 text1

A common use of these tags is to include documentation and categorization for the template on the template page, but not on the pages that transclude it. Under some conditions, it may also be undesirable to render the template on its own page, rendering only the documentation.

A common issue with the use of these tags is the occurrence of unwanted whitespace. The effect of these tags includes only the tags themselves and their content. Any spaces or line breaks added outside the tags is not subject to their control.

Documentation

Documentation helps editors use a template by describing how it is used and possibly by providing an example and a blank invocation. Generally, it is preferable to place documentation and categorization in a subpage to minimize the amount of wikitext that is not included on use. For example:

Template:Thankyou
<div style="float:right; border:1px solid #00f; width:200px; background-color:#fff; padding: 3px;">
[[File:Example.png|left|80px|Example image]]
'''A little thank you...'''<br/><small>for {{{1}}}.<br/>Hugs, {{{2}}}</small>
</div><noinclude>{{/doc}}</noinclude>
Template:Thankyou/doc
Make a small "thank you" note for posting on someone's talk page.

Example:
<nowiki>{{Thankyou|all your hard work|Joe}}</nowiki>
produces <div style="display: table;">
{{Thankyou|all your hard work|Joe}}
</div><includeonly>
[[Category:User talk page templates]]
</includeonly><noinclude>
[[Category:Template documentation]]
</noinclude>

The documentation is put in Category:Template documentation, but <noinclude> prevents any transcluding pages (i.e., the template itself) from being put in the category. The documentation page even includes an invocation of the template. <includeonly> puts the template in Category:User talk page templates, but prevents the documentation from being put in the same category. Finally, <noinclude> in the template prevents the template documentation from being included on any pages that use the template.

References

Portions of the text on this help page are based on:

See also: