optionjs v1.1.2
optionjs
Option manager for javascript components.
Why
Optionjs handles options creation using default values and read/write operations. The most interesting part of using optionjs is the ability to attach handler on an option value change.
Using kind of util inside a component to read/write related options also gives more flexibility to add more options in the future without changing your shipped interfaces.
Installation
Using bower package manager:
bower install https://github.com/gghez/optionjs.git
Using npm package manager for nodejs module:
npm install optionjs
Usage
You can use optionjs as client side javascript resource as well as nodejs module.
Client side (Regular/HTML JS)
Reference optionjs.js script:
<script src="bower_components/optionjs/src/optionjs.js"></script>
Assuming you create a prototype which needs to be configurable using option list. Optionjs replaces option management logical layer. Use optionjs this way:
// onOpt1Change handler
function onOpt1Change(newValue, oldValue) {
console.log('opt1 option value changed from', opt1OldValue, 'to', opt1NewValue);
}
// Constructor
var MyProto = function(options) {
this.options = new OptionsManager(options, {
'opt1': 'opt1 default value',
'opt2': null
});
// An opt1 value change raises onOpt1Change function.
this.options.onChange('opt1', onOpt1Change);
};
// Getter / Setter example
MyProto.prototype.options = function(optKey, optValue) {
if (optValue === undefined) { // Use as getter
return this.options.get(optKey);
} else { // Use as setter
this.options.set(optKey, optValue);
}
}
Server side (NodeJS)
var optionjs = require('optionjs');
var options = optionjs(
{ opt1: 'string1', opt3: 'string3'},
{ opt2: 'default string 2' }
);
console.log(options.get('opt1')); // string 1
console.log(options.get('opt2')); // default string 2
API
###OptionsManager(options, defaults) Constructor creates a new instance of OptionsManager. Example:
var options = OptionsManager(
{opt1: 'string1', opt3: null},
{opt2: 'string2', opt3: 'string3'});
console.log(options.get('opt1')); // string1
console.log(options.get('opt2')); // string2
console.log(options.get('opt3')); // null
Parameter | Description |
---|---|
options | Options object using keys as option names and values as option values. |
defaults | Options object used to complete options on non-existing option name. |
###.get(optKey)
Retrieves an option value given its name (optKey
).
###.set(optKey, optValue)
Defines or overrides existing option given its name (optKey
) and new value (optValue
).
###.onChange(optKey, handler) Attach an event handler called each time option has its value changed.
Parameter | Description |
---|---|
optKey | The option name. |
handler | A user defined function called with respectively new value and old value of option on which it has been attached. |
###.hasChangeHandler(optKey)
Indicates whether option named optKey
has an attached handler spying its value changes.
Returns true
or false
only.
##Development 1. Clone git repository
git clone https://github.com/gghez/optionjs.git
Installation
npm install
Run tests
a. Continuous integration
grunt run
b. One time
grunt test