View source for Wikipedia:Advanced template coding

{{hatnote|Are you in the right place? Basic template coding techniques can be found at [[Help:Template]].}}
{{Wikipedia how to|WP:ADTEMPLATE}}
There are some '''advanced template coding''' techniques to improve the display or editing of [[Help:Template|templates in Wikipedia]]. There are also some tactics for debugging template parameters in the [[MediaWiki]] [[markup language]]. It is preferable that any templates requiring intricate [[control structure]]s or [[conditional expression]]s be written in or [[Wikipedia:Luafication|converted]] to [[Wikipedia:Lua|Lua modules]] because wikitext is not well-designed for this purpose.

Many bugs are associated with the difficulty in dealing with some awkward features in the markup language which lead to coding errors. Unbalanced metacharacters are a major source of errors. For example, coding <code><nowiki>{{1}}}</nowiki></code> instead of <code><nowiki>{{{1}}}</nowiki></code> causes it to act as if it were <code><nowiki>{{1}}&nbsp;}</nowiki></code>, thereby invoking Template:1 +&nbsp;"}".

There are some differences of wiki-formatting of contents of parameters when inside #if-expressions, but not when outside. Templates which need to be [[WP:SUBST|substituted]] need special handling.  Providing parameter defaults or parameter aliases is covered as well.

==Nesting levels limited to 40==
Inside a single template, the nesting limit is 40 nested expressions, such as 40 multiple [[If-then-else|"if-then-else-if..."]]. At the 41st nested "if" keyword an error message might appear, as: ''"Exceeded nesting limit"''. However, when not nested beyond 40 levels, a template can contain hundreds of if-expressions and switch-branches, but not all nested inside the others.

Some templates have contained complex conditional calculations nested over 23 levels deep, for years. Also, some templates have contained hundreds of if-expressions, for years, just NOT all nested as one, giant: ''if-then-else-else-else-else-else...''.

==MediaWiki wiki-formats the clauses inside #if==
{{See also|Help:Conditional expressions}}

