Applescript

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.

NOTE: scripts can do very bad things to a document; keep good backups.

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 supports.

Notes & Agents

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" 

Delete a note:

delete myNote 

Using the make new command, 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.

Attributes

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 

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.

User Attributes

Scripts can create new user attributes:

   tell application "Tinderbox 8"
      set doc to document "xtest.tbx"
      set newAttr to make attribute in doc
      set the type of newAttr to "date"
      set the name of newAttr to "myNewAttribute"
   end tell

Or, to test for an attribute before use, and make it if not found:

tell front document
   -- check URL type attribute $HookURL exists or make one
   try
      set hookTest to attribute named "HookURL"
   on error errMsg number errNum
      set newAttr to make attribute
      set the type of newAttr to "url"
      set the name of newAttr to "HookURL"
      set hookTest to attribute named "HookURL"
   end try
end tell

Be aware that 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. Therefore it is best to test for an attribute's existence before (re-)making it.

user attributes may be accessed as a list:

set userList to user attributes of front document 

User attributes may be renamed. 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:

tell front document
   set attrRef to attribute named "OldName"
   set name of attribute "OldName" to "NewName"
   set attrRef to attribute named "NewName"
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

Attributes have a read-only property, 'category', that groups related attributes. i.e. their attribute Group as seen in Get Info. The category of renamed and deprecated attributes is returned as the category of their replacement.

Links

Nodes 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.

App and Document properties

A read-only string property, build, that represents the build identifier of the application.

The document property selected note operates as it should.

Evaluating Expressions

Tinderbox allows evaluation of 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.

The expression:

delete value of ( attribute of theNote named "Width") 

This 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.

Link Types

Scripts can 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:

delete linkType "experimental" in front document