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! ==Writing templates== <!--[[Help:Subtemplates]] redirects here.--> ===Process=== Templates are just Wikipedia pages. They are created, deleted, and edited in much the same way as any other page. ====Creating==== To create a template, choose an appropriate name, navigate to that page, then click the "Edit" tab or create a new page as needed. Templates are normally placed in the [[WP:Template namespace|template namespace]], though you can place a template intended for your own personal use or for experimentation in your own [[WP:User pages|user space]]. 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. 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==== Edit a template the same way as any other page: navigate to the template and click the "Edit" tab. Be extremely careful when editing existing templates—changes made can affect a large number of pages, often in ways you might not expect. For this reason many high-use templates are [[WP:Protection policy|protected]] against editing except by [[WP:Administrators|administrators]] and [[WP:Template editor|template editors]]; other editors can propose changes on the talk page. Some templates offer a [[WP:Template sandbox and test cases|sandbox and test cases]] for experimentation. ====Deleting==== Unused or inappropriate templates should be deleted. Templates that can be easily merged into another should be merged. To propose the deletion or merger of a template, go to [[WP:Templates for discussion|Templates for discussion]] (TfD). ===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. ===Handling parameters=== In template code, the value of a parameter is represented by items enclosed between {{em|triple}} braces, which is a ''parameter reference''. * The code <code><nowiki>{{{xxx}}}</nowiki></code> expands to the value of the parameter named "xxx". * The codes <code><nowiki>{{{1}}}</nowiki></code>, <code><nowiki>{{{2}}}</nowiki></code>, and so on are expanded to the first, second, and so on unnamed parameters. (Note that an unnamed parameter can alternatively be specified in a template call as an equivalent named parameter named "1", "2", etc.). 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>. You can use default parameter values to effect a parameter alias: For example, if parameters "text" and "message" are names for the same parameter, which can also be specified as the only unnamed parameter, then refer to the parameter with <code><nowiki>{{{message|{{{text|{{{1|}}}}}}}}}</nowiki></code>. If the template call specifies more than one of those parameters, "message" will have priority, followed by "text", and finally by the first unnamed parameter. So if a template call specifies parameters <code>|message=A|text=B|C</code>, the above wikitext expands to <code>A</code>. Because of the multiple meanings of double-brace and triple-brace syntax in wikitext, expressions can sometimes be ambiguous. It may be helpful or necessary to include spaces to resolve such ambiguity. For example, <code><nowiki>{{ {{{xxx}}} }}</nowiki></code> or <code><nowiki>{{{ {{xxx}} }}}</nowiki></code>, rather than typing five consecutive braces, may be more human-readable. But watch out for unwanted whitespace appearing in the template expansion. Parameter references do not get expanded when they are wrapped in {{xtag|nowiki}} tags. ====Example==== The parameter usage example above refers to the {{tl|payoff matrix}} template. Here is the code in the template that implements those parameters: <syntaxhighlight lang="wikitext"> {| id="Payoff matrix" style="background:white; float: {{{Float|right}}}; clear:right; text-align:center;" align={{{Float|right}}} cellspacing=0 cellpadding=8 width={{{Width|225}}} |- |style="width:33%; "| |style="width:33%; border-bottom: solid black 1px;"| {{{2L|Left}}} |style="width:33%; border-bottom: solid black 1px;"| {{{2R|Right}}} |- |style="border-right: solid black 1px; text-align: right; "| {{{1U|Up}}} |style="border-right: solid black 1px; border-bottom: solid black 1px; background:{{{ULc|white}}}; font-size:120%; "| {{{UL|0, 0}}} |style="border-right: solid black 1px; border-bottom: solid black 1px; background:{{{URc|white}}}; font-size:120%; "| {{{UR|0, 0}}} |- |style="border-right: solid black 1px; text-align: right; "| {{{1D|Down}}} |style="border-right: solid black 1px; border-bottom: solid black 1px; background:{{{DLc|white}}}; font-size:120%; "| {{{DL|0, 0}}} |style="border-right: solid black 1px; border-bottom: solid black 1px; background:{{{DRc|white}}}; font-size:120%; "| {{{DR|0, 0}}} |- |style="font-size: 90%;" colspan=3 |''{{{Name|{{PAGENAME}}}}}'' |}</syntaxhighlight> The entity <syntaxhighlight lang="wikitext" inline>{{{2L|Left}}}</syntaxhighlight> instructs the template to use the value of the named parameter <code>2L</code> or the text <code>Left</code> if the parameter is not specified in the call. ====Special case: parameters within an XML-style opening tag==== Parameter references aren't expanded inside [[XML]]-style opening tags. Thus, the following will not work within a template: *{{!mxt|<nowiki><ref name={{{param}}}> Smith, Adam (1776)...</ref></nowiki>}} because the parameter is not expanded. Instead, you can use the <code><nowiki>{{#tag:}}</nowiki></code> [[WP:PF|parser function]], which is—for example—used in {{tlx|sfn}} to generate the {{tag|ref}} element; see also {{section link|Help:Magic words|Formatting}}. Therefore, the following example will work: *{{mxt|<nowiki>{{#tag:ref | Smith, Adam (1776)... | name={{{param}}} }}</nowiki>}} ====Caution: overextending URLs==== If a parameter's value is (or ends with) a [[URL]], check whether it is displayed in Wikipedia with the link overextending by one or more characters after the URL so that clicking the link causes an error or failure. This could happen because the source code does not have a space after the URL or it contains or generates a space that is discarded in the processing. Ensure that in the template expansion a soft space ({{em|not}} a [[Non-breaking space|hard or non-breaking space]]) follows the URL, regardless of whether you or a user supplied the URL or whether it was generated by automated processing. The {{tlx|spaces}} template may be useful. ===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 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]]. {| class="wikitable" style="text-align:center;" width="100%" |+Examples of core parser functions ! width="30%" | Description !! width="40%" | wiki source !! width="30%" | Displayed text |- | Uppercasing text | <syntaxhighlight lang="wikitext" inline>{{uc: Heavens to BETSY! }}</syntaxhighlight> | {{uc: Heavens to BETSY! }} |- | Lowercasing text | <syntaxhighlight lang="wikitext" inline>{{lc: Heavens to BETSY! }}</syntaxhighlight> | {{lc: Heavens to BETSY! }} |- | Getting a namespace name | <syntaxhighlight lang="wikitext" inline>{{NS: 1 }}</syntaxhighlight> | {{NS: 1 }} |- | Getting a Wikipedia URL | <syntaxhighlight lang="wikitext" inline>{{fullurl: pagename }}</syntaxhighlight> | {{fullurl: pagename }} |} The ParserFunctions extension provides more programming-oriented parser functions: {| class="wikitable" style="text-align:center;" width="100%" |+Examples of extension parser functions ! width="30%" | Description !! width="40%" | Wiki source !! width="30%" | Displayed text |- | rowspan="2" | Testing for equality between two strings (or parameters) | <syntaxhighlight lang="wikitext" inline>{{#ifeq: yes | yes | Hooray...! | Darn...! }}</syntaxhighlight> | {{#ifeq: yes | yes | Hooray...! | Darn...! }} |- | <syntaxhighlight lang="wikitext" inline>{{#ifeq: yes | no | Hooray...! | Darn...! }}</syntaxhighlight> | {{#ifeq: yes | no | Hooray...! | Darn...! }} |- | Testing whether a string (or parameter) contains anything (other than whitespace) | <syntaxhighlight lang="wikitext" inline>{{#if: {{{param|}}} | Hooray...! | Darn...! }}</syntaxhighlight> | {{#if: {{{param|}}} | Hooray...! | Darn...! }} |- | [[Help:Calculation|Making a calculation (mathematics)]]<br />[area of circle of radius 4, to 3 decimal places] | <syntaxhighlight lang="wikitext" inline>{{#expr: ( pi * 4 ^ 2 ) round 3 }}</syntaxhighlight> | {{#expr: ( pi * 4 ^ 2 ) round 3 }} |- | [[Help:Calculation|Testing the result of a calculation]]<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 }} |} {| class="wikitable" style="text-align:center;" width="100%" |+Examples of system variables ! width="30%" | Description !! width="40%" | Wiki source !! width="30%" | Displayed text (for this help page) |- | rowspan="2" | Page names | <syntaxhighlight lang="wikitext" inline>{{PAGENAME}}</syntaxhighlight> | {{PAGENAME}} |- | <syntaxhighlight lang="wikitext" inline>{{FULLPAGENAME}}</syntaxhighlight> | {{FULLPAGENAME}} |- | Name of the current namespace | <syntaxhighlight lang="wikitext" inline>{{NAMESPACE}}</syntaxhighlight> | {{NAMESPACE}} |- | Number of registered users | <syntaxhighlight lang="wikitext" inline>{{NUMBEROFUSERS}}</syntaxhighlight> | {{NUMBEROFUSERS}} |- | Number of pages in a given category | <syntaxhighlight lang="wikitext" inline>{{PAGESINCATEGORY:"Weird Al" Yankovic albums}}</syntaxhighlight> | {{PAGESINCATEGORY:"Weird Al" Yankovic albums}} |- | Current software version | <syntaxhighlight lang="wikitext" inline>{{CURRENTVERSION}}</syntaxhighlight> | {{CURRENTVERSION}} |- | Timestamp of last revision | <syntaxhighlight lang="wikitext" inline>{{REVISIONTIMESTAMP}}</syntaxhighlight> | {{REVISIONTIMESTAMP}} |} The <syntaxhighlight lang="wikitext" inline>{{PAGENAME}}</syntaxhighlight> and <syntaxhighlight lang="wikitext" inline>{{NAMESPACE}}</syntaxhighlight>variables are particularly useful, and frequently used, to change template behavior based on the context in which they are included. Templates that contain category links often do this. For example, a cleanup template contains a category link to categorize the calling page as one which needs cleanup, so the template is likely to condition that category link on the <syntaxhighlight lang="wikitext" inline>{{NAMESPACE}}</syntaxhighlight> variable so that talk pages, user pages, and any other pages that might call the template incidentally do not get categorized as pages needing cleanup. ===Nesting templates=== {{shortcut|WP:NEST}} A template may call another template—this is called ''{{dfn|nesting}}'' and the called template is called, in this context, a ''{{dfn|subtemplate}}''. When WikiMedia expands the template, it expands subtemplates as the calls to them appear, so that the final product is essentially the result of expanding templates from the most deeply nested out. While fairly straightforward in application, it involves some noteworthy quirks and tricks. To pass a parameter value from a template call to to a subtemplate, use a parameter reference in the template call to the subtemplate. ;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. A template can even choose which subtemplate parameter to pass conditionally. ;Examples{{colon}} :Template:A contains <syntaxhighlight lang="wikitext" inline>the quick brown {{B|{{{1}}}=fox}} jumps over...</syntaxhighlight>. Template:B (a subtemplate) contains <syntaxhighlight lang="moin" inline>'''{{{jumper}}}'''</syntaxhighlight>. Page X calls A with <syntaxhighlight lang="wikitext" inline>{{A|apple|pear|jumper}}</syntaxhighlight>. This expands to <syntaxhighlight lang="wikitext" inline>"the quick brown '''fox''' jumps over..."</syntaxhighlight>. The third unnamed parameter passed to Template:A is passed as the name of the parameter passed to subtemplate B with the value "fox". {{shortcut|WP:TEMPLATE LOOP}} Template recursion is not available; that is, a template may not call itself directly, or indirectly by calling other templates which call it. Attempts to do so will result in an error message describing a "template loop". 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 [[m:Help:Advanced templates]] and [[m:Help:Recursive conversion of wikitext]] for more information. ===<span id="Noinclude, includeonly, and onlyinclude"></span>Inclusion control: noinclude, includeonly, and onlyinclude=== {{shortcut|WP:NOINCLUDE|WP:INCLUDEONLY|WP:ONLYINCLUDE}} By default, when a page calls a template, MediaWiki includes the expansion of the entire template in the calling page. However, it is possible to modify that behavior, using tags that specify which parts of the template code are to be included. This makes it possible for the template to contain information only for display when the template page itself is displayed, such as the template's [[Wikipedia:Template documentation|documentation]], or [[WP:CAT#T|categories]]. It is also possible to have parts of the template be included in calling pages, but {{em|not}} be displayed when the template page itself is displayed and not be processed when the template page itself is saved (e.g., categories to be applied to calling pages which do not apply to the template). The tags are as follows: * {{xtag|noinclude|p}} – The text between the tags is {{em|not}} included when the template is called, but {{em|is}} processed when the template itself is displayed or saved; a common use is for [[WP:Template documentation|documentation in templates]]. * {{xtag|onlyinclude|p}} – Nothing on the page {{em|except}} what appears between the tags is included when the template is called. * {{xtag|includeonly|p}} – The text between the tags {{em|is}} included when the template is called, but is {{em|not}} processed when the template is displayed or saved. {| class="wikitable" style="text-align: center;" ! Wikitext ! What is rendered {{em|here}} (template page) ! What is included {{em|there}} (calling page) |- |<code><nowiki><noinclude> text1 </noinclude> text2</nowiki></code> |<code>text1 text2</code> |<code>text2</code> |- |<code><nowiki><onlyinclude> text1 </onlyinclude> text2</nowiki></code> |<code>text1 text2</code> |<code>text1</code> |- |<code><nowiki><includeonly> text1 </includeonly> text2</nowiki></code> |<code>text2</code> |<code>text1 text2</code> |- |<code><nowiki><onlyinclude><includeonly> text1 </includeonly></onlyinclude> text2</nowiki></code> |<code>text2</code> |<code>text1</code> |} Perhaps the most common issue with the use of these blocks is unwanted spaces or lines. It is important to remember that the effect of these tags begins immediately before the first angle bracket, not on the previous line or at the previous visible character; similarly the effect ends immediately after the last angle bracket, not on the next line or with the next visible character. For example: :{{mxt|<nowiki>}}<includeonly></nowiki>}} :{{!mxt|<nowiki>}}</nowiki><br /><nowiki></includeonly></nowiki>}} These tags can be nested inside each other, though (for a given page) this is really meaningful only for the {{tag|onlyinclude|o}} tag; nesting {{tag|includeonly|o}} and {{tag|noinclude|o}} tags is fairly pointless. Be careful to properly nest the tags, however. Constructions like {{tag|onlyinclude|o}}abc{{tag|includeonly|o}}def{{tag|onlyinclude|c}}ghi{{tag|includeonly|c}} will {{em|not}} work as expected. Use the "first opened, last closed" rule that is standard for HTML/XML. ===Problems and workarounds=== * The following techniques are helpful in debugging a template: ** Use [[Special:ExpandTemplates]] to see the full recursive expansion of one or more templates. ** 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 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, either use {{xtag|nowiki|s}} before the markup or use the [[HTML]] entities <code>&#58;</code>, <code>&#59;</code>, <code>&#42;</code>, and <code>&#35;</code> respectively. In some cases, the HTML entities will work when the {{tag|nowiki|s}} does not. The problem often occurs when a parameter value in a template call starts with one of the four characters. See also {{tl|Encodefirst}}. * 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. * To protect server resources and avoid infinite loops, the parser imposes certain limits on the depth of transclusion nesting and on the page size with expanded templates. This may cause a page to break if it uses very complex templates, particularly if there are multiple such templates on the same page. For more information, see [[WP:Template limits]]. You can check a page's overall load on the server by examining the generated HTML for a page and looking for the <code>NewPP limit report</code> comments. * Do not use <code>=</code> wikimarkup to create a section header in a template which is intended for use in article space; this will create an edit link on a page that transcludes the template that will confusingly open the <em>template</em> for editing. * You may avoid section edit links to the template by including <code><nowiki><includeonly>__NOEDITSECTION__</includeonly></nowiki></code>. ===Documentation=== {{Details|WP:Template documentation}} Documentation for users, together with the template's categories, normally goes after the template code, inside {{tag|noinclude}} tags. It is normally necessary to put the opening {{tag|noinclude|o}} tag immediately after the end of the code, with no intervening spaces or newlines, to avoid transcluding unwanted whitespace. In the case of complex templates, the documentation is often kept on a separate [[WP:Subpages|subpage]] of the template page (named "Template:{{var|XXX}}/doc"). This applies especially to many [[WP:Protection policy|protected]] templates, so that non-administrators can edit the documentation. To do this, place a call to the {{tlx|Documentation}} template after the main template code and within {{tag|noinclude}} tags. If the "/doc" subpage does not exist, a link appears when you display the template that you can use to create the subpage. The documentation subpage, rather than the template itself, is normally what is placed in categories to represent a template. ===Categorization=== {{See also|WP:Categorization#Template categorization}} ====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]]). ====Categorize templates==== Categorizing your template and documenting its proper usage will make it easier for other editors to find and use. Category declarations for a template itself should be placed on the template's documentation subpage (or inside {{tag|noinclude}} [[html tag|tags]] if there is no documentation subpage) to avoid placing calling pages in the category. ===Aliases=== A [[WP:Redirect|redirect]] of a template functions as an alias. For example, [[Template:Tsh]] redirects to [[Template:Template shortcut]], so you can code {{tlx|tsh|{{var|foo}}}} instead of {{tlx|Template shortcut|{{var|foo}}}}. It is good to prepare template aliases for variations in whitespace and capitalization. For example, there is a template called {{tlx|See Wiktionary}}. The "W" is capitalized, since the word "Wiktionary" is so, but a redirect {{tlx|See wiktionary}} (with lowercase "w") exists because editors may misremember it as the latter. 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