Editing Help/Templates (section)

== Parameters == <!--T:26-->

<!--T:27-->
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.

<!--T:28-->
Suppose you wish to insert a little thank you note in the [[<tvar name=1>Special:MyLanguage/Help:Talk pages</tvar>|talk page]] of other users, such as:

<!--T:29-->


<!--T:30-->
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.
</translate>

<translate><!--T:31--> So that the note will look similar everywhere it is used, you can define a template called <tvar name=tmpl></tvar>, for example.</translate>
<translate><!--T:183--> 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.</translate>
<translate><!--T:184--> For that reason, you should pass them as parameters.</translate>
<translate><!--T:185--> If we ignore the remaining elements to format the box and place the image, the core content of the template will be this:</translate>

<syntaxhighlight lang="wikitext">
<translate nowrap><!--T:32-->
'''A little thank you...'''
for }.
Hugs, }</translate>
</syntaxhighlight>

<translate>
<!--T:33-->
Notice the use of <tvar name=1><code><nowiki>}</nowiki></code></tvar> and <tvar name=2><code><nowiki>}</nowiki></code></tvar>. 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: <tvar name=braces><code><nowiki>}</nowiki></code></tvar>. This is different from normal template name usage.

<!--T:34-->
When using the template on a page, you fill in the parameter values, separated by a "pipe" character (<tvar name=pipe><code>|</code></tvar>). MediaWiki allows parameters to be passed to the template in three ways: Anonymously, Numbered, and Named.

=== Anonymous parameters === <!--T:35-->

<!--T:36-->
To pass in anonymous parameters, list the values of those parameters sequentially:
</translate>

<translate><!--T:37--> <nowiki></nowiki></translate>

<translate>
<!--T:38-->
In this case, the <code><nowiki></nowiki></code> template receives parameters <code><nowiki>}=all your effort</nowiki></code> and <code><nowiki>}=Me</nowiki></code>, producing:

<!--T:39-->


<!--T:40-->
The order in which anonymous parameters are passed in is crucial to its behavior. Reversing the order of the parameters, like so:
</translate>

 <translate><!--T:41--> <nowiki></nowiki></translate>

<translate>
<!--T:42-->
would produce this result:

<!--T:43-->

</translate>

}</nowiki></code></tvar>, etc.) works ''only'' with anonymous parameters.</translate> <translate><!--T:208--> Any parameters identified by name, as shown below, will not be accessible to the template using ordinal numbers.</translate>}}

{{note|1=<translate><!--T:120--> If an equal sign appears inside the argument to an anonymous template parameter, that parameter may be misinterpreted as a [[<tvar name=1>#Named parameters</tvar>|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.</translate> <translate><!--T:121--> This is a common problem when you need to include an external link, or an HTML element with attributes (see <tvar name=1></tvar>).</translate> <translate><!--T:122--> The workaround is to use named parameters instead, or even numbered parameters as explained in the following section.</translate>}}

<translate>
=== Numbered parameters === <!--T:45-->

<!--T:46-->
To pass in parameters by number, identify each parameter when passing it:
</translate>

 <translate><!--T:47--> <nowiki></nowiki></translate>

<translate>
<!--T:48-->
This time, template <code><nowiki></nowiki></code> receives parameters <code><nowiki>}=your friendship</nowiki></code> and <code><nowiki>}=Me</nowiki></code>, though they have been supplied in inverse order, and produces:

<!--T:191-->

</translate>



'''<translate><!--T:177--> Examples:</translate>'''

<pre><translate nowrap><!--T:207--> </translate></pre>

<translate><!--T:178--> produces:</translate>

<translate><!--T:179--> </translate>


<translate>
=== Named parameters === <!--T:49-->

<!--T:50-->
The third way of passing parameters is by name instead of numbers.  In this case, the template contents would be changed to:
</translate>

<syntaxhighlight lang="wikitext"><translate nowrap><!--T:51-->
'''A little thank you...'''
for }.
Hugs, }</translate></syntaxhighlight>

<translate>
<!--T:52-->
Within the template, we use <code><nowiki>}</nowiki></code> and <code><nowiki>}</nowiki></code> to identify each parameter, instead of a number. To pass these parameters by name, identify each parameter when passing it:
</translate>

 <translate><!--T:53--> <nowiki></nowiki></translate>

<translate>
<!--T:54-->
In this case, template <code><nowiki></nowiki></code> receives parameters <code><nowiki>}=being who you are</nowiki></code> and <code><nowiki>}=Me</nowiki></code> and produces:

<!--T:55-->


<!--T:181-->
Named parameters are '''case-sensitive''', so:

<!--T:151-->
<pre><nowiki></nowiki></pre>

