Home | Appendix

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
PRO If you have external AI set up and a code-compatible model, you can use DEVONthink's Script Assistant. Choose the AI model and enter a description of the desired script in the prompt field, then press the ↩ Return key to compose and refine a script.