Content deleted Content added
Giraffedata (talk | contribs) →Nesting templates: Correct parameter passing example |
mNo edit summary |
||
| (44 intermediate revisions by 26 users not shown) | |||
Line 1:
{{
{{Redirect-multi|2|H:T|Wikipedia:Template|help regarding tables|Help:Table|content guidelines|Wikipedia:Template namespace}}▼
{{For-multi|lists of commonly used templates|Wikipedia:Template index|a quick introduction to templates|Help:A quick guide to templates}}
▲{{Redirect|Wikipedia:Template|content guidelines|Wikipedia:Template namespace}}
{{Pp-semi-indef}}
{{Wikipedia how to|H:T|WP:TEMPLATE}}
{{beginner version|Help:A quick guide to templates}}
{{Wiki markup}}
A '''template''' is a Wikipedia page created to be included in other pages. Templates usually contain repetitive material that might need to show up on a larger number of articles or pages. They are commonly used for [[WP:Glossary#Boilerplate text|boilerplate]] messages, standardized warnings or notices, [[Help:Infobox|infoboxes]], [[WP:Navbox|navigational boxes]], and similar purposes. Templates can have parameters so that the same page generates different text on multiple pages that include it.
Line 11 ⟶ 10:
The most common method of inclusion is called [[Help:Transclusion|transclusion]], where the wiki source of the target page contains a reference to the template, using the {{tnull|{{var|Template name}}}} syntax. Another method is [[Help:Substitution|substitution]], where the content of the template is copied into the wiki source of the target page, just once, when it is saved.
[[Help:A quick guide to templates]] gives a brief introduction to the subject. There is further help from MediaWiki
==General description==
Line 26 ⟶ 25:
==Using templates==
===General===
Using a template is
Calling a template causes it to be either ''transcluded'' or ''substituted'' in the page that calls it (
[[Wikipedia:Transclusion|Transcluding]] a template means that when MediaWiki <em>displays</em> the page, it treats the template as if it were directly in the
and subsequent editors cannot tell that it originated from a template.
When you update a template, every page that transcludes it automatically reflects the update when the page is displayed in the future, whereas updating a template has no effect on pages that have previously been saved with the template substituted.
To
The [[number sign]] <code>#</code>
The template namespace is the default, so you can leave out the namespace <code>Template:</code> in the template name, and it is conventional to do so. However, you must specify the namespace prefix for templates in other namespaces, such as <code>User:</code>. To transclude a page in [[WP:MAINSPACE|mainspace]], precede its
▲Whereas MediaWiki variable names are all uppercase, template names have the same basic features and [[WP:NCHASHTAG|limitations]] as all [[Help:Page name|page names]]: they are [[Case sensitivity|case-sensitive]] (except for the first character); [[underscore]]s are parsed as spaces; and they cannot contain any of these characters: <code><nowiki># < > [ ] | { }</nowiki></code>. This is because those are reserved for [[wiki markup]].
{{A note}} Attempting to transclude a template that does not exist produces a [[WP:Red link|red link]], just like linking to any other nonexistent page. Following the link allows one to create that particular template. It is not possible to transclude
▲The [[number sign]] <code>#</code> denotes a [[URI fragment|fragment identifier]], which identifies a {{em|fragment}} or section of a document (such as a [[Help:Section|section]] in a Wikipedia article). Although you can use it in a [[WP:LINK|link]] to link to a section of a template page (like [[Template:Portal#Example]]), fragment identifiers have no meaning in a template call and are ignored. For example, {{tnull|Portal{{var|#Location}}|Books}} is the same as {{tnull|Portal|Books}}.
=== Parameters ===▼
▲The template namespace is the default, so you can leave out the namespace <code>Template:</code> in the template name, and it is conventional to do so. However, you must specify the namespace prefix for templates in other namespaces, such as <code>User:</code>. To transclude a page in [[WP:MAINSPACE|mainspace]], precede its title with a colon, as <code>{<nowiki />{:{{var|Page name}}}}</code>.
<!-- [[Help:Parameters]] redirects here, so: -->▼
▲{{A note}} Attempting to transclude a template that does not exist produces a [[WP:Red link|red link]], just like linking to any other nonexistent page. Following the link allows one to create that particular template. It is not possible to transclude pages between projects (such as different-language Wikipedias or MediaWiki)—to use a template on another language project, a copy of the template must be created in that project.
▲===Parameters===
▲<!--[[Help:Parameters]] redirects here, so: -->
{{about|template parameters|search parameters|Help:Searching#Parameters|section=yes}}
{{Further|Help:Transclusion#Template parameters}}
{{shortcut|H:PARAMETER|WP:PARAMETER}}
The basic transclusion syntax for a template can be further controlled using [[parameters]], which allow you to customize a template’s output. The syntax is <code><nowiki>{{Template name|</nowiki>''parameter''<nowiki>|</nowiki>''parameter''<nowiki>|...}}</nowiki></code>, where <code>{{var|Template name}}</code> is the template’s name, and each <code>{{var|parameter}}</code> can be either a simple value (known as an ''{{dfn|unnamed parameter}}'') or in the form <code>{{var|name}}={{var|value}}</code> (known as a ''{{dfn|named parameter}}''). The first, second, third, etc., unnamed parameters are named <code>1</code>, <code>2</code>, <code>3</code>, etc., so using <code><nowiki>{{Template name|1=value1|2=value2}}</nowiki></code> is equivalent to <code><nowiki>{{Template name|value1|value2}}</nowiki></code>.
Each template has specific parameters it can accept, as defined within its code. You can list named parameters in any order in a template call. Extra or misnamed parameters have no effect, while missing parameters cause a default value to be used. If a parameter is repeated, the last defined parameter value is used.
The value of a parameter can be
If a template call specifies a parameter which is not defined in the template, it has no effect. Editors sometime specify a parameter they know is not defined in the template — for example, editors sometimes include a parameter like {{tag|reason|open}} to add a brief explanation within the source as a [[Wikipedia:Manual of Style/Hidden text|hidden comment]]. (But some templates, such as [[Template:Requested move|Requested move]], are programmed to show the reason parameter if provided). Certain templates, especially complex ones like [[Wikipedia:Infobox|infoboxes]], may use the [[Module:Check for unknown parameters|check for unknown parameters module]] to alert editors about any [[:Category:Unknown parameters|unrecognized parameters]] they code by mistake.
==== Whitespace handling ====
Leading and trailing [[Wikipedia:Whitespace
The collapsing of line breaks around parameters can be used to [[Wikipedia:Template namespace#Readability of the code|improve the readability of a template call]] with many parameters by placing each parameter specification in its own line.
==== Variable length parameter lists ====
In MediaWiki, templates cannot automatically handle an unknown or unlimited number of parameters. Each possible parameter usually has to be predefined in the template code. For example, a template might be set up to use three specific parameters, such as <code>1</code>, <code>2</code>, and <code>3</code>. If someone includes additional parameters beyond those, they will not affect expansion of the template.
However, there are some ways to work around this:
▲Whitespace characters (spaces, tabs, returns) are stripped from the beginnings and ends of {{em|named}} parameter names and values, but not from the middle: thus <code><nowiki>{{ ... | myparam = this is a test }}</nowiki></code> has the same effect as <code><nowiki>{{ ... |myparam=this is a test}}</nowiki></code>. This does not apply to {{em|unnamed}} parameters, where all whitespace characters are preserved.
*Setting a limit: You can write the template to handle a fixed number of parameters by manually specifying each one (e.g., up to 10 or 20 parameters).
*Using templates or [[Wikipedia:Lua|modules]]: For cases needing a flexible number of inputs, templates can use Lua modules or helper templates (like {{mfl|separated entries|main}} or {{tl|separated entries}}). These helper tools provide more advanced handling, such as counting or iterating through parameters, enabling the use of multiple inputs without setting an exact number.
▲The value of a parameter can be the empty string, such as when the pipe or equals sign is followed immediately by the next pipe or the closing braces. This is different from not specifying the parameter at all, which results in a default value, although templates are often coded so as to behave the same in both cases.
However, modules can bypass this limitation. For simpler cases, the separated entries module expands all sequential parameters and lets you set custom delimiters. For more advanced usage, the {{mfl|params}} module enables counting, listing, mapping, filtering, and handling a variable number of parameters without prior knowledge of the exact number.
Templates that accepts an open number of parameters are often collected under [[:Category:Variadic templates]].
===Examples===
Line 98 ⟶ 108:
** To specify an unnamed parameter including an equals sign (for example in a [[URL]] with [[name–value pair]]s), replace the equals sign with the [[mw:Help:Magic words#Other|magic word]] {{tlx|{{=}}}}, which expands to an equals sign that will not be interpreted.
** Another method is to explicitly specify the positional parameters. The first unnamed parameter is named "1" and so on. To call template {{tl|done}} with <code>a=b</code> as the literal value for the first parameter, type either <code><nowiki>{{done|a{{=}}b}}</nowiki></code> or <code><nowiki>{{done|1=a=b}}</nowiki></code>.
* {{anchor|Pipe}}Similarly, it is not possible to use an ordinary pipe character <code>|</code> in a template parameter specification, as it would be interpreted as separating one parameter specification from another.{{efn|Again, this does not apply if it comes within another separately parsed item, such as a piped wikilink.}} This problem can similarly be solved by using the magic word {{tlx|!}} in place of the pipe, or—if the pipe is not intended to be parsed at a higher level—using the [[List of XML and HTML character entity references|HTML entity]] <code>&#124;</code>. Alternatively, for embedding [[Help:Table|wikitables]] in templates, you may use {{tlx|Wikitable}} to avoid excessive {{tlx|!}}.
* Remember that whitespace characters (spaces, tabs, carriage returns, and line feeds) are not automatically stripped from the start and end of unnamed parameters, unlike with named parameters. Including such characters (or any other non-visible characters in any parameters) may in some cases affect the template's behavior in unexpected ways. (Template designers can use {{tl|Trim}} to remove unwanted whitespace in unnamed parameters).
* In documentation and discussions, it is customary to put the name of a template in double braces to emphasize the reference to a template (for example, use {{tl|Trim}} as the name of Template:Trim). If you just type <code><nowiki>{{Trim}}</nowiki></code> in the source page, that will of course call the template, so to make it easy to display the name with the braces, and also make the name a link to the template for the reader's convenience, there is the {{tl|tl}} template (the "'''t'''emplate '''l'''ink" template). For example, {{tnull|tl|Example}} produces {{tl|Example}}. There are various other [[Template:Template-linking templates|template-linking templates]] available with other functions.
Line 123 ⟶ 133:
Before creating a template, do a quick search for existing templates (such as by exploring [[:Category:Wikipedia templates]]) to see if there is already a template that does what you want or a similar template whose code can be copied and modified (or left in place and expanded). Look for generic templates on which the new template can be based; for example, you can create a [[WP:Navbox|navbox]] template easily by creating a brief template that calls the generic [[Template:Navbox]].
There is no hard rule about what name to choose for a template—make it short but reasonably descriptive. The [[Wikipedia:Template namespace|naming guideline]] says: "Template function should be clear from the template name". If similar templates exist, try to follow a consistent naming pattern. You can rename a template without breaking existing [[Help:Transclusion|transclusions]] (what is called ''breakage'') by leaving a [[WP:Redirect|redirect]] to the new template name.
====Modifying====
Line 137 ⟶ 147:
===Coding a template===
Anything that can be included on a normal page or article can be included on a template, including other templates (called ''{{dfn|subtemplates}}''). Templates often make use of programming features—parameters, parser functions, and other [[Help:Magic words|magic words]]—which allow the transcluded content to vary depending on context. There are also special tags to control which information is transcluded and which is not.
==== Metatemplates ====
Various [[Help:Metatemplating|metatemplates]] and metamodules exist to help accomplish common template tasks. They are called like normal templates and [[Help:Modules|modules]], but they serve a purpose that makes writing templates easier. See {{Cl|Wikipedia metatemplates}} and {{Cl|Template metamodules}} for a list of those templates and modules.
===Handling parameters===
Line 144 ⟶ 157:
If a parameter is not specified in the template call, then the parameter reference is not replaced with anything -- it is expanded literally; this means that if the template call does not specify the parameter "xxx", the wikitext <code><nowiki>{{{xxx}}}</nowiki></code> inside the template expands to literally ''<nowiki>{{{xxx}}}</nowiki>'' (not the null string you may have expected). You can get a more useful behavior by specifying a default value in the parameter reference. Do this with the ''pipe syntax'': <code><nowiki>{{{xxx|dflt}}}</nowiki></code> specifies the default value <code>dflt</code> for the named parameter "xxx", and <code><nowiki>{{{1|dflt}}}</nowiki></code> specifies the default value <code>dflt</code> for the first unnamed parameter. Most often, one specifies a null default value, such as <code><nowiki>{{{1|}}}</nowiki></code> or <code><nowiki>{{{xxx|}}}</nowiki></code>.
If a call sets a parameter to the empty string like <code><nowiki>{{Template name|xxx=}}</nowiki></code> then <code><nowiki>{{{xxx|OK}}}</nowiki></code> will produce the empty string and not the default value "OK". Many users will expect that an empty parameter gives the same result as omitting the parameter. You can achieve this with: <code><nowiki>{{#if:{{{xxx|}}}|{{{xxx}}}|OK}}</nowiki></code>. This says: If <code>xxx</code> is assigned a non-empty value then use <code>xxx</code>, otherwise use "OK". If the default value is the empty string then you only have to write <code><nowiki>{{{xxx|}}}</nowiki></code>.
You can use default parameter values to effect a parameter alias:
Line 187 ⟶ 202:
===System variables and conditional logic===
Template code often makes use of the variables and parser functions described at [[Help:Magic words]] to make the template's behavior depend on the environment in which it is included (such as the current time or namespace). Parser functions can be used for some arithmetic calculations and string manipulations on variables and parameter values, but certain standard programming features such as loops and variable assignment are not available. Full string manipulation is not available; some templates providing such function have been created, but they are inefficient and imperfect.
Some of the most frequently used variables and functions are listed below. For more, see [[Help:Magic words]] and the fuller documentation at the MediaWiki pages [[mw:Help:Magic words]] and [[mw:Help:Extension:ParserFunctions]].
Line 218 ⟶ 233:
! width="30%" | Description !! width="40%" | Wiki source !! width="30%" | Displayed text
|-
| rowspan="2" | Testing for equality between two strings (or parameters). If the first two parameters are equal, the third parameter is returned, otherwise the fourth parameter is returned.
| <syntaxhighlight lang="wikitext" inline>{{#ifeq: yes | yes | Hooray...! | Darn...! }}</syntaxhighlight>
| {{#ifeq: yes | yes | Hooray...! | Darn...! }}
Line 225 ⟶ 240:
| {{#ifeq: yes | no | Hooray...! | Darn...! }}
|-
| Testing whether a string (or parameter) contains anything (other than whitespace). If it does, the second parameter is returned, otherwise the third parameter is returned.
| <syntaxhighlight lang="wikitext" inline>{{#if: {{{param|}}} | Hooray...! | Darn...! }}</syntaxhighlight>
| {{#if: {{{param|}}} | Hooray...! | Darn...! }}
Line 233 ⟶ 248:
| {{#expr: ( pi * 4 ^ 2 ) round 3 }}
|-
| [[Help:Calculation|Testing the result of a calculation]]. If the expression is true or non-zero, the second parameter is returned, otherwise the third parameter is returned.<br />[is 1230 even or odd?]
| <syntaxhighlight lang="wikitext" inline>{{#ifexpr: 1.23E+3 mod 2 | Odd | Even }}</syntaxhighlight>
| {{#ifexpr: 1.23E+3 mod 2 | Odd | Even }}
Line 265 ⟶ 280:
| {{CURRENTVERSION}}
|-
| Timestamp of last page revision
| <syntaxhighlight lang="wikitext" inline>{{REVISIONTIMESTAMP}}</syntaxhighlight>
| {{REVISIONTIMESTAMP}}
Line 278 ⟶ 293:
While fairly straightforward in application, it involves some noteworthy quirks and tricks.
To pass a parameter value from a template call
;Example{{colon}}
:Template:A contains <syntaxhighlight lang="wikitext" inline>"the quick brown {{B|{{{3}}} }} jumps over..."</syntaxhighlight>. Template:B (a subtemplate) contains <syntaxhighlight lang="moin" inline>'''{{{1}}}'''</syntaxhighlight>. Page X calls A with <syntaxhighlight lang="wikitext" inline>{{A|apple|pear|fox}}</syntaxhighlight> This expands to <syntaxhighlight lang="wikitext" inline>"the quick brown '''fox''' jumps over..."</syntaxhighlight>. The third unnamed parameter passed to Template:A gets passes as the first unnamed parameter to subtemplate B.
Line 291 ⟶ 306:
When a subtemplate contains unmatched braces—as in <syntaxhighlight lang="text" inline>{{lb}}}</syntaxhighlight>—the unmatched braces are treated as text during processing—they do not affect the parsing of braces in the calling template. But where the template is substituted, the unmatched braces will be parsed as braces when the page is subsequently displayed. This has little practical use, but can occasionally introduce unexpected errors.
See [[
===<span id="Noinclude, includeonly, and onlyinclude"></span>Inclusion control: noinclude, includeonly, and onlyinclude===
Line 305 ⟶ 320:
! What is included {{em|there}} (calling page)
|-
|
|
|
|-
|
|
|
|-
|
|
|
|-
|{{tag|onlyinclude|content={{tag|includeonly|content= {{bxt|text1}} }} }} {{mxtn|text2}}
|
|
|}
Line 334 ⟶ 349:
** Use <code>subst:</code> to substitute a template (rather than transclude it), which can show more clearly what is happening when the template is transcluded; see [[Help:Substitution]].
** Use <code>msgnw:</code> (short for "'''m'''e'''s'''sa'''g'''e, '''n'''o'''w'''iki") to more-or-less transclude the source of the template rather than its expansion. It is not perfect: lists are rendered, comments are removed, and single newlines are replaced with spaces (which is particularly confounding when transcluding wikitext tables).
* If the first character of a template expansion (or parser function result) is one of four wiki markup characters—<code>:</code>, <code>;</code>, <code>*</code>, <code>#</code>{{efn|These are defined in the [https://web.archive.org/web/20180625163321/https://doc.wikimedia.org/mediawiki-core/master/php/classParser.html#ad463888e40c078ac9bcfcaf1231e39d7 <code>doBlockLevels</code> function of Parser.php].}}, it is processed during display as though it were at the beginning of a line, even if the template call is not. This allows you to create various kinds of lists with templates where the template call may not be in the correct place for a list. To avoid this,
* For issues with template substitution, such as how to control whether subtemplates are substituted as well when the parent template is substituted, see [[Help:Substitution]].
* You can use the template {{tlx|Trim}} to strip any initial or final whitespace from unnamed parameter values if this would cause problems; <em>named</em> parameter values are automatically stripped in this way.
Line 350 ⟶ 365:
===Categorization===
{{See also|
====Categorize pages by template inclusion====
Some templates generate category declarations in their expansion, since the template is intended to place calling pages in particular categories. This is often done with maintenance categories. Placing articles into ordinary content categories in this way is discouraged. When doing this, you may have to use {{tag|includeonly}} tags to keep the template itself out of the category. While developing, testing, sandboxing, or demonstrating a template intended to apply a category, either temporarily replace each category with a test category (starting with [[:Category:X1|X1]], [[:Category:X2|X2]], or [[:Category:X3|X3]]) or suppress categorization (see [[WP:CATSUP|category suppression in templates]]).
Line 366 ⟶ 381:
==Template limits==
{{details|Help:Template limits}}▼
{{shortcut|WP:INCLUDELIMIT}}
{{Anchor|Expand limits}}
▲{{details|Help:Template limits}}
'''"Post-expand include size" limit.''' When templates are rendered or expanded to HTML for viewing in your browser, they use memory. This is called the "post-expand include size" and has a limit of 2,048,000 bytes. This size is included as an invisible comment in the HTML output—use your browser's view source feature to show the raw HTML and search for "newpp". The report will look like:
<syntaxhighlight lang="html">
Line 408 ⟶ 423:
The displayed page content generated by a template call (which is the rendering of the expansion of the called template) is the ''template result''. The template result generated by the template call <syntaxhighlight lang="wikitext" inline>{{sic|constellation prize}}</syntaxhighlight> is "{{sic|constellation prize}}".
The ''name'' of a template is the name of the
Some template calls perform a tagging function; such a template call is often called a ''tag'', as in, "If you are in the middle of a major edit, place an {{tl|in use}} tag at the top of the page." This is one of many ways the term "tag" is used in Wikipedia.
Line 455 ⟶ 470:
* [[WP:TemplateData]]—standardized template description used by [[Wikipedia:VisualEditor|VisualEditor]]
* [[WP:WikiProject Templates]]
* [[
* [[mw:Manual:Expr parser function syntax]]
* [[m:User:Happy-melon/Templates]]
* [[mw:Help:ExpandTemplates]]
Line 465 ⟶ 478:
* [[mw:Help:Templates]]
{{div col end}}
=== Mediawiki manual pages ===
* [[mw:Manual:$wgEnableScaryTranscluding]]
| |||