====== modopts.js ======

If you are a Synchronet JavaScript module author or modder and you want to easily add some sysop-configurable options to your module, this is where the Module Options (''[[http://cvs.synchro.net/cgi-bin/viewcvs.cgi/exec/load/modopts.js|modopts.js]]'') library comes to "save the day".

===== Usage =====

==== modopts.ini ====

  - Add a new section to your ''[[dir:ctrl]]/[[config:modopts.ini]]'' file with the name of your module (without the ''.js'' file suffix) as the section name enclosed in square-brackets (''['' and '']'').
  - Choose some key names for the options you need in your script. Use legal JavaScript variable names.

For example:
<file ini>
[yourmodule]
good_thing = true
bad_thing = false
other_thing = some text
</file>

==== yourmodule.js ==== 

You need to execute (via ''load()'') the ''modopts.js'' library, passing an empty //scope// object and passing the name of your module as an argument (without the ''.js'' file suffix), and save the returned object.

Example:

<code javascript>
var options = load({}, "modopts.js", "yourmodule");
</code>

Now if there is any problem reading the ''[yourmodule]'' section from the ''modopts.ini'' file, ''load()'' may return ''null'' or ''undefined''. Referencing ''options.anything'' in your module may result in a JavaScript exception: ''options is null''. To handle this case, assign ''options'' to an empty object:

<code javascript>
var options = load({}, "modopts.js", "yourmodule");
if(!options)
    options = {};
</code>

Now you can safely reference ''options.anything'' and while that may result in an undefined value and exception, depending on use, you won't get an exception because ''options'' itself was undefined. So you can then use ''options.anything'' in your module script:

<code javascript>
if(options.good_thing == true)
   do_good_thing();
if(options.bad_thing == true)
   do_bad_thing();
print(options.other_thing);
</code>

=== Default option values ===

If you want to assign default option values, you can assign them right after you ''load({}, "modopts.js", ...)'', like so:

<code javascript>
var options = load({}, "modopts.js", "yourmodule");
if(!options)
    options = {};
if(options.good_thing === undefined)
   options.good_thing = true;
if(options.bad_thing === undefined)
   options.bad_thing = false;
if(options.other_thing === undefined)
   options.other_thing = "some text";
</code>

Or with string values, you can easily specify defaults //in-line// using the ''||'' operator:

<code javascript>
print(options.other_thing || "some text");
</code>

=== Options Types ===

When using ''modopts.js'' to read an entire section from the ''modopts.ini'' file, the supported key values/property types are:

   * //Number//: any value that is a valid decimal or floating point number or a valid hexadecimal number beginning with ''0x''
   * //Boolean//: a value that is either ''true'' or ''false'' (case-insensitive)
   * //String//: every other value

If you would like to use a different or more precise value/property type for an option, you can do so by using ''modopts.js'' to load one specific option from one specific ''modopts.ini'' section and specify a default value/type.

For example, to load a //Date// option value:

<code javascript>
var date_option = load({}, "modopts.js", "yourmodule", "date", new Date());
</code>

For example, to load a //String// option (even when it's a valid //Number// or //Boolean// value):

<code javascript>
var str_option = load({}, "modopts.js", "yourmodule", "str", "");
</code>

When using ''modopts.js'' to read a single option value from the ''modopts.ini'' file and providing a default option value/type, the supported key values/property types are :

  * Number
  * Boolean
  * String
  * Date
  * Array (comma-separated list of string values)


===== See Also =====
  * [[:custom:javascript:lib:|JavaScript Libraries]]
  * [[:config:ini_files|.ini files]]
  * [[:module:|Modules]]

{{tag>javascript modopts}}