Module:Template wrapper

Module documentation[view] [edit] [history] [purge]

This module is about providing wrapper template services. For tagging wrappable segments within nowrap-scoped text, see Template:Wrap. For a doc page banner that flags a wrapper template, see Template:Wrapper.

Warning This Lua module is used on approximately 753,000 pages, or roughly 1% of all pages .
To avoid major disruption and server load, any changes should be tested in the module's /sandbox or /testcases subpages, or in your own module sandbox. The tested changes can be added to this page in a single edit. Consider discussing changes on the talk page before implementing them.

See also: {{#invoke:params|concat_and_call}}

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; positional parameters 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= – (required) the name, without namespace, of the working template (the template that is wrapped); see §_template below; |_exclude= – comma-separated list of parameter names used by the wrapper template that are not to be passed to the working template; see §_exclude below; |_reuse= – comma-separated list of canonical names that have meaning to both the wrapper template and to the working template; see §_reuse below; |_alias-map= – comma-separated 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=`	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	filter exclued parameters	working template
`\|wrapper parameters=`	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→
	`\|_exclude=`	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	→
	`\|_include-positional=`	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→
	`\|_alias-map=`	→	convert alias parameters to canonical parameters	→	`\|canonical parameters=`	→	–––––––→	→	–––––––→	→	→
	→	→		modify reused canonical parameters	`\|canonical parameters=`
`\|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, Module:Template wrapper will emit the error message:

|_template= missing or empty

_alias-map

|_alias-map= takes a comma-separated 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 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#

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. Mapping positional parameters when |_include-positional=yes may give undesirable results. |_alias-map=1:author and |_include-positional=yes will cause all other positional parameters to be passed to the working template as is: wrapper template {{{2}}} becomes working template {{{2}}}, etc; working template will not get {{{1}}} though it will get |author=.

_reuse

|_reuse= takes a comma-separated list of canonical parameters that have meaning to both the wrapper template and to the working template; not supported for positional parameters.

In the simplest cases, a canonical parameter passed into the wrapper template overrides a default parameter provided in the wrapper template. Sometimes 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 this 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}}}

_reused parameters cannot be overridden.

_exclude

|_exclude= takes a comma-separated list of parameters used by the wrapper template that are not to be passed to the working template. This list applies to all wrapper and canonical parameters (including those canonical parameters 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 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}}}

The modified |url= value is passed on to working template but |id= and its value is not.

_reused and default parameters cannot be excluded.

_include-positional

|_include-positional= is a boolean parameter that takes only one value: yes; the default (empty, missing) is no (positional parameters normally excluded). When set to yes, Module:Template wrapper will pass all 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 no value, use the special keyword unset. Default parameters with this value are passed to the working template as empty (no assigned value) parameters.

_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, 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 which it does using the |_alias-map= parameter:

{{#invoke:template wrapper|{{#if:{{{_debug|}}}|list|wrap}}|_template=citation
 |_exclude=..., _debug <!-- unnecessary detail omitted -->
 |_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}}

{{citation|author=Jane Austen|language=es|mode=cs1|title=[[s:es:Sentido y sensibilidad|Sentido y sensibilidad]]|via=[[Wikisource]]}}

and, with |_debug= unset:

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

Jane Austen. Sentido y sensibilidad (in Spanish) – via Wikisource.

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

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

{{User in New Zealand |4}}

This user is a part-time resident of New Zealand .

