NOTE: the new support for AppleScript is a complex feature to add to a mature application. It may take time for key features to stabilise and to be able to give canonical code examples (which likely may be done in a resource other than aTbRef). Patience is advised.
Tinderbox offers limited AppleScript support, making it easier to automate workflows with other applications. Explaining general AppleScript functionality is outside the scope of aTbRef but the scripting language is well supported with learning resources both online and in book form.
Below are some sample expressions that Tinderbox Applescripting now supports. This creates a new top-level note, and creates an agent in that note:
set myNote to make new note in document "Workspace.tbx"
set myAgent to make new agent in myNote
Set the name of the agent created in the code above:
set name of myNote to "inbox"
Set the value of an attribute, here $Width:
set value of (attribute of myNote named "Width") to 5
Fetch the value of the designated attribute:
get value of (attribute of lastChild of MyNote named "Width")
Note the use of parentheses in this and the preceding example; AppleScript seems to compel this usage.
Return the name of the third top-level note in the specified document:
name of note 3 of document "Workspace.tbx"
Return a reference to the designated note:
find note in [note or document] with path "/path/to/note"
If the target is a document, the path should be an absolute path. If the target is a note, the path can be an absolute path or a relative path with respect to that note.
Return a reference to myNote's container:
find note in myNote with path "parent"
Move a note to the specified container:
move myNote to theContainer
Delete a note:
delete myNote
From v8.0.2, scripts can create new user attributes.
tell application "Tinderbox 8"
set doc to document "xtest.tbx"
set a to make attribute in doc
set the type of a to "date"
set the name of a to "myNewAttribute"
end tell
The type of attribute (kind pre-v8.0.4) determines the attribute type, and may be any of the following case-sensitive values:
- string
- color (N.B. US spelling)
- number
- file
- boolean
- date
- set
- URL (N.B. case)
- list
- interval
Note that references to attributes specify attributes by name, and so existing references are invalidated after the attribute is renamed. You can get a new reference to the renamed attribute thus:
set a to attribute named "theNewName" in document "theDoc.tbx"
v8.0.3 added support for allowing User attributes to be renamed.
From v8.0.4:
- attributes have a read-only property, category, that groups related attributes.
- Links: Nodes now possess a property, links, which is a list of all outbound basic and text links from that note. Links are read-only and have three properties: the source note, the destination note, and the path name.
- the application now has a read-only string property, build, that represents the build identifier of the application.
- make new note with properties {name: “….”} now works as expected.
- the category of renamed and deprecated attributes is now returned as the category of their replacement.
- Tinderbox now lets you evaluate an expression:
evaluate note with expression. The first argument note is an AppleScript specifier for the note, which will be bound to this for the evaluation. The evaluate command may be issued to either the document or to a specific note.
Note: scripts can do very bad things to a document; keep good backups.
Below are changes new to v8.8.0.
The expression:
delete value of ( attribute of theNote named "Width")
Now removes any local value assigned to that attribute. This is equivalent to the Tinderbox command $Width=;
The expression:
act on theNote with "…action…"
Performs an action on the designated note. An action is typically one or more assignment or conditional statements, such as Color=“red” . Act on does not return a value. The expression
evaluate theNote with "…expression…"
Returns the result of evaluating an expression. In an action, = means “assign”; in an expression, = means “comparison” (although the unambiguous operator == is preferred.)
The expression:
refresh theNote
Informs Tinderbox that changes have been made to a note and the user interface may require updating.
Revised the make new command to more cleanly create new agents, adornments and notes, and to return the correct value. Note that the returned designator records is based on the outline position of the newly created note, and subsequent calls that make or delete notes might render it invalid.
Scripts can now access link types:
linkType named "agree" in front document
…returns a link type by name.
linkTypes in front document
…returns a list of link types.
tell document 1
make new linkType with properties {name:"name", color:"green",bold:true}
end tell
…creates a new link type.
If a link type with this name already exists, no new type is created and the properties are applied to the existing link type.
Link types make also be deleted in scripts.
user attributes may be accessed as a list.
When using make new attribute , if a user attribute already exists with the designated name, the existing attribute is modified. If a system attribute already exists with the same name, no changes are made and no attribute is created.
The document property selected note now operates as it should.
The expression:
get the localattributes of TheNote
returns a list of attributes for a note where (both):
- the note has an immediate value for that attribute, rather than inheriting a value from a prototype or the attribute default.
- the attribute is not intrinsic, hidden, or deprecated.