Advanced Action Steps
Table of Contents
- Script
- Run Shortcut
- Run AppleScript
- HTML Preview
- Include Action
- Prompt
- Open URL
- Callback URL
- 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.
- Allow asynchronous execution: If disabled (default), when the end of the script is reached, Drafts will continue on to the next step in the action, or end the action. If enabled, Drafts will pause and wait for a call to
script.complete()to occur in your script to indicate completion of the script operation. This allows for JavaScript asynchronous operations like Promises, async/await, etc. to be used. If enabled your script must callscript.complete()somewhere to complete execution, or your action will fail.
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.
- Return to Drafts: If enabled, when the Shortcut is complete, Shortcuts will return to drafts.
- Wait for response: If enabled, Drafts will wait for a callback response from a target app. See details above.
Run AppleScript
Run AppleScript from Drafts. For examples and more details see the the AppleScript article.
Options
- Script: Text of a valid AppleScript. The AppleScript should contain a subroutine named
executewhich takes a singledraftparameter. When the step is run, the AppleScript will be compiled and run, calling theexecutesubroutine, passing a record of values related to the current draft.
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. 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.
Advanced Previews
In addition to presenting basic preview, HTML Previews can be used to build forms and interactive web pages which send data back to the action. For details, see the Advanced HTML Previews article.
Examples
Options
- Template: The template should output a complete HTML document for display. Linking to external CSS, etc., is supported.
- Hide interface: If enabled, the window containing the preview will not have any toolbars or buttons. Use this feature only if you are using scripting to call
Drafts.continue()orDrafts.cancel()from HTML elements in the preview or the preview can not be closed by the user.
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
- Action: Select an action to include. Using the selector is more reliable, as it references an action in your installation by it’s unique identifier – but is not portable to share with other users.
- Template: Template to construct the name of another valid action. This can be the static text name of another action, or tags that are evaluated to dynamically locate an action. Use this template to include actions by name if you are sharing an action which has “Include Action” steps to work across different installation.
Prompt
Display a prompt with buttons and optional a text input field. The results of the prompt are placed in 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 one of the below (utilizing the appropriate tag name for the prompt):
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.