<!--T:152-->
produces:

<!--T:192-->


<!--T:153-->
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.

<!--T:272-->
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 === <!--T:273-->
</translate>
<translate><!--T:274--> If the template supports it, both kinds of parameters can be used in one call.</translate>
<translate><!--T:465--> The template contents would be changed to:</translate>

<syntaxhighlight lang="wikitext">'''A little thank you...'''
for }}}}.
Hugs, }}}}</syntaxhighlight>

$1signature=$2<nowiki>}}</nowiki></code></tvar> results in:</translate>
|1=<translate><!--T:451--> supporting both parameter types</translate>
|2=<translate><!--T:452--> Me</translate>
}}



<translate><!--T:338--> 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.</translate>
$1reason=$2<nowiki>}}</nowiki></code></tvar> results in:</translate>
|1=<translate><!--T:455--> Me</translate>
|2=<translate><!--T:456--> supporting both parameter types</translate>
}}



<translate><!--T:340--> 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.</translate>
<translate><!--T:341--> This results in a default value of <tvar name=1>}</tvar> being shown, as explained below.</translate>

reason=$1$2<nowiki>}}</nowiki></code></tvar> results in:</translate>
|1=<translate><!--T:460--> supporting both parameter types</translate>
|2=<translate><!--T:461--> Me</translate>
}}



<translate><!--T:464--> Even though "Me" is the second parameter, it is the first ''unnamed'' parameter, and so it is assigned to <tvar name=1><nowiki>}</nowiki></tvar> and <tvar name=2><nowiki>}</nowiki></tvar> is left unassigned.</translate>

<translate>
=== Default values === <!--T:56-->
</translate>

<translate>
<!--T:57-->
If you transclude a template that expects parameters, but do not provide their arguments, in this way:
</translate>

 <translate><!--T:58--> <nowiki></nowiki></translate>

<translate>
<!--T:59-->
in the numbered parameters example above you would get the following:
</translate>



<translate>
<!--T:61-->
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:
</translate>

<syntaxhighlight lang=moin>
<translate nowrap><!--T:62-->
'''A little thank you...'''
for }.
Hugs, }</translate>
</syntaxhighlight>

<translate>
<!--T:63-->
then <code><nowiki>}</nowiki></code> defines that if no argument is provided for parameter <code>}</code>, then the value <code>everything</code> will be used. Similarly, <code><nowiki>}</nowiki></code>, defaults parameter <code>}</code> to value <code>Me</code>. Now, transcluding the template again without passing any argument results in the following:
</translate>

<!-- strictly speaking, this example is false, because the template call was changed to obtain the desired effect - but the effect is the same if the template is defined as described -->
<translate>
<!--T:146-->

</translate>

</nowiki></code></tvar> or <tvar name=2><code><nowiki></nowiki></code></tvar>, the <tvar name=5><code>foo</code></tvar> template considers the <tvar name=3><code>bar</code></tvar> parameter to be <tvar name=4><code>""</code></tvar>.</translate> <translate><!--T:233--> This is different from omitting the parameter altogether, which leaves it undefined and triggers the default value mechanism described above.</translate>
}}
{{note|1=<translate><!--T:342--> 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 [[<tvar name=1>Special:MyLanguage/Extension:ParserFunctions</tvar>|ParserFunctions]].</translate> <translate><!--T:343--> For instance, <tvar name=1><code><nowiki>}|}|undefined}}</nowiki></code></tvar> returns undefined if the parameter is either undefined or empty, while <tvar name=2><code><nowiki>}</nowiki></code></tvar> does so only if the parameter is undefined.</translate>
}}

<translate><!--T:194--> Default values are often used to specify alternate names of parameters.</translate>
<translate><!--T:195--> For example, if you have <tvar name=1><code><nowiki>} }}}</nowiki></code></tvar>, the template will first look for a parameter named "<tvar name=2>a</tvar>".</translate>
<translate><!--T:196--> If it is not set, it will use the parameter named "<tvar name=1>b</tvar>".</translate>
<translate><!--T:197--> If neither "<tvar name=1>a</tvar>" nor "<tvar name=2>b</tvar>" is set, it will output nothing.</translate>

<translate>
=== Passing parameters to other templates === <!--T:344-->
</translate>
<translate><!--T:345--> 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.</translate>
<translate><!--T:346--> This means that <tvar name=1></tvar>, which just calls <tvar name=2></tvar> with no parameters, does not work:</translate>  → 

<translate><!--T:347--> You instead need to explicitly pass the parameter to the other template, i.e if <tvar name=1></tvar> contains</translate>
<syntaxhighlight lang="wikitext">
}|}}}
</syntaxhighlight>
<translate><!--T:348--> then works properly:</translate>
 → 

