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
- Let you change an option, such as the accent color on Questions' buttons.
- Show and tidy up things the extension remembered, like bash's allowed commands.
- Paste a key or web address the extension needs, kept encrypted on your computer.
- Offer a Connect button for an outside account, as Atlassian does.
In your manifest
From the bash extension. The panel is one built file.
"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):
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
| Field | What it does |
|---|---|
settings.component | The 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
- One panel per extension, at most.
- You open it from Settings > Extensions, with the Settings button next to Enable. Charlie itself never opens it.
- The panel still opens while the extension is switched off, so you can fix something before switching it back on.
- Saving doesn't close the panel. You can save on every small change.
- Values saved with
onSaveare not encrypted. Put keys and passwords in a secret instead. - A secret can't be read back by the panel, only checked as set or not set. Handlers can read secrets but can't write them.
- Adding a panel to an existing extension needs a Charlie restart, like any manifest change.
See it in
Every field, in full: reference: settings.