app.settings - Plugin Settings API

Persistent storage for plugin configuration. Each plugin has its own independent settings.json file.

Methods

app.settings.get(key, default?)

Gets a setting value.

Parameters:

• key (string) - Setting key name
• default (any, optional) - Default value

Returns: The stored value or the default value

local quality = app.settings.get("quality", 90)
local format = app.settings.get("format", "PNG")
local enabled = app.settings.get("autoBackup", true)

app.settings.set(key, value)

Saves a setting value.

Parameters:

• key (string) - Setting key name
• value (any) - Value to save (supports string, number, boolean, table)

Returns: boolean, error - Whether successful; returns false, error on failure

app.settings.set("quality", 90)
app.settings.set("format", "PNG")
app.settings.set("autoBackup", true)
app.settings.set("recentPaths", {"/Users/test/Desktop", "/Users/test/Downloads"})

app.settings.remove(key)

Removes a setting entry.

Parameters:

• key (string) - Setting key name

Returns: boolean, error - Whether successful; returns false, error on failure

app.settings.remove("tempData")

app.settings.has(key)

Checks whether a setting entry exists.

Parameters:

• key (string) - Setting key name

Returns: boolean, error - Returns false, error on failure

if app.settings.has("apiKey") then
    -- Use the configured API Key
else
    -- Prompt user to configure
end

app.settings.clear()

Clears all settings for the plugin.

Returns: boolean, error - Whether successful; returns false, error on failure

app.settings.clear()

app.settings.getAll()

Gets all settings.

Returns: table, error - All setting key-value pairs; returns nil, error on failure

local all = app.settings.getAll()
if all then
    for key, value in pairs(all) do
        app.log.info(key .. " = " .. tostring(value))
    end
end

Storage Location

Settings are stored in the settings.json file within the plugin directory:

~/Library/Group Containers/group.net.ymlab.iRightMenu.pro/
  └── Plugins/
      └── {plugin_id}/
          └── settings.json

Supported Value Types

Examples

Remember Last Settings

function MyPlugin:showSettingsDialog()
    -- Load previous settings
    local lastSettings = {
        quality = app.settings.get("lastQuality", 90),
        format = app.settings.get("lastFormat", "PNG"),
        outputDir = app.settings.get("lastOutputDir", app.path.desktop())
    }

    -- Show settings dialog
    local result = app.dialog.form({
        title = "Export Settings",
        fields = {
            {type = "number", id = "quality", label = "Quality", default = lastSettings.quality},
            {type = "select", id = "format", label = "Format",
             options = {"PNG", "JPEG", "WebP"}, default = lastSettings.format},
            {type = "text", id = "outputDir", label = "Output Directory", default = lastSettings.outputDir}
        }
    })

    if result then
        -- Save current settings for next use
        app.settings.set("lastQuality", result.quality)
        app.settings.set("lastFormat", result.format)
        app.settings.set("lastOutputDir", result.outputDir)

        return result
    end

    return nil
end

Configure Plugin Behavior with Settings

function MyPlugin:handleCompress(context)
    -- Read user-configured settings
    local quality = app.settings.get("quality", 90)
    local format = app.settings.get("format", "PNG")
    local autoBackup = app.settings.get("autoBackup", true)

    for _, file in ipairs(context.selectedFiles) do
        if autoBackup then
            app.file.copy(file, file .. ".backup")
        end

        self:compressImage(file, {
            quality = quality,
            format = format
        })
    end
end

Store Complex Data

-- Store recently used items
function MyPlugin:addToRecent(path)
    local recent = app.settings.get("recentItems", {})

    -- Remove if already exists
    for i, item in ipairs(recent) do
        if item == path then
            table.remove(recent, i)
            break
        end
    end

    -- Add to the beginning
    table.insert(recent, 1, path)

    -- Keep only the most recent 10
    while #recent > 10 do
        table.remove(recent)
    end

    app.settings.set("recentItems", recent)
end

function MyPlugin:getRecent()
    return app.settings.get("recentItems", {})
end

Reset Settings

function MyPlugin:handleResetSettings(context)
    local confirm = app.dialog.alert({
        title = "Reset Settings",
        message = "Are you sure you want to reset all settings to defaults?",
        buttons = {"Cancel", "Reset"}
    })

    if confirm == "Reset" then
        app.settings.clear()
        app.notification.show("Done", "Settings have been reset")
    end
end