<translate>
<!--T:349-->
This example does not [[<tvar name=1>#Empty vs undefined parameters</tvar>|preserve emptiness vs. undefinedness in parameter values]]&nbsp;&ndash; you would need more complicated syntax if you wanted to do that.

=== Empty vs undefined parameters === <!--T:275-->
</translate>
<translate><!--T:276--> The <tvar name=1><code>}}t2demo}}  }}</code></tvar> (refer to <tvar name="2"></tvar> ), with a double pipe, sets the first parameter to an '''empty''' string instead of leaving it undefined.</translate>
<translate><!--T:277--> It produces the output <tvar name=1><code>start--middle- a -end</code></tvar>, similar to how <tvar name=2><code>}}t2demo}}1=}}2=  }}</code></tvar> results in <tvar name=3><code>}}</code></tvar>.</translate>
<translate><!--T:278--> On the other hand, explicitly setting the parameter "2" to "a," results in the first unnamed parameter being left '''undefined''':</translate>

<translate>
<!--T:279-->
<tvar name="1"><code>}}t2demo}}2=  }}</code></tvar> results in <tvar name="2">}}</tvar>

<!--T:280-->
If the second parameter should not be trimmed, it must be unnamed.

<!--T:281-->
Therefore, you can assign an empty string to the first parameter, but you cannot leave it undefined.

==== Making emptiness and undefinedness equivalent ==== <!--T:282-->

<!--T:283-->
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.

<!--T:284-->
For example, using <tvar name="1"><code>p=</code></tvar> can show that a template has a parameter "p" that doesn't have a value yet.

<!--T:285-->
To make an empty string and an undefined value equivalent, use the following approaches:
</translate>
* <translate><!--T:286--> Use <tvar name="1"><code><nowiki>}</nowiki></code></tvar> exclusively instead of <tvar name="2"><code>}</code></tvar> or <tvar name="3"><code>}</code></tvar> where "q" is a non-empty value.</translate>
* <translate><!--T:287--> Use conditional checks like <tvar name="1"><code><nowiki>}|..}..|..}}</nowiki></code></tvar>, to ensure <tvar name="2"><code>}</code></tvar> is only used when it has a value.</translate>

<translate><!--T:350--> 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 <tvar name=1><code><nowiki>}|}|parameter is defined|parameter is undefined}}</nowiki></code></tvar>.</translate>

<translate>
=== Using equals signs in unnamed parameters === <!--T:288-->
</translate>
<translate><!--T:289--> Unnamed parameters can include equals signs, but this must be done indirectly.</translate>
<translate><!--T:290--> Here are some methods using <tvar name="1">[[template:T1demo]]</tvar>:</translate>

; <translate><!--T:291--> Default Value for Undefined Parameter</translate>
<translate><!--T:292--> Assign a default value to an undefined parameter:</translate>
 <code><nowiki>}}}</nowiki></code>
<translate><!--T:293--> This renders as:</translate> <code>}}}</code>.

; <translate><!--T:294--> Using the <tvar name="1"><code><nowiki></nowiki></code></tvar> parser function</translate>

<translate><!--T:295--> Use a parser function that safely includes an equals sign:</translate>
 <code><nowiki>b }}</nowiki></code>
<translate><!--T:296--> This renders as:</translate> <code>b }}</code>.

; <translate><!--T:297--> HTML Entities</translate>
<translate><!--T:298--> Replace the equals sign with an HTML entity for display:</translate>
 <code><nowiki></nowiki></code>
<translate><!--T:299--> This renders as:</translate> <code></code>.

<translate>
<!--T:300-->
This renders correctly without affecting the other parameters.

=== Handling unmatched curly and square brackets === <!--T:301-->

<!--T:302-->
Unmatched curly brackets (<tvar name=1><code><nowiki></code></tvar>) or square brackets (<tvar name=3><code><nowiki>[[</nowiki></code></tvar>, <tvar name="4"><code>]]</code></tvar>) must be inside nowiki tags or use HTML entities:
</translate>

* <translate><!--T:303--> Rendering curly brackets have two options:</translate>
** <translate><!--T:304--> Use <tvar name="1"><code><nowiki>&lt;nowiki>{{</nowiki></nowiki></code></tvar> or <tvar name="2"><code>&amp;#123;</code></tvar> for <tvar name="3"><code>{</code></tvar></translate>
** <translate><!--T:305--> Use <tvar name="1"><code><nowiki>&lt;nowiki>}}</nowiki></nowiki></code></tvar> or <tvar name="2"><code>&amp;#125;</code></tvar> for <tvar name="3"><code>}</code></tvar>.</translate> 
* <translate><!--T:306--> Use <tvar name="1"><code>&amp;#91;</code></tvar> for <tvar name="2"><code>&#91;</code></tvar> and <tvar name="3"><code>&amp;#93;</code></tvar> for <tvar name="4"><code>]</code></tvar>.</translate>

