Tutorial: a dictionary tool
Build a real plugin step by step: a panel, the internet, errors, a saved history, a keyword and a setting.
In this tutorial you build Dictionary, a plugin that looks up what an English word means. It is a real tool, and each step adds one idea:
- Draw a panel
- Remember what the user typed
- Ask the internet
- Say what went wrong
- Keep the panel moving
- Save a history
- Open it from anywhere
- Share it
Each step shows the whole main.py as it is at the end of that step, so you
can copy it and run it. Every version on this page was run before it was
published. If you only want the finished plugin, skip to
step 7.
You should know a little Python: functions, if, for, lists and dicts. You
do not need anything installed. If you have not made a plugin before, read the
Quickstart first. It takes five minutes.
Before you start
Section titled “Before you start”-
Open the plugin editor: in the browser at /addons/new, or on the phone at WM Keyboard Tools Plugins Write a plugin.
-
Choose A blank plugin. Name it
Dictionaryand press Create. -
Open the menu (⋮) and choose Name and permissions. Turn on Use API 5 (the wm package). Press Save.
-
Delete the starter code.
Step 1: Draw a panel
Section titled “Step 1: Draw a panel”Start with what the user sees: a box to type a word in, and a button.
from wm import ui
def render(): with ui.column(): ui.input(label="Word") ui.button("Look up", primary=True)Check it. The preview shows a box labelled Word and a Look up button. The button does nothing yet.
with ui.column(): opens a column. Everything you create inside the with
block goes into it, from top to bottom. You can also nest blocks: a
with ui.row(): inside the column puts things side by side.
Step 2: Remember what the user typed
Section titled “Step 2: Remember what the user typed”A panel needs to remember things between presses: here, the word in the box.
That is what plugin.state is for.
from wm import plugin, ui
state = plugin.state(word="", asked="")
def set_word(text): state.word = text
def look_up(word=None): state.asked = (word or state.word).strip()
def render(): with ui.column(): with ui.row(weights=[3, 1]): ui.input(label="Word", value=state.word, on_change=set_word, on_submit=look_up) ui.button("Look up", on_click=look_up, primary=True) if state.asked: ui.label("You asked for: " + state.asked)Check it. Type rain in the box and press Look up. The panel says
You asked for: rain. Pressing Enter on the keyboard does the same.
What is new:
plugin.state(word="", asked="")makes an object with two values. Read and change them asstate.wordandstate.asked.on_change=set_wordcallsset_wordwith the text each time the user types.value=state.wordkeeps the box showing it when the panel draws again.on_submit=look_upcallslook_upwith the text when the user presses Enter.on_click=look_upcalls it with nothing when the user presses the button. That is whylook_uptakesword=None.with ui.row(weights=[3, 1])puts the box and the button on one line. The box takes three parts of the width and the button one.- After every callback the keyboard calls
render()again, so the new label appears on its own.
Step 3: Ask the internet
Section titled “Step 3: Ask the internet”Now look the word up. The free Free Dictionary API
answers https://api.dictionaryapi.dev/api/v2/entries/en/rain with a list of
meanings in JSON.
A plugin can reach the internet only after two things:
-
Open Name and permissions. Turn on Connect to the internet, to the websites it lists.
-
In Websites it may connect to, type
api.dictionaryapi.dev. Press Save.
Then change the code:
from wm import plugin, ui, http
API = "https://api.dictionaryapi.dev/api/v2/entries/en/"
state = plugin.state(word="", meanings=[], error="")
def set_word(text): state.word = text
def look_up(word=None): word = (word or state.word).strip().lower() if not word: return state.word = word state.error = "" state.meanings = [] r = http.get(API + word) if r.status_code == 404: state.error = "No meanings found for " + word + "." return r.raise_for_status() entry = r.json()[0] for m in entry["meanings"]: state.meanings.append({ "part": m["partOfSpeech"], "text": m["definitions"][0]["definition"], })
def render(): with ui.column(): with ui.row(weights=[3, 1]): ui.input(label="Word", value=state.word, on_change=set_word, on_submit=look_up) ui.button("Look up", on_click=look_up, primary=True) if state.error: ui.label(state.error, color="danger") for m in state.meanings: with ui.card(title=m["part"]): ui.output(m["text"])Check it. Type keyboard and press Look up. Two cards appear: a
noun and a verb, each with what it means.
What is new:
from wm import ... http. Thehttpmodule works like therequestslibrary.http.get(url)sends the request, waits, and gives back aResponse.r.status_codeis the HTTP status. This API answers 404 for a word it does not know, so the plugin says so.r.raise_for_status()raiseshttp.HTTPErrorfor any other 400 or 500 status.r.json()reads the body as JSON.ui.card(title=...)draws a card.ui.output(text)draws text with Insert and Copy buttons under it, so the user can put a meaning into what they are writing. That needs no permission, because the user presses the button.
Step 4: Say what went wrong
Section titled “Step 4: Say what went wrong”The internet fails. The phone is offline, the server is slow, or the user has not allowed the internet yet. A plugin that crashes on these leaves an empty panel. Catch the errors and say what happened.
from wm import plugin, ui, http
API = "https://api.dictionaryapi.dev/api/v2/entries/en/"
state = plugin.state(word="", meanings=[], error="")
def set_word(text): state.word = text
def look_up(word=None): word = (word or state.word).strip().lower() if not word: return state.word = word state.error = "" state.meanings = [] try: r = http.get(API + word) if r.status_code == 404: state.error = "No meanings found for " + word + "." return r.raise_for_status() except PermissionError: state.error = "Allow internet access to look words up." return except (ConnectionError, TimeoutError, http.HTTPError) as e: state.error = "Could not reach the dictionary: " + str(e) return entry = r.json()[0] for m in entry["meanings"]: state.meanings.append({ "part": m["partOfSpeech"], "text": m["definitions"][0]["definition"], })
def render(): with ui.column(): with ui.row(weights=[3, 1]): ui.input(label="Word", value=state.word, on_change=set_word, on_submit=look_up) ui.button("Look up", on_click=look_up, primary=True) if state.error: ui.label(state.error, color="danger") for m in state.meanings: with ui.card(title=m["part"]): ui.output(m["text"])Check it. In the browser, turn off your Wi-Fi and press Look up. The panel says it could not reach the dictionary, in the theme’s danger colour.
The errors you can expect from http:
| Error | When |
|---|---|
PermissionError | The manifest does not list network, the host is not in hosts, or the user has not allowed the internet. |
ConnectionError | No connection, or the server could not be reached. Data saver also raises this. |
TimeoutError | No answer within 15 seconds. |
http.HTTPError | You called raise_for_status() and the status was 400 or more. |
Step 5: Keep the panel moving
Section titled “Step 5: Keep the panel moving”http.get(url) waits for the answer. While it waits, the panel cannot react.
For a slow server that feels broken. Pass then= and the call returns at once.
Your function gets the answer later, and the panel draws again then.
from wm import plugin, ui, http
API = "https://api.dictionaryapi.dev/api/v2/entries/en/"
state = plugin.state(word="", meanings=[], error="", busy=False)
def set_word(text): state.word = text
def look_up(word=None): word = (word or state.word).strip().lower() if not word: return state.word = word state.error = "" state.meanings = [] state.busy = True http.get(API + word, then=show, on_error=failed)
def show(r): state.busy = False if r.status_code == 404: state.error = "No meanings found for " + state.word + "." return if not r.ok: state.error = "The dictionary answered " + str(r.status_code) + "." return entry = r.json()[0] for m in entry["meanings"]: state.meanings.append({ "part": m["partOfSpeech"], "text": m["definitions"][0]["definition"], })
def failed(error): state.busy = False if isinstance(error, PermissionError): state.error = "Allow internet access to look words up." else: state.error = "Could not reach the dictionary: " + str(error)
def render(): with ui.column(): with ui.row(weights=[3, 1]): ui.input(label="Word", value=state.word, on_change=set_word, on_submit=look_up) ui.button("Look up", on_click=look_up, primary=True) if state.busy: ui.progress() if state.error: ui.label(state.error, color="danger") for m in state.meanings: with ui.card(title=m["part"]): ui.output(m["text"])Check it. Press Look up. A bar shows for a moment, then the meanings appear.
What is new:
http.get(API + word, then=show, on_error=failed)returns at once. When the answer comes, the keyboard callsshow(r)with theResponse. If anything goes wrong, it callsfailed(error)with the exception instead. That includes the keyboard refusing to send the request at all, because the user has not allowed the internet yet or Data saver is on.state.busyisTruewhile the plugin waits, andui.progress()draws a bar that says “working” while it is.showchecksr.okinstead of callingraise_for_status(), because there is notryaround it to catch the error.
Use then= for anything that can take more than a moment: http, ai, and
the phone features.
Step 6: Save a history
Section titled “Step 6: Save a history”The user looks up the same words again. Keep the last eight, and show them as
chips the user can press. A saved value needs the storage permission.
- Open Name and permissions. Turn on Save data on your device. Press Save.
from wm import plugin, ui, http
API = "https://api.dictionaryapi.dev/api/v2/entries/en/"
state = plugin.state(word="", meanings=[], error="", busy=False)saved = plugin.state(recent=[], persist=True)
def set_word(text): state.word = text
def look_up(word=None): word = (word or state.word).strip().lower() if not word: return state.word = word state.error = "" state.meanings = [] state.busy = True http.get(API + word, then=show, on_error=failed)
def show(r): state.busy = False if r.status_code == 404: state.error = "No meanings found for " + state.word + "." return if not r.ok: state.error = "The dictionary answered " + str(r.status_code) + "." return entry = r.json()[0] for m in entry["meanings"]: state.meanings.append({ "part": m["partOfSpeech"], "text": m["definitions"][0]["definition"], }) remember(state.word)
def remember(word): others = [w for w in saved.recent if w != word] saved.recent = [word] + others[:7]
def failed(error): state.busy = False if isinstance(error, PermissionError): state.error = "Allow internet access to look words up." else: state.error = "Could not reach the dictionary: " + str(error)
def render(): with ui.column(): with ui.row(weights=[3, 1]): ui.input(label="Word", value=state.word, on_change=set_word, on_submit=look_up) ui.button("Look up", on_click=look_up, primary=True) if saved.recent: ui.chips(saved.recent, on_change=look_up) if state.busy: ui.progress() if state.error: ui.label(state.error, color="danger") for m in state.meanings: with ui.card(title=m["part"]): ui.output(m["text"])Check it. Look up keyboard and then rain. Two chips appear over the
results. Press one to look that word up again. Run the plugin again: the
chips are still there.
What is new:
saved = plugin.state(recent=[], persist=True)is a second state. Withpersist=True, it is saved on the phone after every event and comes back the next time the panel opens.- The first state is not saved, on purpose. If the panel closed in the middle
of a look-up, a saved
busy=Truewould show a bar forever. ui.chips(saved.recent, on_change=look_up)callslook_upwith the chip’s text.
In the browser, the Storage tab under the code shows what the plugin saved.
Step 7: Open it from anywhere
Section titled “Step 7: Open it from anywhere”A dictionary is most useful while you type. Three things make it quicker to reach:
- A keyword: typing
@define rainoffers a chip on the suggestion strip. Pressing it opens the plugin and looksrainup. - A tile: the plugin joins the toolbox as a tool, with its own icon.
- A header button that clears the history.
And one setting, so the user can hide the example sentences.
The keyword, the tile and the setting are in the manifest. In the browser, open the Details tab under the code, open plugin.json, make it look like this, and press Apply:
{ "format": "wmkeyboard-plugin", "id": "com.example.dictionary", "name": "Dictionary", "pluginVersion": "1.0.0", "description": "Look up what an English word means.", "apiVersion": 5, "permissions": [ "network", "storage" ], "hosts": [ "api.dictionaryapi.dev" ], "tool": { "icon": "dictionary", "tile": true, "keyword": "define", "chip": true }, "settings": [ { "key": "examples", "type": "switch", "label": "Show examples", "default": "true" } ]}The phone editor has Keyword and Put it in the toolbox on install in
Name and permissions. It cannot add settings yet, so leave out the
examples lines below if you build on the phone.
from wm import plugin, ui, http
API = "https://api.dictionaryapi.dev/api/v2/entries/en/"
state = plugin.state(word="", meanings=[], error="", busy=False)saved = plugin.state(recent=[], persist=True)
def set_word(text): state.word = text
def look_up(word=None): word = (word or state.word).strip().lower() if not word: return state.word = word state.error = "" state.meanings = [] state.busy = True http.get(API + word, then=show, on_error=failed)
def show(r): state.busy = False if r.status_code == 404: state.error = "No meanings found for " + state.word + "." return if not r.ok: state.error = "The dictionary answered " + str(r.status_code) + "." return entry = r.json()[0] for m in entry["meanings"]: state.meanings.append({ "part": m["partOfSpeech"], "text": m["definitions"][0]["definition"], "example": m["definitions"][0].get("example", ""), }) remember(state.word)
def remember(word): others = [w for w in saved.recent if w != word] saved.recent = [word] + others[:7]
def failed(error): state.busy = False if isinstance(error, PermissionError): state.error = "Allow internet access to look words up." else: state.error = "Could not reach the dictionary: " + str(error)
@plugin.keyword("define")def from_keyword(text): look_up(text)
@plugin.command("Clear history", icon="history")def clear_history(): saved.recent = []
def render(): with ui.column(): with ui.row(weights=[3, 1]): ui.input(label="Word", value=state.word, on_change=set_word, on_submit=look_up) ui.button("Look up", on_click=look_up, primary=True) if saved.recent: ui.chips(saved.recent, on_change=look_up) if state.busy: ui.progress() if state.error: ui.label(state.error, color="danger") for m in state.meanings: with ui.card(title=m["part"]): ui.output(m["text"]) if m["example"] and plugin.settings.examples: ui.caption("Example: " + m["example"])Check it. The panel’s header now has a Clear history button. In the
Events tab, send a keyword event with the id define and the value
rain: the plugin looks rain up.
What is new:
@plugin.keyword("define")marks the function the keyboard calls with the text after@define. The manifest’stool.keywordnames the same word. The chip appears while Search shortcuts are on.@plugin.command("Clear history", icon="history")adds a button to the panel’s header. Icons are Material Symbols names.plugin.settings.examplesis the user’s value for theexamplessetting. The app draws the settings page from the manifest; your code only reads it."tile": trueputs the plugin in the toolbox as a tool when it is installed, drawn with thedictionarysymbol from"icon". From there it drags onto the toolbar like any tool. Any plugin can also go on a key, through the layout editor’s Open a plugin action.
Step 8: Share it
Section titled “Step 8: Share it”Press Install the plugin (the arrow at the top). The browser saves
Dictionary-1.0.0.wmplugin. Copy it to the phone and open it from a file
manager. The keyboard shows what the plugin asks for and installs it.
Press Install the plugin. The plugin is in the keyboard’s Plugins tool at once. To give it to someone, choose Save as a file in the menu.
After the install, open the plugin’s page and turn on internet access:
WM Keyboard Tools Plugins Manage pluginsA .wmplugin file is a ZIP of plugin.json and main.py. To list it in an
addon repository, see Sharing your plugin.
DirectoryDictionary-1.0.0.wmplugin
- plugin.json
- main.py
What you learned
Section titled “What you learned”render()describes the panel. The keyboard calls it again after every event.plugin.stateholds what the panel remembers;persist=Truesaves it.- Widgets take callbacks:
on_click,on_change,on_submit. httpneedsnetworkand ahostsentry, and its errors are ordinary Python exceptions.then=keeps the panel moving while an answer is on its way.- Decorators tell the keyboard what your plugin offers:
@plugin.keyword,@plugin.command.
