Tinderbox 8 Icon

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:

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:

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:

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:

Absolute Paths

With an absolute path you are stating the full and exact path. These are absolute paths, as:

$Created(/First Root/Child A/Sibling A1) 

$Created("/Second Root/Child C/D/Child of D") 

Points to note:

Absolute paths are not a big deal in a small document like the example, but if it is a big TBX with deep nesting, you will want to consider using relative paths.

Relative Paths

The basic rules are roughly the same:

For the following example assume the currently selected note is 'Child B' within 'Second Root'.

$Created(../Child A) 

$Created(../../First Root/Child A) 

$Created("../Child C/D/Child of D") 

A relative call from Sibling B2 to its grandparent (Second Root) would be:

$Created(../../Second Root) 

The above examples show two subtle points to note about relative paths:

If you are used to UNIX file navigation, note the absence of the dot '.' method. Also, if you are used to HTML relative links, note the 'up and back' method of navigation: you cannot cite a sub-folder or sibling simply by using its name (without a preceding slash). So some slight variance form what some more expert users may intuit but the usage is consistent within Tinderbox and not difficult to learn.

Partial Paths

An easy mistake to make, especially when trying to disambiguate between two same-named notes, is to use a 'partial' path, such as in citing container name/note name. Although not illegal usage, this does not necessarily get parsed as the user assumes. The logic runs like this:

Bottom line: do not use use partial paths as shorthand. Use a full path or a relative paths as described above.

Paths from Attribute Values

Another enhancement is that a path may be supplied as an attribute.

$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).

Paths containing Parentheses

Paths containing $Names including parentheses, e.g. "Fred Smith (Jr.)", will handle correctly during concatenation. Previously, parentheses caused the new string to terminate at the first parenthesis. For a note with $Name "Fred Smith (Jr.)":

"/Some/Path/"+ $Name 

…giving "/Some/Path/Fred Smith (Jr.)" unlike the old (and incorrect) "/Some/Path/Fred Smith ".

Problematic Characters in $Name and $Path

If intending to do action code based creation/deletion/traversal of links in the document, it is advisable to avoid the following characters when titling notes: forward or backward slashes, opening/closing parentheses, colon, semi-colon. Note: this list is not exhaustive.