Options
All
  • Public
  • Public/Protected
  • All
Menu

ThoughtAsylum Drafts Library

Welcome

  1. Overview
  2. How-To Information
  3. FAQ
  4. Licensing
  5. Authors
  6. Legal Disclaimer
  7. Change Log

Overview

The ThoughtAsylum Drafts Library, also known as TADpoLe, is a collection of JavaScript for working with the Drafts application. They cover a broad range of areas, and will no doubt continue to grow over time. The library was built over the course of several years to meet the author's personal needs to build out more functionality in the Drafts application through it's actions framework, and in particular through the script (JavaScript) action step.

Being a JavaScript developer is not his day job (nor has it ever been); so it is very much a piece of work that is provided as-is and perhaps doesn't adhere to the coding styles and structures that others may use.

The library began construction in 2018 when Drafts 5 was released, and has been reworked several times and grown substantially in the intervening years. The expectation is that it will continue to grow and updates will be posted here when they are suitable for a public release.

At initial release in July 2020, the library contents came in at over 300 functions associated with standard JavaScript objects, Drafts objects, and some TADpoLe specific classes.

How-To Information

Using this Site

This site provides the documentation for the TADpoLe library as well as the library file itself. It is purposefully provided in a similar format to the Drafts scripting resource, and in a similar way you can review each class by selecting one of the links. Within each you will find a variety of properties and functions. Many of the functions are extensions of existing JavaScript or Drafts objects, and all library functions are prefixed TA_ as an identifier.

Functions provide details of the functionality, parameters, returns, and a simple example. Some functions also provide some more detailed sets of information about their use. Properties and classes unique to the library are similarly described with what we hope is enough detail for them to make sense and be used.

Additional Information

Additional pages of information on how to use specific parts of the library will be published over time at ThoughtAsylum.com. Links back to the most relevant posts and pages on ThoughtAsylum will be added here. In addition if you come up with any interesting use cases or how-to guides utilising the library, direct message @sylumer on the Drafts forums with the details, and they might just get included here.

Action Group Suite

The main way that most users will gain access to the library will be through the use of the suite of ThoughtAsylum Action Groups, available from the Drafts Action Directory.

TypeScript Declaration File

Many editors and IDEs accept TypeScript declaration files as inputs to allow intellitype-style features. A TypeScript definition file for this library is available for download. It should always match the details in the latest version.

Download TypeScript Declaration File

JavaScript File

The JavaScript file that contains all of the code for the library can be downloaded directly from this site, but generally we would advise utilising the ThoughtAsylum Action Group to get the latest copy of the library.

Download JavaScript File

Configuration File

The library makes use of a configuration file that applies across many of the functions and directly influences the way some functions operate, and the data available to other functions. The configuration file is in JSON format, and the details can be found in the TadLibrary class section in regards to what all of the library settings/TadLibrary properties are. The file itself is stored by convention in /Library/Scripts/tad.json in the Drafts iCloud directory structure.

If you wish to tailor a value from it's current value, simply edit the value as you might any other JSON file.

JavaScript Beautifier Configuration

The JavaScript beautifier functioality relies on the js-beautify library, and utilises the settings associated with that.

For additional details, take a look at the TA_devBeautifyJSDraft function documentation.

FAQ

1. Why is the library called "tadpole"?
The library name is "TADpoLe". The "TA" refers to thoughtasylum.com, the personal website of the author. The "D" is for Drafts, and the "L" is for library. The other letters just fill in some gaps to make it easier to reference, and hopefully make it a little more memorable.

2. Why do the functions start "TA" rather than "TAD", or "TADL" then? Honestly, the library came later and at first it was just going to be a "ThoughtAsylum" library, so it started out as TA. The library naming came much (years) later, and so the "TA" prefix has been kept, and it's also just a little bit shorter for peopel to type.

The point of having it in the first place is to hopefully avoid namespace clashes with functions users might already have written that would otherwise have the potential of genearting namespace clashes.

