MGListPrompt Documentation

MGListPrompt is a custom list picker dialog for Drafts version 21 or later, intended for use by Actions developers. It allows choosing one item from a list; the items may be drafts, or arbitrary objects. Various configuration options are available.

The latest version of this documentation is available here.

Note: This project is now deprecated. Instead, see MGCheckListPrompt, which supports both single-selection and multiple-selection modes, with additional functionality.


Download

Available from the Drafts Actions repository.

Appearance

Screenshots of MGListPrompt in use are shown below.

MGListPrompt on iPad, light mode.
MGListPrompt on iPad, light mode.
MGListPrompt on iPhone, dark mode.
MGListPrompt on iPhone, dark mode.

Background

Drafts 21 introduced the ability to execute JavaScript within the built-in HTMLPreview window, and to return values from that window to the calling context. This makes it possible to construct custom user interfaces using HTML, CSS, and JavaScript, and to use them within Action scripts. MGListPrompt is such a construct.

Author

MGListPrompt was created by Matt Gemmell.

Please send any feedback via email, instead of social media.

Supported Platforms

All current Drafts platforms are supported: iPadOS, iOS, and macOS.

Functionality

Note: On macOS only, keyboard control of the prompt may first require focusing its content area. Depending on your “Use keyboard navigation to move focus between controls” setting (in System Preferences ► Keyboard ► Shortcuts), this can be accomplished by pressing either Tab or Option-Tab until the keyboard focus moves into the prompt’s content. This is not necessary on iPadOS or iOS.

How to Use

  1. Ensure that you’ve installed the MGListPrompt Library action (part of the MGListPrompt Action Group), and that you have Drafts 21 or later.

  2. Within your own action, add an Include Action step, and set the name value to “MGListPrompt Library”.

  3. You can now use MGListPrompt in your own subsequent script steps.

Example JavaScript

Some example Actions are included with the MGListPrompt Action Group. The following code is a trivial example of MGListPrompt’s use.

// Get most recently modified drafts in the Inbox.
var drafts = Draft.query("", "inbox", [], [], 
									"modified", true, false)
									.slice(0, 5);

// Create an MGListPrompt to choose between the drafts.
var prompt = new MGListPrompt();
prompt.message = "Pick one of these drafts:";
prompt.addDrafts(drafts);

// Show the prompt.
var selectedIndex = prompt.show();

// Report the result.
if (prompt.didShow) {
	if (selectedIndex != -1) {
		app.displaySuccessMessage("Item " + (selectedIndex + 1) 
											+ " was chosen: " 
											+ prompt.choices[selectedIndex].title);
	} else {
		app.displayInfoMessage("Prompt was cancelled.");
	}
} else {
	app.displayErrorMessage("Something went wrong.");
}

API

The following properties and methods are available on an MGListPrompt object.

Properties

.title

String. The title of the prompt, as shown in its titlebar.

Note: The titlebar is not shown by default. It can be shown via .showWindowControls if required.

To provide instructional text to the user at the top of the prompt, see the .message property below.

Default value: "Select"

.message

String. A brief explanatory message shown at the top of the prompt. If the value is an empty string, the message area will not be shown.

Default value: "Select an option:"

.selectButtonTitle

String. The title of the Select button, which confirms the chosen option and dismisses the dialog. If the value is an empty string, “Select” will be used.

Default value: "Select"

.choices

Array of dictionaries. The choices (list items to choose from) shown in the prompt. It’s best to use this property only as a getter; to add choices either individually or in bulk, use the various add… methods detailed below instead. See the addItem(dict) method for details of the dictionary keys.

Note: If there are fewer than two choices, the dialog will not actually be shown when show() is called. This situation can be detected by checking the value of .didShow afterwards.

Default value: []

.selectedIndex

Integer. The (zero-based) index of the item that was chosen in the prompt. If no item was chosen (i.e. the prompt was cancelled, or was never shown), this will be -1.

Default value: -1

.didShow

