Preferences

Extensions can get and set configuration items stored either globally, or specific to a workspace. Simply using this feature to store and retrieve values only requires the use of the Configuration JavaScript API.

Configuration stored for a workspace is written into a .nova folder within the workspace root. This folder may be checked into source control by the user to share configuration between their multiple devices, or between other users working on the project. Configuration is stored using a simple JSON format.

In addition to getting and setting values through the JavaScript API, an extension may define specific configuration items that appear in the global preferences and project settings user interface, and allow the user to set values without directly editing the configuration files.

Defining Configuration Items for UI

Configuration items can be specified that appear in the preferences or project settings. These can appear visually in several ways, depending on needs:

To define configuration items, the extension’s extension.json file should contain a config and / or configWorkspace key, for global or workspace configuration, respectively. Both of these keys take an array of objects in the same format.

As a convenience, these keys may also take a string representing a relative path to a JSON file within the extension’s package that defines the configuration objects, so the extension.json file need not contain the possibly verbose configuration definitions.

An extension does not need to define all possible configuration options it might utilize, only those it wishes to be visually displayed to the user.

Configuration Item Options

Configuration items support the following options:

Enum Values

Enum items specify their array of pre-populated values using the values option. For enum items that allow custom choices (using allowsCustom) this pre-populates the drop-down menu and autocomplete within the field.

The value of the values option should consist of either:

For certain enum configuration item it may be necessary to present options to the user that are not known until runtime. To achieve this, enum items support a resolve option in place of the values option which is the name of a command registered with the CommandsRegistry.

When the item is displayed to the user, this command will automatically be invoked to resolve valid values to pre-populate. The command handler should resolve to the same array format as enum values take using the values option. The item will also display a “reload” button to re-request these values at any time.

By default, if an enum configuration item contains three or fewer choices (and does not use the resolve or allowCustom properties) it will be displayed using radio buttons instead of a pop-up button for better user interaction. If an item wishes to control whether radio buttons are used it can set the radio property to a boolean value.

Example Configuration

An example of configuration items are formatted like so:

"config": [
    {
        "key": "myextension.ignore-selection",
        "title": "Ignore Selection",
        "description": "Whether to always ignore selected text.",
        "type": "boolean",
        "default": false
    },
    {
        "key": "myextension.description",
        "title": "Description",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce diam urna, sagittis et imperdiet a, molestie hendrerit lectus. Duis accumsan viverra lectus et vulputate. Nullam at mi ac ipsum luctus dapibus quis eget ante.",
            "type": "text"
        },
        {
            "title": "Autoconfigure",
            "type": "command",
            "command": "myextension.autoconfigure"
        },
    {
        "title": "File Options",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec eu fermentum nibh.",
        "type": "section",
        "link": "https://library.panic.com/options",
        "children": [
            {
                "key": "myextension.temp-filename-format",
                "title": "Temporary Filename Format",
                "type": "string",
                "placeholder": "foobar.ext.tmp"
            },
            {
                "key": "myextension.count",
                "title": "Count",
                "type": "number",
                "description": "Donec interdum ligula non ipsum consectetur blandit. Nam eget pharetra est.",
                "min": 0,
                "max": 100
            },
            {
                "key": "myextension.file-type",
                "title": "File Type",
                "type": "enum",
                "values": ["text", "photo", "video"],
                "default": "text"
            }
        ]
    }
]