Help: Template Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.Anti-spam check. Do not fill this in! ==Using templates== ===General=== Using a template is much like calling a [[Subroutine|function]] in a programming language – call it, and it returns a value. For a template, the return value is called the ''expansion'' of the template and is treated as part of the calling page source. Like functions, some templates accept parameters that affect the output. Calling a template causes it to be either transcluded or substituted in the page that calls it (which is known as the ''target page''). Transcluding a template means that when MediaWiki displays the page, it treats the template as if it were in the wiki source of the page, whereas substituting means MediaWiki does that when it <em>saves</em> the page (i.e. the content of the template gets stored as part of the target page and subsequent editors cannot tell that it got there via a template). To transclude a template into a page, put {{tnull|{{var|Template name}}}} in the page source at the place where the template is to appear. The first letter of each word of the title may equivalently be lower- or upper-case. To substitute a template into a page, use {{tnull|subst:{{var|Template name}}}} instead. This wikitext is called a ''template call''. In [[MediaWiki]], the [[wiki software]] that Wikipedia uses, [[Help:Magic words#Variables|variables]] are distinct from templates, but they are both identified by double [[Curly brackets|braces]] <code><nowiki>{{ }}</nowiki></code> and they both return a value. 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]]. The [[number sign]] <code>#</code> is called a [[URI fragment|fragment identifier]] because it denotes a {{em|fragment}} or section of a document (such as a [[Help:Section|section]] in a Wikipedia article). Although it [[WP:ANCHOR|can be used]] to link to a section of a template page (like [[Template:Portal#Example]]), there is no reason to put a fragment identifier or fragment name in a template reference. In {{tnull|Portal{{var|#Location}}|Books}}, for example, the string <code>{{var|#Location}}</code> has no purpose and is thus ignored. 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 namspace 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>. {{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}} {{shortcut|H:PARAMETER|WP:PARAMETER}} The basic transclusion syntax given above can be extended with [[parameter]]s, which are used to control the template's output. The syntax for this is {{tnull|{{var|Template name}}|{{var|parameter}}|{{var|parameter}}|{{var|...}}}} where <code>{{var|Template name}}</code> is the name of the template, and each <code>{{var|parameter}}</code> may either contain just a value (these are called ''{{dfn|unnamed parameters}}'') or be of the form <code>{{var|name}}={{var|value}}</code> (''{{dfn|named parameters}}''). The first, second, third, etc. unnamed parameters are given the names <code>1</code>, <code>2</code>, <code>3</code>, etc. 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. What parameters (if any) can or should be passed to a template and how they are to be named is defined in the coding of that template. A template call can specify named parameters in any order. Superfluous or misnamed parameters are ignored; unspecified parameters are assigned default values. If a parameter is specified more than once, the last value takes effect. 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. If a template call specifies a parameter which is not defined in the template, it has no effect. Sometimes editors do this on purpose: For example, {{para|reason}} is frequently used as a pseudo-parameter to explain briefly in the wiki source why the template call was put there.{{efn|Some templates, such as {{tlx|Requested move}}, have code to display {{para|reason}} as visible output; whether to do so is determined on a template-by-template basis.}} Some templates use {{ml|check for unknown parameters|check|...}} to warn the editor if a parameter is being used that is not accounted for in the template's code; this is mostly used for [[Help:Infobox|infoboxes]] and other templates with a large number of complicated parameters, where the presence of an unknown one is usually an unintentional error. If you update such a template to define a new parameter, its call to the module must also be updated to include the new parameter. Wikitext syntax does not allow natively to create truly [[variadic template]]s, but only pseudo-variadic ones, that check the incoming parameters one by one until a certain fixed amount. It is possible to break this limitation however by using dedicated modules. For simple cases, {{ml|separated entries|main}} allows to expand all sequential parameters blindly and has the ability to set custom delimiters. For more complex cases, {{ml|params|}} allows to count, list, map, filter and propagate all incoming parameters without knowing their number in advance. ===Examples=== {{A note}} If you wish to experiment with any of these, you can use the [[Template:Template sandbox|template sandbox]] or your user page or sandbox. You can try out your template with [[Special:ExpandTemplates]]. An example of a very simple template can be found at [[Template:TM]], which expands to wikitext that places the trademark symbol (™), linked to the [[trademark]] article, at that point in the displayed page. A programmer would say that the template "returns" the trademark symbol link wikitext. Display [[Template:TM]] (by clicking on the foregoing link), then click on the "Edit" tab to see the template code (its page source). The active part of that code, which becomes the expansion of the template when it is transcluded, is the single link wikitext <code><nowiki>[[Trademark|™]]</nowiki></code>. The remainder of the page source is enclosed between {{xtag|noinclude}} tags, so it shows up when you display the template page itself but not when you display a page that calls the template. To transclude Template:TM onto another page (i.e., to use it on another page), type {{tlx|TM}} into the source of that page (the target page) and click {{Button|Show preview}}. The page will be displayed with the template call replaced by the expansion of the template, as if the wikitext actually contained <code><nowiki>[[Trademark|™]]</nowiki></code> at that point. The displayed page will therefore contain the wikilink "[[Trademark|™]]". For example, type <code>The trademark symbol is {{tl|TM}}</code> and you will see "The trademark symbol is {{TM}}" when previewing the page or after saving the change. The other way to use a template is to [[Help:Substitution|substitute]] it. If you type <code>The trademark symbol is {{tls|TM}}</code> and preview or save the page, you will see "The trademark symbol is [[Trademark|™]]" just as with the transclusion example above. But if you save the page and then look again at the saved page <em>source</em>,{{efn|There is no way to preview the effect on the page source of substitution without saving the page}} you will see <code>The trademark symbol is <nowiki>[[Trademark|™]]</nowiki></code>, because the template call was replaced by the expansion of the template when you saved the page. There is no ongoing connection to the template call; no one can tell by looking at the page source that you didn't just type <code>The trademark symbol is <nowiki>[[Trademark|™]]</nowiki></code> and if the {{tl|TM}} template changes (or ceases to exist), your page will continue to display as it does now. (In contrast, in the transclusion example above, if the {{tl|TM}} template subsequently changes, your page may then display differently). ===={{anchor|Parameters}} Examples with parameters==== An example of a template that takes parameters is the template {{tlx|about}}. Try typing {{tnull|about|how to use templates|how to use modules|Help:Lua}} in the sandbox—it will produce the following text: {{about|how to use templates|how to use modules|Help:Lua}} The template {{tlx|about}} uses three [[unnamed parameter]]s (also called positional parameters) in the example above, but you can call the same template with different numbers of parameters to give slightly different results, as explained in [[Template:About/doc|the template's documentation]]. For example, {{tnull|about||how to use modules|Help:Lua}}. Note the usage of an empty parameter—in this instance, the consecutive pipes mean that the first parameter specified is an empty string, which in this template will cause it to omit the initial "about" sentence. This produces: {{about||how to use modules|Help:Lua}} A simple example of a template that has named parameters is [[Template:Payoff matrix]], used to generate a 2-by-2 grid. For example: {{Markup|<nowiki>{{payoff matrix | UL = 5 | UR = 7 | DL = 2 | DR = 9 | Name = Example usage }}</nowiki>|{{payoff matrix | UL = 5 | UR = 7 | DL = 2 | DR = 9 | Name = Example usage }}}} See the [[Template:Payoff matrix|template page]] for more possibilities. Notice that the template is called here without specifying all its possible parameters, so undefined parameters are given default values. ===Hints and workarounds=== The following points may be worth noting when using templates: * Templates are not the only method of [[Help:Transclusion|transclusion]], in some cases, other methods such as [[WP:SELECTIVETRANSCLUSION|selective transclusion]] are more appropriate. * {{anchor|Equals}}An unnamed parameter value cannot contain an ordinary equals sign, as this would be interpreted in the parameter specification as a named parameter (with the equals sign separating the name from its value).{{efn|This does not apply if the equals sign comes within another template call or other item which the parser handles separately.}} 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 replace the unnamed parameter specifications with named parameters specifications—unnamed parameters are equivalent to named parameters where 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>. * 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. * When an editor changes a template (by editing the template or one of its subtemplates), the change will ultimately be reflected any time any page that transcludes that template is subsequently displayed. However, the change may not become visible on all pages immediately; a previously cached version of a page, based on the previous version of the template, may continue to be displayed for some time. Use the [[WP:Purge|purge]] function to force a page to be displayed using the latest versions of templates—including on the template page itself, if it contains usage examples. * When viewing old versions of pages, remember that templates will be transcluded as they are now, not necessarily as they were when the old page version was active. * To list all pages that transclude a template, use the [[Help:What links here|What links here]] link on the page when you display the template page. Note that this will {{em|not}} include pages where the template has been substituted, as there is no record of substitutions. * To get a list of templates transcluded on a page, bring up the edit page and find the list below the edit window. This list also includes the subtemplates used by the templates that are directly transcluded. To get such a list for a page section, an old version of the page,{{efn|For an old version, the subtemplate tree will be constructed according to the templates' current state.}} or your newly edited version prior to saving, click {{Button|Show preview}} on the appropriate edit page. * There are limits to the number and complexity of the templates that an article may have. See the "[[#Expand limits|§ Expand limits]]" section for help with this. * If you want the template to leave a [[WP:~|time stamp or signature]], you can write <code><noinclude><nowiki></noinclude><nowiki>~~~~~</nowiki><noinclude></nowiki></noinclude></code>, but this works only when you <em>substitute</em> the template. If you <em>transclude</em> it, you'll just get <nowiki>~~~~~</nowiki>. * To improve readability, programmers usually like to split code with newlines and indent it. Unfortunately, [[MediaWiki]] does not allow this technique; in many instances, these purpose-built newlines are treated by MediaWiki as content. One possible workaround is to add <code><!--</code> before each newline character and <code>--></code> after it, which produces an [[HTML comment]]. Summary: Please note that all contributions to Christianpedia may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here. You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see Christianpedia:Copyrights for details). Do not submit copyrighted work without permission! Cancel Editing help (opens in new window) Discuss this page