Help:Template Coding Recommendations

To help other programmers understanding Wiki code some coding recommendations are here described briefly. For templates in general read also https://www.mediawiki.org/wiki/Help:Templates

The goal of good code is that it does not need an additional extensive documentation to be understood. Ideally the Wiki code should be understandable itself by just reading the Wiki code only. That’s why careful thinking is advised on

• how to name a template
• how to name template parameters
• how to group code
• how to nest code when using nested templates

… and so on.

Template Names

Generally speaking, the name can have any name format, e.g.

• “{{Normal case template name}}” or
• “{{CamelCaseTemplateName}}“ (less good to read but advantage: Wiki search finds it more precisely)

Best praxis: name the template after the task it is doing:

Example	Remarks
{{SkipFirstCommaValue|1={{{list|}}}}} or {{SkipFirstListValue|1={{{1|}}}}}	OK self explaining: it skips the first value of a comma separated list
{{GetEnd|{{{1|}}}}}	Problems: “what does it do? what End?” What value is needed?
{{Val4P|{{{1|}}}}}	Avoid abbreviations that can be misunderstood. Problems: “what does it mean?” “what does it do?” does it provide a «value for “P”-what»?

Avoid template names that need to be documented extra.

Template Parameters

Use generic names regardless to which property they might be mapped to. Ideally template parameters and the corresponding property name might be named identically.

Example	Remarks
|first page= or |starting page=	OK
|prism:startingPage=	“confusing” and “hard to remember”
{{TemplateName|value having an = equal sign}} {{TemplateName|1=value having an = equal sign}}	if there is no construct of |parameter=value, the first code will break, because of the equal sign (=) in the value avoid the no-parameter-is-given situation because of the troublesome equal sign

Template Values

Consider the following tasks.

Task: no trimming of values

{{TemplateName | value }}

Using no parameter name does not trim values. Here it would result in  value  with blanks

Task: trimming of values

{{TemplateName | 1= value }}

Using a parameter name does trim values. #if also always does trim values:

{{#if: test-statement | then-value | else-value }}

Task: testing of empty values

{{#if: {{{1}}} | then-code }}

Will not work for all cases, e.g. if parameter 1 is not given. Solution is to write {{{1|}}} (with an empty default behind the |) instead of {{{1}}}:

{{#if: {{{1|}}} | then-code }}

… will test properly even if parameter 1 is not given.

Task: testing of empty vs. undefined values

• if you want to differentiate between: not-set-at-all, set-but-no-value and set-with-value
• this corresponds to the database states: NULL, '' (=empty) and 'value'

{{#if: {{{parameter|}}} 
| then-code (defined and non-empty) 
| else-code (defined or undefined, empty)
}}

… will differentiate only between parameter being empty or not empty, but one cannot differentiate between being undefined or defined.

{{#ifeq: {{{parameter|+}}} | {{{parameter|-}}} 
| then-code (undefined) 
| else-code (defined, empty or non-empty)
}}

… will differentiate between parameter being defined or undefined.

Task: nested templates and delegating parameters and their values

Consider for instance a {{MainTemplate}} that has 5 unnamed parameters of which the last ones are optional and it uses internally a {{SubTemplate}}:

<!-- code of 
MainTemplate 
-->{{SubTemplate|parameter={{{5}}}}}

Now, if only {{MainTemplate|1=value}} is given and not parameter 5, then MainTemplate will evaluate for SubTemplate a value of actually “{{{5}}}” and not void!

One solution is to write {{{5|}}} (with an empty default behind the |) instead of {{{5}}}:

<!-- code of MainTemplate -->{{SubTemplate|parameter={{{5|}}}}}

… will evaluate to a void value if parameter 5 in MainTemplate was not given.

Template Coding

• use indentation and line breaks to structure the code, following the logic of the code
• you can always use and write in-code comments like this: <!-- not evaluated comments -->

Examples	Remarks
{{#if: test-statement | then-code | else-code }} or <!-- previous code -->}}{{ #if: test-statement | then-code | else-code }}	carefully placed line breaks help to see what belongs to what
{{#if: test-statement | level-1 then-code {{ #if: test-statement | level-2 then-code | level-2 else-code }} | level-1 else-code }}	nesting, also with indentation often 2-spaces are used for indentation
{{#sub:{{{1}}}|{{#pos:{{{1}}}|,}}|0}} {{#sub:{{{1}}} | {{#pos:{{{1}}}|,}} | 0 }}	Readability: group small code fragments avoid space-less code in one big long line
#ifexpr:{{{1}}} #ifexpr:{{{1|0}}} #ifexpr:{{{1|}}} + 0	Avoiding messy rendering on the template page, e.g. … caused in #expr: or #ifexpr: with no default. Solutions: add a default add an empty default and + 0

If possible use simple solutions and avoid complicated code:

Example	Optimized Example
{{#sub:{{{1}}}|0|{{#pos:{{{1}}}|,|0}}}}	{{#explode: {{{1}}}|,|0}}
the code cuts after the first comma usage of 2 parser functions #sub (for sub-strings) and #pos (for character position of ,)	simpler solution using #explode

Querying Semantic Data

Performance optimization:

• query better one large data set instead of 1000 single data base calls in a template loop
• limit queries as narrow as possible

Avoid Tags Not Supported by HTML5

In most cases you can use CSS where tags are not any more supported. Read perhaps: http://www.w3schools.com/TAGs/

Deprecated	HTML5
<big>Word</big>	<span style="font-size:larger;">Word</span>. Other font properties (“|” symbolises another alternative): font-size: smaller|larger|2em etc. font-variant: small-caps color: red|#d65d19 etc.
<center>Word</center>	<span style="text-align:center;">Word</span>
<font color="#800000">Word</font>	<span style="color:#800000;">Word</span>

Documentation

Best praxis:

1. Summary: briefly describe what it does
2. Usage: typical use- and example cases
   • You can use generic examples via {{PAGENAME}}. That way the examples always are correct even if the template itself is renamed.
3. Parameters: explain parameters
4. Technical Documentation:
   • technical stuff important for programmers but not ordinary authors
   • add dependencies (easier for im- and export of templates)
   • perhaps add “Major Changes”-section
   • large template complexes, that act together should have a maintenance category

Copy & Paste Template

<noinclude>
List a … (brief summary)

== Usage ==

 <nowiki>{{</nowiki>{{PAGENAME}}<nowiki>}}</nowiki>
 <nowiki>{{</nowiki>{{PAGENAME}} |parameter=…}}<nowiki>}}</nowiki>
… results in:
{{ {{PAGENAME}}}}

== Parameters ==

<div class="definition-inline">
; |1= : …
; |prameter= : …
</div>
 
== Technical Documentation ==

=== Dependencies ===
* [[:category: ]]
* [[template: ]]
* [[property: ]]

=== Major Changes ===

; 2016-11-17 : text of changes

</noinclude><includeonly>
Template Code
</includeonly>