3. What is the licensing for this library?
See the licensing section section below, but basically it is free to use and re-use.

4. Are there any actions you could share that use the library?
Why yes there is, I guess you skipped over the action group section above. Go back and take a look.

5. I've found a bug, what should I do?
The library is shared on a best efforts basis, and is provided as is. If you have an honest to goodness bug, post to the Drafts forum and tag @sylumer with a simple example that can allow anyone to reproduce the issue. Be sure to provide any example content to prime the example, well formatted code (i.e. put your JavaScript between triple backticks) or a link to a shared action, along with a description of what you are seeing and what you would expect to see.

6. I'd like a function to work differently, what should I do?
Take a copy of the TADpoLe function, change it to do what you want it to, and then include it in your own projects.

Make sure that you save this in your own library file, otherwise, if you update the TADpoLe library, you'll lose your code as the file is oevrwritten. This also stops any issue of mis-attribution if you subsequently share your code.

6. I'd like some help on using the library functions, what should I do?
If you can't figure it out yourself, consider posting to the Drafts forum and seeing if someone there can help you. Be sure to be make your request specific and not boundless or asking for someone else to do all the work for you.

Licensing

TADpoLe is Coffeeware. You are free to make use of this library as long as you like and as much as you like. You owe us nothing.

But, if you do want to give a little, all development is fuelled by coffee, and you can make a donation to the author's coffee fund.

Donate a coffeeDonate a coffee

Please also take the time to read the legal disclaimer below.

Third Party Additions

There are a handful of additional components used by this library, and we would thank the authors for making their code available, and we provide further information about their licensing details here.

JS Beautifier

JavaScript Beautifier is used for the JavaScript formatting functionality.

JS Beautifier (minified) https://github.com/beautify-web/js-beautify

The MIT License (MIT)

Copyright (c) 2007-2017 Einar Lielmanis, Liam Newman, and contributors.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

To Title Case

The String extensions section include a function to convert to title case. This function is a slightly modified version of the To Title Case (v2.1) by David Gouch.

To Title Case 2.1 – http://individed.com/code/to-title-case/
Copyright © 2008–2013 David Gouch. Licensed under the MIT License.

Authors

Author Web Site E-mail Twitter Handle Drafts Forum Handle
Stephen Millard thoughtasylum.com Rarely checked 😬 @sylumer @sylumer

Legal Disclaimer

This library is shared publicly to help others and to contribute back to the wider Drafts community. You may use, and copy small (up five functions) amounts and distribute it with your own code without any need to reference (though references are appreciated). Anything larger and you should distribute with the library and appropriate references back to it so as to enable the recipient to keep up to date with the original content.

Any modifications or derivative works based on any proportion of this library, must carry a notice stating that you changed the software and should note the date and nature of any such change. Please explicitly acknowledge this site as the original source of the library.

This library is expressly provided "AS IS." WE MAKE NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED, IN FACT OR ARISING BY OPERATION OF LAW, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND DATA ACCURACY. WE NEITHER REPRESENTS NOR WARRANT THAT THE OPERATION OF THE CODE WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT ANY DEFECTS WILL BE CORRECTED. NIST DOES NOT WARRANT OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF THE SOFTWARE OR THE RESULTS THEREOF, INCLUDING BUT NOT LIMITED TO THE CORRECTNESS, ACCURACY, RELIABILITY, OR USEFULNESS OF THE CODE.

You are solely responsible for determining the appropriateness of using the library and you assume all risks associated with its use, including but not limited to the risks and costs of errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and the unavailability or interruption of operation. This library is not intended to be used in any situation where a failure could cause risk of injury or damage to property.

Basically, we use this ourselves, we're sharing it publicly so others may benefit, please don't pass the effort put into this off as your own, and while we guarantee nothing regarding use, we really hope that you find it useful in processing your drafts, and remember to always keep good backups just in case.

Change Log

