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.
Further discussion of use of actions:
- Operators
- Basic action code syntax
- Action Code coloured syntax highlighting
- Action Code comments
- Compound Actions
- Conditional Actions (if clauses)
- Conditional statements using multiple arguments
- Counting characters in strings
- Expressions in Action code
- Expressions in paths
- Problematic Characters for Action code in $Name and $Path
- Delaying code execution in prototypes
- Delaying code execution in notes using prototypes
- Stream Processing and parsing
- Stand-alone expressions
- Actions as expressions
- Designators in actions
- Left side expressions
- The 'dot' operators
- Chaining 'dot' functions
- Look-up tables
- Stamps
- Link Actions
- Actions, Stamps and Quickstamps
- Setting an attribute to (no value)
- Setting an attribute to re-enable inheritance
- Short Boolean form
- Self-Cancelling Rules & Actions
- Query back-references
- Using long sections of code
- Using .each() for loops
- Constructing $Attribute references 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 Action code
- Getting section number via Action code
- Working with $Container to move notes
- Pre-populating Displayed Attributes pop-up lists
- Using designator values as note titles
- Strings vs. StyledStrings in operator documentation