Bookmark objects are used to work with folder bookmarks and the FileManager object to provide access to folders outside the Drafts App Sandbox. Bookmarks are unique by name. A user-friendly name should be used, as the first time a bookmark is required, the user is prompted to select the folder in their file system to associate with the bookmark, and a useful name can help guide them to selecting the correct folder.

Learn more about Bookmarks in the User Guide

Example

// find or create a named Bookmark
let bookmark = Bookmark.findOrCreate("My-Folder");
let fm = FileManager.createForBookmark(bookmark);

// write to a file at the root of the bookmark folder
let success = fm.writeString("/ScriptedFile.txt", "This is the file * content");

// read from file in bookmarked folder
let content = fm.readString("/Test Folder/Test.txt")

Credential objects can be used in actions which require the user to provide a username, password and optionally a host name, to connect to a service. By using credentials objects, actions can be written to connect to arbitrary web services without hard coding credentials into the action.

When an authorize() call is made on a credential object for the first time, the user is prompted to enter their credentials, then Drafts stores those for later use. When the action is used again, there will be no prompt required and the stored credentials will be used.

Credentials objects have unique identifiers, and a single set of user credentials can be used across actions by using the same identifier.

The user can delete those credentials at any time by visiting Settings > Credentials and tapping the "Forget" button on a service.

Example

var credential = Credential.create("My Service", "Description of the service to  * appear in user prompt.");

credential.addTextField("username", "Username");
credential.addPasswordField("password", "Password");

credential.authorize();

var http = HTTP.create();
var response = http.request({
"url": "http://myurl.com/api",
"username": credential.getValue("username"),
"password": credential.getValue("password"),
"method": "POST",
"data": {
"key":"value"
},
"headers": {
"HeaderName": "HeaderValue"
}
});

Calendar objects are used to manipulate and create calendars in the built-in Calendars app and its associated accounts.

Example: Event Creation

var calendar = Calendar.findOrCreate("Activities");
var event = calendar.createEvent();
event.title = "Dinner Party";
event.notes = "Bring side dish.";
event.startDate = Date.parse("7pm next friday");
event.endDate = Date.parse("10pm next friday");
event.isAllDay = false;
if (!event.update()) {
  console.log(event.lastError);
}

Example: Reading Calendar Events

// load a calendar
let cal = Calendar.find("Test");
// loop over events in the last 30 days and alert the name of each.
if (cal) {
    let events = cal.events((30).days().ago(), new Date());
    for (let event of events) {
        alert(event.title);
    }
}

CallbackURL objects can be used to open x-callback-url requests and wait for a response from the target app.

NOTE: If you want to open a URL in Safari or another app and do not need a response or x-callback-url support, use the app.openURL(url) method on the App object.

Example

// Open callback URL for each line in a draft
// Setup base Fantastical URL, with no parameters
const baseURL = "fantastical2://x-callback-url/parse/";

// split draft and loop over lines
var lines = draft.content.split("\n");
for (var line of lines) {
// create and configure callback object
var cb = CallbackURL.create();
cb.baseURL = baseURL;
cb.addParameter("sentence", line);
// open and wait for result
var success = cb.open();
if (success) {
console.log("Event created");
}
else { // something went wrong or was cancelled
 console.log(cb.status);
 if (cb.status == "cancelled") {
context.cancel();
}
else {
context.fail();
}
}
}

A single global "context" object is available to scripts to control flow of the currently running action.

It is important to understand that cancel() and fail() will not immediately stop script, just stop any further action steps from being performed.

Example: Control Flow

// test for logical condition before continuing
if (!validationCondition) {
  context.fail();
}
// code below will still run.

Example: Retreive values

// if a "Run Workflow" step preceded this script, lets look for a result
var response = context.callbackResponses[0];
if (response) {
  // Workflow returns one "result" parameter, other apps may use other values.
  var result = response["result"];
  if (result) {
    // so something with the result
  }
}

Dropbox objects can be used to work with files in a Dropbox account. The read and write methods are simple wrappers for uploading and reading content of files on Dropbox.

For advanced uses, the rpcRequest, contentUploadRequest and contentDownloadRequest methods enable direct use of any Dropbox API 2.0 endpoints. These methods are an advanced feature which return raw results from the Dropbox API and may require advanced understanding of the API to process the results. They do enable full access to the API, however, which enabled things like querying files, listing folder contents, uploading to Paper, etc. For details on availalbe methods, see Dropbox API documentation. In the case of all of these methods Drafts takes care of the OAuth request signing and authentication process when necessary.

Example

// create Dropbox object
var db = Dropbox.create();

// setup variables
var path = "/test/file.txt";
var content = "text to place in file";

// write to file on Dropbox
var success = db.write(path, content, "add", true);

if (success) { // write worked!
var dbContent = db.read(path);
if (dbContent) { // read worked!
if (dbContent == content) {
 alert("File contents match!");
}
else {
 console.log("File did not match");
 context.fail();
}
}
else { // read failed, log error
console.log(db.lastError);
context.fail();
}
}
else { // write failed, log error
console.log(db.lastError);
context.fail();
}

