USApedia

Module:Arguments/doc: Difference between revisions

Module Discussion

Module:Arguments/doc (view source)

Revision as of 05:54, 18 November 2024

3,419 bytes added ,  18 November 2024
→‎Options: Italicize "firstInvokeArg" in the examples. This help identifying the frame source of the arguments easier.
VisualWikitext
m (1 revision imported)
(→‎Options: Italicize "firstInvokeArg" in the examples. This help identifying the frame source of the arguments easier.)
Line 1: Line 1:
{{Used in system}}
{{Used in system}}
{{Module rating|p}}
{{Module rating|p}}
{{cascade-protected template|page=module}}


This module provides easy processing of arguments passed from <code>#invoke</code>. It is a meta-module, meant for use by other modules, and should not be called from <code>#invoke</code> directly (for a module directly invocable by templates you might want to have a look at {{ml|params|}}). Its features include:
This module provides easy processing of arguments passed from <code>#invoke</code>. It is a meta-module, meant for use by other modules, and should not be called from <code>#invoke</code> directly (for a module directly invocable by templates you might want to have a look at {{ml|params|}}). Its features include:
Line 81: Line 82:
</syntaxhighlight>
</syntaxhighlight>


=== Options ===
== Options ==


The following options are available. They are explained in the sections below.
The following options are available. They are explained in the sections below.
Line 92: Line 93:
-- Code for processing one argument
-- Code for processing one argument
end,
end,
frameOnly = true,
frameOnly = true,
parentOnly = true,
parentOnly = true,
parentFirst = true,
parentFirst = true,
wrappers = {
wrappers = {
'Template:A wrapper template',
'Template:A wrapper template',
'Template:Another wrapper template'
'Template:Another wrapper template'
},
},
readOnly = true,
readOnly = true,
noOverwrite = true
noOverwrite = true
Line 104: Line 108:
</syntaxhighlight>
</syntaxhighlight>


=== Trimming and removing blanks ===
=== Trimming whitespace ===


Blank arguments often trip up coders new to converting MediaWiki templates to Lua. In template syntax, blank strings and strings consisting only of whitespace are considered false. However, in Lua, blank strings and strings consisting of whitespace are considered true. This means that if you don't pay attention to such arguments when you write your Lua modules, you might treat something as true that should actually be treated as false. To avoid this, by default this module removes all blank arguments.
MediaWiki trims whitespace for named arguments coming from #invoke or a template call, but preserves whitespace for positional arguments. By default, this module helps trim whitespace also for position arguments. To preserve whitespace for positional arguments, set the <code>trim</code> option to <code>false</code>.


Similarly, whitespace can cause problems when dealing with positional arguments. Although whitespace is trimmed for named arguments coming from #invoke, it is preserved for positional arguments. Most of the time this additional whitespace is not desired, so this module trims it off by default.
<syntaxhighlight lang="lua">
local args = getArgs(frame, {
trim = false
})
</syntaxhighlight>


However, sometimes you want to use blank arguments as input, and sometimes you want to keep additional whitespace. This can be necessary to convert some templates exactly as they were written. If you want to do this, you can set the <code>trim</code> and <code>removeBlanks</code> arguments to <code>false</code>.
When the <code>valueFunc</code> option is given, the <code>valueFunc</code> function will be responsible for trimming whitespace, and the <code>trim</code> option will have no effect.
 
=== Removing blank arguments ===
 
"Blank arguments" are arguments from #invoke or template that are blank strings or consist of only whitespace. By default, this module removes all blank arguments. To preserve the blank arguments, set the <code>removeBlanks</code> option to <code>false</code>.


<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local args = getArgs(frame, {
local args = getArgs(frame, {
trim = false,
removeBlanks = false
removeBlanks = false
})
})
</syntaxhighlight>
</syntaxhighlight>
This might be necessary for some templates' operation.
Note: When converting MediaWiki templates to Lua, keep in mind that in Lua, blank strings and strings consisting only of whitespace are considered true. If you don't pay attention to such blank arguments when you write your Lua modules, you might treat something as true that should actually be treated as false.
When the <code>valueFunc</code> option is given, the <code>valueFunc</code> function will be responsible for handling blank arguments, and the <code>removeBlanks</code> option will have no effect.


=== Custom formatting of arguments ===
=== Custom formatting of arguments ===
Line 224: Line 241:
{{cob}}
{{cob}}