2020-10-10

  • New: Editor - functions for adding and removing text to lines while retaining the same effective selection - TA_prependLinesRetainSelection(), TA_unprependLinesRetainSelection(), TA_appendLinesRetainSelection(), TA_unappendLinesRetainSelection().
  • New: Editor - functions for working with the sections created by navigation markers - TA_sectionGetContentByIndex(), TA_sectionGetContentByHeading(), TA_sectionGetIndexesForHeading(), TA_sectionWrapByIndex(), TA_sectionAppendByIndex(), TA_sectionPrependByIndex(), TA_sectionWrapByHeading(), TA_sectionAppendByHeading(), TA_sectionPrependByHeading(), TA_sectionHeadingByIndex(), TA_sectionBodyByIndex(), TA_sectionBodyByHeading(), TA_sectionGetHeadings().
  • New: Prompt - TA_promptButtonArrayIndexed() - get the index of selected button from an array of buttons in a prompt.
  • Update: Prompt - modifified some code to compact some simple conditionals down to single lines to aid readability.
  • Doc Fix: Editor - TA_isTextSelected() - typo in function name.
  • Doc Fix: Editor - TA_mdScriptSelectedText() - typo in function description.

2020-09-28

  • Doc Fix: Workspace - TA_selectWorkspace() - added some more details about return on cancel.
  • Bug Fix: Workspace - TA_selectLoadWorkspaceByButton() - correction of a length to a null check on cancel of workspace selection. (FlohGro)

2020-09-27

  • New: Action - TA_getAllActions() - class method to retrieve action objects for all installed actions.
  • New: Action - TA_actionPopulateMore() - populates an action with several additional properties (also documented in the class).
  • New: App - line based content insertion functions - fileImporterBasic(), fileImporterTagEnabled().
  • New: Draft - file import functions - TA_addAfterLine(), TA_addAtStartOfLine(), TA_addAtEndOfLine().
  • New: Draft - TA_tagAddArray() - add an array of tags to a draft.
  • New: Math - TA_isOneIn() - generates Boolean based on a 1 in N chance of occurrence.
  • New: String - functions for purposefully adding corruptions to text for checking spell check, etc. - TA_mistypeSlip(), TA_mistypeSlipQWERTY(), TA_mistypeSwitch().
  • New: String - functions for working with simple front matter content - TA_frontMatterIncluded(), TA_frontMatterSimpleKeyValue().
  • New: String - functions for removing text from the start and end of a string - TA_startsWithRemove(), TA_endsWithRemove().
  • New: String - TA_randChar() - generates Boolean based on a 1 in N chance of occurrence.
  • Update: Library file now built to includes additional markers denoting what sub-module file was used in populating a section of the library file.
  • New: String - TA_csvToArray() - converts comma separated values to an array with better reliability than a split(",") alone would provide.
  • Update: Draft - TA_tagAddCSV() modified to utilise TA_tagAddArray().
  • Doc Fix: Added description for TadLibrary.metaPath.
  • Doc Fix: Revised some of the descriptions around Draft.TA_meta*() functions.
  • Doc Fix: Various typo corrections across the site.

