This version is out of date, covering development from v9.0.0 to v9.3.0. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

Tinderbox v9 Icon

adornment

The designator adornment allows notes on an adornment to refer to the adornment's attributes. Only available in an adornment's $OnAdd action and in no other contexts. This is similar to the 'Link type honouring operators' designator.

In this context, using parent would result in the value being taken from the parent of the current map view.

The use of 'adornment' has been expanded. In all other contexts than the above, the designator 'adornment' refers to the map view adornment(s) on which the current note rests. If the note overlaps two or more adornments, "adornment" designates the uppermost (front-most) adornment.

If the note overlaps no adornment, then "adornment" is bound to "this". For example, the rule

$Color=$Color(adornment); 

will change the note's colour to match the colour of an adornment, but leaves the colour unchanged if the note does not overlap an adornment. This latter usage, with an inherent 'if on adornment' switch makes for more flexible coding in maps.

From v9.3.0 there are further alterations, …

The designator adornments returns all the adornments that are contained inside the current note, ie. this containers child map. The data is returns as a List of the adornments' $Path, in $OutlineOrder.

Siblings vs. children

For any given map, in terms of $OutlineDepth/$OutlineOrder, notes on the map are siblings of the maps' adornment(s). However, for adornments any adornments are for the addressed item's child map. If the logic seems odd, bear in mind that a map (timeline, etc.) is normally addressed in terms of its enclosing—and thus parent–container.

Thus, for an item on a map to get its sibling adornments use either of these relative references, use either:

$MyList = $Name(adornments(parent)) 

$MyList = $Name(adornments(..)) 

noting that .. is the unix term for the parent folder. For most Tinderbox users, who aren't familiar with Unix structures, the parent offset reference is the most sensible to use.

Title vs. ID and action code

When using a large number of adornments, e.g. to set out a time or date grid, many of the individual adornments may not have a unique $Name. For instance if there is an adornment '10' mapping the first 10 minutes of an hour, there may be multiple adornments on the same map with the same $Name and $Path. Recall that when accessing a note via a not unique title/path, Tinderbox always matches the first match by $OutlineOrder, even when processing a list. In other words, processing a list of $Name values with multiple '10' values, the action will act on the same, first match target, every time.

$ID offers a sensible workaround, not least because within the action code context the use of item titles ($Name) is a convenience. If you want to process a list of adornments for whatever ever reason it may therefore make sense to use their $ID instead as this will always be unique. For example:

$MyList = $ID(adornments) → a list of child adornment IDs

$MyList = $Name(adornments(parent)) → a list of sibling adornment IDs