Automation : Basic AppleScript Terminology

Quick links:

Talking to DEVONthink
DEVONthink's dictionary
DEVONthink Windows
Using Locations
Working with a selection

Basic AppleScript Terminology

AppleScript is not a difficult language to learn. Its plain English approach of "talking" to applications and elements is easily understandable. However, like any language, there are some variations in the words you can use; dialects, if you will. AppleScript is implemented by the developer of an application, so the commands and parameters may be conceptually the same as another application's, but using a different term. This is certainly not meant to be a complete guide to AppleScripting DEVONthink, but what follows are some common terms or concepts you're likely to encounter. The examples here and in this chapter are meant to give you basic ideas about scripting DEVONthink.

Talking to DEVONthink

In AppleScript you "talk" to programs like DEVONthink using a tell statement, typically referring to an application either by its name, "DEVONthink 4", or its bundle identifier, "com.devon-technologies.think". While these forms will work, we strongly recommend to talk to DEVONthink using the application ID DNtp, as seen in the following statement:

Example:

tell application id "DNtp"
close current database
end tell

DEVONthink's dictionary

AppleScript-capable applications have their commands, elements, and properties listed in an AppleScript dictionary. DEVONthink includes a large dictionary as a great reference for you. To view the dictionary, open the Script Editor application, select File > Open Dictionary and choose DEVONthink in the appearing window. You can also add DEVONthink to your Script Editor library. Select Window > Library, click the + button and choose DEVONthink. This way you keep DEVONthink's dictionary at hand.

Note: Using the in your script is optional, but including it can make the script seem a bit less robotic. You can also use possessive forms, if they feel more comfortable to you. For example, all the lines in this script are functionally the same:

Example:

tell application id "DNtp"
set flag of children of current group to true
set the flag of the children of the current group to true
-- Possessive Forms
set the flag of the current group's children to true
set the current group's children's flag to true
end tell

As noted above, the dictionary is the best place to find specific terminology to be used with DEVONthink.

Again, this isn't a course on AppleScript, but there are a few DEVONthink-specific things you should understand when scripting our application.

Records: Almost every item in a DEVONthink database is a record, a record with properties. Do a search for "record" in the dictionary and you'll see it's a fundamental unit with a wide range of properties associated with it. This means you won't be writing code like, get the second rich text file…. You will be dealing with records with a particular type, in this case rtf.

There are many commands specifically for use with records: create record with, exists record with…, etc. Also note there are some commands that require the term record. For example: move, delete, and convert. You will see a dictionary listing move record, so you can see the command isn't merely move, it's move record.

Parents and Children: Another concept to understand is parents & children. Generally speaking, these classes deal with the container or the contents of some object. The parent of an object is the group containing it. The children of a group are the immediate contents of that group. It does not include the children of sub-groups. Children can be documents or groups; parents can only be groups, tag groups, or RSS feeds.

Example:

tell application id "DNtp"
set thisGroup to current group
name of (the children of thisGroup whose (type is XML))
end tell

DEVONthink Windows

While there are standard windows in DEVONthink, it is better to refer to them by their proper classes. A document window (or content window) is a standalone document window. A main window (or viewer window) is a main window. However, they are both subsets of the think window class so it's often useful to use this term to cover either case.

Using Locations

One of the common tasks people want to perform with AppleScript is importing files to a specific group. In order to direct the files to a given location, you need to reference it properly. Below are three general options for choosing a location:

incoming group: This targets the Global Inbox, or the inbox of a database when using incoming group of current database.
current group: This targets the currently selected group in the current database.
display group selector: This shows the group selector so you can choose a location on demand.

There are many times you want to direct files into a specific group. That group may not be the current group you're in and you may not want to choose a destination each time. Here are two common ways of specifying a particular group in your database to be a destination group in your script:

get record at…: This command allows you to set a variable by specifying a group's location in your group structure. The location is a text string, always beginning with a forward slash denoting the root of the database.
get record with UUID…: When using an item link, you can use the alpha-numeric string from the reference URL to point to a specific item. (This command works with both groups and documents.) This form is very useful since it doesn't change when an item's name or location changes.

Example:

tell application id "DNtp"
set myGroup to get record at "/Inbox/New Files"
import "~/Desktop/001.txt" to myGroup
set groupTwo to get record with uuid "98BBF96D-7743-46C6-9EB4-51C6EF68373C"
import "~/Desktop/002.txt" to groupTwo
end tell

Working with a selection

Many times you want to process items you have selected in DEVONthink. What class you use depends on the selection.

selected records: Use this term when items are selected in the item list.
root of think window: When a group selected in the Navigate sidebar, it is not the "selection". It sets the root of the window.

As a practical example of working with a selection, imagine you want to generate a list of names and dates for use in a document you're working on. Below is a handler commonly seen in DEVONthink scripts:

repeat with thisRecord in (selected records) … end repeat: This is a very common handler, used when processing a selection, single or multiple items.

Example:

tell application id "DNtp"
if selected records is {} then return
set nameList to {}
repeat with thisRecord in (selected records)
copy ((name of thisRecord) & ": " & (creation date of thisRecord as string) & return) to end of nameList
end repeat
create record with {name:"Files", type:text, content: (nameList as string)} in incoming group
end tell