Boolean. After the show() method has been called, this indicates whether the prompt did indeed show or not (regardless of whether an item was chosen, or the prompt was subsequently cancelled).

In particular, .didShow will be false if there were too few items (i.e. fewer than two) to make the prompt meaningful; it will not be shown in this situation.

Default value: false

.selectsImmediately

Boolean. Determines the interaction mode of the prompt, as follows.

Default value: false

.escapeHTML

Boolean. Determines whether HTML tags and entities within the prompt’s choices will be escaped (i.e. converted to plain text) before being displayed. Enabled by default.

For example, when enabled, the HTML tag <strong> will be displayed as plain text in the prompt. When disabled, the tag will be “injected” into the prompt as HTML, and will thus affect subsequent content, perhaps with unintended consequences.

Note: If enabled, this takes effect before .processMarkdown.

Default value: true

.processMarkdown

Boolean. Determines whether Markdown within the prompt’s choices will be converted to HTML before being displayed. Disabled by default.

For example, when enabled, the string _hello_ will be converted to the HTML <em>hello</em> before being added to the prompt.

Note: If enabled, this takes effect after .escapeHTML.

Default value: false

.allowsDoubleClickToSelect

Boolean. Determines whether choices can be double-clicked (or double-tapped) to immediately select them — i.e. to choose them and confirm the choice all in one action, immediately dismissing the prompt. Enabled by default.

This has no effect if .selectsImmediately is enabled.

Default value: true

.allowsTypeToSelect

Boolean. Determines whether the user can type to select choices, using partial matching of their titles. If enabled, this will disable the ability to use the number keys to directly select the first ten choices.

Default value: false

.includedDraft

String. The title (or portion of the title) of a draft to include inline within the prompt. This works as follows.

A suggested use of this functionality is to override the prompt’s CSS to create custom appearances, without needing to edit the MGListPrompt Library action itself.

Default value: ""

.includedContent

String. Similar to .includedDraft, this is optional content to include inline within the prompt’s HTML. See the .includedDraft property for details on where the content will be inserted.

The two properties can be used together, in which case .includedDraft precedes .includedContent.

An example of using this feature to override the prompt’s CSS (making the light-theme highlight colour be purple instead of blue) is shown below.

prompt.includedContent = `
<style>
:root {
	--highlight-color-light: #90f;
}
</style>
`

Default value: ""

.showWindowControls

Boolean. Determines whether the usual HTMLPreview window controls will be shown. Disabled by default. Re-enabling the window controls (for example, the Share button which will export the prompt’s HTML) can be useful for debugging.

Default value: false

Methods

addDraft(draft)

Parameters: draft (Draft object)

Adds a Draft object to the prompt’s choices by extracting the following information to create an item dictionary (see the addItem(dict) method below).

Return value: None

addDrafts(draftsArray)

Parameters: draftsArray (Array of Draft objects)

Adds an array of Draft objects to the prompt’s choices. See the addDraft(draft) method for more information.

Return value: None

addItem(dict)

Parameters: dict (Dictionary)

Adds an item dictionary to the prompt’s choices. The available keys are as follows.

Return value: None

addItems(dictsArray)

Parameters: dictsArray (Array of Dictionaries)

Adds an array of item dictionaries to the prompt’s choices. See the addItem(dict) method for dictionary keys.

Return value: None

escapeHTMLString(html)

Parameters: html (String)

Convenience method to escape the given string’s HTML tags and entities, causing them to be shown as plain text.

Return value: String

loadDraftWithTitle(draftTitle)

Parameters: draftTitle (String)

Convenience method to load the body (without title line) of the first draft whose title contains the given string. This method is primarily for private use. If successful, the return value is the body content of the relevant draft. If unsuccessful, an empty string is returned.

Return value: String

show()

Parameters: None

Shows the prompt, if at least two choices are available, and returns the index of the selected choice (if any). If the prompt is not shown due to insufficient choices, .didShow will be false. If the prompt is shown but is cancelled by the user, the return value will be -1.

Return value: .selectedIndex (Integer)