Action Step: Script

Script action steps allow you to manipulate a draft, and perform basic logical operations effecting the action being performed, and the draft itself. The scope of what is possible with Script steps is limited, they are not intended to be a full scale scripting engine.

Script steps are written in JavaScript and have access to all basic JavaScript library functions (including Regular Expressions) and a few special methods and objects created by Drafts.

The library of special Drafts functions will likely grow over time, but is basic for the initial release.

The best way to start learning about scripting in Drafts is to download some examples from the Drafts Action Directory.

The "draft" Object

The current draft upon which the action is being performed is exposed to the script step JavaScript context as a "draft" object. The draft object has properties which correspond to the values of the draft. In some cases, not all of these properties have values – for example, if an action is being performed via URL scheme on a text without a draft stored in the Drafts database.

Properties on the draft object can be manipulated within the script. For example, the "content" property contains the text of the draft, and assigning a new string value to "draft.content" will alter that value.

Changes to the "draft" object by the script step will exist for the life of the current action, unless a call to "draft.commit()" is made at the end of the script step to persist these changes. This means you can safely manipulate the draft content in ways which you only wish to apply to action steps occurring after the script step within the same action. For example, performing a Regular Expression search to pull all links from a draft and list them. A script step at the beginning of the Action could create this list, set "draft.content" to the new string, then a second action step could save that result to a file in Dropbox – all without changing the original draft.

If you want to save the changes, just call "commit(draft)" in the script step.

"draft" Object Properties

• content: The text content of the draft.
• createdDate: Date the draft was created.
• createdLatitude/createdLongitude: Location coordinates of draft creation.
• modifiedDate: Date the content of the draft was last changed.
• modifiedLatitude/modifiedLongitude: Location coordinates for last modification of draft content.
• accessedDate: Date the draft was last opened, even if the content was not changed.
• selectionStart: The location in the string where the last cursor selection in the editor started.
• selectionLength: The length (in characters) of the last cursor selection in the editor.
• archived: Boolean value to get/set whether the draft has been archived.
• flagged: Boolean value to get/set the flagged status of the draft. 
• uuid: The unique identifier of the current draft. It is possible this will be a temporary value for drafts that are not saved to the database.

"draft" Object Functions

• defineTag(tagName, tagString) : Define a custom template tag for use in action steps happening later in the same action. For example, a script step could calculate the number of words in a draft, then call "draft.defineTag("wordCount",100)". Action steps occurring after the script step in the same action would be able to use "[[wordCount]]" as a tag in their templates and have it evaluated to the value defined in the script step. 
• getTag(tagName) : Returns the current value of a custom tag defined elsewhere, for example in a prompt step in the same action, or in another script step.
• processTemplate(template) : Runs the passed template string through the Drafts template engine, expanding any standard [[]] drafts tags, encoding, markdown and even expanding fenced TextExpander snippets.

Other Utility Functions

• commit(draft) : Persist changes made to the draft object to the database. By default, changes will only exist in the life span of the current action, calling commit() will permanently update the draft.
• getClipboard(): Returns current contents of the system clipboard.
• setClipboard(string): Set the system clipboard to the string passed.
• alert(message) : Show message dialog with message, similar to standard Javascript browser alert.
• stopAction() : Set a flag to stop further execution of steps after the current script step within the Action.  This can be used to validate inputs in a script, and cancel execution of the action if it does not fit the requirements.
• cancelAction() : Similar to 'stopAction' but will stop further execution of the action without an error.
• markdown(string, useXHTML) : Returns string converted to HTML through the Markdown engine. If "useXHTML" is true, output will be XHTML complaint (useful for Evernote ENML compatibility), otherwise HTML5 output will be used.
• encodeHTMLEntities(string) : Encodes the string to HTML safe entities, e.g. converting & to &
• decodeHTMLEntities(string) : Decodes HTML entities.