<code>Module:ExampleArgs</code> is then called by <code>Template:ExampleArgs</code>, which contains the code <code><nowiki>{{#invoke:ExampleArgs|main|firstInvokeArg}}</nowiki></code>. This produces the result "firstInvokeArg".
<code>Template:ExampleArgs</code> contains the code <code><nowiki>{{#invoke:ExampleArgs|main|''firstInvokeArg''}}</nowiki></code>.


Now if we were to call <code>Template:ExampleArgs</code>, the following would happen:
Now if we were to call <code>Template:ExampleArgs</code>, the following would happen:
Line 232: Line 249:
! style="width: 60%;" | Code
! style="width: 60%;" | Code
! style="width: 40%;" | Result
! style="width: 40%;" | Result
|-
| <pre>{{#invoke:ExampleArgs|main|''firstInvokeArg''}}
(call #invoke directly without template)</pre>
| ''firstInvokeArg''
(call #invoke directly without template)
|-
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| firstInvokeArg
| ''firstInvokeArg''
|-
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstInvokeArg
| ''firstInvokeArg''
|-
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstInvokeArg secondTemplateArg
| ''firstInvokeArg'' secondTemplateArg
|}
|}


Line 252: Line 276:
|-
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| firstInvokeArg
| ''firstInvokeArg''
|-
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstInvokeArg
| ''firstInvokeArg''
|-
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstInvokeArg
| ''firstInvokeArg''
|}
|}


Line 284: Line 308:
|-
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| firstInvokeArg
| ''firstInvokeArg''
|-
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
Line 321: Line 345:
})
})
</syntaxhighlight>
</syntaxhighlight>
The <code>wrappers</code> option changes the default behaviors of the <code>frameOnly</code> and <code>parentOnly</code> options.
{{collapse top|title=Behaviors of ''frameOnly'' and ''parentOnly'' in relations with wrapper templates}}
; If <code>Template:ExampleArgs</code> is specified as a wrapper template:
; <code>parentOnly</code> is true or not set
The frame arguments will not be used at all.
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Code
! style="width: 40%;" | Result
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
|
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstTemplateArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstTemplateArg secondTemplateArg
|}
; <code>parentOnly</code> is false, <code>parentFirst</code> is false or not set
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Code
! style="width: 40%;" | Result
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| ''firstInvokeArg'' secondTemplateArg
|}
; <code>parentOnly</code> is false, <code>parentFirst</code> is true
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Code
! style="width: 40%;" | Result
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstTemplateArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstTemplateArg secondTemplateArg
|}
; If <code>wrappers</code> is set but <code>Template:ExampleArgs</code> is not in the <code>wrappers</code> list:
; <code>frameOnly</code> is true or not set
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Code
! style="width: 40%;" | Result
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| ''firstInvokeArg''
|}
; <code>frameOnly</code> is false, <code>parentFirst</code> is false or not set
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Code
! style="width: 40%;" | Result
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| ''firstInvokeArg'' secondTemplateArg
|}
; <code>frameOnly</code> is false, <code>parentFirst</code> is true
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Code
! style="width: 40%;" | Result
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstTemplateArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstTemplateArg secondTemplateArg
|}
{{collapse bottom}}


Notes:
Notes:
# The module will automatically detect if it is being called from a wrapper template's /sandbox subpage, so there is no need to specify sandbox pages explicitly.
# The module will automatically detect if it is being called from a wrapper template's /sandbox subpage, so there is no need to specify sandbox pages explicitly.
# The ''wrappers'' option effectively changes the default of the ''frameOnly'' and ''parentOnly'' options. If, for example, ''parentOnly'' were explicitly set to 0 with ''wrappers'' set, calls via wrapper templates would result in both frame and parent arguments being loaded, though calls not via wrapper templates would result in only frame arguments being loaded.
# If the ''wrappers'' option is set and no parent frame is available, the module will always get the arguments from the frame passed to <code>getArgs</code>.
# If the ''wrappers'' option is set and no parent frame is available, the module will always get the arguments from the frame passed to <code>getArgs</code>.


Line 336: Line 469:


It is possible to alter this behaviour with the <code>readOnly</code> and <code>noOverwrite</code> options. If <code>readOnly</code> is set then it is not possible to write any values to the args table at all. If <code>noOverwrite</code> is set, then it is possible to add new values to the table, but it is not possible to add a value if it would overwrite any arguments that are passed from #invoke.
It is possible to alter this behaviour with the <code>readOnly</code> and <code>noOverwrite</code> options. If <code>readOnly</code> is set then it is not possible to write any values to the args table at all. If <code>noOverwrite</code> is set, then it is possible to add new values to the table, but it is not possible to add a value if it would overwrite any arguments that are passed from #invoke.
== Notes ==


=== Ref tags ===
=== Ref tags ===
Anonymous user
Retrieved from ‘https://openusaproject.com/wiki/Special:MobileDiff/12529’