The term 'item' is not a Tinderbox definition but is useful in the context of discussing action code and documenting action code usage.
A single note 'item' can be referenced as:
- A note's title ($Name).
- A path. This is useful if the note name is not unique.
- An item-scope note designator, e.g 'parent' or 'firstSibling'.
- A query function, e.g. find(), collect(), collect_if(), links(). The query must resolve to a single note item. If more than one item is returned Tinderbox will use the first of the list, by $OutlineOrder, as the destination item. It thus makes sense to avoid such ambiguity and ensure the query is sufficiently scoped to return only one match.
- An expression - i.e. action code that evaluates as any of the above.
- A string attribute value that is an expression or a literal title/path.
- A discrete value in a list attribute that is an expression or a literal title/path.
Strings are always quoted, whereas references are not, e.g. "Some note" vs $MyString. The string parts of expressions are quoted as in normal action code.
The overall point is that whether using a string literal value (i.e. just stating a name) or using a code expression, the outcome must evaluate to provide Tinderbox with a reference to a single note.
Complex expressions may require use of parentheses and/or use of eval() to help Tinderbox understand the order of evaluation and to deal with encapsulated evaluations.
If the argument supplied evaluates to a title rather than a path, and the title is not unique across the whole current TBX document, Tinderbox will use just the first of the matching notes as defined by their $OutlineOrder.