Building Workflows

../_images/workflows.png

Workflows allow you to extend Editorial with your own commands. Each workflow is a sequence of simple steps (“actions”) that are executed sequentially. There are lots of different actions that do all kinds of things – converting Markdown to HTML, searching for regular expressions, showing dialogs and email sheets, playing sound effects, setting the clipboard contents, and much more.

A couple of workflows are bundled with the app – looking at how they were built is one of the best ways to get started with learning how to make your own. If you’re new to this, try changing some simple things in an existing workflow at first – once you’re comfortable with that, you can easily build your own workflows from scratch.

Tap on the info button next to a workflow in the list to see details and start editing. You can also tap on the Edit button to rearrange the list, or to delete workflows. If you accidentally deleted a bundled workflow, you can get it back by selecting “Restore Default Workflows & Snippets” in the settings.

You don’t need to know how to write code for building workflows, but if you do, you can create custom actions and script actions with Python that make your toolbox even more powerful.

Getting Started – Workflow Actions

To create a new workflow, open the workflow list from the editor (wrench icon), and tap the + button. If you want to edit an existing workflow or see how it was built, you can tap the info button next to it and select “Edit Workflow”.

You’ll be presented with an empty canvas for your actions. Tap the + button at the top to add an action from the library.

Tapping on the title of an action allows you to configure its parameters. The parameters of an action are used to customize its behavior, for example, set the title of an alert, text that should be inserted in the editor, and so forth. Each type of action has a different set of parameters that is explained in detail in the action reference. You can also get to the documentation of a specific action directly from the workflow editor: Either tap one of the (?) buttons in the library (while adding an action), or use the Help button in an action’s options menu (on the iPad, tap the (▼) button, on the iPhone, tap and hold an action’s title).

The actions in a workflow are executed sequentially, and each action passes its output (a piece of text) as input to the next action, which can then do something with it. For example, one action might produce the currently selected text as output, the next action could convert its input (the selected text) to uppercase, passing it to the next action that might copy it to the clipboard.

Actions that do not actually process their input will often simply pass it to the next action.

Variables

../_images/variable_key.png

In addition to this simple input/output mechanism, there are variables that can be used as placeholders in any text parameter. You can combine regular text with variables, much like a template. To insert a variable, simply tap one of the buttons on the extended keyboard. When an action is run, all the variables are expanded to their actual values. For a complete overview of the built-in variables, please see this reference.

You can also define your own variables for intermediate results by using the Set Variable action. For example, you might want to store the selected text in a variable before modifying the selection.

Action Blocks

../_images/action_blocks.png

There are two kinds of special block actions: Conditional Block (If...Then...) and Repeat Block.... Each of them consists of two parts. You drag other actions between those parts to create a block of actions that is controlled by the If or Repeat action that contains it. You can also hide the actions that are part of the block by tapping the Hide Actions button. This also allows you to save an entire block with multiple actions as a preset (see below), or to drag an entire block of actions at once (you can also create nested blocks this way).

A conditional (if-then) block is only executed when some condition is true. You can use this to verify requirements of your workflow, e.g. check the file extension of the current document. If the condition is not met, the block is simply skipped.

A repeat block executes a sequence of actions for either every line in the input, or every match of a regular expression. The output of the entire block is the combined output of each repetition. For example, if each iteration of the block adds an asterisk before the input line, the result of the entire block would be a bulleted list.

Options and Presets

../_images/action_options.png

In addition to parameters, each action has some settings for controlling its behavior and how it appears in the list. On the iPad, you can access these options by tapping the (▼) button next to an action’s title. On the iPhone, you have to tap and hold the action’s title instead.

To make your workflow easier to read, you can set a custom title for each action. This can be particularly helpful as a comment for complex actions that use regular expressions or scripts. If you want to make an action stand out in the workflow editor, you can also assign a color label to it.

You can also save an action as a preset from the options menu. This allows you to reuse an action in other workflows, without having to configure all its parameters again. You’ll typically want to set a custom title for presets, but you can also use this as a simple list of favorite actions.

Finally, there is a Pause Before Running option in the options menu. This can be helpful for “stepping through” a workflow, and to inspect an action’s parameters with all the variables expanded. It can also be useful to interrupt a workflow that you want to continue manually, for example after having opened a differrent document. In this case, you can turn off the ”...Show Parameters” option. While a workflow is paused, the rest of the app remains usable. Please note that this option is only available in the iPad version of Editorial.