Update: I have turned this review into an interactive book with additional & exclusive content. You can find it on iTunes, on sale for a limited time. More information is available here.
Ole Zorn knows how to push the boundaries of iOS. His latest app, Editorial for iPad, redefines the market of text editors for iOS, and, in many ways, sets a new standard for iOS automation and desktop-class apps. Editorial makes me want to work from my iPad.
Before I get to the details, allow me to offer some backstory to properly contextualize Editorial and the process that led me to its launch today. I have been testing Editorial for the past eight months (since late November 2012, when I received the first beta build), and I’ve seen the app go through numerous iterations and changes. At one point I wasn’t even sure Editorial would come out anymore. Editorial has become the essential part of my iOS workflow, and it only seems fair to have a proper introduction.
Editorial Review – Table of Contents
- Editorial, The Text Editor
- Workflows and Variables
- Workflow Sharing
- The URL Scheme
- Best Practices and Tips
- Basic Workflows
- Advanced Workflows
- A New iOS
In the summer of 2012, I decided to re-evaluate my iOS workflow and reassess the way I was using third-party apps and services to get my work done on a daily basis. My main goal was to find cohesiveness and coherence in how I could work from iOS – and especially my iPad – without ending up producing subpar content because of limitations in my workflow. I wanted to get rid of the notion that I needed a Mac for certain tasks, and (quite possibly to also prove this to myself, my colleagues, and my readers) I wanted to demonstrate that it wasn’t so absurd to think I could work from an iPad without compromises.
I had my reasons for deciding to embark on such a journey. I’ve shared more details on other occasions, but, to summarize, being forced to work efficiently only if I had my MacBook was becoming a problem for me, as MacBooks – even the Airs – just aren’t as portable as iPhones and iPads. And even if you could argue that the 11-inch Air is the king of Mac portability, I challenge you to work from that device for 8 hours straight while stuck in a hospital bed.
The idea of being able to get the same amount of work – with the same degree of quality and speed – done exclusively from an iPad seemed untenable, but I knew that it was what I needed to accomplish.
Longtime MacStories readers may be familiar with the process that I’ve gone through, as it’s been regularly documented on the site and my Twitter account. At first, I thought that centralizing key tasks and documents in Dropbox as plain text files would be the solution; arguably, I managed to set up a beautiful workflow that revolved around .txt files and a single Dropbox folder for organizing my todo list, my notes, my articles, my research material, and, sometimes, even my memories and ideas.
The problem is – workflows aren’t meant to be beautiful. They should be flexible, streamlined, and efficient. Working with a variety of different bits of content on the same level of plain text was a beautiful, liberal idea – but it wasn’t efficient.
I came to the conclusion that, in spite of the inner beauty of plain text, some things were better off as rich text or contained inside an app’s database. By saving links to interesting webpages as plain text URLs, I was losing the ability to easily tap on them and open them in a browser; by organizing tasks in a plain text list, I started feeling like a GTD hippie, presumptuously denying the higher appeal of tools like OmniFocus and Reminders. Plain text is great…until it’s not. It’s silly to deny the fact that, in today’s modern Web, we’re dealing with all kinds of rich content, which gets lost in the transition to plain text or hierarchical file structures (such as Dropbox); managing tasks in a text list is an elegant, old-fashioned concept that I’m sure Don Draper would have appreciated 50 years ago, but that, today, I wouldn’t choose over smart features like alarms, notifications, and location data in my todo app. I didn’t drop plain text altogether: I chose plain text for some tasks, and started using other apps for different purposes.
Around October 2012, the workflow I had settled with largely resembled the one I’m still relying upon today:
- My articles for MacStories are stored as plain text files in a single folder in Dropbox; once they’re published, they’re archived in a sub-folder. On the Mac, my editor of choice is Sublime Text 2, which uses Marked for Markdown previews and HTML generation.
- My tasks are organized in Reminders. It used to be Due, then OmniFocus, but I’ve been liking Reminders’ simplicity and fast sync across platforms and devices. On the Mac, I run my own “quick entry” tool based on AppleScript, and I like how Fantastical gives me a list of all reminders in the menubar. On iOS, I’m a fan of Agenda’s Reminders integration.
- I process my mail with Mail.app on the Mac; on iOS, I use a combination of Triage and Dispatch for processing and writing, and Gmail for push notifications.
- My personal memories are stored in Day One.
- Bookmarks (for sites that I want to archive for future reference with a full copy of the original webpage) are saved in Pinboard (a service that I also use every day for discovery).
- Everything else goes into Evernote, where I keep a few notebooks and tags and use saved searches a lot. My paperless system is based on Evernote; my article ideas and things I want to check out are available as notes; I keep annotated screenshots in it with Skitch; I use it to gather reference material for interviews and other projects I’m working on, collect show topics for The Prompt, and more. Evernote’s smart organization tools and cross-platform availability have outclassed Dropbox’s folder-based structure for me, and I don’t think that Mavericks’ Tags will be enough to win me back into the Finder.
Instead of forcing everything to fit the plain text model, I’m using different services and multiple apps that tend go beyond “just text” and that sync with other devices. Some may argue that this is convoluted; I think that I’m using the best for me.
As I was getting comfortable with my new way of working with iOS and OS X, I started noticing that, in spite of the system being solid, I still couldn’t complete key work-related tasks on my iPad. I was slow: screenshots took forever to be composited on iOS, as opposed to my two-second generation on the Mac with Keyboard Maestro; starting a new post from a link in my RSS reader took me minutes; when my colleagues pinged me about news items I should quickly check out, I would often reply “Sorry, I’m on the iPad right now”. And that was unacceptable.
I lacked a system that would allow me to automate tedious and common tasks to save time. I didn’t fully appreciate the importance of tools like Alfred and Keyboard Maestro until I lost them. Because of iOS’s sandboxed nature and Apple’s unwillingness to create power-user automation tools for it, I ended up with a nice set of apps and services…that didn’t take me anywhere. I was back to square one.
Until I stumbled upon Pythonista, developed by Ole Zorn, thanks to Gabe’s recommendation. Earlier in 2012, I started learning my way around AppleScript, which, somewhat surprisingly, is still alive and supported by Apple and third-party developers. I’m not a programmer by trade, and AppleScript was easy enough to pick up and tinker with to create little programs that would help me save time. AppleScript is often regarded as the programming language that “normal people” can understand and use; I never thought I would ever approach something more complex and “serious” like Python. I did, eventually, because Gabe made a terrific argument in favor of iOS automation through Python scripting. Which sounded completely crazy at the time.
Pythonista is a Python interpreter for iOS: it can run Python programs as long as modules from the Python library have been added by the developer. What’s amazing about Pythonista, though, isn’t the polished design or custom keyboard – it’s the fact that it leverages native iOS functionalities and UI elements to integrate them with Python scripts. For instance, you can load native iOS alert dialogs or banner notifications with Pythonista and make them display or launch custom text and actions; you can open URLs in Safari and build URL schemes to make multiple apps communicate with each other; you can access the system clipboard, fetch photos from and save them to the iOS Camera Roll, and even use secure password storage – all while working in a Python environment.
From my original review of Pythonista, aptly titled “Automating iOS”:
I don’t think iOS automation will ever be exactly like OS X automation. Pythonista has a series of limitations that, in comparison, running Python on OS X or any other desktop operating system doesn’t have. Hardcore Python users may not like this. At the same time, though, I also find working in Pythonista more intuitive, safer, and, ultimately, easier. Why shouldn’t I “compromise” if the end result is the same but I actually get more joy out of the experience?
Pythonista became the glue that was missing from my iOS workflow. By leveraging the strengths of Python scripting and mixing them with access to native iOS areas, Pythonista allowed me to create workflows to automate screenshot generation, Markdown conversion to HTML, publishing articles to WordPress, saving bookmarks to Pinboard (before Pinbook and Pushpin came around) add new tasks to my todo app, downloading files in iCab, and more.
Pythonista clearly wasn’t for everyone, but it singlehandedly revolutionized my workflow by letting me use multiple apps without wasting time with repeating boring tasks. Pythonista changed my perspective on how it was possible to get work done on iOS, even if I understood that mine was an extremely particular use case that didn’t necessarily reflect the general state of advancement of the iOS platform. Despite that “niche factor”, though, I felt that Pythonista did, in a way, raise awareness in regard to the kind of software that Apple was accepting on the iOS App Store, paving the way for a future “movement” of users and developers interested in exploring the potential of treating iOS devices as serious work machines. I don’t think it’s a coincidence that, after Pythonista, interest in URL schemes and iOS productivity software has seen the launch of powerful new apps, increased adoption of callbacks for inter-app communication (even by Google), and lots of interesting workflows being explored by independent writers and developers.
Shortly after my review of Pythonista was published, developer Ole Zorn told me that he had been working on a “spin-off” of the app that was a text editor powered by the same Python engine but that also used a GUI for Automator-like actions and workflows. Coming from the massive change that Pythonista had been for me and as a fan of Sublime Text on OS X, I was immediately intrigued by the idea. It sounded exactly like the kind of follow-up to Pythonista that Gabe and I were imagining when we talked about “a Sublime Text for iOS”. On November 29, 2012, I received the first beta of Editorial.
Fast-forward 8 months, Editorial is available on the App Store today. I have been testing every beta, built hundreds of workflows for it, and spent hours testing its workflow system, URL scheme, and integration with other iOS apps. I believe I have a good understanding of how Editorial works and the choices behind its interface and actions. In the past 8 months, Editorial has turned my iPad into a device that I want to use more than my Mac, because it combines the power of automation with the fun and low-friction nature of iOS. I wanted to share with my readers and followers the reasons why I was going iPad-only for a month, but I couldn’t. Today, I can.
Editorial, The Text Editor
Editorial is a text editor that supports Markdown, syncs with Dropbox, and comes with “accessory panels” to access a preview of documents (converted from Markdown to HTML), a Python console and scratchpad, a documentation viewer, and a web browser for quick research.
Editorial supports Dropbox versions, TextExpander snippets as well as its own abbreviation system, it comes with a powerful URL scheme, and – the core aspect of the app – it lets you automate text editing and communication with other apps through a workflow systems that is reminiscent of Automator and combines built-in actions with the possibility of running Python scripts. Editorial can be used to “just take some notes”, but it truly shines when the browser and workflows are put to good use for research purposes and to automate writing and editing in Markdown.
Like Byword, Editorial can be synced with Dropbox or used with local storage; as you can imagine, I’m using the app with my Dropbox account, and, more specifically, with the /Apps/ folder where I keep all the .txt files of articles that I’m working on.
Editorial’s interface design is clean: a sidebar on the left lists all your text files and folders, while accessory panels are available on the right side of the text editor as a series of tabs at the top. Both the sidebar and panels can be accessed by swiping horizontally on screen, with Editorial making it extremely clear (either through drag handles or the use of shadows) that the text editor is the main content area of the app; alternatively, the omnipresent hamburger button and a panel button in the title bar allow you to open their respective views without having to swipe.
Dropbox sync can be configured from the Settings (available through the cog icon next to the hamburger button). Editorial is capable of accessing your entire Dropbox, meaning that you’ll be able to point the app to the Dropbox folder that you’re already using to store text files through the “Sync Folder” option; in my tests, Editorial fetched hundreds of files in about a minute, and it didn’t return any error upon first sync.
The Settings also show the first aspects of user customization available in Editorial. Notably, the app comes with a light and dark color scheme: the former is reminiscent of Zorn’s work on Pythonista, and the latter is suited for late night writing sessions or, in general, people who like dark color schemes (I prefer the light one on my iPad mini).
Line spacing can be tweaked, as well as text width and the default browser that the app will use to open links in workflow actions. The first version of Editorial supports Safari, Chrome, and iCab in the Settings, and perhaps it would have been nice to see more options in this initial release, such as 1Password or other popular third-party iOS browsers; however, this is mitigated by the fact that, because “Open URL” actions (more in a bit) can open any URL scheme, Editorial users can set up workflows to open URLs in any app they want.
Editorial supports TextExpander snippets but it also allows you to set up snippets created with its proprietary syntax and tokens. In the “Snippets & Abbreviations” screen of the Settings, you’ll see options to ignore case when typing snippets, enable or disable TextExpander integration, and suggest TextExpander snippets. Similar to Pythonista’s code completion, Editorial can display small “bubbles” above the keyboard that suggest a matching snippet showing the abbreviation (with letters you’ve already typed highlighted in blue) and a preview of the full snippet.
This can be handy for choosing between snippets that share the same first letters in the abbrevation, and Editorial has an option to choose whether you’d prefer the suggestion bubble to come up after the first letter is typed, or after two letters (the default option). While the “first letter” option may sound incovenient, it’s actually a good way to enable users who have abbreviations starting with characters like semicolons to type less and still see their suggested snippets.
Alongside the usual controls for spellcheck, auto-correction, and auto-capitalization, Editorial offers separate settings for Markdown and plain text editing. For Markdown users, Editorial can show an inline preview for things like bold and italic text, links, footnotes, headers, blockquotes and code blocks. If the inline preview is active in the settings, you’ll get control over heading fonts, code fonts, and advanced options; otherwise, you’ll only be able to tweak the main text font, which defaults to Source Sans Pro and 9 other fonts (font size can be tweaked, too). Editorial is very deliberate in that it doesn’t give the user access to hundreds of personalization options for colors and fonts, but instead limits the tweaking to two color schemes, 10 fonts, sizes, and line spacing. Under the Advanced screen, you’ll see options to change the opacity of the formatting character for the Markdown inline preview, and fields to manage supported file extensions and set a default one (mine is txt).
Editorial’s file sidebar has a few nice touches worth mentioning. At the bottom, a sorting button lets you sort files and folders (both are supported in the app) by name and modification date; folders are always displayed at the top, but their sorting behavior matches the one of files below. To create a new file manually (it’s also possible to do so programmatically with workflows), you can hit the + button on the left. Editorial can navigate inside subfolders, where files will be downloaded and made available for viewing; files can be deleted by swiping over them, and there is an Edit button to delete multiple files, move them, or create a new folder.
There are two other little features that I like about the sidebar. The first is the fact that it supports pull-to-refresh, which I’ve come to expect from any app that uses lists and gets data from the Internet, even if it’s not a timeline of messages; the second is how you can tap & hold the sidebar button to bring up a switcher for recent documents that persists across sessions (if you quit and relaunch Editorial), which is a nice way to multitask between multiple documents.
Editorial’s text editor looks simple, but it’s packed with functionalities. The writing area elevates content with a handy Markdown preview that ensures you can get a quick visual understanding of your place in a document by seeing larger, bold fonts for headers and blue inline links. Many apps have live inline Markdown syntax highlighting these days, and Editorial’s one supports most special Markdown formatting such as the aforementioned headers and links, but also bold, italic, lists, footnotes, blockquotes, and more. I find it useful, and it looks good (especially with the default font).
The keyboard takes up where Pythonista left off and offers an extra row and character auto-pairing for parentheses, brackets, and quotes; as I also mentioned in my Pythonista review, automatic character pairing can be confusing for some users, but, for me, it is a great addition to the writing experience as, combined with the extra keyboard row, it lets me quickly hit the parenthesis character once without having to remember to close it later. Like Pythonista, the keyboard row also doubles as a swiping area to replicate the popular Hooper selection concept: swipe your finger across the keyboard row, and you’ll be able to move the cursor in the editor. I’m quite fond of this feature in both Pythonista and Editorial, and I like that the gesture rarely results in characters being accidentally typed on screen.
And last (again, like Pythonista), characters in the extra row that have a “dog ear” in their upper right corner can present a set of alternative characters (such as curly brackets for parentheses) upon tapping & holding, whereas (unlike Zorn’s Python app) the rightmost corner of the row has been reserved to an Undo button (for unlimited Undo actions, which also shows a “Redo” option with tap & hold) and a special Snippets popover.
At the top of the editor, Editorial shows the bookmarks and title bars. The bookmarks bar is a key area of the app and the one that starts revealing the differences between Editorial and most iPad text editors: similar to the one you’d see in a web browser, this bar lets you bookmark and launch workflows, URLs, and documents.
Workflows (more in the next section) can be bookmarked from the Workflow Details popover (accessible by tapping the wrench button in the upper right corner), but they can also be added from the Bookmarks popover, which can be opened by tapping the familiar book-shaped icon on the left of the bookmarks bar.
If you want to create a new bookmark from scratch (that is, without bookmarking an existing workflow), you can tap the + button in the Bookmarks popover to open the Edit Bookmark view, from where you’ll gain access to several options that include entering a title for a new bookmark, choosing whether you want to launch a URL in the web browser, set the bookmark target to the current document (so you’ll be able to quickly reopen it from another document), or run an existing workflow from your library. Alternatively, you can create bookmarks with fixed or flexible space: these are namesakes of options that OS X users have grown accustomed to seeing in the “Customize Toolbar” screen of modern Mac apps, and they enable icons to be better organized and grouped with separators.
One of the best design choices of Editorial is, in fact, the possibility to assign custom icons to workflows. Available from Workflow Details > Icon, Editorial comes with 90 monochromatic icons you can freely assign to any workflow, and that you’ll see in the editor and browser’s bookmark bar and popover.
But there’s more. In Editorial, bookmarks don’t have to use the same name of a workflow in your library. Say, for instance, that you have a workflow called “Append To Evernote”, but that you realize the name is too long for the bookmarks bar: once bookmarked, you can tap & hold the item, edit its name to make it shorter, and Editorial will still launch the workflow you originally bookmarked. This is a wise implementation, as it lets you keep workflows with descriptive titles but use shorter names for the bookmarks bar, where you’ll likely want to save as much space as possible. Under the hood, this is made possible by Editorial’s way of assigning a unique “command ID” to each workflow, which I’ll elaborate upon later in this review.
Editorial’s bookmarks bar is flexible in how it combines custom names and icons with the ability to bookmark workflows, websites, and even documents and launch them directly from the editor with one tap. Instead of cramming shortcuts to selected features in another extra keyboard row, Editorial elegantly takes cue from web browsers and puts bookmarks away from the keyboard (which is already crowded with just one additional row).
You can also bookmark an amount of items that exceed the length of the bookmarks bar, and they will be shown in a popover available from the >> button on the right side of the bookmarks bar. This popover contains a button to hide the bookmarks bar entirely if you never want to see it.
In my Editorial setup, every workflow bookmark that I have has been given a custom icon and a shorter name for the bookmarks bar. I don’t use separators; I have some workflows that have been bookmarked without a name (they have just an icon) and I don’t keep bookmarks for documents or websites in the editor. I keep the bookmarks bar visible, as I tend to add inline links or formatting while I’m writing and because I run workflows that go beyond simply acting on the text that I’m currently seeing. I use the bookmarks bar all the time, and I believe it’s one of Editorial’s best implemented features that differentiates it from text editors I’ve tried over the years.
The document’s name in the title bar can be tapped to reveal a popup menu with buttons to access Dropbox versions, edit the filename, see word and character count, and navigate to sections of a document containing Markdown-style headers (which is particularly handy for long documents with several sections – like this review).
Versions work by fetching revisions of a document stored in Dropbox and loading them in a version browser interface that, by default, displays the latest (current) version as two tabs at the top of the screen. The version browser can be minimized by tapping the Text Editor button in the top toolbar (a feature that is shared across other functionalities in Editorial); when the version browser is minimized and docked at the bottom of the editor, you can write and edit your document without limitations.
The version browser primarily acts as a diff tool, comparing two versions of the same file and displaying additions as green highlights and deletions in red (text that is unchanged won’t be highlighted); at the top, you can choose to compare an older version with the current one, or two old versions against each other.
When comparing an old version with the current one available in Editorial (and synced to Dropbox), you’ll have two options for restore: you can “restore this version” (through the arrow icon at the top) to quickly take an entire version and restore it (replacing the current one), or you can manually select a deletion and choose “Restore Selection” from the copy & paste menu. In both cases, the version browser will be minimized, selecting the document’s text (with a gray selection) and showing an Undo button at the bottom to cancel the restore process. If you don’t want to see deletions inline, you can “collapse deletions”, and they will be displayed as ellipses in the version preview screen. I don’t use versions much – it’s one of those features that you’ll be glad to have when you’ll need it; it has certainly saved me in those couple of occasions where I had deleted something that I wanted back.
The “gray selection” that I mentioned above is Editorial’s way of keeping the selection active when the iPad’s keyboard is dismissed.
In most iPad apps, selecting text when the keyboard is shown and then dismissing the keyboard results in losing the selection; Editorial has a custom selection engine that allows you to select text as you normally would when the keyboard is shown, but also to dismiss the keyboard, keep the selection, and tap the dimmed selection again to bring up the keyboard without losing the selection at all. When the selection is dimmed, you can do anything that you can typically do with a non-custom selection, such as extend it and copy text. This is a minor detail – but one that shows the level of care that went into making sure Editorial could enhance even the smallest, most obvious aspects of editing text on an iPad. After months of testing, I believe this implementation is superior to Apple’s text selection – it doesn’t solve all the problems of editing text on iOS, but it’s a solid addition.
Editorial’s selection engine is best demonstrated by the in-document search available in the top toolbar: when searching for an occurrence of a word in the current document, Editorial will highlight results in yellow and select the first occurrence with a gray selection. You can move between multiple occurrences with the arrow buttons next to the search field, or tap the selection to make it active and start typing with the keyboard to delete/replace a selected occurrence.
Last year, I took a look at the best MultiMarkdown previews in iOS text editors, and I concluded that Byword had the best preview tool. Editorial follows Byword’s example and provides an excellent Preview panel that supports inline images (both as MMD or HTML code), code blocks and blockquotes, footnotes, links, headers, and more. You can tap & hold links to open them or add them to Safari’s Reading List, and, overall, the preview just looks great. One thing I don’t like is that there is no shortcut for generating and copying HTML text in the Preview panel, as Editorial forces you to build a workflow for that. While this is a common scenario in Editorial as Zorn preferred showcasing the power of workflows over adding native features to the interface, I think that adding a “Copy HTML” button in the Preview would be a smart move that wouldn’t clutter the UI too much.
Even without using workflows, Editorial’s text editor is versatile enough to guarantee a pleasant writing experience thanks to syntax highlighting, the extra keyboard row with character auto-pairing, swipe gestures and custom selection, versions, search, and the rich Preview panel. Editorial can be used as a text editor that doesn’t rely on workflows, but that would be short-sighted: Editorial’s real power lies in the workflow system, which is unlike anything you’ve seen on iOS before.
Workflows and Variables
Workflows are at the heart of Editorial: they define the app’s nature, its automation and inter-app communication capabilities, and its unique proposition for iPad users. Workflows are deeply intertwined with Editorial’s feature set and they’re completely open to user customization.
A workflow is a set of actions run sequentially from top to bottom – from the first action to the last one. Workflows generally handle text, as they are based on an input/output mechanism that receives and produces text to pass to other actions. Workflows can interact with text from the main editor, but they don’t have to. Moreover, because of the variety of available actions, workflows don’t have to exclusively handle text: you can augment them with Python scripting to create and upload images, add interactivity to them with actions that play sounds or present alert dialogs, open URLs, and move the position of the cursor in Editorial’s text editor. Workflows, reminiscent (in terms of UI and overall concept) of Automator for OS X, are primarily aimed at enhancing Editorial’s writing and editing process, but, with enough time and imagination, they can be turned into powerful solutions to automate several aspects of iOS.
A workflow is made of actions, and actions are available in the Action Library. Editorial comes with 50 built-in actions that range from working with text to presenting custom UI elements or converting Markdown, and they are organized in categories:
- Conditional Block (If… Then…)
- Custom Action
- Generate Text
- Repeat Block
- Run Python Script
- Set Variable
- Extend Selection
- Get Bookmark URL
- Get Document Name
- Get Document Text
- Get File Contents
- Get Selected Text
- Move Caret
- Open Document
- Replace Selected Text
- Select Closest Word
- Select Range
- Set File Contents
- Compose Email
- Compose Text Message
- Compose Tweet
- Console Output
- Request Text Input
- Select from List
- Show Alert
- Show Dictionary Definition
- Show HTML
- Show HUD Alert
- Change Case
- Convert Markdown to HTML
- Escape for Regular Expression
- Expand Snippet
- Extract Range
- Extract URLs
- Filter Lines
- Find / Replace
- Prefix / Suffix Lines
- Remove Duplicate Lines
- Remove Whitespace
- Sort Lines
- URL Escape
- Play Sound Effect
- Set Clipboard
- Open URL
- Search Web
Many of these action names are rather self-explanatory, and, for a detailed summary of each action’s capabilities, you can open Editorial’s documentation and read through the Workflow Actions Reference. In this article, I’ll demonstrate Editorial’s workflow system by example, describing an action’s role in a workflow when necessary and providing an overview of the workflows that I use in Editorial.
Workflows can be accessed by tapping the wrench button in the upper right corner of the text editor; from the popover, you can swipe down to reveal a search bar to filter your workflows, hit the + button to create a new one, or tap Edit to navigate into Workflow Details. A workflow can have a name, abbreviation, description, icon, and, as mentioned above, it can also be added to the bookmarks bar; when searching for a workflow, Editorial can look both into the name and description fields – useful if you, like me, will end up with dozens of workflows and remembering names won’t suffice.
When you create a new workflow, you start with a blank canvas and a top toolbar that contains the name of your workflow (you can tap to edit it), a play button to run the workflow, a sharing icon, a Done button to go back to the editor, a + button to add new actions, and a button to minimize the workflow editor. Minimizing a workflow, like versions, allows you to keep the editor open while also seeing what’s happening in the current document – useful for debugging workflows that manipulate document text.
To add actions to a workflow, you can tap on them in the Action Library; each action that you’ll add will be inserted at the bottom of the workflow. Besides a name, actions have a brief description and a “?” button that you can tap to view the piece of documentation for an action inline within the Action Library popover. To rearrange actions in a workflow, you just drag & drop them.
When you run a workflow, the wrench icon turns into a spinning indicator:
To better explain the process of creating workflows in Editorial, I’m going to demonstrate how you can build a workflow to insert an inline Markdown link in the editor.
Editorial is aware of things like the currently selected text or the webpage you have opened in the built-in web browser; to insert an inline link in a document you’re editing, we can take advantage of these aspects to avoid manual typing and copying of URLs.
The easiest way to insert a link would be to use a single Replace Selected Text action, which replaces the selected text with a replacement text you can specify in the workflow; tapping on the action to add it to the workflow reveals the better part of Editorial’s workflow system:
There are several things to look at here for first-time users, and understanding the basic mechanism behind this simple action will be key to building more complex workflows.
Actions can be configured with parameters; in most cases, parameters can modify the input text that an action receives or the output that it produces, but they can also take on more advanced tasks such as setting the name of a button in an alert dialog or running regular expressions. In the case of Replace Selected Text, the default variable shown in the Replacement Text parameter is
Variables are a key aspect of Editorial’s workflow system and you’ll have to learn how to use them and combine them with arbitrary text and other variables in order to chain multiple actions together. Variables are text tokens that can be stored in a workflow and re-used in other actions without having to follow a one-way input -> output pattern; every time a variable is used in a parameter, it is expanded and used by the workflow with its full text contents. An example of this may be a variable containing a placeholder for the current date and time that is generated at the beginning of the workflow but only used in the last action (when it’s not the direct input anymore); or, a variable containing a URL that was fetched from the browser in the first action, and used after a series of actions that worked with other bits of data. Variables are a handy way to store text that you’ll want to use in a workflow at a later time without having to constantly leverage the input/output mechanism, or, worse, the system clipboard.
For the Replace Selected Text action, the blue, OS X token-like bubble called
Input is actually a variable that, as the name suggests, will be expanded to the text passed by the previous action. Because, however, we have a single action in the workflow, there is no “input” and the replacement text will end up being empty – unless we use other variables.
In the workflow editor, Editorial’s Markdown-oriented extra keyboard row turns into a series of buttons to quickly insert default variables into actions. The variables that Editorial ships with are:
- The current input
- Text that is currently selected
- File name and extension
- Browser title, URL, and selection
- The start/end (as range) of the current selection in the editor
- Date variables (for year, month, day)
- Time variables (for hour, minute, second, AM/PM)
- The contents of the system clipboard
Additionally, in the same keyboard row, you’ll also see a tab key to insert a tab between characters, and, in some actions, a blue selection button to set the cursor position in a text string. The latter is similar to TextExpander’s cursor macro: if, for instance, you want to paste the browser URL and title in the editor and end up with the cursor between them, you can use the variables as shown below:
Variables can be inserted into actions by tapping on them in the extra keyboard row; variables that depend upon data that may or may not be available (such as a browser URL or a selection) will be returned as empty if they can’t be expanded (e.g. if Editorial doesn’t have any URL open in the built-in browser, there is no “Browser URL” variable to expand). In multi-line parameters, such as Replacement Text, you can have a mix of variables and plain text you’ve entered manually (e.g. “Browser URL” variable + “This is a cool link” text string); in single-line parameters (such as “Title” in the Show Alert action), only variables manually set by the user can be inserted using a “Variable” button in the copy & paste menu (a limitation of Editorial 1.0 – you can’t have both plain text and variables in single-line parameters).
Aside from built-in variables, users can set their own variables through the aptly-named Set Variable action. Setting a variable requires two parameters, Variable Name and Value; variables set through the “Set Variable” action will be available in the (also aptly-named) “Variable…” popover of the extra keyboard row.
The Replace Selected Text action we’ve added to our test workflow reveals, upon closer inspection, more features besides variables. An “x” button next to the action name allows you to delete an action from a workflow, while a drag handle to the far right lets you rearrange an action’s position in a workflow. Unfortunately, Editorial 1.0 doesn’t come with an “insert action at this point” command, so drag handles will soon turn into your best (and only, because you have no other choice) friends for long workflows that will require lots of drag & drop (new actions are always inserted at the bottom of a workflow).
Actions can be renamed, paused, and saved as presets. By hitting the down-pointing triangle button next to the drag handle, you’ll open a popover showing a custom title field, a button to save an action in your preset library (for future reuse), and a “Pause Before Running switch that, if activated, reveals a second ”…Show Parameters" option. Title and presets are useful if you want to make actions more illustrative and easier to access in other workflows, whereas pausing allows you to debug a workflow and understand what parameters are being used, or, more simply, pause while something else needs to finish loading.
A paused action will show a slightly different triangle button and, when run, will open a rectangle-shaped indicator on the left side of the screen, which contains a blue “Continue” button and an edit button to show the parameters that are being used, plus a Stop button. The pause indicator can be dragged up and down on screen; if the “Show Parameters” option is set to On, the popover with parameters will come up by default.
Pausing actions can come in handy when debugging workflows and having to inspect parameters that are passed from one action to another; on the other hand, though, don’t underestimate the potential of pausing as a way to make other actions complete and return a correct set of data – such as moving between different documents or launching another app and then coming back to Editorial.
With an increased knowledge of Editorial’s workflow system, we can go back to our Replace Selected Text and use a mix of plain text and default variables to turn a text selection into a Markdown inline link. As it turns out, we can accomplish this by building a workflow that contains a single action and that uses three variables and plain text characters to use Markdown’s inline link syntax:
If you pause the action before running it, you can see the parameters that Editorial is going to use: the current selection in the editor, and URL + title from the built-in web browser. When run, the action will simply replace the selection with the new data inline, putting the cursor at the end of the Markdown link.
This workflow is simple and it gets the job done, but it could be improved in several ways: it doesn’t have any way to check for available conditions; it doesn’t know how to handle errors; and, it could use a “success message” to let the user know that the workflow was completed without issues. All of this can be accomplished in Editorial by adding more actions to the workflow.
The first thing I would add is a conditional block to check whether a URL is actually open in the browser. A conditional block (or “If block”) contains a group of actions that are run only if certain conditions are met; actions inside a conditional block are nested in the workflow editor, and you can have up to three nested levels of conditions inside a conditional block, a feature that opens up to a great deal of condition-checking and workflow accuracy.
There are five conditions that can be checked for any text string supported by Editorial (input, variables, plain text, etc):
- Run if…is Equal to
- Run if…is Not Equal to
- Run if…Contains
- Run if…Doesn’t Contain
- Run if…Matches Regular Expression
Combining these five conditions with variables and nested blocks unlocks a deeper layer of flexibility – if you want to build state-of-the-art workflows that can adapt to varying situations and scenarios, you’re going to have to use conditional blocks profusely.
For our workflow, the first condition we want to check is whether there is an active selection in the editor, and, if there’s not, stop the workflow and tell the user why. Therefore, we can add a conditional block that, in case of an empty Selected Text variable, will stop the workflow and show a HUD message to communicate the error. To check for an empty variable, you can leave the “is Equal to” multi-line parameter empty.
The Stop action can be used to stop a workflow or a Repeat Block (more on this later); additionally, it can show a native HUD alert containing a text message. In our case, we’ll write “Select some text first!” to inform the user that the workflow to replace the currently selected text was stopped for lacking a text selection in the first place.
Still, even with a selection, Editorial may not have a webpage open in the built-in browser, and we’re relying on Browser URL and Browser Title for our replacement text. Because Markdown will generate an inline link even without a Browser Title, we’ll add a second conditional block similar to the first one, but this time checking for an empty Browser URL. Like the first block, the workflow will be stopped if the condition is met.
Once we’ve ensured that Editorial has an active selection in the editor and that a URL is open in the browser, we can go ahead and run the Replace Selected Text action that we built at the beginning, this time renaming it as “Insert Inline Link” to make it nicer and more explanatory. To communicate the correct and complete execution of the workflow, we can insert a Show HUD action that will show a HUD alert similar to the Stop action’s one, but with a checkmark; in the Show HUD action, you can specify a text message and duration (1, 2, or 3 seconds) of the translucent overlay (which doesn’t block touches on screen, unlike alert dialogs).
At this point, we’ve ended up with a solid workflow that does what intended, using conditional blocks to make sure actions aren’t run when data isn’t available, and built-in variables to grab text from the browser and editor. I like inline Markdown links, as I prefer seeing what I’m linking to directly from the sentence that I’m currently editing, without having to scroll to another position in the document. And yet, there are times when I need to use reference links – either for syntax compatibility or readability purposes.
How hard would it be to tweak our workflow to make it ask us whether we want to use an inline or reference link, and if we choose reference ensure that it’ll correctly create a link for us? Not too hard – but the solution I’m going to show you will use Editorial’s most advanced features: Python scripts and Custom Actions.
Python and Custom Actions
Like Pythonista, Editorial comes with a built-in Python interpreter and a scriptable editor. The differences between the two apps, however, go beyond the assumption that they share the same Python engine for the same tasks: Editorial’s Python scripts can do the same things they could in Pythonista – in fact, you should be able to port your scripts over without major changes (if any) – but they’ve been enhanced to directly plug into the text editor and workflows as well. This is epitomized by the fact that “Run Python Script” is actually a workflow action in Editorial.
I don’t need to explain the potential and limitations of Zorn’s Python interpreter on iOS: for that, my initial Pythonista review and subsequent coverage of the app updates should be enough to give you an idea of the scope of native iOS integrations that Pythonista achieved. Editorial follows the same path, and adds a new
workflow module with functions to get and set variables, receive input and parameters, set output, and stop a workflow. If, when building a workflow, you’ll come up with an idea that can’t be realized with built-in actions, you can resort to Python scripting for a more advanced solution that unlocks the power of Python’s Standard Library and Zorn’s custom modules for iOS (all of them ported from Pythonista).
For instance, sets of actions that deal with list creation and appending text may be easier to put together in Python (if you know your way around the basics of the language) rather than multiple actions and variables in a workflow. With Editorial’s “Run Python Script” action, getting the value (i.e. the expanded text) of a variable is as fast as
Name is, unsurprisingly, the name of a variable you’ve previously set in a workflow; the opposite is true for
workflow.set_variable(), where you assign a string of text to a variable’s value. And, as you can guess, when running
workflow.set_output() in Python, the output will be fetched by Editorial’s built-in Input variable in a following action.
The “Run Python Script” action comes with two types of editor: the inline, “mini” source code editor and the full editor.
The first one is shown inline within a workflow, and it comes with Pythonista’s syntax highlighting and line numbers but no automatic character pairing or auto-completion. This is meant for s