A global editor object is available in all action scripts. This object allows manipulation of the main editing window in Drafts, altering the text, text selections, or loading a different draft into the editor, etc.

Typically scripting actions that work like custom keyboard commands and similar will utilize the editor functions to manipulate text.

NOTE: Generally speaking, editor methods are best used for quick text manipulations of the type used in the extended keyboard. Most substantial updates to draft content are better applied using the draft object.

Helper methods to escape and unescape HTML entities in a string.

Added: R15

Examples

let s = "<One> & Two";
let escaped = HTML.escape(s); // "&#x3C;One&#x3E &#x26; Two"
let unescaped = HTML.unescape(encoded); // "<One> & Two"

Event object represent individual calendar events. For usage examples, see Calendar object documentation.

Display of HTML Preview window, the same as the HTMLPreview action step. Returns true if user closed preview with the "Continue" button, false if the user cancelled.

Example

let html = "<html><body>My Document</body></html>"

let preview = HTMLPreview.create();
if (preview.show(html)) {
// continue button was pressed
}
else {
// cancel button was pressed
}

The OutlookMessage object can be used to create and send mail messages through Outlook.com integrated accounts, similar to those created by a Outlook action step. Creating and sending these messages happens in the background, with no user interface, so messages must be complete with recipients before calling send(). Sending is done via the Microsoft Graph API. Outlooks accounts are authenticated when used for the first time using OAuth - to use more than one account, call create with different identifier parameters.

Example

let message = OutlookMessage.create();
message.toRecipients = ["joe@sample.com", "Jim Test <jim@test.com>"];
message.subject = "My test message";
message.body = "Body text";

var success = message.send();
if (!success) {
console.log("Sending outlook message failed");
context.fail();
}

Drafts includes a full version of the MultiMarkdown 6 engine to render Markdown text to HTML and other supported formats. For details on the meaning of the various options, refer to MultiMarkdown documentation.

Example

var inputString = "# Header\n\nMy **markdown** text";
var mmd = MultiMarkdown.create();

mmd.format = "html";
mmd.criticMarkup = true;
var outputString = mmd.render(inputString);

Wraps an array of todo and/or project items and encodes them into a URL for use to send the request to Things.

Things Integration Notes

• Things is a popular task and project management app from Cultured Code. Things supports advanced URL schemes (required Things v3.4 or greater on iOS) which can accept multiple todos, projects, headings in a single call to the app. The scripting interfaces below are convenience wrappers that allow easy creation and encoding of the URLs needed to pass this type of information to Things.

The TJS* JavaScript objects are wrappers around an open source Swift library provided by Cultured Code, with a few modifications to work in JavaScript. In all cases, nothing is committed to Things until the the items are wrapped in a TJSContainer, and the URL it generates called to send the data to Things. This is best done with Drafts’ CallbackURL object (see example below).

For more information about what values Things understands in these objects, refer to their URL scheme documenation.

Example

// create a Things Project
var project = TJSProject.create();
project.title = "My Project From Drafts";
project.notes = "Let's do this stuff";

// create and add a heading to the project
var heading = TJSHeading.create();
heading.title = "First Heading";
project.addHeading(heading);

// add todos to the project
var todo1 = TJSTodo.create();
todo1.title = "My first todo";
todo1.when = "today";
project.addTodo(todo1);

var todo2 = TJSTodo.create();
todo2.title = "My second todo";
todo2.when = "tomorrow";
project.addTodo(todo2);

// create a container to handle creation of Things URL
var container = TJSContainer.create([project]);

// Use CallbackURL object to open URL in Things.
var cb = CallbackURL.create();
cb.baseURL = container.url;
var success = cb.open();
if (success) {
console.log("Project created in Things");
}
else {
context.fail();
}

GoogleDrive objects can be used to work with files in Google Drive accounts.

Example

// create GoogleDrive object
var drive = GoogleDrive.create();

// setup variables
var fileName = "MyTestFile";
var parent = ""; // root of drive
var content = "text to place in file";

// write to file on GoogleDrive
var success = drive.write(fileName, parent, content);

if (success) { // write worked!
var driveContent = drive.read(fileName, parent);
if (driveContent) { // read worked!
if (driveContent == content) {
 alert("File contents match!");
}
else {
 console.log("File did not match");
 context.fail();
}
}
else { // read failed, log error
console.log(drive.lastError);
context.fail();
}
}
else { // write failed, log error
console.log(drive.lastError);
context.fail();
}

Drafts includes Discount-based, GitHub flavored Markdown parser based on GHMarkdownParser. For details on the meaning of the various options, refer to Markdown documentation.

Example

var inputString = "# Header\n\nMy **markdown** text";
var md = GitHubMarkdown.create();

var outputString = md.render(inputString);

Drafts defines a single global device object which provides access to information about the current device.

Examples

// get system info from device object
var model = device.model;
var system = device.systemName;
var osVersion = device.systemVersion;
var batteryLevel = device.batteryLevel;

