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:

• A checkbox (boolean)
• A single-line text box (string)
• A file path text box with Choose… button (path)
• A numerically-formatted text box with stepper (number)
• A pop-up button showing choices (enum)
• A multiline text box (text)
• A section that contains multiple items (section)
• A button that can invoke an extension command (command)
• A list of editable string items (stringArray, New in Nova 4.)
• A list of editable paths (pathArray, New in Nova 4.)

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:

• key: The configuration key by which the value is stored and referenced
• type: The type of the item, affecting which user interface controls are used
• required: Whether the item requires a value to validate (default is false)
• title: The user-readable title of the item (this will be automatically localized)
• description: The user-readable descriptive text of the item (this will be automatically localized)
• link: A URL string that will be opened when clicking the item’s help (?) button
• placeholder: Placeholder text displayed within the item’s text field if no value is set
• default: The default value of the item
• children: Child items displayed beneath and indented from the item (section types only)
• max: The maximum value of the item (number types only)
• min: The minimum value of the item (number types only)
• allowsCustom: Whether the item supports custom text values to be entered (enum types only)
• radio: Whether the item should prefer being displayed using radio buttons when possible (enum types only, New in Nova 4.)
• command: A command name registered with the CommandsRegistry to be invoked when clicking the item’s button (command types only)

• values: An array of pre-populated values to display for an item (enum types only). See Enum Values for more information.
• resolve: A command name registered with the CommandsRegistry that will be invoked when the item is shown to resolve the array of pre-populated values (enum types only). See Enum Values for more information.
• allowFiles: Whether the item allows choosing files from open panels (path and pathArray types only, default is true)
• allowFolders: Whether the item allows choosing folders from open panels (path and pathArray types only, default is false)
• relative: Whether the item prefers relative paths when choosing paths from open panels (path and pathArray types only, default is false)
• filetype: An array of strings that denotes the type of files (by extension or Uniform Type Identifier) that are valid for choosing in open panels (path and pathArray types only)

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:

• An array of strings, which act as both the raw value (stored in the configuration) and user-displayed title of the item in the pop-up list.
• An array of two-item arrays (tuples), where the first value is the raw string value (stored in the configuration) and the second value is the user-displayed title for that item in the pop-up list.

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"
            }
        ]
    }
]