Module:Unsubst/sandbox/doc: Difference between revisions

← Older edit

VisualWikitext

Latest revision as of 22:37, 14 March 2025

@@ Line 1: / Line 1: @@
 <includeonly>
-{{Module:Unsubst/doc}}
+<!-- Categories where indicated at the bottom of this page, please. -->
+Helper module to facilitate a substituted template transform into a template transclusion.
+Some templates, such as {{tl|Citation needed}}, should never be substituted. A trick to avoid that is to make a template substitute to its transcluded form.
+=== Usage ===
+To turn a template into a self-substituting template, wrap the existing template code with:
+<pre>
+{{SAFESUBST:<noinclude />#invoke:Unsubst||$B=
+ [ ... existing template code ... ]
+}}
+</pre>
+The wikitext to display when not substed must be given as "$B". All other parameters passed to the #invoke will be copied to the generated template invocation as default values. If the value of any of these default parameters is <code>__DATE__</code>, that value in the generated template invocation will be the current month and year.
+Some templates have a {{tag|noinclude|o}} but no matching {{tag|noinclude|c}} at the end of the template. In such cases the missing {{tag|noinclude|c}} must be added before the ending <code>{{))}}</code>.
+==== Advanced ====
+<pre>
+{{SAFESUBST:<noinclude />#invoke:Unsubst||$params=[ parameters ]|$aliases=[ aliases ]|$flags=[ flags ]|$B=
+ [ ... existing template code ... ]
+}}
+</pre>
+Due to Lua limitations, parameters are normally ordered randomly when the template is substituted. {{para|$params}} can be used in #invoke:Unsubst to list template parameters in order, comma-separated (e.g. <code>egg,bacon,sausage,cheese,spam</code>). Numbered parameters should be before others in the list. Any remaining parameters are tacked onto the end of the generated invocation.
+Parameter aliases can be listed in {{para|$aliases}} (and shouldn't be listed in {{para|$params}}), and will be replaced automatically. Each alias and its replacement should be formatted as <code>alias>replacement</code>, and each of those pairs should be comma-separated (e.g. <code>œuf>egg,melt>cheese</code>). Note that this parameter can function with or without {{para|$params}}.
+Parameter {{para|$flags}} can be used to modify other facets of the module's behaviour; entries are comma-separated. Valid flags are <code>override</code> (allows parameters in the #invoke: to take precedence over parameters in the original template invocation); <code>keep-whitespace</code> (prevents whitespace from being trimmed from unnamed parameters); and <code>remove-empty</code> (removes empty parameters).
+These parameters can be manipulated using parser functions to provide more complicated options (note that in the parameters any parser function, or template or module invocation, should also have <code><nowiki>SAFESUBST:<noinclude /></nowiki></code>).
+=== Example ===
+Consider a template Template:Example containing the following code:
+<pre>
+{{SAFESUBST:<noinclude />#invoke:Unsubst||foo=bar |date=__DATE__ |$B=
+ [ ... Template code goes here ... ]
+}}
+</pre>
+{| class="wikitable"
+! Original !! Result
+|-
+| {{tls|example}} || {{tlc|Example|foo=bar|date{{=}}{{#time:F Y}}}}
+|-
+| {{tls|example|foo{{=}}X}} || {{tlc|Example|foo{{=}}X|date{{=}}{{#time:F Y}}}}
+|-
+| {{tls|example|baz{{=}}X}} || {{tlc|Example|foo=bar|baz{{=}}X|date{{=}}{{#time:F Y}}}}
+|-
+| {{tls|example|date{{=}}January 2001}} || {{tlc|Example|foo{{=}}bar|date{{=}}January 2001}}
+|}
 [[Category:Module sandboxes]]
 [[Category:Module sand&test]]