Help:Metatemplating

In the context of Wikipedia, metatemplating involves the use of templates to generate other templates. Some metatemplates work like any other template, and are transcluded. Others generate wiki markup on-the-fly; these are macro metatemplates, and are substituted. Metatemplating enables standardized templating, whereby many templates can utilize a common set of components and formats.

Macro metatemplates carry the normal disadvantages of substitution, but they also take advantage of two strong points: substitution is ultimately more efficient, and it allows for the dynamic generation of wiki markup. This makes it suitable for more intricate systems than those created with transclusion.

Substitution

There are two substitution prefixes: subst: and safesubst:. The difference appears when a template is transcluded instead of substituted; in such a case, subst: templates will print text as-is, without evaluating, while safesubst: templates will transclude.

Substitution will reevaluate when the resulting template is included, unlike transclusion. This makes it useful for macro templating.

Bubbling

Substitution bubbles:

• If Template A transcludes Template B, and Template B contains safesubst: includes, safesubst: will use transclusion. subst: would not evaluate.
• If Template A substitutes Template B, and Template B contains safesubst: includes, safesubst: will use substitution. subst: would also substitute.

Substitution bubbling continues through a chain of substitutions until a transclude is reached, at which point only transcludes are used.

Marking templates meant for substitution

Templates meant exclusively for substitution should have Template:Tl2 at the top of their documentation pages.

So that other users can learn to use substituted templates, top-level metatemplates that will appear in normal templates (rather than in other metatemplates) should mark their presence with a comment. This comment usually goes at the end of the template, and simply contains a link to the substituted template:

...<!--
--
-- Substituted from [[Template:Example]].
--
--></includeonly><noinclude>...

Delayed evaluation

The process of generating text during the first substitution to be evaluated in future transclusions/substitutions is delayed evaluation. Templates are used to form a chain of substitutions and transclusions. Delayed evaluation generally requires that all but the last include in the chain be substitution.

Delayed evaluation can be achieved via a template by printing text that will be evaluated as wiki markup by another template. For example, < and > are printed as-is when they are alone, but together they can be used to form tags. If a template wanted to form a tag when substituted, it could use the form {{{|<}}}example/{{{|>}}}. The angled brackets are enclosed in separate wiki markup blocks, so they do not join. Since a "blank" parameter name is always undefined, the angled brackets will always be printed as the fallback values, and the resulting text will be <example/>.

HTML entities

(X)HTML entities such as | (|) will not be translated during substitution, so they will never evaluate. They are only useful for preventing text from being evaluated at all.

Undefined parameter defaults

Parameters can have default values for when they are undefined: {{{parameter-name|default-value}}}

There is one parameter that always defaults: the unnamed parameter. When the parameter name is omitted, the default value will always print: {{{|always-prints}}}

Undefined parameter defaults are useful for escaping text that would otherwise be evaluated. For example, to break up a tag that should print as text:

{{{|<}}}example/{{{|>}}}

After the first substitution:

<example/>

Further includes would evaluate the tag.

Parameters are processed prior to substitution, so they can also be used for conditional substitution. For example, to only substitute when the nosubst parameter is undefined:

{{{{{nosubst|subst:}}}example}}

Tags

Curly braces delimit angled brackets to prevent the formation of a tag, so the easiest way to escape tags is with undefined parameter defaults. This does not have the overhead of a template call. Example:

{{{|<}}}example/{{{|>}}}

After the first substitution:

<example/>

Tags can be escaped much like braces. Alternatively, the Template:Tl2 template can be used, though it is less efficient. Producing the same result as the previous example:

<includeonly><</includeonly>example/<includeonly>></includeonly>
{{lessthan}}example/>

This is usually only necessary for includeonly, noinclude, and nowiki tags. In such a case, it is preferable to use the Template:Tl2, Template:Tl2, and Template:Tl2 templates, respectively:

{{includeonly|{{example}}}}

After the first substitution:

<includeonly>{{example}}</includeonly>

Further transclusions and substitutions:

This is an example of a template. For help with templates, see Help:Template.

Braces

Curly braces, if separated by includeonly tags, will print as-is. Note that these three tags (includeonly, noinclude, and nowiki) cannot be nested within themselves, so this trick can only be used in top-level code. nowiki tags won't work, as they won't be removed by the substitution process. There are several possible combinations:

<includeonly>{{</includeonly>example<includeonly>}}</includeonly>
{{<includeonly>example</includeonly>}}
{{<includeonly/>example<includeonly/>}}

After the first substitution, each produces:

{{example}}

Further transclusions and substitutions:

This is an example of a template. For help with templates, see Help:Template.

A less efficient method is to use metatemplates that print braces. Unlike includeonly tag separation, metatemplates will work when inside another wiki markup block, such as within an argument to another template. There are general-purpose metatemplates using parentheses in place of braces. This will produce a result identical to that of the previous example:

{{((}}example{{))}}

Other metatemplates for producing similar combinations:

• Template:Tl2 produces {
• Template:Tl2 produces }
• Template:Tl2 produces {{
• Template:Tl2 produces }}
• Template:Tl2 produces {{{
• Template:Tl2 produces }}}

See also Category:Template namespace templates.

The template {{braces}} can produce, for example, the following:

{{braces|Templatename|item1|item2|...|item8}}Template:Nbsp→Template:Nbsp{{Templatename | item1 | item2 | ... | item8}}

{{braces|code=on|Templatename|item1|item2|...|item8}}Template:Nbsp→Template:Nbsp{{Templatename | item1 | item2 | ... | item8}}

For more details, see Template:Braces.

Other wiki markup symbols

These characters and sequences often need to be escaped when writing a template, but should be evaluated by future templates. Also see § Braces above. Line breaks are shown by \n.

• Template:Tl2 produces |
• Template:Tl2 produces ||
• Template:Tl2 produces [
• Template:Tl2 produces ]
• Template:Tl2 produces [[
• Template:Tl2 produces ]]
• Template:Tl2 produces =
• Template:Tl2 produces |-
• Template:Tl2 produces  \n\n|-
• Template:Tl2 produces the start of a centered table; see the s-start source code for details.
• Template:Tl2 produces |}
• Template:Tl2 produces <