Tinderbox 7 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 an absolute path down from a top-level note (though it needn't 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 string as a single note name.

Quoting of Paths

Historically paths weren't quoted where used in Tinderbox code - and thus may be omitted in many older code examples you find. However, post version 4.0, in general did no harm to quote paths where used. From v5.7.x, 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 - don't 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; from v4.6 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 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:

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:

Although any note's Text window lists its ancestors in the sidebar, only the last 3 are shown - i.e. father, grandfather and great-grandfather (in reverse order). If you need to work out the full list you will need to open an outline view (or possibly a chart view), or look at $Path in the Info view (General section).

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're used to UNIX file navigation, note the absence of the dot '.' method. Also, if 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 - don't 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): Aliases

$Container(original): 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 - incorrect - "/Some/Path/Fred Smith ".