Module:Template wrapper/doc

This module is to be used in wrapper templates to allow those templates to provide default parameter values and allow editors to pass additional parameters to the underlying working template.

When writing a wrapper template, give this module all of the normally required default parameters necessary to use the wrapper template in its base form. Editors then use the wrapper template as-is or may supply additional wrapper and canonical parameters. Any of the canonical parameters supported by the working template may be added to the wrapper template or supplied by editors in article space. When an editor supplies a parameter that has a default value in the wrapper template, the editor-supplied value overrides the default. When it is necessary to remove a default parameter, editors may set the parameter value to the special keyword unset which will cause this wrapper module to erase the wrapper template's default value for that parameter. This module discards empty named parameters.

Positional parameters are not normally passed on to the working template. Setting |_include-positional=yes will pass all positional parameters to the working template. Positional parameters cannot be excluded and may be unset.

Parameters that are used only by the wrapper should be either positional ({{{n}}}) or listed in |_exclude= (a comma-separated list of named parameters). This module will not pass _excluded parameters to the working template.

Usage

{{#invoke:Template wrapper|wrap|_template=working template|_exclude=named parameter, named parameter, …|_reuse=named parameter, named parameter, …|_alias-map=alias parameter:canonical parameter|_include-positional=yes|<default parameter>|<default parameter>|…}}

Control parameters

|_template=

The name, without namespace, of the working template (the template that is wrapped); see § _template below. (required)

|_exclude=

Comma-delimited list of parameter names used by the wrapper template that are not to be passed to the working template; see § _exclude below.

|_reuse=

Comma-delimited list of canonical names that have meaning to both the wrapper template and to the working template; see § _reuse below.

|_alias-map=

Comma-delimited list of wrapper-template parameter names that are to be treated as aliases of specified working template canonical parameters; see § _alias-map below.

|_include-positional=

Pass all positional parameters to the working template; see § _include-positional below.

Definitions

Canonical parameter

A parameter supported and used by the working template.

Wrapper parameter

A parameter used by the wrapper template; may provide data for canonical parameters or control other aspects of the wrapper template.

Alias parameter

A wrapper parameter that is contextually meaningful to the wrapper template but must be renamed to a canonical parameter for use by the working template.

Reused parameter

A parameter that is shared by both wrapper and working templates and has been modified by wrapper template.

Default parameter

A canonical parameter given a default value in the wrapper template.

Parameter processing

Wrapper template		Module:Template wrapper												Working template
Canonical parameters	🢧					|parameter=					🢧	Excluded params stripped	🢧	Working template
Wrapper parameters	🢧	|_exclude=	🢧
		|_include-positional=	🢧
		|_alias-map=	🢧	Convert alias params to canonical	🢧	|canonical parameters=					🢧
	🢧						🢧	Reused canonical params modified
Alias parameters	→						|reused parameters=				→	–––→	→
			|_reuse=	→	–––––––→	→	–––––––→				→
|canonical parameters=	→	–––––––→	→	–––––––→	→	–––––––→	→
		|default parameters=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	–––→	→

Parameter details

_template

The only required parameter, |_template= supplies the name, without namespace, of the working template (the template that is wrapped). If this parameter is omitted, the module will emit the error message:

_alias-map

|_alias-map= takes a comma-delimited list of wrapper template parameters that are to be treated as aliases of specified working template canonical parameters. Each mapping element of the list has the form:

<from>:<to> – where <from> is a wrapper parameter name and <to> is a canonical parameter name.

In this example, it may be preferable for a wrapper template to use |assessor= which may be unknown to the working template but the working template may have an equivalent |author=, so in the {{#invoke:}} we would write:

|_alias-map=assessor:author

Positional/unnamed parameters may also be mapped to canonical parameters:

|_alias-map=1:author, 2:title, 3:language

Enumerated wrapper parameters may be mapped to enumerated canonical parameters using the # enumerator specifier:

|_alias-map=assessor#:author#

Given the above example, |assessor2= will map to |author2=; also, |assessor= and |assessor1= will map to |author1=.

Multiple wrapper parameters can map to a single canonical parameter:

|_alias-map=1:author, assessor:author

Wrapper parameters listed in |_alias-map= are not passed to the working template. Also, mapping positional parameters when |_include-positional=yes may give undesirable results. For instance, using both |_alias-map=1:author and |_include-positional=yes will cause all other positional parameters to be passed to the working template as is, such that the wrapper template's {{{2}}} becomes the working template's {{{2}}}, etc. The working template will not get {{{1}}}, though it will get |author=.

_reuse

|_reuse= takes a comma-delimited list of canonical parameters that have meaning to both the wrapper and working templates. These parameters cannot then be overridden.

In the simplest cases, a canonical parameter passed into the wrapper template overrides a default parameter provided in the wrapper template. In other instances a wrapper parameter is the same as a canonical parameter, and the wrapper template needs to modify the parameter value before it is passed to the working template. In such an example, |title= is both a wrapper parameter and a canonical parameter that the wrapper template needs to modify before passing to the working template. To do this, we first write…

|_reuse=title

…then, in the wrapper template's {{#invoke:Template wrapper|wrap|_template=…|…}} we write…

|title=Modified {{{title}}}

_exclude

|_exclude= takes a comma-delimited list of parameters used by the wrapper template that are not to be passed to the working template. This list applies to all parameters (including those that are renamed alias parameters) received from the wrapper template.

As an example, a wrapper template might use |id= to supply a portion of the value assigned to a default parameter |url=, so we would write…

|_exclude=id

…then, in the wrapper template's {{#invoke:Template wrapper|wrap|_template=…|…}} we write…

|url=https://example.com/{{{id}}}

…so the modified |url= value is passed on to working template, but |id= and its value are not.

Reused and default parameters cannot be excluded.

_include-positional

See also: § _alias-map.

|_include-positional= is a boolean parameter that acts on only one value: yes; the default (whether empty or undefined) is no (positional parameters normally excluded). When set to yes, the module will pass all unnamed/positional parameters to the working template.

Overriding default parameters

Editors may override default parameters by simply setting the default parameter to the desired value in the wrapper template. This module ignores empty parameters (those parameters that are named, but which do not have an assigned value). When it is desirable to override a default parameter to assign a null value, use the special keyword unset. Default parameters with this value are passed to the working template as empty (with no assigned value).

Reused parameters cannot be unset or overridden.

Debugging/documentation mode

This module has two entry points. A wrapper template might use a module {{#invoke:}} written like this…

{{#invoke:Template wrapper|{{#if:{{{_debug|}}}|list|wrap}}|_template=<working template>|_exclude=_debug, …|…}}

…where the |_debug= wrapper parameter, when set to any value, will cause the module to render the call to the working template without actually calling the working template.

As an example, {{Cite wikisource}} is a wrapper template that uses {{Citation}} as its working template. {{Cite wikisource}} accepts positional parameters, but {{Citation}} does not, so the wrapper template must convert the positional parameters to named parameters using the |_alias-map= parameter:

{{#invoke:Template wrapper|{{#if:{{{_debug|}}}|list|wrap}}|_template=Citation
  |_exclude=…, _debug
  |_alias-map=1:title, 2:author, 3:language

This example uses positional parameters and sets |_debug=yes to show that the {{Citation}} template is correctly formed…

{{Cite wikisource|Sentido y sensibilidad|Jane Austen|es|_debug=yes}}

Template:Cite wikisource

…and again with |_debug= unset…

{{Cite wikisource|Sentido y sensibilidad|Jane Austen|es|_debug=}}

Template:Cite wikisource

The |_debug= name is chosen here for convenience, but it may be anything so long as it matches the {{#if:}} parser function in the {{#invoke:}}.

You may also call the link function to get something like the left-hand side of a userbox. This is essentially the list function with the template name turned into a link.