Matt Gemmell

TOLL is available now!

An action-thriller novel — book 2 in the KESTREL series.

★★★★★ — Amazon

Custom Prompts for Drafts

development & tech 2 min read

Drafts 21 is out today, and it brings a major new feature for Actions developers: the ability to create custom user interfaces using the HTMLPreview window, which can now execute JavaScript and pass data back out to the calling context or action.

Accordingly, I’ve released MGCheckListPrompt, a custom selection/picker dialog which lets you choose from a list of options — which can be either drafts, or arbitrary choices. There are lots of configurable options and conveniences, including: full keyboard navigation/control (no pointing devices/fingers required); support for Mac, iPad, and iPhone; automatic light/dark theme support; customisable appearance via CSS; optional type-to-select mode; and more. Both multiple-selection (checkboxes) and single-selection (radio-buttons) modes are supported.

It’s fully documented, includes various example actions, and works with Drafts 21 or later on iPadOS, iOS, and macOS.

It should also serve as a useful example of what you can do with the new HTMLPreview functionality in Drafts 21.

Here are some details about MGCheckListPrompt. This is a screenshot of it on the iPad, in the light theme.

MGCheckListPrompt on iPad

Each choice (which can be a draft object, or a dictionary for an arbitrary option) supports a flagged status just like in Drafts itself.

Flagged status

The entire thing is keyboard-navigable, with no requirement to use a pointing device (but you can if you want to, of course). I find it really quick and easy to use. You can see the keyboard focus in the screenshot below.

Keyboard focus

Light and dark themes are supported automatically, and they’ll follow Drafts itself rather than the system (because you might have set Drafts to display in a specific theme mode).

Dark mode

There’s a help overlay to remind you of the keyboard shortcuts currently available. They vary depending on whether you’ve chosen to enable type-to-select or not.

Help

This is the type-to-select option, which updates live as you type. It’s off by default. When it’s enabled, you can also switch off the visual highlighting of the typed query, if you prefer.

Type to select

Another optional feature (off by default) is the live selection counter, to track how many items in the list are currently checked.

Selection counter

If you prefer circular checkboxes (checkdiscs?) for some reason, you can opt into those.

Rounded checkboxes

As long as the optional “type to select” mode is off, you can use the number keys 1-0 to directly select items 1-10 respectively. You can also choose to show those numeric shortcut keys within the corresponding checkboxes when they’re unchecked, as a visual reminder.

Numeric shortcuts

Here’s the single-selection mode, with radio-buttons instead of checkboxes, and various options to customise its behaviour.

Single-selection mode

And for those who aren’t satisfied with the clean default appearance, the API supports injecting your own CSS both globally and on a per-choice basis. You can even inject JavaScript to customise the prompt’s functionality, if you want to do that.

Custom CSS

I hope you’ll find this reusable custom prompt useful in your own Actions and workflows. Remember that you’ll need Drafts 21 or later to use it. Thanks for reading.