2020-09-05

  • New: TadHTMLPrompt - new class for displaying some standardised HTML Prompts.
  • New: TadLibrary - new back link related settings.
  • New: ActionGroup - functions for returning count information about all action groups - TA_actionGroupCounts(), TA_actionGroupActionCount(), TA_actionGroupSeparatorCount().
  • New: ActionGroup - functions for returning information about an action group - TA_actionNames(), TA_separatorNames().
  • New: App - TA_toggleThemeMode() - switches the app theme between light and dark.
  • New: App - functions for returning count information about all action groups - TA_actionGroupCounts(), TA_actionGroupActionCount(), TA_actionGroupSeparatorCount().
  • New: App - functions for returning information about and across action groups - TA_actionNames(), TA_actionGroupNames(), TA_getActionGroupActionNames(), TA_getActionGroupSeparatorNames().
  • New: Draft - TA_backLinkAdHoc() - display a list of drafts that backlink to a draft using any of the wiki-link methods, along with some draft data, and allow the user to select to load a draft.
  • New: Draft - TA_backLinkSectionInsertLink() - insert a draft wiki-style cross-link into a special back-link section of a draft; useful to create a back-link when also creating a fore link in another draft.
  • New: Draft - TA_bodyFirstNonBlankLine() - return the first non-blank line in a draft, after the title.
  • New: Draft - TA_mdTitleLinks() - convert unlinked URLs in a draft to Markdown links using the page title of the URL as the link text.
  • New: Draft - functions for version counts - TA_versionCount(), TA_versionCountMax(), TA_versionDraftMax().
  • New: Editor - TA_isTextSelected() - check function for if any text is currently selected in the editor.
  • New: Editor - TA_loadAcUUID() - load draft with specified UUID into editor and activates.
  • New: Editor - functions for expanded copy & paste - TA_extendedCopy(), TA_extendedCut().
  • New: String - TA_mdTitleLinks() - convert unlinked URLs to Markdoown links using the page title of the URL as the link text.
  • New: String - TA_removeMDHeader() - remove Markdown heading markers from a string.
  • New: String - TA_trimToSnippet() - trims a string down to a maximum length and adds an ellipsis to indicate it was longer, where necessary;
  • Update: Draft - TA_draftCountSummary() - now includes count information for Action Groups, a little draft versions information, and a typo correction.
  • Update: HTTP - TA_getTitleFromURL() - now trims whitespace from the title.
  • Doc Fix: Various typo corrections across the site.

2020-08-08

  • New: TadLibrary - testLibsAlert - added a new property to allow the test libraries alert to be disabled as it can slow things down if you use the library functionality a lot.
  • New: TadMiscellaneous - additional code execution functions - TA_devExecuteRunSelection(), TA_devExecuteRunSelectedLines(), TA_devExecuteRunCurrentDraft().
  • New: TadMiscellaneous - TA_playSoundPath() and TA_playMP3Data() - triggering of audio playback (Mac only).
  • New: TadMiscellaneous - TA_decimalSeparator() - returns the decimal separatror character.
  • New: App - additional clipboard management functions - TA_clipboardAppend(), TA_clipboardPrepend(), TA_clipboardEmpty().
  • New: Draft - functions for working with custom, peristent, meta data for a draft: TA_metaInit(), TA_metaSave(), TA_metaTag().
  • New: FileManager - functions to work with files where a file path is associated with a draft in its meta data - TA_fileMetaPath(), TA_fileMetaSave(),
  • New: Math - TA_frac() - get the fractional part of a number to "reasonable" precision.
  • New: String - functions for removing lines that match or don't match a substring: removeLinesStarting(), removeLinesNotStarting(), removeLinesEnding(), removeLinesNotEnding(), removeLinesContaining(), removeLinesNotContaining(), TA_fileMetaLoad();
  • New: String - TA_removeTrailingNewlines() - removes new line characters from the end of a string.
  • New: Workspace - TA_loadWorkspaceNext() & TA_loadWorkspacePrevious() - allow cycling through workspaces in the order defined in Drafts.
  • Update: TadLibrary - TA_libraryTestLibLoad() - now uses testLibsAlert to determine if testing should be alerted to on each run.
  • Doc Fix: TadMiscellaneous - TA_JSONArraySorter() - missing documentation added.
  • Doc Fix: Math - TA_randInt() - correction of example.
  • Doc Fix: Various typo corrections across the site.

