View source for Template:Options/doc

A common options mechanism for templates.

== Usage ==

=== Initialization ===
The configuration of options must be registered before the options can be used. It can be done via {{tl|options/init}}, for example(It will be used for all following examples as well):
<pre>
{{options/init|item<!-- init config for "item" namespace
-->|key:icons=yes<!--  declare an option named "icons", and its default value is "yes"
-->|key:small=no<!-- default value of "small" option is "no"
-->|value:small:n=no<!-- value "n" for "small" is same as "no", so {{options/set|item|small=n}} is same as {{options/set|item|small=no}}
-->|key:style=<!-- default value of "style" is empty value.
-->|alias:css=style<!-- "css" is an alias of "style", so {{options|item|css}} is same as {{options|item|style}}
-->}}
</pre>
{{options/init|item<!-- init config for "item" namespace
-->|key:icons=yes<!--  declare an option named "icons", and its default value is "yes"
-->|key:small=no<!-- default value of "small" option is "no"
-->|value:small:n=no<!-- value "n" for "small" is same as "no", so {{options/set|item|small=n}} is same as {{options/set|item|small=no}}
-->|key:style=<!-- default value of "style" is empty value.
-->|alias:css=style<!-- "css" is an alias of "style", so {{options|item|css}} is same as {{options|item|style}}
-->}}
It is possible to have it load automatically("autoload") via <code>Template:<namespace>/initOptions</code>. For example, for <code><nowiki>{{options|icon|small}}</nowiki></code>, it will try to transclude <code>Template:item/initOptions</code>.

=== Get/set options ===

Get:
<code><nowiki>{{options/get|<namespace>|<key>}}</nowiki></code> or <code><nowiki>{{options|<namespace>|<key>}}</nowiki></code>

Set:
<code><nowiki>{{options/set|<namespace>|<key1>=<value1>|<ke2>=<value2>|...}}</nowiki></code> or <code><nowiki>{{options|<namespace>|<key1>=<value1>|<key2>=<value2>|...}}</nowiki></code>

Note: The latter form is a bit slow, but more handy for writing. For using in templates the former is prefer, and for using in articles both are ok.

Example:
<pre>
{{options/get|item|icons}}<!-- get default value -->
{{options/set|item|icons=no}}<!-- set it to "no" -->
{{options/get|item|icons}}<!-- now it will be "no" -->
{{options/set|item|icons=all|small=yes}}<!-- set multiple options -->
{{options/get|item|icon}}
{{options/get|item|small}}
</pre>
It will output:
<code>{{unitTest|yes no all yes|{{options/get|item|icons}}<!-- get default value 
-->{{options/set|item|icons=no}}<!-- set it to "no" 
--> {{options/get|item|icons}}<!-- now it will be "no" 
-->{{options/set|item|icons=all|small=yes}}<!-- set multiple options 
--> {{options/get|item|icons}} {{options/get|item|small}}}}</code>

=== Snapshot ===
It is possible to save current state of options to a snapshot, then restore it later.

<code><nowiki>{{options/snap|<namespace>|<snpashot_name>}}</nowiki></code>

<code><nowiki>{{options/restore|<namespace>|<snpashot_name>}}</nowiki></code>

Example:
<pre>
{{options/set|item|icons=aa|small=bb}}<!--
-->{{options|item|icons}} {{options/get|item|small}} <!-- aa bb 
-->{{options/snap|item|save1}}<!--
-->{{options/set|item|icons=xx|small=yy}}<!--
-->{{options|item|icons}} {{options/get|item|small}} <!-- xx yy 
-->{{options/restore|item|save1}}<!--
-->{{options|item|icons}} {{options/get|item|small}} <!-- aa bb -->
</pre>
It will output:
<code>{{unitTest|aa bb xx yy aa bb|{{options/set|item|icons=aa|small=bb}}<!--
-->{{options|item|icons}} {{options/get|item|small}} <!-- aa bb 
-->{{options/snap|item|save1}}<!--
-->{{options/set|item|icons=xx|small=yy}}<!--
-->{{options|item|icons}} {{options/get|item|small}} <!-- xx yy 
-->{{options/restore|item|save1}}<!--
-->{{options|item|icons}} {{options/get|item|small}} <!-- aa bb -->}}</code>

There is a special snapshot created during initialization, it can be restored via <code><nowiki>{{options/reset|<namespace>}}</nowiki></code>

== Subpages ==
<div style="-webkit-column-count:3;column-count:3;">
{{#dpl:
|namespace=Template
|titlematch=Options/%
|notcategorymatch=% translation
|nottitlematch=%/doc%
|ordermethod=title
|columns=3
}}
</div>

<noinclude>
{{category|Template documentation}}
{{language info|en=Template:Options/doc}}
</noinclude>