<translate>
<!--T:307-->
Below are some examples:
</translate>

; <translate><!--T:308--> Unmatched curly brackets</translate>
 <code><nowiki>&lt;/nowiki> }}</nowiki></code>
<translate><!--T:309--> This correctly renders the braces without breaking the template.</translate>

; <translate><!--T:310--> Unmatched square brackets</translate>
 <code><nowiki></nowiki></code>
<translate><!--T:311--> This correctly renders the braces without breaking the template.</translate>

<translate><!--T:312--> This renders as:</translate>
<code></code>

<translate>
<!--T:313-->
Unmatched pairs not placed in nowiki tags either prevent template expansion or are taken as closing braces for the template call.

<!--T:314-->
Below are some examples:
</translate>

 <code><nowiki></nowiki></code>

<translate>
<!--T:315-->
This will not expand correctly because of unmatched brackets.

<!--T:316-->
The correct use:
</translate>

 <code><nowiki></nowiki></code>

<translate><!--T:317--> This renders as:</translate>
<code></code>

<translate>
==== Template-generated brackets ==== <!--T:351-->
</translate>
<translate><!--T:352--> An alternate technique for passing arguments with unmatched brackets is to wrap them in another template.</translate>
<translate><!--T:407--> In that situation, (which exists with <tvar name=1></tvar> and <tvar name=2>)</tvar> on this wiki), the unmatched brackets will be rendered literally, and not decoded as another template call.</translate>
<translate><!--T:353--> For example:</translate>
<syntaxhighlight lang="wikitext">
t1demo}}
</syntaxhighlight>
<translate><!--T:354--> results in:</translate>
t1demo}}

<translate><!--T:355--> When [[<tvar name=1>Special:MyLanguage/Help:Substitution</tvar>|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.</translate>
<translate><!--T:356--> For example:</translate> 
<syntaxhighlight lang="wikitext">
t1demo|foo}}
</syntaxhighlight>
<translate><!--T:357--> will expand on save to:</translate>
<syntaxhighlight lang="wikitext">

</syntaxhighlight>
<translate><!--T:358--> which will then render as:</translate>

 

<translate><!--T:359--> 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.</translate>
<translate><!--T:360--> This technique may be used to implement [[<tvar name=1>Special:MyLanguage/Manual:Recursive conversion of wikitext</tvar>|recursive substitutions]] that take multiple saves to evaluate.</translate>

<translate>
=== Using pipes in parameter values === <!--T:361-->
</translate>
<translate><!--T:362--> A parameter value cannot contain a pipe character (<tvar name=1>|</tvar>), because it would be interpreted as the end of that parameter and the start of the next parameter.</translate>
<translate><!--T:363--> This can be worked around by using the  <tvar name=2><code><nowiki></nowiki></code></tvar>, or the HTML entity <tvar name=3>&amp;124;</tvar>.</translate>
<translate><!--T:364--> The two methods of doing this have slightly different behavior, which can be relevant in some corner cases like when a template is producing [[<tvar name=1>Special:MyLanguage/Help:Tables</tvar>|wikitable]] syntax.</translate>

<translate><!--T:365--> Example:</translate>
<code><nowiki></nowiki></code>
<translate><!--T:366--> produces:</translate>
 

<translate><!--T:367--> The "<tvar name=1>def</tvar>" doesn't display because it is treated as part of another unnamed parameter, which the template does not use.</translate>

<code><nowiki>def}}</nowiki></code>
<translate><!--T:368--> produces:</translate>
def}} 

<translate><!--T:369--> The "<tvar name=1>def</tvar>" displays properly.</translate>

<code><nowiki></nowiki></code>
<translate><!--T:370--> produces:</translate>
 

<translate>
<!--T:371-->
The "<tvar name=1>def</tvar>" displays properly again.

=== Formatting template calls using extra parameters === <!--T:372-->

<!--T:373-->
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.

<!--T:374-->
For example:
</translate>

<syntaxhighlight lang="wikitext">

</syntaxhighlight>

<translate><!--T:375--> is equivalent to, assuming the template doesn't recognize SPACEN as a parameter name:</translate>

<syntaxhighlight lang="wikitext">

</syntaxhighlight>

<translate>
<!--T:376-->
It is also possible to use the same name for each spacer (often the empty string), but this will populate <tvar name=1>[[:Category:Pages using duplicate arguments in template calls]]</tvar>, which many wikis prefer to keep empty to catch instances of user error.

<!--T:377-->
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.