View source for Help:Metatemplating

In the context of Wikipedia, '''metatemplating''' involves the use of [[Help:Templates|templates]] as a base to generate other templates.  Some '''metatemplates''' work like any other template, and are [[Wikipedia:Transclusion|transcluded]].  Others generate [[Help:Wiki markup|wiki markup]] on-the-fly; these are macro metatemplates, and are [[Wikipedia:Substitution|substituted]].  Metatemplating enables standardized templating, whereby many templates can utilize a common set of components and formats.

Macro metatemplates carry the normal [[Help:Substitution#When to use substitution|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: <code>[[H:SUBST|subst:]]</code> and <code>[[WP:SAFESUBST|safesubst:]]</code>.  The difference appears when a template is transcluded instead of substituted; in such a case, <code>subst:</code> templates will print text as-is, without evaluating, while <code>safesubst:</code> 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 <code>safesubst:</code> includes, <code>safesubst:</code> will use transclusion.  <code>subst:</code> would not evaluate.
* If Template A substitutes Template B, and Template B contains <code>safesubst:</code> includes, <code>safesubst:</code> will use substitution.  <code>subst:</code> 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 {{tl2|subst only}} 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:

 <span style="color: Gray">...</span>&lt;!--
 --
 -- Substituted from <nowiki>[[Template:Example]]</nowiki>.
 --
 --&gt;<span style="color: Gray">&lt;/includeonly&gt;&lt;noinclude&gt;...</span>

== 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, &lt; and &gt; 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 <code><nowiki>{{{|&lt;}}}example/{{{|&gt;}}}</nowiki></code>.  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 <code>&lt;example/&gt;</code>.

=== HTML entities ===

(X)HTML entities such as <code>&amp;#124;</code> (&#124;) 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: <code><nowiki>{{{parameter-name|default-value}}}</nowiki></code>

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

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:

 <nowiki>{{{|&lt;}}}example/{{{|&gt;}}}</nowiki>

After the first substitution:

 <nowiki>&lt;example/&gt;</nowiki>

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 <code><nowiki>nosubst</nowiki></code> parameter is undefined:

 <nowiki>{{{{{nosubst|subst:}}}example}}</nowiki>

=== 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|undefined parameter defaults]].  This does not have the overhead of a template call.  Example:

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

After the first substitution:

 <nowiki>&lt;example/&gt;</nowiki>

Tags can be escaped much like [[#Braces|braces]].  Alternatively, the {{tl2|lessthan}} template can be used, though it is less efficient.  Producing the same result as the previous example:

 <nowiki>&lt;includeonly&gt;&lt;&lt;/includeonly&gt;example/&lt;includeonly&gt;&gt;&lt;/includeonly&gt;</nowiki>
 <nowiki>{{lessthan}}example/&gt;</nowiki>

This is usually only necessary for <code>includeonly</code>, <code>noinclude</code>, and <code>nowiki</code> tags.  In such a case, it is preferable to use the {{tl2|includeonly}}, {{tl2|noinclude}}, and {{tl2|nowiki}} templates, respectively:

 <nowiki>{{includeonly|{{example}}}}</nowiki>

After the first substitution:

 <nowiki>&lt;includeonly&gt;{{example}}&lt;/includeonly&gt;</nowiki>

Further transclusions and substitutions:

{{example}}{{-}}

=== Braces ===

Curly braces, if separated by <code>includeonly</code> 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. <code>nowiki</code> tags won't work, as they won't be removed by the substitution process.  There are several possible combinations:

 <nowiki>&lt;includeonly&gt;{{&lt;/includeonly&gt;example&lt;includeonly&gt;}}&lt;/includeonly&gt;</nowiki>
 <nowiki>{{&lt;includeonly&gt;example&lt;/includeonly&gt;}}</nowiki>
 <nowiki>{{&lt;includeonly/&gt;example&lt;includeonly/&gt;}}</nowiki>

After the first substitution, each produces:

 <nowiki>{{example}}</nowiki>

Further transclusions and substitutions:

{{example}}{{-}}

A less efficient method is to use metatemplates that print braces.  Unlike <code>includeonly</code> 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:

 <nowiki>{{((}}example{{))}}</nowiki>

Other metatemplates for producing similar combinations:

<!-- Please use tl2 here for consistency. -->
* {{tl2|(}} produces <code><nowiki>{</nowiki></code>
* {{tl2|)}} produces <code><nowiki>}</nowiki></code>
* {{tl2|((}} produces <code><nowiki>{{</nowiki></code>
* {{tl2|))}} produces <code><nowiki>}}</nowiki></code>
* {{tl2|(((}} produces <code><nowiki>{{{</nowiki></code>
* {{tl2|)))}} produces <code><nowiki>}}}</nowiki></code>

See also {{cl|Template namespace templates}}.

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

: {{tlx|braces|Templatename|item1|item2|...|item8}}{{nbsp|2}}→{{nbsp|2}}{{braces|Templatename|item1|item2|...|item8}}
: {{tlx|braces|code{{=}}on|Templatename|item1|item2|...|item8}}{{nbsp|2}}→{{nbsp|2}}{{braces|code=on|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 {{section link|#Braces}} above.  Line breaks are shown by {{color|green|\n}}.

<!-- Please use tl2 here for consistency. -->
* {{tl2|!}} produces <code><nowiki>|</nowiki></code>
* {{tl2|!!}} produces <code><nowiki>||</nowiki></code>
* {{tl2|!(}} produces <code><nowiki>[</nowiki></code>
* {{tl2|!)}} produces <code><nowiki>]</nowiki></code>
* {{tl2|!((}} produces <code><nowiki>[[</nowiki></code>
* {{tl2|!))}} produces <code><nowiki>]]</nowiki></code>
* {{tl2|1==}} produces <code><nowiki>=</nowiki></code>
* {{tl2|!-}} produces <code><nowiki>|-</nowiki></code>
* {{tl2|-!-}} produces <code><nowiki>&amp;nbsp;</nowiki>{{color|green|\n\n}}<nowiki>|-</nowiki></code>
* {{tl2|s-start}} produces the start of a centered table; see the [//en.wikipedia.org/w/index.php?title=Template:s-start&action=edit s-start source code] for details.
* {{tl2|end}} produces <code><nowiki>|}</nowiki></code>
* {{tl2|lessthan}} produces <code><nowiki>&lt;</nowiki></code>

[[Category:Help]]