Difference between revisions of "Template:Use"

From MHWiki
(Graduate to main template namespace from User:Ericb/Use)
 
(Revamped Template:Use page to include a {{USE}} for Dummies + Warning Explanation for Template:If errors)
Line 1: Line 1:
<noinclude>Since this wiki [[:User_talk:Giorgio_Sintichakis|lacks Extension:ParserFunctions]] such as {{#if:test|if text|if empty}}, it is desirable to provide an alternate syntax for conditional expansion (choosing one of two strings depending on whether the test string is empty, or choosing one of two strings depending on whether the test string matches a target string).  This template is the workhorse behind conditional templates, and exploits some characteristics of named parameters - namely, if a parameter is named more than once, then the last use of that name is valid; and the calling page can use parameter expansions to control which named parameters this template will see.
+
<noinclude>
 +
:''To Editors: If you have come to this page to find out why there is a warning in your Edit page, see [[#here|here]].''
  
This macro understands up to two named parameters, and ignores all others. If the named parameter "indir" is given, then its value is an indirection that gives the other named parameter whose value will be used as the overall expansion.  Otherwise, the value of the named parameter "use" will be the overall expansion. Examples:
+
Background:
  <nowiki>{{use|use=hello}}</nowiki> gives "hello"
+
Since this wiki [[:User_talk:Giorgio_Sintichakis|lacks Extension:ParserFunctions]] such as [https://www.mediawiki.org/wiki/Help:Extension:ParserFunctions##if <nowiki>{{</nowiki>#if:test|if text|if empty<nowiki>}}</nowiki>] and [https://www.mediawiki.org/wiki/Help:Extension:ParserFunctions##ifeq <nowiki>{{</nowiki>#ifeq:test1|test2|if equal|if differ<nowiki>}}</nowiki>], it is desirable to provide an alternate syntax for conditional expansion (choosing one of two strings depending on whether the test string is empty, or choosing one of two strings depending on whether the test string matches a target string). This template is the workhorse behind conditional templates [[Template:If]] and [[Template:Ifeq]]: it exploits some characteristics of named parameters - namely, if a parameter is named more than once, then the last use of that name is valid; and the calling page can use parameter expansions to control which named parameters this template will see.
  <nowiki>{{use|use=first|use=second}}</nowiki> gives "second"
+
 
  <nowiki>{{use|indir=name|name=hello|use=world}}</nowiki> gives "hello"
+
Overview:
 +
This macro understands up to two named parameters, and ignores all others. If the value of the named parameter "use" is given, then its value will be the overall expansion. If the named parameter "indir" is given, then its value is an indirection that gives the other named parameter whose value will be used as the overall expansion, overriding any "use" parametersRegardless of what parameter is used, the last given value of the used parameter will be used as the overall expansion.
 +
 
 +
Examples:
 +
  1)<nowiki>{{use|use=first}}</nowiki> gives "first"
 +
  2)<nowiki>{{use|use=first|use=second}}</nowiki> gives "second"
 +
  3)<nowiki>{{use|indir=name|name=third|use=first}}</nowiki> gives "third"
 +
4)<nowiki>{{use|indir=name|name=third|name=fourth|use=first}}</nowiki> gives "fourth"
 +
 
 +
Further illustration: It is '''assumed''' in this section that you have generally understood how [https://www.mediawiki.org/wiki/Help:Templates#Parameters Templates#Parameters] work, in particular the sections on named parameters and default values.
 +
The base code used in this function is: <nowiki>{{{{{{indir|use}}}|}}}</nowiki>.
 +
 +
First, we ignore the nested (to put it simply, the inner most one) parameter <nowiki>{{{indir|use}}}</nowiki>, let's call it "NEST" for instance.
 +
The base code can then be simplified as: <nowiki>{{{NEST|}}}</nowiki>.
 +
This should be pretty simple to understand at this point given the assumed knowledge: the function calls the "NEST" parameter and will expand on the "NEST" parameter if it is defined, otherwise, nothing will happen (since there is nothing after the pipe character).
 +
 +
Next, we consider the nested parameter <nowiki>{{{indir|use}}}</nowiki> or "NEST":
 +
What this says is that the "indir" parameter is called upon first for the value when "NEST" is expanded. If "indir" is defined, the value "indir" is then expanded on (see final note below). If "indir" is undefined, the value of "use" is then used. Note that the placement of the parameters, separated by only the pipe character, determines the priority order of the parameters being called upon.
 +
 +
Putting it all together, the "NEST" template is undefined if both "indir" and "use" are undefined, hence, this implies that other parameters other than "indir" and "use" are ignored. The priority order in "NEST" also implies that "use" is overriden should "indir" be defined. The behaviour where only the last given value of the used parameter is valid is a standard feature in MediaWiki.
 +
 +
As a final note, you may have noticed that "indir" is being expanded on rather than being used: this has to do loosely with the fact that "indir" has six braces in front of it directly, indicating that "indir" represents a slightly more complicated form of named parameter where parameter value is itself also a parameter. As such, if "indir" is defined, its parameter value must also be defined for the function to have a final value, that is to say, <nowiki>{{use|indir=name|use=first}}</nowiki> will result in nothing happening. You may wish to consult [https://meta.wikimedia.org/wiki/Help:Advanced_templates#Variable_parameter_name Advanced_templates#Variable_parameter_name] (the subsection on "Parameter name from another parameter in the same template") for more info.
 +
 
 +
<div id="here">[For Editors] Warning explanation: It is '''assumed''' in this section that you understand how [[Template:Use]], [[Template:If]] and [[Template:Ifeq]] works.</div>
 +
For [[Template:If]] errors:
 +
Recall that the base code in the [[Template:If]] function is: <nowiki>{{use|use={{{2|}}}|use{{{1|}}}={{{3|}}}}}</nowiki>.
 +
For the sake of simplicity, let's ignore all the named parameters and name them A, B and C -> the function becomes <nowiki>{{use|use=B|useA=C}}</nowiki>.
 +
Also recall that the A represents the "test", B represents the "if text" and C represents the "if empty".
 +
 +
Consider a situation where "if empty" applies: A is null and the base code is simplified to <nowiki>{{use|use=B|use=C}}</nowiki>.
 +
Then, what we have is two values for the "use" parameter, which is considered a [https://en.wikipedia.org/wiki/Help:Duplicate_parameters Duplicate parameters error].
 +
Why is it an error? In this case, if B is changed to D, the function has essentially changed but C is still the final value used. And different functions leading to the same output is definitely something that is seen as not ideal.
 +
Does it matter for MHWiki? No! In a situation where "if empty" applies, we don't really care whether it's B or D, we wanted C anyway as the output.
 +
 +
 
 +
For [[Template:Ifeq]] errors:
 +
WIP
 
</noinclude><includeonly>{{{{{{indir|use}}}|}}}</includeonly>
 
</noinclude><includeonly>{{{{{{indir|use}}}|}}}</includeonly>

Revision as of 18:06, 12 June 2021

To Editors: If you have come to this page to find out why there is a warning in your Edit page, see here.

Background:

Since this wiki lacks Extension:ParserFunctions such as {{#if:test|if text|if empty}} and {{#ifeq:test1|test2|if equal|if differ}}, it is desirable to provide an alternate syntax for conditional expansion (choosing one of two strings depending on whether the test string is empty, or choosing one of two strings depending on whether the test string matches a target string). This template is the workhorse behind conditional templates Template:If and Template:Ifeq: it exploits some characteristics of named parameters - namely, if a parameter is named more than once, then the last use of that name is valid; and the calling page can use parameter expansions to control which named parameters this template will see.

Overview:

This macro understands up to two named parameters, and ignores all others. If the value of the named parameter "use" is given, then its value will be the overall expansion. If the named parameter "indir" is given, then its value is an indirection that gives the other named parameter whose value will be used as the overall expansion, overriding any "use" parameters.  Regardless of what parameter is used, the last given value of the used parameter will be used as the overall expansion.

Examples:

1){{use|use=first}} gives "first"
2){{use|use=first|use=second}} gives "second"
3){{use|indir=name|name=third|use=first}} gives "third"
4){{use|indir=name|name=third|name=fourth|use=first}} gives "fourth"

Further illustration: It is assumed in this section that you have generally understood how Templates#Parameters work, in particular the sections on named parameters and default values.

The base code used in this function is: {{{{{{indir|use}}}|}}}.

First, we ignore the nested (to put it simply, the inner most one) parameter {{{indir|use}}}, let's call it "NEST" for instance.
The base code can then be simplified as: {{{NEST|}}}.
This should be pretty simple to understand at this point given the assumed knowledge: the function calls the "NEST" parameter and will expand on the "NEST" parameter if it is defined, otherwise, nothing will happen (since there is nothing after the pipe character).

Next, we consider the nested parameter {{{indir|use}}} or "NEST":
What this says is that the "indir" parameter is called upon first for the value when "NEST" is expanded. If "indir" is defined, the value "indir" is then expanded on (see final note below). If "indir" is undefined, the value of "use" is then used. Note that the placement of the parameters, separated by only the pipe character, determines the priority order of the parameters being called upon.

Putting it all together, the "NEST" template is undefined if both "indir" and "use" are undefined, hence, this implies that other parameters other than "indir" and "use" are ignored. The priority order in "NEST" also implies that "use" is overriden should "indir" be defined. The behaviour where only the last given value of the used parameter is valid is a standard feature in MediaWiki.

As a final note, you may have noticed that "indir" is being expanded on rather than being used: this has to do loosely with the fact that "indir" has six braces in front of it directly, indicating that "indir" represents a slightly more complicated form of named parameter where parameter value is itself also a parameter. As such, if "indir" is defined, its parameter value must also be defined for the function to have a final value, that is to say, {{use|indir=name|use=first}} will result in nothing happening. You may wish to consult Advanced_templates#Variable_parameter_name (the subsection on "Parameter name from another parameter in the same template") for more info.
[For Editors] Warning explanation: It is assumed in this section that you understand how Template:Use, Template:If and Template:Ifeq works.
For Template:If errors:
Recall that the base code in the Template:If function is: {{use|use={{{2|}}}|use{{{1|}}}={{{3|}}}}}.
For the sake of simplicity, let's ignore all the named parameters and name them A, B and C -> the function becomes {{use|use=B|useA=C}}.
Also recall that the A represents the "test", B represents the "if text" and C represents the "if empty".

Consider a situation where "if empty" applies: A is null and the base code is simplified to {{use|use=B|use=C}}.
Then, what we have is two values for the "use" parameter, which is considered a Duplicate parameters error.
Why is it an error? In this case, if B is changed to D, the function has essentially changed but C is still the final value used. And different functions leading to the same output is definitely something that is seen as not ideal.
Does it matter for MHWiki? No! In a situation where "if empty" applies, we don't really care whether it's B or D, we wanted C anyway as the output.

For Template:Ifeq errors:
WIP