Charliehub · by A.N.D.Why

Building block 4 · The basics

Settings

A settings panel is a small screen you open yourself to adjust an extension. You might pick a color, review saved choices, paste a key, or connect an account.

What you'd use it for

In your manifest

From the bash extension. The panel is one built file.

bash / manifest.json
"settings": { "component": "./build/Settings.js" }

The component receives the saved values and a way to save new ones. This is the start of bash's panel (trimmed):

bash / src/Settings.jsx (trimmed)
const { Surface, Field, Text } = CharlieUI

export default function Settings({ values, onSave }) {
  const initial = values && Array.isArray(values.rules)
    ? values.rules : []
  const [rules, setRules] = React.useState(initial)

  const remove = (target) => {
    const next = rules.filter((r) => !(
      r.scope === target.scope &&
      r.pattern === target.pattern))
    setRules(next)
    onSave({ rules: next })
  }
  ...
}

What each part means

FieldWhat it does
settings.componentThe path to the built panel file in your extension folder. Required if you declare settings.
values (prop)What the panel saved last time. An empty object the first time.
onSave (prop)Call it with the new values to save them. It replaces the whole saved object.

What the panel can do

Save ordinary options

Call onSave. Your tool handlers read the result with await ctx.getSettings(). Nothing is passed along automatically: Questions' handler reads the accent and hands it to its own picker.

Save a key or password

Call window.api.extensions.saveSecret(name, key, value). Your handlers read it with ctx.secrets.get(key). The panel can check whether one is set with hasSecret, and remove it with clearSecret. Finder saves your hub's web address this way.

Connect an account

Call window.api.connections.connect(name, connection) to start the sign-in, and status or disconnect to show and undo it. See Connections.

Things to know

See it in

Every field, in full: reference: settings.