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 agent 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 be 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 be 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 be 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 Quickstamp is a method for applying an unsaved stamp action, and is run once on each selected note or agent when 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: action code can not create new notes nor delete existing ones.
Syntax: discussed under basic action code syntax. Note the point above re case-sensitivity.
Further discussion of use of actions:
- Basic action code syntax
- Compound Actions
- Conditional Actions (if clauses)
- Conditional statements using multiple arguments
- Expressions in paths
- Delaying code execution in prototypes
- Delaying code execution in notes using prototypes
- Stand-alone expressions
- Left side expressions
- The 'dot' operators
- Chaining 'dot' functions
- Look-up tables
- Actions, Stamps and Quickstamps
- Setting an attribute to (no value)
- Short Boolean form
- Setting an attribute to re-enable inheritance
- Self-Cancelling Rules & Actions
- $Attribute = $1 (queries and if statements)
- Using long sections of code
- Using .each() for 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 Action code
- Getting section number via Action code
- Working with $Container to move notes
- Pre-populating key attribute pop-up lists
- Using designator values as note titles