Tinderbox supplies a number of 'designator' terms, use of which instead of a note's $Name or path which may infer an individual note, or in a few cases a group of notes. Item designators are generally hierarchical in their references. Designators ignore map adornments, so cannot be used to match adornments.
Designators are generally used with attribute value references ($Name(parent)), as action or export code arguments (linkTo(grandparent), linkFrom(grandparent(original))). In some cases cases they are specific to certain operators, as with links() and the link direction designators.
Most item and group designators can use paths (or note name, if unique) to refer to data from a different note from the current context, e.g. descendants("Projects"), or use other designators as path/group proxies, e.g. grandparent(original). This makes them even more flexible in use: see the section on paths for more detail.
However, designators may not nest the find(query) designator inside another designator.
Both item and group scoped designators are allowed in attribute references. For example:
$MyList=$Color(children);
finds a list of the colours ($Color) of each child of this note, and
$MyList=$Color(children).unique;
finds the same list but without duplicates. N.B. lists can hold duplicate values.
Working with numerical values:
$MyNumber=$Width(children).max;
will find the maximum width of the container's children.
When the same designator is applied to the attribute $Text
$Text=$Text(children);
the texts of each child are placed in this note's $Text, separated by paragraph breaks. To append the same child text to existing text:
$Text=$Text+"\n"+$Text(children);
There are also separate series of designators designed to help date creation/calculation and the polarity of links.
Designators are generally used with attribute value references ($Name(parent)), as action or export code arguments (linkTo(grandparent), linkFrom(grandparent(original))). In some cases cases they are specific to certain operators, as with links() and the link direction designators.
Most item and group designators can use paths (or note name, if unique) to refer to data from a different note from the current context, e.g. descendants("Projects"), or use other designators as path/group proxies, e.g. grandparent(original). This makes them even more flexible in use: see the section on paths for more detail. However, designators may not nest the find(query) designator inside another designator.
Designators and root-level properties
From v9.6.0, Tinderbox no longer forbids expressions that interrogate properties of the root note—the parent of top-level notes. For example, a top-level note can now get the value of $MapBackgroundColor(parent) if it wants to know the background colour of the top-level map.
Using designator values as note titles
Tinderbox does not regard designators as 'reserved' values. It is perfectly possible to have a note called "children". However, in action or export code, if referring to such a note via code always use the full path ($Path) of the note rather than its title ($Name) to avoid ambiguity as to the intended object of the reference.
Quoting designators vs. paths or /titles
By convention, designators are normally not quote-enclosed in action code (i.e. queries and actions (and most export code)). Although designators are strings, not using quotes helps Tinderbox's parser to identify them as designators as opposed to notes of the same name. Designators used as path proxies, e.g. $Name(parent), may safely be quoted. Historically, path arguments were not quoted but since v5 there has been a move to explicitly quoting all string values. Ideally do not use notes with a $Name matching a designator also using designators in that TBX's actions (using explicit paths can route around such name collisions).
Designators for Date data construction
Designators, or rather 'keywords', for use defining date/time elements in Date-type data are described separately.
A listing of designators
Designators are listed via their scope: