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 (modopts.js) library comes to “save the day”.

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

For example:

[yourmodule]
good_thing = true
bad_thing = false
other_thing = some text

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:

var options = load({}, "modopts.js", "yourmodule");

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:

var options = load({}, "modopts.js", "yourmodule");
if(!options)
    options = {};

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:

if(options.good_thing == true)
   do_good_thing();
if(options.bad_thing == true)
   do_bad_thing();
print(options.other_thing);

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

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";

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

print(options.other_thing || "some text");

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:

var date_option = load({}, "modopts.js", "yourmodule", "date", new Date());

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

var str_option = load({}, "modopts.js", "yourmodule", "str", "");

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)

• JavaScript Libraries
• .ini files
• Modules