GeezerVisonThe World Wide Web, restored to 800 pixels of glory. | ||||||||||||
| Home|About|Gaming cabinet|Archives|How it works|Starter sites | ||||||||||||
GeezerVison is showing www.mediawiki.org — Help:Templates - MediaWiki
If you have standard texts you want to include on several pages, the MediaWiki template feature comes into play. Unlike extensions and media files , there is no central repository for templates. Templates can be newly written or, to save duplicating work already done, exported from another wiki e.g. Wikipedia, and then imported into the target wiki. Basic usageTemplates are standard wiki pages whose content is designed to be transcluded (embedded) inside other pages.
Templates follow a convention that the name is prefixed with " To transclude a template, you use double opening & closing curly brackets The simplest use of templates is as follows: Create a page called Hello! Welcome to the wiki. You have created your first template! Now, insert the code below in a new page: {{Welcome}}
When the new page is viewed, the text "Hello! Welcome to the wiki." will appear instead of You can then insert Hi there! Welcome to this wonderful wiki. And revisit any of the 100 pages where the template was used, you'll see the new text instead of the original one. In this way, you have changed the content of 100 pages without editing them, because the template is transcluded into these pages. This is the basic mechanism. There are several additional features of transclusion that enrich this mechanism and make templates very useful.
Ways to invoke a templateTemplates can be used in other pages in these ways:
<noinclude> <languages/> </noinclude> '''A little thank you...''' for {{{reason|{{{1}}}}}}. Hugs, {{{signature|{{{2}}}}}} <noinclude> [[Category:Template examples{{#translation:}}|{{PAGENAME}}]] </noinclude> In fact, an ordinary wiki page can also be used as a template, simply by specifying the namespace it resides in, so:
If the specified namespace doesn't exist, the full title is assumed to be a template:
Regardless of what syntax is used, the name of the template can be relative to the current page
For example, if It can also be generated dynamically.
For example, ParametersTo enrich the mechanism of transclusion, MediaWiki allows parameters to be passed to a template when it is transcluded. Parameters allow the template to produce different contents or have different behaviors. Suppose you wish to insert a little thank you note in the talk page of other users, such as:
So that the note will look similar everywhere it is used, you can define a template called Template:Thankyou , for example. Although the note should look similar whenever a user thanks another user, its specific contents (i.e., the reason and the signature) will be different. For that reason, you should pass them as parameters. If we ignore the remaining elements to format the box and place the image, the core content of the template will be this: '''A little thank you...''' for {{{1}}}. Hugs, {{{2}}} Notice the use of When using the template on a page, you fill in the parameter values, separated by a "pipe" character ( Anonymous parametersTo pass in anonymous parameters, list the values of those parameters sequentially: {{Thankyou|all your effort|Me}} In this case, the
{{Thankyou|Me|all your effort}}
would produce this result:
Identifying parameters by order (with
{{{1}}}, etc.) works only with anonymous parameters. Any parameters identified by name, as shown below, will not be accessible to the template using ordinal numbers.If an equal sign appears inside the argument to an anonymous template parameter, that parameter may be misinterpreted as a named parameter (which is explained below in this document) treating the text before the equal sign as the parameter name and the text after it as the argument value. This is a common problem when you need to include an external link, or an HTML element with attributes (see T16235). The workaround is to use named parameters instead, or even numbered parameters as explained in the following section.
Numbered parametersTo pass in parameters by number, identify each parameter when passing it: {{Thankyou|2=Me|1=your friendship}}
This time, template
This may also be useful when any of the numbered parameters contains an "=" sign.
Examples: {{Thankyou|1=adding "="|2=Me}}
produces:
This also requires that the unnamed parameters be numbered, i.e.
1=, 2=.Named parametersThe third way of passing parameters is by name instead of numbers. In this case, the template contents would be changed to: '''A little thank you...''' for {{{reason}}}. Hugs, {{{signature}}} Within the template, we use {{Thankyou|signature=Me|reason=being who you are}}
In this case, template
{{Thankyou|signature=Me|Reason=being who you are|reason=being case-sensitive}}
produces:
Spaces and newlines are automatically stripped from the start and end of named parameter names and values, but are preserved in unnamed parameters. Mixing named and unnamed parametersIf the template supports it, both kinds of parameters can be used in one call. The template contents would be changed to: '''A little thank you...''' for {{{reason|{{{1}}}}}}. Hugs, {{{signature|{{{2}}}}}} Then,
Similarly,
Default valuesIf you transclude a template that expects parameters, but do not provide their arguments, in this way: {{Thankyou}}
in the numbered parameters example above you would get the following:
'''A little thank you...''' for {{{reason|everything}}}. Hugs, {{{signature|Me}}} then
The value of a parameter can be an empty string. For example, in
{{foo|bar=}} or {{foo|bar=|baz=qux}}, the foo template considers the bar parameter to be "". This is different from omitting the parameter altogether, which leaves it undefined and triggers the default value mechanism described above.If you need to treat an empty string the same way as a missing parameter, you can use a conditional operator through an extension like ParserFunctions. For instance,
{{#if:{{{1|}}}|{{{1|}}}|undefined}} returns undefined if the parameter is either undefined or empty, while {{{1|undefined}}} does so only if the parameter is undefined.Default values are often used to specify alternate names of parameters.
For example, if you have Passing parameters to other templatesIf raw parameter syntax is generated by the above template call, and then passed through to another template, it is not interpreted as a parameter. This means that {{Thankyou2 }}, which just calls {{Thankyou }} with no parameters, does not work: {{thankyou2|everything|me}} → A little thank you... for {{{1}}}. Hugs, {{{2}}}
{{thankyou|{{{1}}}|{{{2}}}}} then works properly: {{thankyou3|everything|me}} → A little thank you... for everything. Hugs, me
Empty vs undefined parametersThe
If the second parameter should not be trimmed, it must be unnamed. Therefore, you can assign an empty string to the first parameter, but you cannot leave it undefined. Making emptiness and undefinedness equivalentGood template coding practices result in passing an empty string to a parameter working the same as not assigning any value. This makes things easier and more consistent. For example, using To make an empty string and an undefined value equivalent, use the following approaches:
If for some reason you want to treat undefined parameters differently from empty parameters or any other possible value you can compare the same parameter twice with different defaults, i.e Using equals signs in unnamed parametersUnnamed parameters can include equals signs, but this must be done indirectly. Here are some methods using template:T1demo:
Assign a default value to an undefined parameter:
This renders as:
Use a parser function that safely includes an equals sign:
This renders as:
Replace the equals sign with an HTML entity for display:
This renders as: This renders correctly without affecting the other parameters. Handling unmatched curly and square bracketsUnmatched curly brackets (
Below are some examples:
This correctly renders the braces without breaking the template.
This correctly renders the braces without breaking the template. This renders as:
Unmatched pairs not placed in nowiki tags either prevent template expansion or are taken as closing braces for the template call. Below are some examples:
This will not expand correctly because of unmatched brackets. The correct use:
This renders as:
Template-generated bracketsAn alternate technique for passing arguments with unmatched brackets is to wrap them in another template. In that situation, (which exists with {{(( }} and {{)) }}) on this wiki), the unmatched brackets will be rendered literally, and not decoded as another template call. For example: {{t1demo|{{((}}t1demo{{))}}}} results in: start{{t1demo}}end When substituting a template, template inclusions are parsed once when the subst happens (with the same caveats explained above) and then a second time when rendering the resulting wikitext. For example: {{subst:((}}t1demo|foo}} will expand on save to: {{t1demo|foo}} which will then render as: startfooend If the wikitext generated via the first subst itself includes "subst:" syntax it will not be processed on the same save, but may be on the next save. This technique may be used to implement recursive substitutions that take multiple saves to evaluate. Using pipes in parameter valuesA parameter value cannot contain a pipe character (|), because it would be interpreted as the end of that parameter and the start of the next parameter.
This can be worked around by using the parser function Example:
The "def" doesn't display because it is treated as part of another unnamed parameter, which the template does not use.
The "def" displays properly.
The "def" displays properly again. Formatting template calls using extra parametersSince templates ignore parameters they are passed but do not handle specifically, they can be used as a way of a adding extra whitespace or unused content to the template call. For example: {{template name|foo|bar|baz|mumble|quux}} is equivalent to, assuming the template doesn't recognize SPACEN as a parameter name: {{template name|SPACE1= |foo|SPACE2= |bar|SPACE3=Random stuff |baz|SPACE4= |mumble|SPACE5= quux }} It is also possible to use the same name for each spacer (often the empty string), but this will populate Category:Pages using duplicate arguments in template calls, which many wikis prefer to keep empty to catch instances of user error. This can be used to make the template render in a way similar to its output, like showing each row of w:Template:Chess position on its own like to make the wikitext also look like a chessboard. Tracking parameter usageSee also: Help:Tracking categories
It may be wise for a template to add a link or category to a page if a certain parameter or combination of parameters is used, to make if possible to easily determine what pages are using a given parameter, and thus what the impacts of changing that parameter in the template would be. Evaluation processThis is an advanced topic which you can skip unless you need it.
Generally speaking, template parameters are substituted into the template after tokenization, but as is. They are not evaluated until they are used. This has a few consequences:
Template parameters are pass by value, which means a template cannot modify its arguments. Parameters are treated as associative array, and parameter names are evaluated before parameter values. If the same parameter name is given more than once (either as named or unnamed), only the last instance is used, and the page is added to Category:Pages using duplicate arguments in template calls. Template calls starting with the magic word Many but not all parser functions, parser tags and trancluded special pages are not directly included like templates but instead are replaced by a "strip marker". This means you cannot manipulate the results with parser functions like padleft: or similar functions from extensions, as they see the strip marker instead of the result of the parser function. Recursion in templatesIncluding a template in itself won't throw MediaWiki into infinite recursion.
MediaWiki will stop the recursion with the template's name in bold.
For example, if the content of Template:Aaaa is This safeguard precludes a potentially useful template idiom where a template self-normalizes its own calling arguments.
In this forbidden example {{#if:{{{1|}}}|{{d|y={{#sub:{{{1}}}|0|4}}|m={{#sub:{{{1}}}|4|2}}|d={{#sub:{{{1}}}|6|2}}}}|<!-- processing path with arguments y,m,d regardless of original call pattern -->}} If A feasible way for the MediaWiki software to loosen the self-recursion rule would be to require that each recursive call have a distinct argument count from all previous active calls, at most once recursing with the argument count non-decreasing. That would provide a strong guarantee against infinite self-recursion while enabling useful idioms such as the one described here in a flexible manner. If the processing path is of low complexity, a simple solution using only one template is to handle each calling convention on a separate if/else branch, duplicating the logic of the processing path within each case. If the processing path is more complex, each call-structure case can delegate to an implementation template with a unified call structure which provides the final template behaviour. Tables in parametersSince the pipe character (
Before the introduction of these magic words, many wikis used templates to accomplish the same things. On such a wiki, the magic words take precendence over the same-named templates. Example table
Table code: {| class=wikitable !A!!B!!C |- |A1||B1||C1 |- |A2||B2||C1 |} Escaped table code: {{{!}} class{{=}}wikitable !A!!B!!C {{!}}- {{!}}A1{{!}}{{!}}B1{{!}}{{!}}C1 {{!}}- {{!}}A2{{!}}{{!}}B2{{!}}{{!}}C2 {{!}}} Note that the first left-brace (
Some wikis go even further and provide other convenience templates like {{(!}} ( {{(!}} class{{=}}wikitable !A!!B!!C {{!}}- {{!}}A1{{!!}}B1{{!!}}C1 {{!}}- {{!}}A2{{!!}}B2{{!!}}C2 {{!)}} Controlling template inclusionBy default, a template's content is displayed in its entirety, both when viewed directly and when included in another page. The template's page when viewed directly appears exactly as the template would render without any parameters. If the template requires parameters to function properly, this will result in raw wikitext syntax or errors as a result of them being missing. For example:
However, you can control which parts of a template will be seen and included by the use of the Anything between
Likewise, anything between
Everything outside Everything outside For example, if a page like Help:Templates/onlyinclude demo has the wikitext: abc<onlyinclude>def</onlyinclude>ghi<includeonly>jkl</includeonly> The result of transcluding it is def. Nesting of these tags is also possible. The three partial transclusion tags enable all possible combinations of what is processed and rendered.
Comments also fill a role.
Inclusion tags are respected when using Section transclusionTo transclude different sections of a template on different pages, you can wrap the content in onlyinclude tags and use an if statement on parameters to select which section. Consider "Template:Example" with this wikitext: == Section 1 == {{#ifeq:{{{1|1}}}|1| Content of section one. }} {{#ifeq:{{{1|2}}}|2| == Section 2 == Content of section two. }} This will render both sections on the example page itself, and allow other pages to transclude the first section with Another approach is to use literal parameter syntax instead: {{{section1| == Section 1 == Content of section one. }}} {{{section2| == Section 2 == Content of section two. }}} Transclude the first section with A third approach is to use Labeled Section Transclusion . Organizing templatesFor templates to be effective, users need to find them, and find out how to use them. To find them, users can:
To give usage information, include an example like this one on the template page: <noinclude>
== Usage ==
Welcome users:
{{Thankyou|reason=your reason|signature=your signature}}
</noinclude>
Then, an editor can simply copy and paste the example to use the template. While editing a page, a list of all templates used is available under the editing form, in a collapsible section titled Linking to a templateA template page can be linked to like any other wiki page. For example, the link Template:Navbar is generated using the wikicode On many wikis, Template:Tl can be used to provide a link to a template formatted in a way that shows the "double curly-braces" wikicode necessary to transclude the template without actually doing the tranclusion.
For example, the code This construct is commonly used when referring to templates in template documentation, on help pages, and on talk pages.
The same effect can be achieved by using Template namingThe name of a template is case-sensitive excluding the first character. You make redirects for alternate capitalizations.
For example, if a template is named "AdminAbbr", you can create a redirect named "Adminabbr".
This way, the template can be called with either Because template names are interpreted in the same way to the names of other pages, underscores are replaced with spaces, and any text after a number sign (what would be a anchor in a standard link) is ignored. An underscore Possible uses of templatesTemplates can be used for any situation in which one wants two or more pages to contain identical or similar content that is edited together rather than independently. They can be used to:
Copying from one wiki to anotherIt is possible, if allowed by the wiki configuration to transclude templates from other wikis. This configuration setting is disabled on Wikimedia wikis. Otherwise, you need to manually copy the template and its dependencies from the source wiki to the destination wiki to use it. Templates often require CSS or other templates, so users frequently have trouble copying templates from one wiki to another. The steps below should work for most templates. MediaWiki codeIf you have import rights (specifically
If you don't have import rights on the new wiki:
This will copy the entire code necessary, and will suffice for some templates.
Note that only page elements parsed in rendering the page get exported, consequently documentation subpages are not exported as part of this process.
If it doesn't work also check for red links listed under After successfully importing the template and all its linked templates from the other wiki, edit it to change customisations to suit your wiki. For example to change a logo, remove redundant categories or red links. ExtensionsAn extension often used in templates is ParserFunctions. Visit page Extension:ParserFunctions and check if any of the functions listed there are used in the templates you've copied. If so, you have to install the ParserFunctions extension. To install it, you'll need system admin access to the server of your MediaWiki installation. Another dependency that may be used in templates, especially those on Wikipedia, is Lua. Having CSS and JavaScript codeBesides MediaWiki code, many templates make use of CSS and some rely on JavaScript to work fully. If the copied templates are not behaving as expected, this may be the cause. To copy the required CSS and JavaScript to your wiki you'll normally need to have admin privileges, because you'll be editing system messages in the "MediaWiki:" namespace.
RedirectionIf a page uses a redirect as a template, the redirect is resolved before processing the template and the target is used instead. This won't work if the target doesn't exist (a broken redirect), or is itself a redirect (a double redirect). A page that just includes another page as a template might look like a redirect, but there are several differences between them:
Embedding works on pages that support redirects and doesn't work on pages without it.
Parser functionsMain page: Help:Parser functions
MediaWiki also supports parser functions, which function similarly to templates but follow slightly different syntax:
See alsoGeneral template usage
Special constructs used in templates
Other relevant information
External links
| ||||||||||||
| You are visitor 01402503 — GeezerVison does not store the pages you look up. Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required. |