An issue which complicates template processing, for parameters, is the wiki-formatting of parameter contents when inside of if-logic (such as #if or #ifeq) or #switch (or lc:, lcfirst:, uc:, ucfirst:). {{As of|2012|5}}, the [[mw:Markup spec|MediaWiki markup parser]] is still wiki-formatting the contents of parameters when ''inside'' #if-expressions (but not outside). This means that parameters containing spaces, lead semicolon, colon (":") or pound sign ("#") can change their values while inside the if-clauses (surprise!). So, for example, a parameter <syntaxhighlight lang="wikitext" inline>{{{4}}}</syntaxhighlight> when outside an #if can display differently than inside <syntaxhighlight lang="wikitext" inline class="nowrap">{{#ifeq:{{{1}}}=0|{{{4}}} ...}}</syntaxhighlight>. The worst shock is when parameter 4 contains a leading semicolon, which triggers formatting to become ye-olde bolded ''semicolon-header line'':

: <syntaxhighlight lang="wikitext" inline>TEST 1: {{#if:{{{4|}}}|{{{4|;}}} <== yes, semicolon|no, 4=empty}}</syntaxhighlight>
: <syntaxhighlight lang="wikitext" inline>TEST 2: {{#if:{{{4|;}}}|{{{4|;}}} <== yes, semicolon|no, 4=empty}}</syntaxhighlight>
{| class=wikitable width=400px
|
: TEST 1: {{#if:{{{4|}}}|{{{4|;}}} <== yes, semicolon|no, 4=empty}}
: TEST 2: {{#if:{{{4|;}}}|{{{4|;}}} <== yes, semicolon|no, 4=empty}}

; <== Separate example of semicolon-header
|}
The problem occurs whether inside of #if, #ifexpr, #ifeq or #switch markup expressions. If the parameter is preceded by text, in either of the then/else clauses, then the wiki-formatting inside the parameter does not occur.
: <syntaxhighlight lang="wikitext" inline>TEST 3: {{#ifexpr:{{{1|7}}}=7|<b></b>{{{4|;}}} equals 7|not 7}}</syntaxhighlight>
: <syntaxhighlight lang="wikitext" inline>TEST 4: {{#ifexpr:{{{1|7}}} < 9|{{{4|#}}} LESS THAN 9|not<9}}</syntaxhighlight>
: <syntaxhighlight lang="wikitext" inline>TEST 5: {{#ifexpr:{{{1|7}}} < 9|&#32;{{{4|#}}} LESS THAN 9|not<9}}</syntaxhighlight>
: <syntaxhighlight lang="wikitext" inline>TEST 6: "{{#ifexpr:{{{1|7}}} < 9|&#32;{{{4|#}}} LESS THAN 9|not<9}}"</syntaxhighlight>
{| class=wikitable width=400px
|
: TEST 3: {{#ifexpr:{{{1|7}}}=7|<b></b>{{{4|;}}} equals 7|not 7}}
: TEST 4: {{#ifexpr:{{{1|7}}} < 9|{{{4|#}}} LESS THAN 9|not<9}}
: TEST 5: {{#ifexpr:{{{1|7}}} < 9|&#32;{{{4|#}}} LESS THAN 9|not<9}}
: TEST 6: "{{#ifexpr:{{{1|7}}} < 9|&#32;{{{4|#}}} LESS THAN 9|not<9}}"
|}
In TEST 4, the leading pound sign "#" triggered auto-numbering of the line (indented with "1."). The situation of having a leading semicolon, colon or "#" might be relatively rare, but this is just a reminder: for showing the true contents of a template parameter, try to display a parameter ''outside'' the start of any if-statement clauses, or display other text before the parameter inside the if-logic, or else prepare for some shocking results when a parameter is wiki-formatted for display inside the if-logic.

If the result of #if, etc. is not intended to be formatted, using <code>&amp;#35;</code>, <code>&amp;#58;</code>, and <code>&amp;#59;</code> instead of <code>#</code>, <code>:</code>, and <code>;</code> will work fine.
: <syntaxhighlight lang="wikitext" inline>TEST 7: {{#ifexpr:{{{1|7}}} < 9|{{{4|&amp;#35;}}} LESS THAN 9|not<9}}</syntaxhighlight>
{| class=wikitable width=400px
|
: TEST 7: {{#ifexpr:{{{1|7}}} < 9|{{{4|&#35;}}} LESS THAN 9|not<9}}
|}

==Debugging==
Many coding errors can be debugged, more easily, by attempting to isolate the code section where coding errors most likely occurred. Intense proofreading, of the logic flow, is most often the quickest fix, such as checking for typical syntax errors (see below: [[#Common coding errors|"Common coding errors"]]). Sometimes, a section of troublesome code could be copied into a short test page, then by edit-preview, tested there, separately. However, if editing that extra-page window seems like too much effort, then consider merely copying the code to the top of the current template. Similarly, a template could be developed, in the early stages, as multiple sections of code, each to be debugged separately, then eventually joined together, such as nested sections with if-then-else-if.

As a review of those options, consider:
* Try carefully proofreading troublesome code, matching <nowiki>"{{" with "}}"</nowiki>. (consider using [[User:Equazcion/WikiTemplate UDL|Equazcion's syntax highlighter]] for [[Notepad++]])
* Copy a template section into a test-page edit-window, for debug.
* Copy a template section to the top of the template, for debug.
* Restructure a template so that each section is more separated.
The basic strategy: isolate the code section to be debugged.

Next, the testing, of each section of code, is crucial. There are some age-old adages to heed:
* ''If it hasn't been tested, then it doesn't work.''
* ''You can expect what you inspect.'' ([[W. Edwards Deming]])
Perhaps put a variety of examples on each template's doc subpage, to help detect problems early in development. However, for complex templates, then the talk-page, or a special subpage "/testcases", should contain a section of numerous examples (a whole lot of them) to demonstrate the full scope of template features.

==Defaulting parameters in expressions and if-logic==
When developing sections of markup that use template parameters, try to always set each parameter with a default value, especially inside expressions or if-logic coding:
* <syntaxhighlight lang="wikitext" inline>{{#expr: 109.75 / {{{1|1}}} }}</syntaxhighlight> &rarr; default {1} as 1 not zero.
* <syntaxhighlight lang="wikitext" inline>{{#ifeq: {{{answer|y}}}|y|show yes}}</syntaxhighlight>
If a particular parameter is given the same default value across the whole page, then that value could be easily changed, in a text editor, by a global search-and-replace [[string substitution]], to change the default value to some other value, for testing each case.

If those parameters are not given default values, then those sections of code cannot be tested, during edit-preview, while editing the template. Any parameter without a default value will become the literal triple-brace text (such as the literal 7 characters: <syntaxhighlight lang="wikitext" inline>{{{x}}}</syntaxhighlight>), and non-defaulted parameters cannot be evaluated, in expressions or if-logic, during an edit-preview of the template page.

==Common coding errors==
There are several common coding errors which will cause problems when processing templates. The following can be used as a checklist, to help debug problems, when a template seems to be acting bizarre:

* ''Too few closing braces:'' A common problem is to put only 2 closing-braces around a parameter number or name, such as <syntaxhighlight lang="wikitext" inline>{{{1}}</syntaxhighlight>. Having only 2 closing-braces <syntaxhighlight lang="wikitext" inline>}}</syntaxhighlight> might treat the parameter as a template named "Template:1" (preceded by a lone "{" brace).
* ''Unopened comments:'' Forgetting to insert <syntaxhighlight lang="html" inline><!--</syntaxhighlight> at the start of an HTML comment can cause bizarre results, with no error message. Forgetting the exclamation point is very common: <syntaxhighlight lang="html" inline><--</syntaxhighlight> should be <syntaxhighlight lang="html" inline><!--</syntaxhighlight>.
* ''Unclosed comments:'' Forgetting to insert <syntaxhighlight lang="html" inline>--></syntaxhighlight> at the end of an HTML comment can cause bizarre results, with no error message.
* ''Omitting colon or "#" on "#ifexpr":'' Forgetting to insert "#" or colon for "#ifexpr:" or "#expr:" can produce bizarre results, when passed into other subtemplates.

:Omitting colon becomes literal text: <syntaxhighlight lang="wikitext" inline>{{#ifexpr {{{1|y}}}=0|then zero|else not}}</syntaxhighlight>

Note that those common coding errors could have been easily spotted by a simple syntax checker, such as warning that 3&2 braces could be trouble: <syntaxhighlight lang="wikitext" inline>{{{size|180px}}</syntaxhighlight> is treated as "{Template:Size" trying to pass 180px as the parameter because of only 2 end-braces.

Again, always checking first for common errors, as the first step, can avoid time hunting for "complex errors" which never really existed. Remember: the [[MediaWiki]] markup language is extremely error-prone, so that's why so many coding errors occur, and that's why:
: Consider the above as a ''checklist'' to try first, as a type of sanity-check for the template.
Many hideous problems truly are merely 1-minute syntax fixes.

== Coding a template to allow WP:SUBST substitution ==
{{shortcut|WP:SUBSTALLOW}}
In rare cases, a template might need to be rewritten to allow text substitution (per [[WP:SUBST]]), where the results of running a template will be saved into the page during an edit-SAVE operation. In that case, the safesubst-prefix must be inserted into ''every'' markup function used inside that template, at every level of nested logic. Also, every HTML comment must be surrounded by "noinclude" tags: <syntaxhighlight lang="wikitext" inline><noinclude><!--HTML comment HERE--></noinclude></syntaxhighlight>.{{efn|But if you want the HTML comment to appear, as is the case, for example, with [[WP:WARN|User warning templates]], then do not enclose the HTML comment in <code><nowiki><noinclude></nowiki></code> tags.}} Otherwise, all of the triggered HTML comments will be stored inside the SAVEd page, in the sequence executed by running the template. NOTE: All the extra "noinclude" and <syntaxhighlight lang="wikitext" inline>safesubst:<noinclude/></syntaxhighlight> keywords will likely require the template's markup to be re-indented inside, to fit all that extra inserted text, which will widen and clutter the original markup style.

Specifically, to alter a template to allow text substitution, then the prefix <syntaxhighlight lang="wikitext" inline>safesubst:<noinclude/></syntaxhighlight> must be inserted inside the opening double-brace <syntaxhighlight lang="wikitext" inline>{{</syntaxhighlight> of each markup function inside that template. Some examples of inserting the safesubst-prefix inside a template's markup:

* <syntaxhighlight lang="wikitext" inline>Total articles now: {{NUMBEROFARTICLES}}</syntaxhighlight> &rarr; {{NUMBEROFARTICLES}}
* <syntaxhighlight lang="wikitext" inline>Total articles was: {{ subst:NUMBEROFARTICLES}}</syntaxhighlight> &rarr; 3,953,715
* <syntaxhighlight lang="wikitext" inline>{{ safesubst:<noinclude/>#ifeq:{{{1|AX}}}|AX|yes}}</syntaxhighlight>
* <syntaxhighlight lang="wikitext" inline>{{ safesubst:<noinclude/>lc:THIS LOWERCASE TEXT}}</syntaxhighlight> &rarr; {{ safesubst:<noinclude/>lc:THIS LOWERCASE TEXT}}
In general, every markup function which starts with double-brace <syntaxhighlight lang="wikitext" inline>{{</syntaxhighlight> must be altered to insert the long safesubst-prefix <syntaxhighlight lang="wikitext" inline>safesubst:<noinclude/></syntaxhighlight> (with no space afterward).{{efn|If you are familiar with [[regular expressions]], you can do this like this:
* Search for pattern <code><nowiki>([^{]){{([^{])</nowiki></code> and replace it with <code><nowiki>\1{{ safesubst:<noinclude/>\2</nowiki></code>
Or, in one step, for one style of regex :
* <code><nowiki>s/([^{]){{([^{])/\1{{ safesubst:<noinclude/>\2/g</nowiki></code>
You might need to break up long lines; see "Indenting the long lines" in this section. As a practical matter, it's easier to join lines of code than to break them, so if you replace the blank in the replace-pattern above with a newline (plus optional white space) instead, it will break lines with every substitution; when it's done, just go back and join any lines that are too short.}} The action of keyword "safesubst" is to allow conditional substitution of markup, when the whole template is invoked as {&#123;subst:MyTemplate|...}}. In essence, the keyword "safesubst" could be called "ifsubst" as meaning, "if 'subst:' was used to invoke this template, then substitute here as well".

Remember: The safesubst-prefix must be inserted into ''every'' markup function inside that template, except for test logic never used in an actual page. Any markup which omits "safesubst" will fail if the template is executed by the subst mode, "{&#123;subst:MyTemplate|...}}". Parameters are not changed, so <syntaxhighlight lang="wikitext" inline>{{{1}}}</syntaxhighlight> would remain unchanged, without a safesubst-prefix.

'''Exceptions:''' Only logic which would never be stored in a page could omit "safesubst", such as test-logic which is triggered by special parameter values never used inside a stored page. Any markup which omits "safesubst" will only work during regular transclusion but fail if the template is executed by using the subst-mode prefix "subst:". For more examples, and further technical explanations, see: [[WP:Substitution]].

'''Indenting the long lines:''' All of the added safesubst-prefix text will widen lines, so to improve readability, they could be split and indented before any of the <syntaxhighlight lang="wikitext" inline>safesubst:<noinclude/></syntaxhighlight> prefixes. For example:
* <syntaxhighlight lang="wikitext" inline>{{ safesubst:<noinclude/>#ifeq:{{ </syntaxhighlight><br/>{{in5|7}}<syntaxhighlight lang="wikitext" inline>safesubst:<noinclude/>padleft:|1|{{{1}}} }}|A|Begins with "A"}}</syntaxhighlight>
In that indentation style, the text "safesubst:&lt;noinclude/>" begins the next line. Avoid wrapping a line after the prefix <syntaxhighlight lang="wikitext" inline>safesubst:<noinclude/></syntaxhighlight> because several markup functions might fail to work correctly unless the safesubst prefix is immediately attached before the keyword, such as <syntaxhighlight lang="wikitext" inline>{{&nbsp;safesubst:<noinclude/>#ifeq:...}}</syntaxhighlight>

== Examples of very large templates ==
When trying to perform more-complex, or intricate, operations, there might be an instinctive fear that templates cannot be as large as needed. However, there are many very large templates which have been running, for years, on Wikipedia, for example:
* [[Template:Citation/core]] - formats 621 source-reference parameters into standardized form
* [[Template:Infobox settlement]] - formats various town/region infoboxes in consistent form
The source-footnote formatter, [[Template:Citation/core]], displays a standardized citation format, as invoked by several wrapper templates which pass hundreds of parameters, where the core logic checks 621 parameter values, in the conditional markup expressions.

== Try some programming==
The [[Special:ExpandTemplates]] page takes some [[Help:Wikitext|wikitext]] and expands everything in double braces recursively: templates, [[Help:Parser function|parser functions]] like <nowiki>{{#if:...}}</nowiki>, and variables like <nowiki>{{CURRENTDAY}}</nowiki>

==See also==
{{div col|colwidth=22em}}
* [[WP:Category suppression]]
* [[WP:Advanced article editing]]
* [[WP:Advanced footnote formatting]]
* [[WP:Advanced table formatting]]
* [[WP:Advanced text formatting]]
* [[WP:Thinking outside the infobox]]
* [[WP:Alert]]
* [[Help:Punctuation]]
* [[WP:Wikimedia Foundation error]]
* [[WP:About translating German Wikipedia]]
* [[WP:Lua]]
* {{tl|if}} and {{tl|Ifequal}}.
* [[Template:Wrapper template]]
* [[m:Help:Calculation]]
{{div col end}}

==Notes==
{{notelist}}
<div style="font-size:87%; line-height: 1.33em;">
<!--:<sup>[a]</sup> - The... -->
</div>

<!--PASTE TEXT:
:* <nowiki> </nowiki> -->

{{Wikipedia essays|building}}
{{Wikipedia technical help|collapsed}}
[[Category:Wikipedia essays|Advanced template coding]]
[[Category:Wikipedia how-to|Advanced template coding]]
[[Category:Wikipedia how-to essays|Advanced template coding]]
[[Category:Wikipedia essays about article formatting]]
[[Category:Wikipedia essays about templates|Advanced templated coding]]