Options

Scripts are supposed to be pretty simple, but sometimes you want the user to configure them, for example to turn on/off specific abilities of the script instead of just enabling/disabling it entirely.

You can do this using the options API, which allows you to add arbitrary entries into the script menu.

Note

The options API goes hand in hand with the event bus API, so make sure to give that a read before attempting options.

Each option has common properties, like a type, id and an optional label, which defaults to the ID.

const option /*: Option */ = {
    type: "...", // one of "button", "checkbox", "radio" or "group"; check the OptionType type
    id: "my-script-option",
    label: "My amazing option", // optional
    // type-specific properties, ...
};

export default {
    // ...
    options: [option],
    load(context /*: ScriptContext */) {
        // this is where the event bus comes in
        context.addEventListener("option_change", (e /*: OptionChangeEvent */) => {
            console.log("An option has been changed: ", e.option.id);
            console.log("Is it our option?", e.option === option);
        });
    },
    unload() {},
};

Buttons

The most ubiquitous of them all, the button. It does exactly what one would expect it to do - an action is triggered when you press it.

const button /*: ButtonOption */ = {
    type: "button",
    id: "my-script-button",
    label: "My amazing button",
};

// ...

Checkboxes

An obvious solution for boolean configuration options, a checkbox!

Checkbox checked state is not persisted by slicer and will be RESET on refresh.

const checkbox /*: CheckboxOption */ = {
    type: "checkbox",
    id: "my-script-checkbox",
    label: "My amazing checkbox",
    checked: false, // not checked by default
};

// ...

Radio buttons

For whenever you need to represent an enum-like value, there’s always a radio button.

Radio button selection is not persisted by slicer and will be RESET on refresh.

const radio /*: RadioOption */ = {
    type: "radio",
    id: "my-script-radio",
    label: "My amazing radio button",
    items: [
        {
            id: "apple",
            label: "Apples", // optional, defaults to the ID
        },
        {
            id: "orange",
            label: "Oranges",
        },
    ],
    selected: "apple", // a selected item ID, apples are default!!
};

// ...

Groups

Last but not least, there’s the group option for cases where you need to group related options together into one slick menu.

const group /*: GroupOption */ = {
    type: "group",
    id: "my-script-group",
    label: "My amazing group",
    options: [
        // options declared like normal
        {
            type: "button",
            id: "my-script-button",
            label: "My amazing button",
        },
        {
            type: "checkbox",
            id: "my-script-checkbox",
            label: "My amazing checkbox",
            checked: false,
        },
    ],
};

// ...