Tinderbox v9 Icon

Hierarchy of Content

Hierarchy of Content

A Tinderbox document has two basic kinds of structure: one is the structure formed by links between notes. The other is the hierarchical structure of the document. A Tinderbox note can contain other notes, which can contain other notes, and so on. The notes can thought of this as chapters containing sections containing divisions; or topics containing sub-topics; or in any way that fits the user's workflow.

In the image for this article, the 'MyString' column shows the relevant designator (in correct case-sensitive form). Note that designators are case-sensitive when used in export/action code; by convention designators are normally not quoted in action code, although they are strings. The OutlineDepth column shows the $OutlineDepth for each note (1 being root level).

IMPORTANT: inheritance of attribute values (e.g. via prototypes) is not a feature of hierarchy. Put another way, a child note does not automatically inherit all its parent's customisation: that may be made to happen but will require the user to add some action code.

Several terms are used to describe relationships within a hierarchy:

  • parent: the item one level up. A parent note contains one or more child notes (children), and thus contains one or more levels of sub-notes. A parent note may also be referred to as a 'container' as it contains other notes. ('parent' designator)
  • sibling: an item that has the same parent. ('firstSibling', 'prevSibling', 'nextSibling', 'lastSibling' designators). The group designator siblings means all items with the same parent as the current item.
  • child: an item one level down. In Tinderbox, when a note contains other notes, those notes are its children. A child note is thus any note that has a parent note, i.e. it is not a top level note. ('child', 'lastChild', 'randomChild', 'previous' (child), 'next' (child), Nth child (zero-based) 'child[N]' designators).
  • descendant: a child, or a child of a child, and so on, of the current note.
  • ancestor: a parent, or a parent of a parent, and so on, of the current note.
  • grandparent: specifically the parent of a note's parent. ('grandparent' designator)
  • root: an item that has no parent. In a Tinderbox document, the document as a whole is the root: it contains the top-level notes, and nothing contains it. Root level notes have $OutlineDepth of 1. Root is not used as a designator but does have a role in export code: see ^root^.
  • cover: the first root level sibling. Thus, if there is more than one root-level note, the cover is the oldest sibling. ('cover' designator). This is little used in Tinderbox and has more purpose in its sibling program Storyspace.
  • original. The note upon which an alias is based. ('original' designator)
  • this and current. These generally mean the same thing. 'this' applies to the currently selected item; where transclusion is used (e.g. during export, see ^include^) current applies to the note in current scope of evaluation.
  • agent. This is a method for agent queries to refer to the agent's attribute values and for aliases to refer to their parent agent in agent actions. ('agent' designator)
  • adornment. Not illustrated, as only used in map view. It fulfils the same role as 'agent' in adornments and smart adornments ('adornment' designator)
  • ID. Not a hierarchical element, but an item's $ID value (a 10-digit number) can be used as a designator.

Not illustrated: item-scope designators: 'that' and 'find()'.

There are several group terms to describe Tinderbox notes:

  • all: all notes in the current TBX file. ('all' designator)
  • ancestors: all ancestors. ('ancestors' designator)
  • children: all children. ('children' designator)
  • descendants: all descendants, i.e. all children and their children. ('descendants' designator)
  • sibling: all siblings. ('siblings' designator)

Any note containing other notes is a 'container'; put another way, a container is any note that has children/descendants. Agents are a special class of container, holding an alias to every note matching the query stored in their $AgentQuery attribute. Map adornments are not containers. Though not originally intended as such, outline separators can be used as containers.