طراوت بارانی: ۱ نسخه واردشده

2019-04-17T10:33:59Z

۱ نسخه واردشده

→ نسخهٔ قدیمی‌تر	نسخهٔ ‏۲۸ فروردین ۱۳۹۸، ساعت ۱۴:۰۳
(بدون تفاوت)

ویکی‌ادبیات>Mensis Mirabilis در ‏۱۱ دی ۱۳۹۷، ساعت ۲۲:۵۸

2019-01-01T22:58:27Z

صفحهٔ تازه

{{چپ‌چین}}


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 <code>unset</code> 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 <code>unset</code>.

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

== Usage ==

<code><nowiki>{{#invoke:</nowiki>{{BASEPAGENAME}}|wrap|_template={{Var|working template}}|_exclude={{Var|named parameter}}, {{Var|named parameter}}, ...|_reuse={{Var|named parameter}}, {{Var|named parameter}}, ...|_alias-map={{Var|alias parameter}}:{{Var|canonical parameter}}|_include-positional=yes|<{{Var|default parameter}}>|<{{Var|default parameter}}>|...}}</code>

;Control parameters
:{{پارا|_template}} – (required) the name, without namespace, of the working template (the template that is wrapped); see §[[#_template|_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|_exclude]] below
:{{پارا|_reuse}} – comma-separated list of canonical names that have meaning to both the wrapper template and to the working template; see §[[#_reuse|_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|_alias-map]] below
:{{پارا|_include-positional}} – pass all positional parameters to the working template; see §[[#_include-positional|_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

{| class="nowrap"
|+parameter processing
!style="border:1px solid black"|wrapper template !! !!style="border:1px solid black" colspan="11"|Module:Template wrapper !! !! style="border:1px solid black"|working template
|-
| style="border: 1px solid black;"|{{پارا|plain=yes|{{Var|canonical parameters}}}}|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="border: 2px solid black;" rowspan="5"|filter exclued parameters|| ||style="border: 2px solid black;" rowspan="10"|working template
|-
| style="border: 1px solid black;"|{{پارا|plain=yes|{{Var|wrapper parameters}}}}|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → 
|-
| || || style="border: 1px solid black;"|{{پارا|plain=yes|[[#_exclude|_exclude]]}}|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → || → 
|-
| || || style="border: 1px solid black;"|{{پارا|plain=yes|[[#_include-positional|_include-positional]]}}|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → 
|-
| || || style="border: 1px solid black;"|{{پارا|plain=yes|[[#_alias-map|_alias-map]]}}|| → ||style="border: 2px solid black;" rowspan="3"|convert alias parameters to canonical parameters|| → ||style="border: 1px solid black;" rowspan="2"|{{پارا|plain=yes|{{Var|canonical parameters}}}}|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → || || → 
|-
| || || || || → || → ||style="border: 2px solid black;" rowspan="4"|modify reused canonical parameters
|-
| style="border: 1px solid black;"|{{پارا|plain=yes|{{Var|alias parameters}}}}|| → ||style="text-align: center;"|–––––––→|| → || || || || → ||style="border: 1px solid black;"|{{پارا|plain=yes|{{Var|reused parameters}}}}|| → ||style="text-align: center;"|–––→|| → 
|-
| || || style="border: 1px solid black;"|{{پارا|plain=yes|[[#_reuse|_reuse]]}}|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → 
|-
| style="border: 1px solid black;"|{{پارا|plain=yes|{{Var|canonical parameters}}}}|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → 
|-
| || || style="border: 1px solid black;"|{{پارا|plain=yes|{{Var|default parameters}}}}|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––––––→|| → ||style="text-align: center;"|–––→|| → 
|}

==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:
:<code style="color:inherit; border:inherit; padding:inherit;">|_template=</code> 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:
:<code><{{Var|from}}>:<{{Var|to}}></code> – where: <code><{{Var|from}}></code> is a wrapper parameter name and <code><{{Var|to}}></code> 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 <code><nowiki>{{#invoke:}}</nowiki></code> 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 <code>#</code> 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. 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 <code><nowiki>{{{2}}}</nowiki></code> becomes working template <code><nowiki>{{{2}}}</nowiki></code>, etc; working template will not get <code><nowiki>{{{1}}}</nowiki></code> 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

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 <code><nowiki>{{#invoke:Template wapper|wrap|_template=...|...}}</nowiki></code> we write:
:{{پارا|title|Modified <nowiki>{{{title}}}</nowiki>}}

_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 <code><nowiki>{{#invoke:Template wapper|wrap|_template=...|...}}</nowiki></code> we write:
:{{پارا|url|<nowiki>https://example.com/{{{id}}}</nowiki>}}
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: <code>yes</code>; the default (empty, missing) is <code>no</code> (positional parameters normally excluded). When set to <code>yes</code>, Module:Template wrapper will pass all positional parameters to the working template.

See also §[[#_alias-map|_alias-map]].

===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 <code>unset</code>. Default parameters with this value are passed to the working template as empty (no assigned value) parameters.

_reused parameters cannot be <code>unset</code> or overridden.

==Debugging aid==
This module has two entry points. A wrapper template might use a module <code><nowiki>{{#invoke:}}</nowiki></code> written like this:
:<code><nowiki>{{#invoke:</nowiki>{{BASEPAGENAME}}|<nowiki>{{#if:{{{_debug|}}}|list|wrap}}</nowiki>|_template=<{{Var|working template}}>|_exclude=_debug, ...|...}}</code>
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/sandbox}} is a wrapper template that uses {{الگوب|citation}} as its working template. {{Tld|cite wikisource/sandbox}} accepts positional parameters but {{Tld|citation}} does not so the wrapper template must convert the positional parameters to named parameters which it does using the {{پارا|_alias-map}} parameter:
:<syntaxhighlight lang="moin">{{#invoke:template wrapper|{{#if:{{{_debug|}}}|list|wrap}}|_template=citation/new
|_exclude=..., _debug 
|_alias-map=1:title, 2:author, 3:language</syntaxhighlight>
This example uses positional parameters and sets {{پارا|_debug|yes}} to show that the {{Tld|citation}} template is correctly formed:
:<code><nowiki>{{cite wikisource/sandbox|Sentido y sensibilidad|Jane Austen|es|_debug=yes}}</nowiki></code>
::{{cite wikisource/sandbox|Sentido y sensibilidad|Jane Austen|es|_debug=yes}}
and, with {{پارا|_debug}} unset:
:<code><nowiki>{{cite wikisource/sandbox|Sentido y sensibilidad|Jane Austen|es|_debug=}}</nowiki></code>
::{{cite wikisource/sandbox|Sentido y sensibilidad|Jane Austen|es|_debug=}}
The {{پارا|_debug}} name is chosen here for convenience but may be anything so long as it matches the <code><nowiki>{{#if:}}</nowiki></code> in the <code><nowiki>{{#invoke:}}</nowiki></code>.
<includeonly>{{Sandbox other||


}}</includeonly>

{{پایان چپ‌چین}}

پودمان:Template wrapper/توضیحات - تاریخچهٔ نسخه‌ها

طراوت بارانی: ۱ نسخه واردشده

ویکی‌ادبیات>Mensis Mirabilis در ‏۱۱ دی ۱۳۹۷، ساعت ۲۲:۵۸