The above documentation is transcluded from Module:Template wrapper/doc. (edit | history)
Editors can experiment in this module's sandbox (edit | diff) and testcases (create) pages.
Subpages of this module.

 require('strict');

 localerror_msg='<span style=\"font-size:100%\" class=\"error\"><code style=\"color:inherit; border:inherit; padding:inherit;\">&#124;_template=</code> missing or empty</span>';


 --[[--------------------------< I S _ I N _ T A B L E >--------------------------------------------------------

 scan through tbl looking for value; return true if found, false else

 ]]

 localfunctionis_in_table(tbl,value)
 fork,vinpairs(tbl)do
 ifv==valuethenreturntrueend
 end
 returnfalse;
 end


 --[[--------------------------< A D D _ P A R A M E T E R >----------------------------------------------------

 adds parameter name and its value to args table according to the state of boolean list argument; kv pair for
 template execution; k=v string for template listing.

 ]]

 localfunctionadd_parameter(k,v,args,list)
 iflistthen
 table.insert(args,table.concat({k,'=',v}));-- write parameter names and values to args table as string
 else
 args[k]=v;-- copy parameters to args table
 end
 end


 --[[--------------------------< A L I A S _ M A P _ G E T >----------------------------------------------------

 returns a table of local template (parent frame) parameter names and the target template names that match where
 in [key]=<value> pairs where:
 	[key] is local template parameter name (an alias)
 	<value> is target template parameter name (the canonical parameter name used in the working template)

 The parameter |_alias-map= has the form:
 	|_alias-map=<list>
 where <list> is a comma-separated list of alias / canonical parameter name pairs in the form
 	<from> : <to>
 where:
 	<from> is the local template's parameter name (alias)
 	<to> is the target template's parameter name (canonical)
 	for enumerated parameters place an octothorp (#) where the enumerator digits are placed in the parameter names:
 		<from#> : <to#>

 ]]

 localfunctionalias_map_get(_alias_map)
 localT=mw.text.split(_alias_map,'%s*,%s*');-- convert the comma-separated list into a table of alias pairs
 localmapped_aliases={};-- mapped aliases will go here
 locall_name,t_name;-- parameter names

 for_,alias_pairinipairs(T)do-- loop through the table of alias pairs
 l_name,t_name=alias_pair:match('(.-)%s*:%s*(.+)');-- from each pair, get local and target parameter names
 ifl_nameandt_namethen-- if both are set
 iftonumber(l_name)then
 l_name=tonumber(l_name);-- convert number-as-text to a number
 end
 mapped_aliases[l_name]=t_name;-- add them to the map table
 end
 end

 returnmapped_aliases;
 end


 --[[--------------------------< F R A M E _ A R G S _ G E T >--------------------------------------------------

 Fetch the wrapper template's 'default' and control parameters; adds default parameters to args

 returns content of |_template= parameter (name of the working template); nil else

 ]]

 localfunctionframe_args_get(frame_args,args,list)
 localtemplate;

 fork,vinpairs(frame_args)do-- here we get the wrapper template's 'default' parameters
 if'string'==type(k)and(vand(''~=v))then-- do not pass along positional or empty parameters
 if'_template'==kthen
 template=v;-- save the name of template that we are wrapping
 elseif'_exclude'~=kand'_reuse'~=kand'_include-positional'~=kand'_alias-map'~=kthen-- these already handled so ignore here; 
 add_parameter(k,v,args,list);-- add all other parameters to args in the style dictated by list
 end
 end
 end

 returntemplate;-- return contents of |_template= parameter
 end


 --[=[--------------------------< P F R A M E _ A R G S _ G E T >------------------------------------------------

 Fetches the wrapper template's 'live' parameters; adds live parameters that aren't members of the exclude table to
 args table; positional parameters may not be excluded

 no return value

 ]=]

 localfunctionpframe_args_get(pframe_args,args,exclude,_include_positional,list)
 fork,vinpairs(pframe_args)do
 if'string'==type(k)andnotis_in_table(exclude,k)then-- do not pass along excluded parameters
 ifvand(''~=v)then-- pass along only those parameters that have assigned values
 if'unset'==v:lower()then-- special keyword to unset 'default' parameters set in the wrapper template
 v='';-- unset the value in the args table
 end
 add_parameter(k,v,args,list)-- add all other parameters to args in the style dictated by list; alias map only supported for local-template parameters
 end
 end
 end

 if_include_positionalthen
 fori,vinipairs(pframe_args)do-- pass along positional parameters
 if'unset'==v:lower()then-- special keyword to unset 'default' parameters set in the wrapper template
 v='';-- unset the value in the args table
 end
 add_parameter(i,v,args,list);
 end
 end
 end


 --[[--------------------------< _ M A I N >--------------------------------------------------------------------

 Collect the various default and live parameters into args styled according to boolean list.

 returns name of the working or listed template or nil for an error message

 ]]

 localfunction_main(frame,args,list)
 localtemplate;
 localexclude={};-- table of parameter names for parameters that are not passed to the working template
 localreuse_list={};-- table of pframe parameter names whose values are modified before they are passed to the working template as the same name
 localalias_map={};-- table that maps parameter aliases to working template canonical parameter names
 local_include_positional;

 ifframe.args._excludeand(''~=frame.args._exclude)then-- if there is |_exclude= and it's not empty
 exclude=mw.text.split(frame.args._exclude,"%s*,%s*");-- make a table from its contents
 end
 -- TODO: |_reuse= needs a better name (|_reuse=)
 ifframe.args._reuseand(''~=frame.args._reuse)then-- if there is |_reuse= and it's not empty
 reuse_list=mw.text.split(frame.args._reuse,"%s*,%s*");-- make a table from its contents
 end

 ifframe.args['_alias-map']and(''~=frame.args['_alias-map'])then-- if there is |_alias-map= and it's not empty
 alias_map=alias_map_get(frame.args['_alias-map']);-- make a table from its contents
 end

 template=frame_args_get(frame.args,args,list);-- get parameters provided in the {{#invoke:template wrapper|...|...}}
 ifnil==templateor''==templatethen-- this is the one parameter that is required by this module
 returnnil;-- not present, tell calling function to emit an error message
 end

 _include_positional='yes'==frame.args['_include-positional'];-- when true pass all positional parameters along with non-excluded named parameters to ...
 -- ... the working template; positional parameters are not excludable

 local_pframe_args=frame:getParent().args;-- here we get the wrapper template's 'live' parameters from pframe.args
 localpframe_args={};-- a local table that we can modify

 fork,vinpairs(_pframe_args)do-- make a copy that we can modify
 pframe_args[k]=v;
 end

 -- here we look for pframe parameters that are aliases of canonical parameter names; when found
 -- we replace the alias with the canonical. We do this here because the reuse_list works on
 -- canonical parameter names so first we convert alias parameter names to canonical names and then
 -- we remove those canonical names from the pframe table that are reused (provided to the working
 -- template through the frame args table)

 fork,vinpairs(alias_map)do-- k is alias name, v is canonical name
 ifpframe_args[k]then-- if pframe_args has parameter with alias name
 pframe_args[v]=_pframe_args[k];-- create new canonical name with alias' value
 pframe_args[k]=nil;-- unset the alias
 end
 end

 fork,vinpairs(pframe_args)do-- do enumerated parameter alias -> canonical translation
 if'string'==type(k)then-- only named parameters can be enumerated
 ifalias_map[k..'#']then-- non-enumerated alias matches enumerated parameter pattern? enumerator at end only
 pframe_args[alias_map[k..'#']:gsub('#','')]=v;-- remove '#' and copy parameter to pframe_args table
 pframe_args[k]=nil;-- unset the alias
 elseifk:match('%d+')then-- if this parameter name contains digits
 localtemp=k:gsub('%d+','#');-- make a copy; digits replaced with single '#'
 localenum=k:match('%d+');-- get the enumerator

 ifalias_map[temp]then-- if this parameter is a recognized enumerated alias
 pframe_args[alias_map[temp]:gsub('#',enum)]=v;-- use canonical name and replace '#' with enumerator and add to pframe_args
 pframe_args[k]=nil;-- unset the alias
 end
 end
 end
 end

 -- pframe parameters that are _reused are 'reused' have the form something like this:
 --	|chapter=[[wikisource:{{{chapter}}}|{{{chapter}}}]]
 -- where a parameter in the wrapping template is modified and then passed to the working template
 -- using the same parameter name (in this example |chapter=)

 -- remove parameters that will be reused
 fork,vinipairs(reuse_list)do-- k is numerical index, v is canonical parameter name to ignore
 ifpframe_args[v]then-- if pframe_args has parameter that should be ignored
 pframe_args[v]=nil;-- unset the ignored parameter
 end
 end

 pframe_args_get(pframe_args,args,exclude,_include_positional,list);-- add parameters and values to args that are not listed in the exclude table

 returntemplate;-- args now has all default and live parameters, return working template name
 end


 --[[--------------------------< W R A P >----------------------------------------------------------------------

 Template entry point. Call this function to 'execute' the working template

 ]]

 localfunctionwrap(frame)
 localargs={};-- table of default and live parameters and their values to be passed to the wrapped template
 localtemplate;-- the name of the working template

 template=_main(frame,args,false);-- get default and live parameters and the name of the working template
 ifnottemplatethen-- template name is required
 returnerror_msg;-- emit error message and abandon if template name not present
 end

 returnframe:expandTemplate{title=template,args=args};-- render the working template
 end


 --[[--------------------------< L I S T >----------------------------------------------------------------------

 Template entry point. Call this function to 'display' the source for the working template. This function added
 as a result of a TfD here: Wikipedia:Templates_for_discussion/Log/2018_April_28#Module:PassArguments

 This function replaces a similarly named function which was used in {{cite compare}} and {{cite compare2}}

 Values in the args table are numerically indexed strings in the form 'name=value'

 ]]

 localfunctionlist(frame,do_link)
 localargs={};-- table of default and live parameters and their values to be passed to the listed template
 localtemplate;-- the name of the listed template

 template=_main(frame,args,true);-- get default and live parameters and the name of the listed template
 ifnottemplatethen-- template name is required
 returnerror_msg;-- emit error message and abandon if template name not present
 end
 ifdo_linkthen
 template=('[[%s|%s]]'):format(frame:expandTemplate{title='Transclude',args={template}},template)
 end
 table.sort(args)
 fori=1,#argsdo
 localstripped=args[i]:match('^'..i..'=([^=]*)$')
 ifstrippedthenargs[i]=strippedelsebreakend
 end
 returnframe:preprocess(table.concat({
 '<code style="color:inherit; background:inherit; border:none;">&#123;&#123;',
 template,
 ('<wbr><nowiki>|%s</nowiki>'):rep(#args):format(unpack(args)),'&#125;&#125;</code>'}));-- render the template
 end

 localfunctionlink(frame)
 returnlist(frame,true)
 end

 --[[--------------------------< E X P O R T E D F U N C T I O N S >------------------------------------------
 ]]

 return{
 link=link,
 list=list,
 wrap=wrap,
 };

Retrieved from "https://en.wikipedia.org/w/index.php?title=Module:Template_wrapper&oldid=1117461841"