// create and display it in an alert
var s = "Model: " + model + "\n";
s = s + "System: " + system + "\n";
s = s + "OS: " + osVersion + "\n";
s = s + "Battery: " + batteryLevel;
alert(s);

// branch logic based on platform
if (device.systemName == 'macOS') {
// do something only on Mac
}
else {
// do something only on iOS
}

Script integration with Notion. This object handles OAuth authentication and request signing. The entire Notion REST API can be used with the request method.

Example

// list pages which have been shared with the Drafts integration
// API Docs: https://developers.notion.com/reference/post-search
let endpoint = "https://api.notion.com/v1/search"

let notion = Notion.create();
let result = notion.request({
"url": endpoint,
"method": "POST",
"data": {
"filter": {
"value": "page",
"property": "object"
}
}
});

// result has JSON payload
// with page properties
if (result.statusCode == 200) {
alert(`Notion Pages Loaded:

\({result.responseText}</span>`)
}
<span class="hljs-keyword">else</span> {
alert(`Notion Error: <span class="hljs-variable">\){result.statusCode}

${notion.lastError}`);
context.fail();
}

Represents a Things heading within a project. See TJSContainer documentation for details on making requests to Things.

The Message object can be used to create and send mail iMessages, similar to those created by a "Message" action step.

Examples

var msg = Message.create();
msg.toRecipients = ["joe@sample.com"];
msg.subject = "My test message";
msg.body = "Body text";

var success = msg.send();

The GmailMessage object can be used to create and send mail messages through Gmail accounts, similar to those created by a Gmail action step. Creating and sending these messages happens in the background, with no user interface, so messages must be complete with recipients before calling send(). Sending is done via the Gmail API. Gmail accounts are authenticated when used for the first time using OAuth - to use more than one account, call create with different identifier parameters.

Example

let message = GmailMessage.create();
message.toRecipients = ["joe@sample.com"];
message.subject = "My test message";
message.body = "Body text";

var success = message.send();
if (!success) {
console.log("Sending gmail failed");
context.fail();
}

Script integration with Twitter. The updateStatus method is a convenience method for posting a tweet, but the entire Twitter API can be used with the request method, which handles OAuth authentication and authorization.

Example

// create twitter object
var twitter = Twitter.create();
// post tweet
var success = twitter.updateStatus("My tweet content!");

if success {
console.log(twitter.lastResponse);
}
else {
console.log(twitter.lastError);
context.fail();
}

OneDrive objects can be used to work with files in a OneDrive account.

Example

// create OneDrive object
var drive = OneDrive.create();

// setup variables
var path = "/test/file.txt";
var content = "text to place in file";

// write to file on OneDrive
var success = drive.write(path, content, false);

if (success) { // write worked!
var driveContent = drive.read(path);
if (driveContent) { // read worked!
if (driveContent == content) {
 alert("File contents match!");
}
else {
 console.log("File did not match");
 context.fail();
}
}
else { // read failed, log error
console.log(drive.lastError);
context.fail();
}
}
else { // write failed, log error
console.log(drive.lastError);
context.fail();
}

macOS only. Requires Drafts 19 or greater.

ShellScript objects can be used to execute Unix shell scripts.

Bash Example

// define text of bash script
let script = `#!/bin/bash
echo "Total arguments : $#"
echo "1st Argument = $1"
echo "2nd argument = $2"
`;
let runner = ShellScript.create(script);

if (runner.execute(["1", "2"])) {
alert("STDOUT: " + runner.standardOutput);
}
else {
alert("STDERR: " + runner.standardError);
}

Ruby Example

let script = #!/usr/bin/env ruby
ARGV.each do |a|
puts "Argument: #{a}"
end;
let runner = ShellScript.create(script);


if (runner.execute(["1", "2"])) {
alert("STDOUT:\n" + runner.standardOutput);
}
else {
alert("STDERR:\n" + runner.standardError);
}

Note: When executed, scripts are saved to temporary files in the Drafts' script directory at ~/Library/Application Scripts/com.agiletortoise.Drafts-OSX and run. Scripts should not be written to make assumptions about their location in the file system (e.g. using relative paths). The first time a script is executed, the user will be asked to grant permissions to the script directory.

Represents a Things project, with headings and todo items. See TJSContainer documentation for details on making requests to Things.

Script integration with Medium.com. This object handles OAuth authentication and request signing. The entire Medium REST API can be used with the request method, and convenience methods are provided for common API endpoints to get user information, list publications and post.

If an API calls fails, typically the result will be an undefined value, and the lastError property will contains error detail information for troubleshooting.

Prompts allow the creation and display of custom dialogs to request information or confirmation from the user.

Example

var p = Prompt.create();

p.title = "Hello";
p.message = "World!";

p.addTextField("textFieldName", "Label", "");

p.addDatePicker("myDate", "Start date", new Date(), {
"mode": "date"
});
p.addButton("First");
p.addButton("Second");

var didSelect = p.show();

var textFieldContents = p.fieldValues["textFieldName"];
var startDate = p.fieldValues["myDate"];

if (p.buttonPressed == "First") {
// do something
}