Settings Builders

Settings pages are built dynamically from Python lists. Two examples of where this is done include the global persistent settings for each plugin, as well as the settings for each instance of the plugin. The settings_dict will always follow the same format.

General Structure

The variable is a list of dicts, where each dict represents a new setting. The settings page is built from top to bottom, so if you want one setting above another, put it first in the list.

The entered settings are saved in a dictionary, using a consistent format. For example, plugin instance specific settings are passed to the plugin's run function as settings_dict.

# Example settings builder
{
    "type": "string",
    "value": "Welcome to Ultrasonics. This is a basic sample plugin to help with development of future plugins."
},
{
    "type": "text",
    "label": "Search Term",
    "name": "searchterm",
    "value": "Flume"
},
{
    "type": "radio",
    "label": "Category",
    "name": "category",
    "id": "category",
    "options": [
        "Track",
        "Artist",
        "Album"
    ]
}

# Returned settings_dict
{
    "searchterm": "ODESZA",
    "category": "Artist"
}

Possible Settings

String

Used to display text to the user. Cannot provide input.

{
    "type": "string",
    "value": "Welcome to Ultrasonics. This is a basic sample plugin to help with development of future plugins."
}

Text

Allows the user to input text. No validation is performed on the front-end, and data is returned as a string. "value" is just the textbox placeholder value, not a default value.

{
    "type": "text",
    "label": "Search Term",
    "name": "searchterm",
    "value": "Flume"
}

Radio

A standard HTML radio item. Users can select one (or none) of the "options". Use this for boolean settings, with options "Yes" and "No". Returns the value of the selected option.

{
    "type": "radio",
    "label": "Category",
    "name": "category",
    "id": "category",
    "options": [
        "Track",
        "Artist",
        "Album"
    ]
}

Select

Works like a radio, but with a dropdown menu. Users can select one of the "options". Returns the value of the selected option.

{
    "type": "select",
    "label": "Number of Plays",
    "name": "plays",
    "options": [
        "<1000",
        "1000-10,000",
        "10,000-100,000",
        "100,000+"
    ]
}

Hidden

Create a hidden input, with a pre-specified value. Useful if you want to immortalise some variable at the time of settings creation, such as a unique id. Returns the "value".

{
    "type": "hidden",
    "name": "random_id",
    "value": "some_value"
}

Link

Creates a link that the user is able to click on.

{
    "type": "link",
    "value": "https://spotify.com"
}

Auth

Used for interaction with ultrasonics-api. Specify the route to be called to request authentication. Returns the result of the authentication process, likely a stringified JSON containing auth tokens.

{
    "type": "auth",
    "value": "/spotify/auth/request"
}