Introducing TADpoLe

10 Jul 2020

I’ve been a user of the Drafts app for many years, and while I have written some posts and regularly try to help people out on the Drafts forum, I’m quite excited to be sharing the first of a couple of bigger Drafts related projects I’ve been working on. In fact this one has effectively been years in the making, and is finally in a form where I think it is fit for sharing; though time will tell as to how true that really is. One can never truly tell until that first step is taken. Today, I’m releasing something called “TADpoLe”.

What is TADpoLe?

Well, TADpoLe is the name of a new JavaScript library for use with Drafts. The library is based on functions I’ve written over the past few years to accomplish tasks in Drafts. The functions have been built around standard Drafts objects and a few library-specific classes. In total there are over 300 functions in this first release, and they vary in their complexity, but they have been built as much as possible with re-use in mind.

Library Documentation

In order to try and make this as familiar and accessible to Drafts users as I can, I’ve also developed a set of documentation alongside the library in the same format as the Drafts scripting reference. This documentation is available at a new sub-site, tadpole.thoughtasylum.com.

Every function and class is documented. This includes details of parameters and returns as well as a description of what the function is doing, and a simple example showing the function being used.

Of course, at the time of writing, this is a first release, so I may have a few spelling errors and inconsistencies to pick up on. Any rough edges will be smoothed out over time.

The home page of the sub-site also contains lots of additional information about the library such as licensing, an FAQ and some specifics about some of the functionality areas it includes. If you plan to make use of the library directly, then I would recommend having a read through those details.

Example Actions

As I noted, I’ve created this library out of my own needs, so there have been practical drivers behind all of it. While I’m not sharing all of my personal actions, the good news is that there is a Drafts action group . The action group fulfils several purposes.

1. It is a way to share some examples of how the library can be utilised.
2. It provides a way to keep the library updated - there’s an action to refresh the library.
3. It provides a way for those who won’t be using the library directly to make use of many of the functions in the library.
4. It gives me a single way of managing actions to share with people.

While I’ve probably shared many dozens of Drafts actions in the forums and on social media over the last few years, most of them I have placed as unlisted as they were often tailored to specific needs. With this action group I’m finally switching to publishing something to the masses. I know it’s long past time, but my intention right from the start has been to do it this way, and it has simply taken this long to have the requisite tasks bubble through on my to-do list.

The ThoughtAsylum Action Group, is available now from the Drafts Action Directory.

Before you start using the action group it is essential that you run the "TAD-Setup/Refresh" action. This downloads the latest TADpoLe and supporting libraries to iCloud for the actions to utilise. Not every action in the group uses this library, but the majority do.

It contains over 275 actions in over 40 action groups, which I think might well make it the biggest action group in the directory. Trying to understand what everything does however probably needs a little bit of additional explanation.

First of all, while every action has a description, this isn’t great for browsing as you have to edit each action to view it. To that end you can browse a list of all of the action details right here on this site.

Secondly, there will be some actions that are more involved than a brief description might be able to get across. I’ll be writing some blog posts about these that will hopefully fill in some of the details. I’m going to try and get some of the more significant ones out as soon as I can after release, and you can keep an eye on the site for those, and they will all be linked from the TADpoLe overview page.

I expect that as soon as you start browsing the list or the group, that you will spot that every action in the group begins with “TAD-”. I realise that isn’t exactly user friendly, but it serves a particular purpose in readily identifying these actions as part of this action group beyond the filtering provided by search. This in turn is useful for the purposes of inclusion referencing.

Apart from during testing, or on an ad hoc basis, I do not use the actions in this action group directly, but I do use the actions from calling actions in other groups. It is through these other actions that I build action groups for keyboard rows and assign shortcut keys. By creating a calling action and giving it all of the properties I want for that particular group, I can include an action from the ThoughtAsylum action group and have it run those action steps. I can then include the same action in multiple places with one single source to maintain. By having the “TAD-” prefix I know that the action comes from this action group rather than one of my others (yes I have other action groups a bit like this for more personally tailored activities).

Based on this, I have a few pieces of advice for using the group.

1. Always leave the action group alone, then when I push updates to the action directory you can update it without it affecting anything you have modified.
2. Do pick and choose the actions you want to use, and then create your own action groups (remember you can call an action from many other actions in many other groups) that contain simple actions that just include the actions you wish to use from the ThoughtAsylum action group.
3. If you want to tailor an action, duplicate the existing one, copy it to your own action group and tailor it there. Consider setting up your own reference library action group like this one if you might use it in multiple places.

This approach should keep everything clean and isolated. You should be able to get all of the benefits the action group may be able to offer both now and in the future, without any risk of losing your own personalised configurations; though I would always recommend that you have regular backups enabled in Drafts’ settings just in case

Conclusion

It’s early days, and I’m sure there will be some things to iron out around the code and the documentation, but every journey begins with the first step. I still have many actions that are in various states of clarity that I’d like to get into the library, and I have an ever growing list of ideas of things I intend to create at some point that will no doubt see their way into being included as well.

I personally get benefit from the library and the associated actions every single day. But that’s very much expected, I created the vast majority of them for me. The only question I have is can my efforts be a benefit to others too. I hope the answer is yes, and publishing these today is how I’ll find out.