Action Code

An action is an automatic way of setting a certain attribute to a certain value (with the exception of system read-only attributes which cannot be altered).

Here 'note' may be read to mean any note-like object (note, agent, adornment, etc.). The term 'rule' is just one form of applying an action and relates to the scope of its use. Actions can be invoked a number of ways:

• An OnAdd action is performed by a container upon a note added to it, or by an adornment to a note placed upon it. A note's OnAdd action code is stored in its $OnAdd attribute. It can also be easily be viewed or edited via the Action tab of the Action Inspector. An OnAdd applies only to direct new children and thus not their children (i.e. other descendants).
• An Agent Action is performed by an agent1 upon any alias of a note it creates as a result of a match to its query. An agent's AgentAction action code is stored in its $AgentAction attribute. It can also be easily be viewed or edited via the Action tab of the Action Inspector. Note: agents have no OnAdd and conversely notes have no Agent Action, thus the Action Inspector can show both in the same UI.
• An OnRemove action is performed by a container upon a note removed from it, or by an adornment on a note moved off it. This can be seen as the opposite of an OnAdd action. A note's OnRemove action code is stored in its $OnRemove attribute. It can also easily be viewed or edited via the Remove tab of the Action Inspector.
• An OnJoin action is performed by a member of a composite, once, upon any item joining the composite (or being moved within it) so as to touch the item with the OnJoin action. A note's OnJoin action code is stored in its $OnJoin attribute.
• A Rule is performed by a note or agent upon itself its Rule is run; this happens from time to time, typically every few seconds. A note's Rule action code is stored in its $Rule attribute. It can also easily be viewed or edited via the Rule tab of the Action Inspector.
• An Edict is performed by a note or agent upon itself its Edict is run; this happens from time to time, typically about once an hour. A note's Edict action code is stored in its $Edict attribute. It can also easily be viewed or edited via the Edict tab of the Action Inspector.
• A Stamp is a pre-saved action that is run once on each selected note or agent when selected from the Stamps menu or applied via the Stamps Inspector. Stamps are saved in a Tinderbox document and edited via the Stamps Inspector.
• A function is a pre-saved set of actions that can be called from any action, allowing a complex process to be reused without having to duplicate a lot of code. Unlike a stamp, a function can take input values that are used by the function to generate its output.
• A Quickstamp is a method for applying an unsaved stamp action, and is run once on each selected note or agent applied via the Quickstamp Inspector. Quickstamps are ad hoc use of code and not saved after use. For re-usable code use a Stamp (above) instead.

*An ^action(some_code)^ export code allows inclusion of action code in an export template. The action code input some_code is executed when the template is evaluated. Attributes storing action events. View a full listing of attributes storing actions. Case sensitivity: Action code operators are always case-sensitive (unlike export codes). Agents can have actions. An agent performs its action on aliases of all the notes it finds that match its agent query. Making/deleting notes: See create(), createAgent() and delete(). Syntax: discussed under basic action code syntax. Note the point above re case-sensitivity. Originally, Tinderbox had 'actions' that notes applied to them elves or their children. These were written in 'Action Code' though at the time what is now 'Export Code' was generally used for internal macros (actions). In v4 and v5 this mix was clarified: Export Code moved to being for export only whilst all internal 'coding' was done using 'Action Code', i.e. the style of code used for writing actions. Action code is now the most likely, indeed only, form of automation users are likely to meet unless they use export features to pass information out of Tinderbox. Action Code is not a formal coding language (programmers, take note!), and being artisanal software has grown as needed: it has what it needs or its users has asked for. It may lack some features that those with a programming back ground might assume are 'standard'. Further discussion of use of actions:

• Actions
• Coloured syntax highlighting in Action code
• Basic action code syntax
• Expressions vs. Actions in Action code
• Basic Comparison Operators
• Compound Actions
• Conditional statements using multiple arguments
• Defining an 'item' object—a single item—in action code
• Defining 'group' list objects—one or more items—in action code
• Why is a text 'line' in action code actually a paragraph?
• Explicit declaration of lists using square brackets
• Explicit declaration of dictionaries using curly braces
• Punctuation and special characters in definitions, actions and expressions
• Designators in actions
• Designators
• Comments in Action code
• Action code operator terminology explained
• Variables
• Functions
• Operators
• Problematic Characters for Action code in $Name and $Path
• Conditional Actions (if clauses)
• Counting characters in strings
• Getting and setting attribute values and inheritance
• Delaying code execution in prototypes and notes using prototypes
• Stream Processing and parsing
• JSON processing
• XML processing
• Using attributes as global variables or constants
• Chaining 'dot' operators
• Look-up tables
• Actions, Stamps and Quickstamps
• Self-Cancelling Rules & Actions
• Using regular expression back-references
• Using long sections of code—code notes
• Using .each() for loops
• Constructing $Attribute references in loops
• Detecting first or last item context in loops
• Adding joins in loops
• Concatenation versus addition
• Parentheses as a guide to code execution
• Updates and cascading actions
• Optimising code for performance
• Checking and setting Time correctly in Date data
• Debugging user-written Action code
• Getting section numbering via Action code
• Moving notes by setting $Container
• Strings vs. StyledStrings in operator documentation
• Type coercion, strings and numbers
• Sorting Date-type data

---

See also—notes linking to here:

• Legacy Query Code for agents
• Actions
• Query Syntax
• Agent & Queries
• A Tinderbox Reference File