While looking through the Drafts scripting documentation for help with another idea for an action, I found a couple of Editor functions that I hadn’t noticed before. One of them led to a big improvement to my TaskPaper action group.

As explained in this post, I use Drafts now for handling TaskPaper task lists on my iPhone and iPad. Drafts has some nice built-in features for TaskPaper lists, and its extensibility through actions allows more features to be added. I wrote a handful of actions geared toward my use of TaskPaper, and added them to the Drafts Action Directory, a repository of community-created actions. You can download them from here.

One of the actions in my TaskPaper group worked as a toggle to add/remove blank lines between tasks. I keep my lists in a format that looks like this,

with no blank lines between projects except for the Archive section at the end. This is great for keeping the list tight but is a problem when I want to rearrange projects to bring the more important ones to the top. Drafts has an Arrange Mode which is perfect for this sort of thing, but it requires blank lines delimiters to define text groupings that can be moved as blocks.

Originally, I made an Un/Block action, which added or removed blank lines between projects, depending on the list’s current state. My rearranging workflow was this:

1. Tap Un/Block to add the blank lines.
2. Tap the Arrange Mode button at the bottom of the screen to enter Arrange Mode.
3. Rearrange the projects.
4. Tap the Un/Block button to remove the blank lines.

This worked well but was a little clumsy. Then I saw the showArrange and arrange functions in the Drafts Editor library. The showArrange function wasn’t quite what I needed, but the arrange function was perfect. It takes text as an argument, stops the flow of the script while the user rearranges it, then returns the rearranged text.

By incorporating arrange, I was able to change the script of the Un/Block action into this:

javascript:
1:  // Allow user to rearrange projects by temporarily adding
2:  // blank lines above all projects
3:
4:  // Regexes for project headers.
5:  var projREtight = /([^\n])(\n[^:\n]+:)/g;
6:  var projREloose = /(\n\n)([^:\n]+:)/g;
7:  var archiveRE = /^(Archive:)$/m; 8: 9: // Get the text of the current draft 10: var d = draft.content; 11: 12: // Make new text with blank lines above all project 13: // headers that didn't have them. 14: var e = d.replace(projREtight, '$1\n$2'); 15: 16: // Go into arrange mode with this new text 17: // and wait until the user is done rearranging. 18: e = editor.arrange(e); 19: 20: // Take blank lines away except above the Archive section. 21: e = e.replace(projREloose, '\n$2');
22:  e = e.replace(archiveRE, '\n\$1');
23:  editor.setText(e);


It adds the blank lines in Line 14, lets the user rearrange the blocks in Line 18, and then removes the blank lines in Line 20 (Line 21 restores the blank line above the Archive section). Now the rearranging happens within the execution of the script, so I’ve renamed the action Rearrange. The workflow is reduced to two steps:

1. Tap Rearrange.
2. Rearrange the projects.

This is not just faster, it’s more natural because the action is named for what I really want to do and all the necessary-but-incidental format fiddling happens behind the scenes.

So, yeah, reading the documentation can be helpful. I have a sense the activate, deactivate, and dictate functions, which are also things I missed when I first looked in the Editor section, will be finding their way into my scripts soon.