Advanced Action Steps

Table of Contents

  1. Script
  2. Run Shortcut
  3. HTML Preview
  4. Include Action
  5. Prompt
  6. Open URL
  7. Callback URL
  8. Run Drafts 4 Action

Script

Script steps execute Javascript. Scripting is a larger topic, refer to the scripting article for more information on using scripts in Drafts.

Options

  • Script: The script to execute.

Run Shortcut

Run a named shortcut in the Apple Shortcuts app.

If the “Wait for response” option is enabled, Drafts will hold processing of the action waiting on a response from Shortcuts. If the Shortcuts responds using x-success, the action will continue and any response parameters provided by the target app will be available in the context.callbackResponses (docs) object for subsequent script steps in the action. Additionally, a new template tag will be defined for the result parameter included in the callback response, named “shortcut_result”. For example, if the shortcut returned “Hello”, the template tag [[shortcut_result]] would be available for later action steps in the same action, and it would return Hello. If the target app responds with x-cancel callback, the action will be cancelled - x-error will fail the action and log responses.

If “Wait for response” is enabled, Drafts will wait for 120 seconds for a response from the target app, and cancel the remainder of the action if none is received.

Options

  • Shortcut name: Name of a valid Shortcut in the Shortcuts app. Must match exactly.
  • Template: Template for content to send to Shortcuts as an “input” parameter.
  • Wait for response: If enabled, Drafts will wait for a callback response from a target app. See details above.

HTML Preview

Opens an in-app browser displaying the content of an HTML template. Commonly used for Markdown previews, but can display any HTML generated by the template or a script.

Continue-Cancel buttons

Note that the HTML Preview step displays both cancel and continue buttons. If the cancel button is used, the action is cancelled. If continue is used, the action continues. This only has a noticeable if there are additional action steps after the preview, but the buttons do behave differently. Consider an action which displays a preview, and then saves the content to a file if, and only if, the action is continued.

Built-in Templates

There are three options to set a default template on an HTML preview step. Each of these styles (Basic, Swiss, Foghorn) are configured to do Markdown conversion of current draft and display in a basic HTML wrapper suitable for most Markdown preview needs. To select one of the built-in templates, press the Reset button and select a template.

Import, Export and External Templates

Import and export buttons allow templates to be loaded from and saved back to files in the file system. External templates stored in iCloud Drive/Drafts/Library/Templates can also be referenced using the [[template|path]] template tag.

Examples

Options

  • Template: The template should output a complete HTML document for display. Linking to external CSS, etc., is supported.

Include Action

Include the steps defined in another action in the current action as if they were defined there instead. Useful for preventing duplication of re-used scripts and other functionality.

Options

  • Name: Name of another valid action.

Prompt

Display a prompt with buttons and optional a text input field. The results of the prompt are placed in a template tags for use in subsequent action steps. More advanced prompts are possible with the prompt script object as well.

Keys, Tags and Multiple Prompts

Prompts use Drafts tagging system to expose values from the prompt for use in action steps which occur after the prompt in the same action. The tags used are constructed using the “Key” value for the prompt. If using a single prompt in an action, the default “prompt” key is fine and will result in two new tags being available:

  • [[prompt_button]]: will contain the name of the button pressed in the prompt.
  • [[prompt_text]]: will contain the text in the optional text field. If using multiple prompts in the same action, you can distinguish results by the changing the “Key” on the prompt steps. A key of “myselection” will result in tags [[myselection_button]] and [[myselection_text]], etc.

These tags can then be used in subsequent steps. A common application would be to prompt for a filename to use, then use the [[prompt_text]] tag as the filename value in a Dropbox step. The Save to Dropbox as… action in the directory demonstrates this example.

If you wish to use the results of prompt in an script action step, you can retrieve the values using the draft.getTemplateTag('tagName'); function.

Options

  • Key (default: prompt): The key is used to create Drafts tags based on the text input and/or buttons pressed when the prompt is displayed to the user. See discussion below.
  • Title (default: Prompt): A short title of the prompt window.
  • Message (default: blank): A longer text to appear in the prompt and explain the input desired, if necessary.
  • Include text field (default: OFF): If ON, the prompt will include a single line text input field which can be used to take information from the user. Text field default (default: blank): The default text to place in the text field, if included. This field can contain Drafts tags, like [[title]] to set a default value. After the prompt is displayed, the value in the text field will be accessible via the a [[prompt_text]] tag in scripts and templates used in steps after the prompt step.
  • Include cancel button (default: ON): If ON, a “Cancel” button will automatically be included in the prompt. The cancel button will cancel execution of the action and no further steps after the prompt will be run.
  • Buttons (default: OK): A string listing buttons to include in the prompt. Multiple buttons can be listed by using the | character as a separator, for example “Red|Green|Blue” would result in three buttons appearing in the prompt. After the prompt is displayed, the name of the button tapped by the user will be available in the [[prompt_button]] tag in scripts and templates used in steps after the prompt step.

Open URL

Construct and open an URL. Can be used to open web URLs, but also other apps utilizing non-http URL schemes.

Options

  • Template: Template for URL.
  • Encode tags: If enabled, the output of Drafts template tags will automatically be encoded for use in URL query parameters. For example, if the current draft has the text “Hello World” the [[draft]] tag would return “Hello%20World” with this option enabled. If you are using tags previous encoded in prior action steps, this can be diabled.
  • Use Safari: If enabled, Drafts will open the URL in-app using Safari View Controller, rather than passing the URL to iOS to open.

Callback URL

Similar to Open URL, but for use with other apps with support x-callback-url to return to other apps after completing a URL action.

When using this step, create a target URL in the template, but do not include x-callback-url return parameters (x-success, x-error, x-cancel) as Drafts will generate and add those parameters.

If the “Wait for response” option is enabled, Drafts will hold processing of the action waiting on a response from the target app. If the target app responds using x-success, the action will continue and any response parameters provided by the target app will be available in the context.callbackResponses (docs) object for subsequent script steps in the action. Additionally, new template tags will be defined for each parameter included in the callback response, named “callback_parameterName”. For example, if the callback included result=Hello, the template tag [[callback_result]] would be available for later action steps in the same action, and it would return Hello. If the target app responds with x-cancel callback, the action will be cancelled - x-error will fail the action and log responses.

If “Wait for response” is enabled, Drafts will wait for 120 seconds for a response from the target app, and cancel the remainder of the action if none is received.

Options

  • Template: Template for URL.
  • Encode tags: If enabled, the output of Drafts template tags will automatically be encoded for use in URL query parameters. For example, if the current draft has the text “Hello World” the [[draft]] tag would return “Hello%20World” with this option enabled. If you are using tags previous encoded in prior action steps, this can be disabled.
  • Wait for response: If enabled, Drafts will wait for a callback response from a target app. See details above.

Run Drafts 4 Action

Run a named action in the Drafts 4, the previous version of Drafts. This step is a convenience method for cases where a certain action configured in Drafts 4 can not be directly migrated to Drafts 5.

Under the hood this method uses Drafts 5 callback URL support and Drafts 4 URL schemes to open Drafts 4, run the action, and return to Drafts.

Options

  • Action name: Name of a valid action in the Drafts 4 app. Must match exactly.
  • Template: Template for content to send to Drafts 4 as an “text” parameter.