MonkeyConfig Home

MonkeyConfig Documentation

Last revised: Jul 23, 2011

Initialization

To add a configuration dialog to your script, create a new instance of the MonkeyConfig class: 

var cfg = new MonkeyConfig({
    title: 'World Domination Script Settings',
    parameters: {
        'sidekick': {
            type: 'select',
            choices: [ 'Darth Maul', 'Chuck Norris', 'Professor Chaos' ]
        }
    },
    menuCommand: true,
    onSave: function (values) {
        alert(values.sidekick + ' is now your sidekick');
    }
});

The available properties are listed below.

Property Description
buttons An array of strings that determines which buttons are displayed in the dialog window. Each string can be one of: "cancel", "defaults", or "save".
default: [ "save", "defaults", "cancel" ]
menuCommand If set to true, then a new option is created in the User Script Commands menu to open the configuration dialog, and the value of the title property is used as a label. If set to a string, the string is used as the label instead of title.
parameters
(or params)		 An object that maps configuration parameter names to their definitions.
title Configuration dialog title.
default: "Configuration"
onSave Callback function called when the "Save" button is clicked.

Parameters

Common options:

default The default value of the field.
html The HTML code to use instead of the default rendering of the field.
If the string "[FIELD]" is present in the code, it will be replaced with the default rendering (useful when you want to wrap the field in an additional HTML element).
label The label for the field.
If not specified, the label is generated from the name of the field, with the first character converted to uppercase and underscores replaced with spaces.
type The type of the field. One of: "text", "number", "select", "checkbox", or "custom".
value The initial value of the field (takes precedence over the default value).

Text

A text field. 

name_prefix: {
    type: 'text',
    'default': 'foo'
}

Field-specific options:

long If set to true, the field is displayed as multi-line (a textarea).
If set to a number, it defines the number of rows in the text field.

Number

A number field. 

maximum_length: {
    type: 'number',
    'default': 42
}

Select

A select field. 

animation_speed: {
    type: 'select',
    choices: [ 'Slow', 'Medium', 'Fast' ],
    'default': 'Fast'
}
animation_speed: {
    type: 'select',
    choices: [ 'Slow', 'Medium', 'Fast' ],
    'default': 'Fast',
    variant: 'radio column'
}

Field-specific options:

choices A list of options to choose from. Either an object that maps option values to their labels, or an array of values (in which case they also serve as labels).
multiple If set to true, multiple choices can be selected.
variant A string that determines how the field is displayed.

For single selection, the following values are recognized:
  • "radio" – a list of radio buttons
  • "radio column" – a list of radio buttons arranged in a column
For multiple selection (multiple set to true):
  • "checkboxes" – a list of checkboxes
  • "checkboxes column" – a list checkboxes arranged in a column
If not specified, a standard HTML <select> element is used (usually a drop-down list for single selection, and a select box for multiple selection).

Checkbox

A checkbox field. 

random_order: {
    type: 'checkbox',
    default: true
}

Custom

A custom field. The HTML code to render this field must be provided with the html option. 

dimensions: {
    type: 'custom',
    html: '<input type="text" style="width: 3em;" /> x ' +
          '<input type="text" style="width: 3em;" />',
    set: function (value, parent) {
        parent.querySelectorAll('input')[0].value = value[0];
        parent.querySelectorAll('input')[1].value = value[1];
    },
    get: function (parent) {
        return [ parent.querySelectorAll('input')[0].value, 
                 parent.querySelectorAll('input')[1].value ];  
    },
    default: [ 100, 50 ]
}

Field-specific options:

get The getter function. It takes one parameter: parent – the DOM element containing the structure defined by html. It must return the current value of the field.
set The setter function. It takes two parameters: value, which is the new value to set, and parent, the DOM element containing the structure defined by html.