This version is out of date, covering development from v4.6.0 to v4.7.1. It is maintained here only for inbound reference links from elsewhere.
Jump to the current version of aTbRef.
|A Tinderbox Reference File : Objects & Concepts : Paths||aTbRef Site Map|
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 slash must be escaped with a back-slash: 'Large\/Medium' otherwise the backslash is treated as part of a path. As of v4.6.2, quoting paths is option is such contexts.
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 ../. A path not starting with either of these will result in Tinderbox treating the string as a single note name.
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'.
Just use the note name on it's own:
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 (N.B in reverse order). If you need to work out the full list you'll need to open an outline view (or possibly a chart view)
Absolute paths aren't 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.
The basic rules are roughly the same:
For the following example assume the currently selected note is 'Child B' within 'Second Root'.
$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:
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 can't 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.
Another enhancement is that a path may be supplied as an attribute.
... where MyPath is a user attribute holding a path.
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".
|Up: Objects & Concepts|
|Previous: Windows & Views||Next: Links|
Licensed under Creative Commons Attribution-Noncommercial-Share Alike 3.0 License
[See aTbRef CC licence Attribution/Waiver info info]