To 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:
A little thank you...
for all your effort.
hugs, Me
The thank you note will have a reason (in this case, "all your effort") and a signature ("Me"). Your objective is for any user to be able to thank any other user, for any reason whatsoever.
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
{{{1}}}
and
{{{2}}}
. This is the way to identify, within templates, the parameters that will be passed in when the template is used. Note that, within the template, each parameter is surrounded by
three
braces:
{{{ }}}
. This is different from normal template name usage.
When using the template on a page, you fill in the parameter values, separated by a "pipe" character (
|
). MediaWiki allows parameters to be passed to the template in three ways: Anonymously, Numbered, and Named.
Anonymous parameters
To pass in anonymous parameters, list the values of those parameters sequentially:
{{Thankyou|all your effort|Me}}
In this case, the
{{Thankyou}}
template receives parameters
{{{1}}}=all your effort
and
{{{2}}}=Me
, producing:
A little thank you...
for all your effort.
hugs, Me
The order in which anonymous parameters are passed in is crucial to its behavior. Reversing the order of the parameters, like so:
{{Thankyou|Me|all your effort}}
would produce this result:
A little thank you...
for Me.
hugs, all your effort
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
task T16235
). The workaround is to use named parameters instead, or even numbered parameters as explained in the following section.
Numbered parameters
To pass in parameters by number, identify each parameter when passing it:
{{Thankyou|2=Me|1=your friendship}}
This time, template
{{Thankyou}}
receives parameters
{{{1}}}=your friendship
and
{{{2}}}=Me
, though they have been supplied in inverse order, and produces:
A little thank you...
for your friendship.
hugs, Me
This may also be useful when any of the numbered parameters contains an "=" sign.
- Examples
{{Thankyou|1=adding “=”|2=Me}}
produces:
A little thank you...
for adding “=”.
hugs, Me
Warning:
| This also requires numbering each other parameter.
|
Named parameters
The 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
{{{reason}}}
and
{{{signature}}}
to identify each parameter, instead of a number. To pass these parameters by name, identify each parameter when passing it:
{{Thankyou|signature=Me|reason=being who you are}}
In this case, template
{{Thankyou}}
receives parameters
{{{reason}}}=being who you are
and
{{{signature}}}=Me
and produces:
A little thank you...
for being who you are.
hugs, Me
Named parameters are
case-sensitive
, so:
{{Thankyou|signature=Me|Reason=being who you are|reason=being case-sensitive}}
produces:
A little thank you...
for being case-sensitive.
hugs, Me
The advantage of using named parameters in your template, besides also being flexible in the order parameters can be passed, is that it makes the template code much easier to understand if there are many parameters.
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 parameters
If the template supports it, both kinds of parameters can be used in one call.
For example,
{{Thankyou|supporting both parameter types|signature=Me}}
results in:
A little thank you...
for supporting both parameter types.
hugs, Me
Be careful when doing this, because it can result in conterintuitive results as unnamed parameter counts are based only on the unnamed parameters, not the named parameters. For example,
{{Thankyou|Me|reason=supporting both parameter types}}
results in:
A little thank you...
for supporting both parameter types.
hugs, {{{2}}}
The template is coded to prefer the named parameter for the reason over the unnamed parameter, resulting in the "Me" being lost and no signature being given. This results in a default value of {{{2}}} being shown, as explained below.
Default values
If 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 {{{1}}}.
hugs, {{{2}}}
Since no arguments were passed in, the template presents the parameters themselves, instead of their respective values. In these cases, it may be useful to define
default
values for the parameters, i.e. values that will be used if no value is passed in. For example, if the template contents are changed to:
'''
A little thank you...
'''
for
{{{
reason|everything
}}}
.
hugs,
{{{
signature|Me
}}}
then
{{{reason|everything}}}
defines that if no argument is provided for parameter
{{{reason}}}
, then the value
everything
will be used. Similarly,
{{{signature|Me}}}
, defaults parameter
{{{signature}}}
to value
Me
. Now, transcluding the template again without passing any argument results in the following:
A little thank you...
for everything.
hugs, Me
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.
Often default values are used to specify alternate names of parameters.
For example, if you have
{{{a|{{{b|}}} }}}
, the template will first look for a parameter named "a".
If it is not set, it will use the parameter named "b".
If neither "a" nor "b" is set, it will output nothing.
Passing parameters to other templates
If 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}}}
.
You instead need to explicitly pass the parameter to the other template, i.e if {{
Thankyou3
}} contains
{{
thankyou
|{{{
1
}}}|{{{
2
}}}}}
}
then
{{
thankyou3
|everything|me}}
->
A little thank you...
for everything.
hugs, me
} works properly.
This example does not
preserve emptiness vs. undefinedness in parameter values
- you would need more complicated syntax if you wanted to do that.
Empty vs undefined parameters
The
{{
t2demo
||
a
}}
(refer to {{
T2demo
}} ), with a double pipe, sets the first parameter to an
empty
string instead of leaving it undefined.
It produces the output
start--middle- a -end
, similar to how
{{
t2demo
|
1=
|
2=
a
}}
results in
start--middle-
a
-end
.
On the other hand, explicitly setting the parameter "2" to "a," results in the first unnamed parameter being left
undefined
:
{{
t2demo
|
2=
a
}}
results in start-{{{1}}}-middle-
a
-end
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 equivalent
Good 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
p=
can show that a template has a parameter "p" that doesn't have a value yet.
To make an empty string and an undefined value equivalent, use the following approaches:
- Use
{{{p|}}}
exclusively instead of
{{{p}}}
or
q
where "q" is a non-empty value.
- Use conditional checks like
{{#if:{{{p|}}}|..{{{p}}}..|..}}
, to ensure
{{{p}}}
is only used when it has a value.
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
{{#ifeq:{{{foo|bar}}|{{{Foo|baz}}}|parameter is undefined|parameter is defined}}
.
Using equals signs in unnamed parameters
Unnamed parameters can include equals signs, but this must be done indirectly.
Here are some methods using
template:T1demo
:
- Default Value for Undefined Parameter
Assign a default value to an undefined parameter:
{{T1demo|{{{1| a=b }}}}}
This renders as:
start a=b end
.
- Using the
{{=}}
parser function
Use a parser function that safely includes an equals sign:
{{T1demo| a{{=}}b }}
This renders as:
start a=b end
.
- HTML Entities
Replace the equals sign with an HTML entity for display:
{{T1demo| a=b }}
This renders as:
start a=b end
.
This renders correctly without affecting the other parameters.
Handling unmatched curly and square brackets
Unmatched curly brackets (
{{
,
}}
) or square brackets (
[[
,
]]
) must be inside nowiki tags or use HTML entities:
- Rendering curly brackets have two options:
- Use
<nowiki>{{</nowiki>
or
{
for
{
- Use
<nowiki>}}</nowiki>
or
}
for
}
.
- Use
[
for
[
and
]
for
]
.
Below are some examples:
- Unmatched curly brackets
{{T1demo| <nowiki>{{</nowiki>content<nowiki>}}</nowiki> }}
This correctly renders the braces without breaking the template.
- Unmatched square brackets
{{T1demo| text [link] more text }}
This correctly renders the braces without breaking the template.
This renders as:
start text [link] more text end
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:
{{T1demo|abc]]def[[ghi}}
This will not expand correctly because of unmatched brackets.
The correct use:
{{T1demo|abc<nowiki>]]</nowiki>def<nowiki>[[</nowiki>ghi}}
This renders as:
startabc]]def[[ghiend
Template-generated brackets
An 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:
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 values
A 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
{{!}}
, or the HTML entity &124;.
The two methods of doing this have slightly different behavior, which can be relevant in some corner cases like when a template is producing
wikitable
syntax.
Example:
{{T1demo|abc|def}}
produces:
startabcend
The "def" doesn't display because it is treated as part of another unnamed parameter, which the template does not use.
{{T1demo|abc{{!}}def}}
produces:
startabc|defend
The "def" displays properly.
{{T1demo|abc|def}}
produces:
startabc|defend
The "def" displays properly again.
Since 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
|
SPACE1
=
|
bar
|
SPACE2
=
Random stuff
|
baz
|
SPACE3
=
|
mumble
|
SPACE4
=
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.
This 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:
- If you have a
Template:Start
containing
{{mytemplate
, and a
Template:End
containing
|foo=bar}}
, and put
{{start}}{{end}}
on a page,
mytemplate
isn't transcluded, because tokens like "|" cannot be added by a template and keep their special meaning in templates. You can still use templates to control the name of a parameter or template, but you cannot split a template call amongst multiple templates.
- Dead-code elimination:
If you make a template call like
{{foo|{{DISPLAYTITLE:Bar}} }}
, and
Template:Foo
does not contain {{{1}}}, then the
DISPLAYTITLE
is not used, since it is only evaluated when needed, and there is no parameter to substitute it into, so it is never evaluated. This usually comes into play when using
Extension:ParserFunctions
, and can be especially noticed when used in combination with the
int:
magic word that varies by user language. This isn't perfect, and in some cases even if the result of expanding a template is not used (because it is part of an if statement condition, for example), the process of evaluating it can still have
side effects
. For example, any
links
produced or other templates used will still be added to
Special:WhatLinksHere
even if they are not displayed.
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 instace is used, and the page is added to
Category:Pages using duplicate arguments in template calls
.
Template calls starting with the magic word
subst:
or
safesubst:
are evaluated in a separate first pass that only happens at save time, along with ~~~~ and links using the
pipe trick
.
If they cannot be evaluated during the first pass,
subst:
calls are ignored, and
safesubst:
are treated as if a normal template.
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 templates
Including 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
a {{Aaaa}} z
, it'll display "a a
Template loop detected:
Template:Aaaa
z z".
This safeguard precludes a potentially useful template idiom where a template self-normalizes its own calling arguments.
In this forbidden example
template:d
can either be called
{{d|20200311}}
or
{{d|y=2020|m=3|d=11}}
.
If called in the first manner, it recurses into itself with the second argument structure (obtained using string parser functions), which then follows a unified processing path.
{{
#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
template:d
is modified to recurse into
template:d/2
and
template:d/2
is an
identical manual copy
of
template:d
this idiom works fine as the self-recursion safeguard operates dynamically and not statically.
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 parameters
Since the pipe character (
|
) and equality sign (
=
) have different meanings in template calls and wikitables, in order to use table markup in the value of a template parameter one generally needs to "escape" those characters (i.e., protect them from interpretation as template markup) using special sequences:
- the built-in
magic word
{{!}}
provides an "escaped" version of
|
since MediaWiki 1.24
- the built-in magic word
{{=}}
provides an "escaped" version of
=
since MediaWiki 1.39
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 (
{
) is interpreted as a literal left-brace character because it is immediately followed by the
{{!}}
magic word.
Similarly, the last right-brace (
}
) is interpreted as a literal right-brace character because it is immediately preceeded by the same magic word.
However, in some cases these brace characters do cause problems, so some wikis provide templates for escaping these characters, as well:
- the template call
{{(}}
might provide an "escaped" version of
{
- the template call
{{)}}
might provide an "escaped" version of
}
Some wikis go even further and provide other convenience templates like
{{
(!
}}
,
{{
!)
}}
,
{{
!!
}}
.
On such a wiki, the code can be simplified a bit to this form:
{{
(!
}}
class
{{
=
}}
wikitable
!A!!B!!C
{{
!
}}
-
{{
!
}}
A1
{{
!!
}}
B1
{{
!!
}}
C1
{{
!
}}
-
{{
!
}}
A2
{{
!!
}}
B2
{{
!!
}}
C2
{{
!)
}}