Using Drafts Templates

templates
tags
#1

Template Basics

Drafts actions consist of “steps”. Action steps are available for a wide range of functions and services: Sending message, mail, saving files and much more. Regardless of what the purpose of the step is, any steps that output information have some fields that allow you to control what text is used by the step, and (with a few small exceptions) use templates to dynamically generate that text.

If you have poked around in the action editor and wonder what some of those [[title]] and [[body]] things are, this article is for you.

Templates are plain text combined with tags. Consider tags placeholders for some piece of information you want inserted when the action is run. Drafts tags are identified by double square brackets ([[ ]]), surrounding the tag name and options. Most tags insert some content or meta data related to the current draft on which an action is being performed.

Common Content Tags

The tags that get the most use, and which you are likely to see as defaults in many action steps, are:

  • [[draft]] : Replaced with full text of the current draft.
  • [[title]] : Replaced with text of only the first line of a draft.
  • [[body]] : Replace with everything but the first line of the draft.

So, take as an example the “Copy” action which ships with Drafts in the “Basic” action group. The action places the contents of the current draft in the clipboard. The action itself consists of one Clipboard action step, with the template [[draft]]. If you wanted an action that copied just the first line of the draft to the clipboard, you could change the template of the clipboard action step to [[title]].

The default “Mail” action which ships with the app uses the [[title]] tag for the subject line of the email, and [[body]] as the content of the email.

Tags can be mixed with static text in templates, so you could also have the template string Title: [[title]], which would produce the first line of the draft, with the prefix Title:.

There is a handy [[line|n]] tag that lets you extract individual or ranges of lines from the content of a draft. This is an example of a tag with a formatting option, separated from the tag name by a | pipe character. In this case that options take line number (1 for the first, 2 for the second, etc.), or range, like 1..3 for first through third line. If you omit the beginning or end line number, the range will assume beginning or end, so ..4 is the first four lines and 5.. is the fifth line to the end of the draft. Negative indexes which cound back from the end can also be used, so [[line|-1]] would get you just the last line.

This can be very useful in splitting up values from a draft into separate values. Say you want an action which saves to a folder in Dropbox, but you want to specify that in the draft itself. You could type the following draft:

My File Name
Personal

This is the content of the draft.

Then have an action configured with a Dropbox action step using the following template values for its fields:

  • Name: [[line|1]].txt
  • Path: /[[line|2]]/
  • Template: [[line|3..]]

Using this action, on the draft sample text above would result in a file on Dropbox named “My File Name.txt” in the folder “Personal”, with the content “This is the content of the draft.”

Date and Time Tags

Another commonly used set of tags are date related tags. The available date tags are:

  • [[date]]: Current date, defaulting to the format %Y-%m-%d, which is equivalent to YYYY-MM-DD.
  • [[created]]: The date the current draft was created.
  • [[modified]]: The date the content of the current draft was last modified.

Each of these tags can also take a formatting string, after the | separator, using strftime formatting. There are formatting characters to allow configuration of almost any possible date and time string - including year, month names, day names, and much more. The Apple strftime reference has details on all the available options. A few commonly used format examples:

  • [[date|%Y-%m-%d]] : Result: 2019-01-31
  • [[date|%I:%M %p]] : Result: 06:19 PM
  • [[date|%d %B %Y %H:%M:%S]] : Result: 31 January 2019 21:19:20

Dr. Drang wrote and excellent blog post about date tags in Drafts which is an excellent resource as well.

The most common use case for date tags is including timestamps when appending to a daily journal file, for example.

Additional Tags

Visit the template reference for a complete list of available built-in tags. Using tags you can access information like location data stored with a draft, its UUID and permalink, tags, and more.

No Tags Required

Keep in mind that just because templates in actions can contain tags to dynamically insert text, they don’t need to. Many times you just want plain old static text in a template to add boilerplate snippets,

Special Template Markup

In addition to tags, there are a couple of special markup conventions used in templates for convenience, they are:

  • {{ }} : Any text between double curly braces will be URL encoded for use in URL query parameters. This is typically used in Open URL action steps to properly encode text to be included in a URL.
  • %% %% : Any text between double percent signs will converted from Markdown to HTML using your default Markdown options. Useful when publishing to locations which want HTML input.
  • <<textexpander-shortcut>> [iOS Only] : If you use TextExpander, it is possible to dynamically expand a TextExpander snippet when a template is evaluated. Generally useful for snippets you do not want expanded until the action is run because they contains dates or other output which is time sensitive. To expand a snippet in a template, wrap the snippet’s shortcut text in << >>.

Conclusion

With just a few tweaks to templates, you can create an array of useful actions that save time and formatting.

4 Likes

TIP: Creating New Drafts with Templates
Preview templates
#2

Re: Textexpander
Is there something I am doing wrong? or some setting I missed? Attempting to enclose the TE shortcut doesn’t seem to work. <<TE-Shortcut>> The last bracket doesn’t appear to be a part of the code. It does not expand.

0 Likes

#3

A few troubleshooting questions:

  • You have a snippet with the shortcut “TE-Shortcut”?
  • It’s an exact match (e.g. case-sensitive)?
  • Your snippets are refreshed, and TE expansion and “expand in actions” are enabled in Drafts settings?
  • You can type that snippet in a draft and it works?
  • It’s not a fill-in snippet? Those cannot be dynamically evaluated, only as you type.
0 Likes

#4

That was an example only.
The snippet is actually ddate. It inserts the current date at the location.
Yes. It is an exact match.
All is refreshed and enabled.
Yes it works in drafts and every where else too.
This is what it looks like in the document

0 Likes

#5

How are you applying the snippet for expansion? Is it simply an Insert Text action or are you using another method to initiate the evaluation?

0 Likes

#6

Yikes! It was an operator error! Problem solved!

It was a lack of understanding on my part.

0 Likes