Settings

How plugin settings work

A plugin never draws its own settings page. It declares its settings in the manifest, and Athanor draws the form with its own controls: a switch, a number field, a text field or a menu. Every plugin's settings look the same and behave the same.

People change them in the Plugins window: Installed tab › ⋯ on the plugin's row › Settings, which opens the Settings section of the plugin's detail column. Each change saves at once.

A minimal example

manifest.json (the relevant part):

{
  "permissions": ["document.read"],
  "contributes": {
    "checks": [{ "key": "heavy", "title": "Heavy structures", "runOn": "change" }]
  },
  "settings": [
    { "key": "limit", "type": "number", "label": "Flag structures heavier than (g/mol)", "default": 500, "min": 100, "max": 2000 },
    { "key": "severity", "type": "select", "label": "Show them as", "options": ["note", "warning"], "default": "note" }
  ]
}

main.js:

let settings = { limit: 500, severity: 'note' };
async function load() { settings = { ...settings, ...(await athanor.settings.get()) }; }
void load();
athanor.on('settingschange', () => { void load(); });
 
athanor.checks.on('heavy', (page) => page.structures
  .filter((s) => (s.mw ?? 0) > settings.limit)
  .map((s) => ({ atom: s.atoms[0].id, severity: settings.severity, title: 'Heavy structure',
    message: `${s.formula} weighs ${s.mw} g/mol, over ${settings.limit}.` })));

athanor.settings.get() resolves with an object of every declared key: the value the person set, or the default. A key with no saved value and no default is left out. It needs no permission.

athanor.on('settingschange', fn) calls fn (with no argument) when the person changes a value while the plugin is running. Read the values again with get().

Field types

Every field also needs key (up to 40 characters) and label (up to 80 characters, shown beside the control).

Rules and limits

• Up to 30 settings per plugin.
• A select needs one to 20 options, each up to 60 characters. A default that is not one of the options is ignored.
• A field with an unknown type, or without key or label, makes the manifest invalid.
• Only declared keys of the declared type are ever stored. A saved value that no longer fits its field (after an update changed the field) falls back to the default.
• Values are kept on the device and, when the person is signed in, on their arbastro account, so they follow the person to other devices.
• Settings hold preferences, not data. Keep them small.