2020-08-01

  • New: TadConsole - new log entry retrieval functions TA_filterLog(), TA_filterLogEntry(), TA_filterLogEntries(), TA_logEntryFirst(), TA_logEntryLast(), TA_logEntryFirstType(), TA_logEntryLastType(), TA_logEntryFirstCode(), TA_logEntryLastCode(), TA_logEntryFormat().
  • New:TadLibrary property, encodeMap used to define a set of URL encoding mappings for a new string function.
  • New:TadLibrary - TA_buildLibraryAction() used to rebuild the libarry action from file. Doing it by hand occasionally crashes the Mac app because the script step is so large. Doing this programmatically without dabbling in the UI gives a much quicker result with vastly reduced risk of crashing.
  • New: TadMiscellaneous - TA_JSONArraySorter() - JSON array sort comparator function.
  • New: Prompt - TA_confirm() - confirmation prompt that allows the user to selecte a yes/no response.
  • New: String - new overwriting and inserting functions: TA_overwriteRange0(), TA_overwriteRange1(), TA_insertAfter0(), TA_insertAfter1().
  • New: String - TA_replaceAllMap() - carries out a set of multiple text replacements based on a set of key value pairs.
  • New: String - TA_encodeURI() - applies a more extensive and extensible range of URL encoding than encodeURIComponent().
  • Update: Prompt - TA_promptButtonArray() - added an optional parameter to hide the cancel button.
  • Bug Fix: TadConsole - TA_saveLog() - fixed attempt to capture draft version information before first draft has been created. (BJB)
  • Bug Fix: Prompt - TA_promptButtonArray() - fixed message entry not displaying.
  • Doc Fix: TadConsole_logEntry - Corrected description.
  • Doc Fix: Various typo corrections across the site.

2020-07-25

  • New: TadConsole - new class for advanced console-like logging.
  • New: Math - TA_randInt() - generates a random integer between two values (inclusive).
  • New: Editor - new word wrapping functions: TA_selectionPrependWords(), TA_selectionAppendWords(), TA_selectionWrapWords(), TA_selectionDelimitWords().
  • New: FileManager - TA_delete() - file deletion.
  • New: FileManager - TA_snapshot() - timstamped file duplication.
  • New: HTTP - TA_quoteSimpsons() - access The Simpsons quote generator to get a random character quote.
  • New: String - new word wrapping functions: TA_prependWords(), TA_appendWords(), TA_wrapWords(), TA_delimitWords().
  • New: String - new file path functions: TA_fileNameFromPath(), TA_fileNameBaseFromPath(), TA_fileNameExtensionFromPath(), TA_fileNameRemoveExtensionFromPath(), TA_folderPathFromPath().
  • New: TadMiscellaneous - TA_getTimestampyyyyMMddhhmmssxxx() - generates timestamps accurate to milliseconds.
  • New: TadMiscellaneous - TA_uuidv4() - UUID generator.
  • Update: TadMiscellaneous - TA_getTimestampyyyyMMddhhmmss() - changed to use a better element padding technique.
  • Bug Fix: Draft - TA_selectRecentTagRename() - Corrected to include display summary information parameter described in documentaion.
  • Bug Fix: Draft - TA_selectAnyTagDelete() - Corrected to include display summary information parameter described in documentaion.
  • Bug Fix: Draft - TA_selectRecentTagDelete() - Corrected to include display summary information parameter described in documentaion.
  • Doc Update: Revisions across the library to display Optional label against optional function parameters.
  • Doc Fix: Draft - TA_tagAddCSV() - Corrected example to not use a single item array as the parameter.
  • Doc Fix: Draft - TA_draftNew() - Corrected example to include an example parameter.
  • Doc Fix: Draft - TA_dictateList() - Corrected to include some missing parameter definitions.
  • Doc Fix: HTTP - TA_randomInteger() - Added missing details about parameters.
  • Doc Fix: Prompt - TA_promptButtonArray() - Corrected to specify that p_strMessage parameter can be set to an empty string, but is not an optional parameter.
  • Doc Fix: Prompt - TA_doubleTextFieldPrompt() - Corrected to specify that default value parameters can be set to be empty strings, but are not optional parameters.
  • Doc Fix: String - TA_capitalise() - Corrected structure of the example.

2020-07-14

  • Bug Fix: Fix for duplication of '.js' on library naming. (FlohGro)

2020-07-12

  • Bug Fix: Re-added TadCommand class to library build scripts for rebuild and redistribution.

2020-07-10

  • Initial release.