The Thing Builder is a Shortcuts shortcut for easily creating projects or adding tasks to existing projects/areas in Things. It is born primarily of the need for some sort of project template, though it can also be used for more ad-hoc creation of projects in a text editor or batch-adding tasks to projects and areas.
Download the shortcut here. When the shortcut contents are displayed, scroll to the bottom and tap Add Untrusted Shortcut.
The Thing Builder accepts text, which can be sent via the share sheet or entered when the shortcut is run. If the shortcut is run without input from the share sheet, it will prompt for input, with the default value being the contents of the clipboard.
Things 3 for iPhone or iPad is required. Although Things is not a universal app, the shortcut will call the correct action for the device in use.
The Thing Builder is built on top of Things’ URL scheme—specifically, the JSON payload. While the syntax is mine, the data model the syntax maps to is documented there, so if you want a better understanding of my shortcut, that may help.
Feel free to modify and redistribute this shortcut.
The Thing Builder uses a Markdown-inspired syntax for its basic structure. The primary intended use case is to create new projects, for which the main structural prefixes are:
| Prefix | Item | Notes |
|---|---|---|
# |
Project name | |
## |
Heading | |
*/- |
Task/checklist item | Checklist items are indented below tasks (either tabs or spaces work) |
Thus, a project could be created like so:
# Podcast Episode
- Prep
- Record
- Save files
- Me
- Alice
- Bob
## Edit
- Pre-process files
- Me
- Alice
- Bob
- Edit episode
## Show Notes
- Compile links
- Choose title
- Write show notes
## Finish
- Publish episode
- Upload MP3
- Add show notes
- Publish
- Tweet link
- Archive project
Alternatively, multiple tasks can be added to an existing project or area by using / instead of # at the top of the document:
/ Grocery List
- Eggs
- Milk
- Bread
Projects and tasks can have attributes added to them by including particular prefixes on the same or subsequent lines. Extra lines of attributes can be indented for clarity, but do not need to be; the only semantic indentation is for checklist items.
| Prefix | Attribute | Notes |
|---|---|---|
/ |
List | The area/project to which a project/task will be added; will be ignored on tasks when creating a new project (all tasks will be added to the new project) |
## |
Heading | When adding tasks to an existing project, can be used to specify a heading—if this heading does not already exist in the project, it will be ignored. (When creating a new project, the document must follow the outline structure above, and tasks will be added to the preceding heading.) |
> |
When | Supports natural language, e.g. Tuesday, in 3 days, or March 14; and Things’ terms with specific meaning, e.g. Evening or Someday |
! |
Deadline | Supports natural language as above |
@ |
Tag | Multiple tags are allowed |
// |
Note | This must be the last attribute on a given line; as with code comments, everything after // is included in the note and ignored by the parser. |
Additionally, including $open (case-insensitive) among the project attributes will open the project in Things after creation. Omitting it will create the project in the background. This only applies when creating a new project.
Now, we can create a reusable template with relative dates and deadlines:
# Podcast Episode
/Podcast !Friday $open
- Prep !Today @Alice @Bob
- Record
> Evening @Studio
- Save files > Evening @Studio
- Me
- Alice
- Bob
## Edit
- Pre-process files > Tomorrow
- Me
- Alice
- Bob
- Edit episode > Tomorrow
## Show Notes
- Compile links
- Choose title @Alice @Bob
- Write show notes
## Finish
- Publish episode > Friday // https://mypodcastcms.fm
- Upload MP3
- Add show notes
- Publish
- Tweet link
- Archive project > Friday
Our grocery list additions could also be updated:
/ Grocery List
- Eggs !Tomorrow // 1 dozen
- Milk ## Dairy // Whole and 2%
- Bread ## Bakery
The Thing Builder has two more tricks up its sleeve for streamlining data entry—particularly for reusing the same set of attributes in multiple places: variables and batch blocks.
Variables are what they say on the tin: a set of attributes that can be defined and then added by name in multiple places. Variables take the form [[Variable Name]] and are defined at the bottom of the document with a colon. This example variable adds a tag and a checklist to any task in which it is included:
[[Accounting]]: @Accounting
- Angela
- Oscar
- Kevin
If a variable is used in the document but not defined, it will be requested when the Thing Builder is run.
Batch Blocks allow you to add the same attributes (or variables) to a series of tasks without repeating them each time. If the first line of a block of text consists of only attributes, those attributes will be added to all tasks before the next empty line. Dates, tags, or notes can be added this way. Checklists cannot be added directly, but can be if passed through a variable.
Putting these together, we can clean up our project and allow for setting a couple values when run:
# Podcast Episode [[Episode Number]]
/Podcast ![[Release Date]] $open
- Prep !Today [[Cohosts]]
> Evening @Studio
- Record
- Save files
[[All Hosts]]
## Edit
> Tomorrow
- Pre-process files
[[All Hosts]]
- Edit episode
## Show Notes
- Compile links
- Choose title [[Cohosts]]
- Write show notes
## Finish
> [[Release Date]]
- Publish episode // https://mypodcastcms.fm
- Upload MP3
- Add show notes
- Publish
- Tweet link
- Archive project
[[Cohosts]]: @Alice @Bob
[[All Hosts]]:
- Me
- Alice
- Bob
This template will now ask for an episode number and a release date when it is run through the Thing Builder and include them in the created project.
Note: There is a cascading logic to attributes in batch blocks and on individual tasks—that is, an attribute on a task (such as a deadline) will override the same attribute at the top of the block (except in the case of tags, which are additive).
There is one more way to run the Thing Builder shortcut: from within another shortcut. This means that dedicated shortcuts can be created with embedded text and any other logic or prompts, and then the resulting text (including Shortcuts’ magic variables) can be passed to the Run Shortcut action for the Thing Builder to process.
I have a version of the podcast episode project above in a “Build Episode Project” shortcut, which pulls in the current episode number from Data Jar (tied into other automations) and confirms it and the publish date (with a calculated default value) before proceeding. I also have a packing list shortcut with several Choose From List actions and some date math, and a set of project templates I use for my day job, which are stored in Data Jar and provided for me to choose from in yet another shortcut.
Thing Builder & Documentation ©2021 Sean Lunsford