Skip to content
WM KeyboardWM Keyboard
Accessibility

Saving data and settings

Keep data between sessions with storage, give your plugin a settings page, and set reminders.

A plugin starts fresh each time its panel opens. To keep anything longer, save it. This page covers the three ways to keep things on the phone, plus a settings page the app draws for you.

Use it forNeeds
plugin.state(..., persist=True)the values your panel works withstorage
storageanything else, by keystorage
secretsAPI keys and tokensstorage

All three stay on the phone, belong to your plugin only, and are deleted when the user uninstalls it. An update leaves them alone.

The easiest way. Values in a saved state come back the next time the panel opens:

from wm import plugin
saved = plugin.state(notes=[], sort="newest", persist=True)

Change saved.notes like any value, and it is saved after the event. State and events has the details.

storage works like a dict whose values are kept on the phone:

from wm import storage
storage["notes"] = ["milk", "eggs"]
notes = storage.get("notes", [])
if "draft" in storage:
del storage["draft"]
for key in storage:
print(key, storage[key])

It has the dict methods you expect: get, setdefault, pop, update, keys, values, items, clear and len(storage). Values are anything JSON holds.

Limit
Keys512
One value64 KB
Everything1 MB

storage.used() gives the bytes in use and storage.quota the most you may use. A write that goes over raises ValueError. Catch it and tell the user, so they do not lose what they typed:

try:
storage["notes"] = notes
except ValueError:
ui.toast("Storage is full. Delete some notes first.")

The user can see and clear your plugin’s storage on its page:

WM Keyboard  Tools  Plugins  Manage plugins

In the web editor, the Storage tab shows the same, and you can edit values there while you test.

For keys and tokens: secrets.get(name, default), secrets.set(name, value) and secrets.remove(name). Values are text, kept apart from storage in the keyboard’s private files, where other apps cannot read them. They never appear in a backup or the storage inspector, and uninstalling the plugin deletes them. They are not encrypted on the phone. See API keys.

List settings in the manifest and the app draws them on your plugin’s page. You never draw a settings screen yourself:

plugin.json (excerpt)
"settings": [
{"key": "units", "type": "choice", "label": "Units", "default": "metric",
"options": ["metric", "imperial"]},
{"key": "examples", "type": "switch", "label": "Show examples", "default": "true"},
{"key": "count", "type": "number", "label": "How many results", "default": "5"},
{"key": "greeting", "type": "text", "label": "Greeting", "summary": "Said when the panel opens"},
{"key": "server", "type": "host", "label": "Your server"},
{"key": "token", "type": "secret", "label": "API token"}
]
Field
keyThe name you read it by: lowercase letters, digits and _, starting with a letter or _, up to 32 characters.
typeswitch, text, number, choice, host or secret.
labelThe row’s title.
summaryOne line under the title. Optional.
defaultThe starting value, always written as text: "true", "5", "metric". A secret has none.
optionsFor choice: the values to pick from.

Up to 24 settings. A host setting adds the website the user types to your hosts; see the user’s own server.

A secret setting is for an API key or token. The page shows only whether one is saved, never the key itself, and the box the user types it into hides what they type. The value is kept in your plugin’s secrets under the setting’s key, so plugin.settings.token and secrets.get("token") read the same thing, and secrets.set("token", ...) from your panel changes what the page shows. It needs the storage permission. While no key is saved it reads as None.

Read the values in code as attributes. A switch reads as True or False and a number as a number:

from wm import plugin
if plugin.settings.examples:
...
limit = plugin.settings.get("count", 5)

Reading a key the manifest does not declare raises AttributeError; plugin.settings.get(key, default) does not.

Your plugin can change its own settings too, for a “Remember this” button or a choice made in the panel:

plugin.settings.set("units", "imperial")
plugin.settings.reset("units") # back to the manifest's default

The value has to fit the row: True or False for a switch, a number for a number, one of the options for a choice, and text for text and secret. Anything else raises ValueError. The change is saved at once and the settings page shows it. Resetting a secret forgets the key.

A host setting is the one your plugin cannot write. Setting it raises PermissionError: the server a plugin may reach is the user’s to type, and a plugin that could write it would widen its own access to the internet. @plugin.setting_changed hooks do not run for your own changes.

To react when the user changes a setting while the panel is open:

@plugin.setting_changed("units")
def units_changed(value):
look_up()

When the panel cannot work until a setting is filled in, such as the address of the user’s server, send them to the page with a button. plugin.open_settings() opens your plugin’s page in Settings. It works only in answer to something the user did in the panel, such as a tap, so a plugin cannot pull the user out of what they were typing:

def render():
if not plugin.settings.server:
ui.empty("Type your server's address first.", icon="dns",
action="Open settings", on_click=plugin.open_settings)
return
...

The web editor uses each setting’s default while you test. Settings can be translated like the rest of your plugin.

A reminder is a notification at a time you choose. The app shows it, even after the keyboard closes. Your code does not run when it fires. It needs the reminders permission:

import time
from wm import reminders
reminders.set("tea", time.time() + 4 * 60, "Tea is ready")
reminders.cancel("tea")
reminders.list()

The notification is titled with your plugin’s name. Up to 64 at a time, 200 characters of text each, up to ten years ahead. Setting the same id again moves that reminder.