Paths

Tinderbox allows you to identify notes by relative or absolute paths, not just name. If a tag's request matches neither a keyword nor a note, Tinderbox tries to interpret it as a path. For example:

/news …is the top-level note named "news"

/news/Iraq …is the note named "Iraq", inside the top-level note "news"

../Chicago …is the note named "Chicago" that is a sibling of this note

../.. …is the grandparent of this note.

Using paths implies:

• knowledge of the Tinderbox document's outline structure
• where in the outline that named notes are used
• that the outline will not change.

If a note name contains a forward slash, as in 'Large/Medium', then the path must be enclosed with quotes, e.g. Large/Medium should be cited as "Large/Medium". A deprecated legacy alternate is to escape the slash by a preceding backslash, e.g. Large\/Medium. Doing otherwise, the backslash is treated as part of a path, i.e. as a container delimiter.

A path beginning with a / is always a (complete) absolute path down from a top-level note (though it need not be the cover if there is more than one top level note). Relative paths start with ../ (i.e. period+period+slash). A path not starting with either of these will result in Tinderbox treating the proffered string as a single note name.

Quoting of Paths

Historically paths were not quoted where used in Tinderbox code, and thus may be omitted in many older code examples you find. However, users should switch to quoting paths as they are string literals. Past convention in code examples is to quote paths in action code but not in export code, but this largely reflects past usage and should not prompt current users to omit quotes.

An exception to quoting paths occurs, where a path argument is actually an expression or an attribute name. A simpler way to view this is that quote enclosing a string of text is to say to Tinderbox, "This is just text. Do not try interpreting any control/code characters found within it", i.e. a string literal.

Using Path arguments in Tinderbox

Many operators and codes in Tinderbox that allow a note name as an argument also allow a 'path' to be used. All attributes can also take a path argument, allowing an attribute from some other note to be referenced.

For new users, figuring out paths can be a bit confusing. But firstly, why might a path argument needed? If a note name is not unique across the whole TBX document, then when Tinderbox finds a reference to that name, it will use the first one found (using $OutlineOrder). So, using a path rather than a note name can help identify exactly to which note you wish to refer. Consider using paths explicitly if:

• Your document deliberately does not use unique note names
• It may be that names may not remain unique over the life of the document.

That's the 'why', but how do you refer to a note using a path? To investigate this consider the following TBX outline:

  First Root
    Child A
      Sibling A1
      Sibling A2
    Child Z
  Second Root
    Child A
      Sibling A1
    Child B
      Sibling B1
      Sibling B2
    Child C/D
      Child of D

In this demo, you'll note that there are some duplicate note names. For the examples below, to help give starters code such as they might use for real, the examples are written as if making an attribute reference to the value of the system attribute 'Created'.

Note name (i.e. no path)

Just use the note name on its own:

$Created(Child B) 

$Created(Child A) 

$Created("Child C/D") 

$Created("/Second Root") N.B. need for root slash

Notes:

• note name will not suffice if you want to reach the 'Child A' in 'Second Root'. The note of the same name within 'First Root' will always get called.
• any paths (or just note names) with forward slashes must be 'escaped' by quoting the whole string.
• citing root-level note names must include a slash prefix, i.e. when the $Name is the $Path—or rather the $Path is "/"+$Name . See also notes on partial paths further below.
• there is still legacy support for the now deprecated old usage of preceding (/) slashes in paths with a backslash (\) character.

Ways to view a note's path

The clearest way is to view $Path data but various views offer ways to see all or part of the path:

• hoisted views show a 'breadcrumb' trail indicating ancestor container, and thus the path to notes in the current view.
• Outline, Chart and (albeit less obviously) Treemap views allow the (ancestor) path to be viewed. In the case of Outline and Chart it may involve expanding the outline branch holding the current note. In the case of the treemap it is a case of spotting the nested containers.
• Text pane. Holding the cursor over the note name results in a tooltip showing the full path of the note. This is useful when a $Name is not unique within the document.

Paths from Attribute Values

A path may be supplied as an attribute to address an attribute of another note than the current one.

$Text($MyPath) 

…where $MyPath is a user attribute holding a path.

Paths from Expressions

Path may also be supplied in the form of an expression such a string concatenation or simple arithmetic:

$Text(' "../"+(1+2) ') 

…would collect the $Text of a note named "3".

Paths with Designators

Most Tinderbox designators can use a path to refer to a different context. For example:

min(child("/some/other map note",$Xpos) 

^min(child("/some/other map note",Xpos)^ 

Paths with nested references

It is possible to cite an offset combining designators.

  ancestor
    Examples
      A
        1
        2
      Aliases
        A
  another
    More
      B
        3

For the alias A

$Container(this) is "Aliases"

$Container(original) is "Examples"

The designator parent(original) will give the parent of the original -- the parent of Examples, So $Container(parent(original)) is "ancestor".

The designator original(parent) will give the original of the parent -- "Aliases". So $Container(original(parent)) is "another".

Thus nested references like this tend to be written as spoken: the 'parent of the original' being parent(original).

Further notes on Paths:

• Problematic Characters for Action code in $Name and $Path
• Absolute Paths
• Relative Paths
• Partial Paths