Deprecated
This is Tinderbox Cookbook version 2.0.1, created in conjunction with Tinderbox 7.3.2. The locale settings used to export this document: en-US. Most date tests were written/tested on a UK day/month order system and thus tests may fail if exported using different locale settings.This page explores Tinderbox’s path references — ways Tinderbox actions, rules, and export templates refer to specific Tinderbox notes.
All examples on this page are now deprecated:
- Deprecation. Some codes are now marked 'deprecated'. This means that while they may still work, such syntax should be avoided. New documents should not use such syntax and existing documents in regular use should be have their code reviewed to avoid retaining deprecated usage.
If planning ongoing use of TBXs that contain deprecated code, users are strongly advised to update their code to the suggested replacement syntax before support for deprecated codes is removed.
Deprecated Action Codes
[Attribute]() - find value
Tests whether a regular expression can be found in an attribute of a note.
Deprecated - use .contains/.icontains.
| description | try | expect | result | ok |
|---|---|---|---|---|
Tests whether this note's text contains the name, "Lincoln" |
Text(Lincoln) | true | true | not yet |
Tests whether the text of this note contains a "B" followed by a vowel. |
Text(B[aeiou]) | false | not yet |
saturation()
computes the saturation of a color — the intensity of its hue, on a scale of 0 (completely neutral) to 100 (intensely saturated). Alternatively, creates a new color whose hue and brightness are unchanged, but with a new saturation.
Deprecated - use Color.saturation.
| description | try | expect | result | ok |
|---|---|---|---|---|
| saturation("bright red") | 100 | 100 | not yet | |
| saturation("warm gray") | 25 | 25 | not yet | |
| saturation("warm gray",25) | #807060 | #807060 | not yet | |
| saturation("warm gray",5) | #807c79 | #807d7a | not yet | |
| saturation("warm gray",75) | #805020 | #805020 | not yet |
utf8("theString")
utf8("theString")
Deprecated - not needed as Tinderbox now outputs UTF-8 as the default encoding.
| description | try | expect | result | ok |
|---|---|---|---|---|
| utf8("Four score and seven years ago") | Four score and seven years ago | Four score and seven years ago | not yet | |
User string is •, utf-8: e2 80 a2 |
urlEncode(utf8($UserString)) | %e2%80%a2 | %E2%80%A2 | not yet |
User string is ü. utf-8: c3 bc |
urlEncode(utf8($UserString)) | %c3%bc | %C3%BC | not yet |
Deprecated Export Codes
action( action )
Perform the specified action code, possibly changing the values of one or more attributes. Nothing is exported.
Deprecated - use ^value(action())^
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^action($UserString="Hello!")^^get(UserString)^ | Hello! | Hello! | not yet | |
| ^action($UserString="Hello")^^action($UserString="Adieu")^^get(UserString)^ | Adieu | Adieu | not yet |
any( group , attribute[, data] )
Returns true if any member of the group has a value for the given attribute. Alternatively, it returns true if the specified data is matched.
Examples are based on the following data:
| Name | UserFlag | UserNum |
|---|---|---|
| apple | true | 12 |
| pear | false | 3 |
| lemon | false | 3 |
| lime | true | 2 |
Deprecated - use ^value(any())^
| description | try | expect | result | ok |
|---|---|---|---|---|
Just an attribute. For this test to return false all children must have $UserFlag value of false. |
^any(children,$UserFlag)^ | true | true | not yet |
| ^any(children,$UserFlag,false)^ | true | true | not yet | |
| ^any(children,$UserFlag,false)^ | true | true | not yet | |
| ^any(children,$UserNum,3)^ | true | true | not yet | |
| ^any(children,$UserNum,42)^ | false | false | not yet | |
For non-Boolean fields any value other than the standard defaults (empty string/set, zero number, never date) is coerced to 'true'. |
^any(children,$UserNum)^ | true | true | not yet |
Using action code |
^value(any(children,$UserFlag))^ | true | true | not yet |
Using action code |
^value(any(children,!$UserFlag))^ | true | true | not yet |
Using action code |
^value(any(children,$UserNum==3))^ | true | true | not yet |
Using action code |
^value(any(children,$UserNum==42))^ | false | not yet | |
Using action code. For non-Boolean fields any value other than the standard defaults (empty string/set, zero number, never date) is coerced to 'true'. |
^value(any(children,$UserNum))^ | true | true | not yet |
beginsWith( target, data )
Tests if the target string begins with the data string. Unlike contains(), beginsWith uses simple string match, not regular expressions.
Deprecated - use ^value(String.contains(regex))^
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^beginsWith(frost kitten,frost)^ | true | true | not yet | |
beginsWith does not match regular expressions |
^beginsWith(frost kitten,fr.st)^ | false | not yet | |
$Name is frosty morning . |
^beginsWith(^get($Name)^,frost)^ | true | true | not yet |
$Name is summer evening. |
^beginsWith(^get($Name)^,"frost")^ | not yet | ||
test name ($TestName is 'frosty morning'. UserString is 'frosty'. |
^beginsWith(^get($TestName)^,^get($UserString)^)^ | true | true | not yet |
Name ($TestName) is 'frosty morning'. $UserString is 'Hamlet'. |
^beginsWith(^get($TestName)^,^get($UserString)^)^ | not yet |
capitalize( data )
Transforms a string or attribute to use initial capitals.
Deprecated - use ^value(capitalize())^
| description | try | expect | result | ok |
|---|---|---|---|---|
Use a literal string. |
^capitalize(frosty friday)^ | Frosty Friday | Frosty Friday | not yet |
Use a literal string. Only the initial letters are capitalised. |
^capitalize(fROSTY fRIDAY)^ | FROSTY FRIDAY | FROSTY FRIDAY | not yet |
Use a literal string. Only the initial letters are capitalised. |
^capitalize(frOSTy friDaY)^ | FrOSTy FriDaY | FrOSTy FriDaY | not yet |
Don't use quotes around the string value. Doing so causes the argument not to be processed. |
^capitalize("frosty friday")^ | Frosty Friday | "frosty Friday" | not yet |
The value of $UserString is 'frosty friday'. |
^capitalize(^get(UserString)^)^ | Frosty Friday | Frosty Friday | not yet |
Don't use quotes around the string value. The value of $UserString is 'frosty friday'. |
^capitalize("^get(UserString)^")^ | Frosty Friday | "frosty Friday" | not yet |
You must use ^get^ or ^getFor^ to access attribute values. The value of $UserString is 'frosty friday'. |
^capitalize($UserString)^ | Frosty Friday | $UserString | not yet |
The ^value^ here is not needed as ^get^ returns the attribute value - see above. The value of $UserString is 'frosty friday'. |
^capitalize(^value(^get(UserString)^)^)^ | Frosty Friday | Frosty Friday | not yet |
The value of $UserString is 'frosty friday'. |
^capitalize(^value(eval($UserString))^)^ | Frosty Friday | Frosty Friday | not yet |
| ^value(capitalize(fROSTY fRIDAY))^ | FROSTY FRIDAY | FROSTY FRIDAY | not yet | |
| ^value(capitalize($UserString))^ | FROSTY FRIDAY | FROSTY FRIDAY | not yet |
contains( target, data )
Tests if the target string contains the data string using regular expressions.
Deprecated - use ^value(String/Set/List.contains(pattern))^
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^contains(frosty morning,ocelot)^ | false | false | not yet | |
| ^contains(frosty morning,fr.st)^ | true | true | not yet |
count( group )
Counts the number of notes within the specified group (container or group placeholder).
Data for the examples is taken from the following example, taken from /data/todo.
- todo
- Groceries
- apple
- garlic
- lemons
- Calls
- Jackson
- Letters
- Dr. Bryan
- Edmund Morris
- Mike Bonifer
- Work
- back up hard disk
- write chapter 17
- pay bills
- Groceries
Deprecated - use ^value(count())^
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^count(children(/data/todo))^ | 4 | 4.00 | not yet | |
| ^count(children(/data/todo/Groceries))^ | 3 | 3.00 | not yet | |
| ^count(children(/data/todo/Groceries/garlic))^ | 0 | 0.00 | not yet | |
Deprecated alternate forms of descendants designator: descendant, descendent |
^count(descendants(/data/todo))^ | 14 | 14.00 | not yet |
| ^count(ancestors(/data/todo))^ | 1 | 1.00 | not yet | |
| ^count(ancestors(/data/todo/Groceries/garlic))^ | 3 | 3.00 | not yet |
created( item[, format] )
Date/time (with optional formatting) of the creation of specified note based on $Created.
Deprecated - use ^value(format($Created,"formatString")^
| description | try | expect | result | ok |
|---|---|---|---|---|
| Test note ⇕ | ^created(this,"m/d/y")^ | 2/3/2009 | 2/3/2009 | not yet |
creator( item )
Name of the creator of the specified note as in $Creator (derived from Preferences).
Deprecated - use ^value($Creator)^
| description | try | expect | result | ok |
|---|---|---|---|---|
Who made the current note? No item parameter supplied |
^creator^ | Cookbook Tester | Cookbook Tester | not yet |
Who made 'this' note? |
^creator(this)^ | Cookbook Tester | Cookbook Tester | not yet |
Who created note "Tinderbox Action and Export Cookbook"? |
^creator(Tinderbox Action and Export Cookbook)^ | system | Cookbook Tester | not yet |
days( date, N )
Tests if date is within N days of today.
Deprecated - use ^value(days())^
| description | try | expect | result | ok |
|---|---|---|---|---|
$Date is 04/07/1976, 00:00 |
^days(^get(Date)^,7)^ | false | not yet | |
| ^days(yesterday,7)^ | true | true | not yet |
do( theMacro [,argument, anotherArgument, etc.] )
Execute the named macro (macro must already be defined in the current TBX).
Deprecated - use ^value(do())^
encode( data )
Encodes the argument string, replacing common non-ASCII characters with the corresponding HTML entities in &#NNNN form where NNNN is 2 or more characters holding a hexadecimal number value. For example, '&' is converted to '&'
NOTE: since the move to utf-8 output, the need for this code has reduced. Indeed, using it may cause double-encoding to occur so the entities are shown rather then the intended character they represent.
Deprecated - use ^value(encodeHTML())^
| description | try | expect | result | ok |
|---|---|---|---|---|
In this case, the entity's ampersand has been double-encoded to show the actual entity code. In real use the character on screen would be a ü as drawn by an 'ü' code. |
^encode(Hückel)^ | Hückel | Hückel | not yet |
endsWith( target, data )
Tests if the target string ends with the data string using simple string matching, in contrast to false which matches regular expressions.
Deprecated - use ^value(String.contains(regex))^
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^endsWith(frosty morning,morning)^ | true | true | not yet | |
| ^endsWith(frosty morning,night)^ | false | false | not yet | |
| ^endsWith(frosty morning,m...ing)^ | false | false | not yet |
equal( data1, data2 )
Returns the Boolean result of comparing data1 string with data 2 string. Primarily used with
every( group , attribute[, data] )
Returns true if every member of the group has a value for the given attribute. Alternatively, it returns true if the specified data is matched.
Examples are based on the following data:
| Name | UserFlag | UserNum |
|---|---|---|
| apple | true | 12 |
| pear | false | 3 |
| lemon | false | 3 |
| lime | true | 2 |
Deprecated - use ^value(every())^
| description | try | expect | result | ok |
|---|---|---|---|---|
Just an attribute. For this test to return false all children must have $UserFlag value of false. |
^every(children,$UserFlag)^ | false | false | not yet |
| ^every(children,$UserFlag,false)^ | false | false | not yet | |
| ^every(children,$UserNum,3)^ | false | false | not yet | |
For non-Boolean fields any value other than the standard defaults (empty string/set, zero number, never date) is coerced to 'true'. |
^every(children,$UserNum)^ | true | true | not yet |
exists( item | attribute)
Returns a Boolean evaluation within an ^if condition of whether an item note/object exists or if an attribute holds a value.
Deprecated - use $AttributeName short form Boolean test
firstWord( data )
Extracts the first word from the data string.
Deprecated - use ^value(firstWord())^
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^firstWord(We hold these truths to be self-evident)^ | We | We | not yet |
get( attribute[, format] )
fetch the value of any attribute of this note. If the optional second attribute is supplied, it specifies the formatting to be used. This allows custom formatting of dates.
Deprecated - use ^value($AttributeName)^ or ^value(format($AttributeName,"formatString"))^
| description | try | expect | result | ok |
|---|---|---|---|---|
Name is 'simple'. |
^get($Name)^ | simple | simple | not yet |
$Date is 7 December 2008 For UK system try Expected = "7 December 2008" For US system try Expected = "7 December, 2008" (N.B. comma) |
^get($Date,"L")^ | 7 December 2008 | 7 December 2008 | not yet |
$TestBoolean is set to true using an ^action^ call in $Try. |
^action($TestBoolean=true)^^get($TestBoolean)^ | true | true | not yet |
$TestBoolean is set to false using an ^action^ call in $Try. |
^action($TestBoolean=false)^^get($TestBoolean)^ | false | false | not yet |
getFor(path | item, attribute[, format] )
Fetch the value of any attribute of the note cited as a path or item. If the optional third attribute is supplied, it specifies the formatting to be used. This allows custom formatting of dates.
Deprecated - use ^value($AttributeName(reference))^ or ^value(format($AttributeName(reference),"formatString"))^
isDescendedFrom( item )
Boolean test if item is a descendant of the object in current scope.
Deprecated - use ^value(descendedFrom())^
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^isDescendedFrom(parent)^ | true | true | not yet | |
| ^isDescendedFrom(../..)^ | true | true | not yet | |
| ^isDescendedFrom(nextSibling)^ | false | false | not yet | |
| ^isDescendedFrom(/NoSuchNote)^ | false | false | not yet | |
UserString is "parent" |
^isDescendedFrom(^get(UserString))^ | true | true | not yet |
justChildren( [template] )
Includes only the immediate children of the current note (or agent) in the current Web page using their default template file or with the specified template file.
From v4.6 this is the same as ^children^ and deprecated in favour of the latter.
lastModified( item[, format] )
Date/time (with optional formatting) of the creation of specified note based on $Modified.
Deprecated - use ^value(format($Modified,"formatString"))^
lowercase( data )
Transforms a string or attribute to use all lower case.
Deprecated - use ^value(lowercase())^
| description | try | expect | result | ok |
|---|---|---|---|---|
Value is string 'Zoo'. |
^lowercase(Zoo)^ | zoo | zoo | not yet |
$UserString is "Zoo". |
^lowercase(^get(UserString)^)^ | zoo | zoo | not yet |
max( group , attribute[, precision] )
Returns the maximum value of an attribute in the designated group, with an optional precision.
Examples are based on the following data:
| Name | UserFlag | UserNum |
|---|---|---|
| apple | true | 12 |
| pear | false | 3 |
| lemon | false | 3 |
| lime | true | 2 |
Deprecated - use ^value(max())^
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^max(children(/data/fruit),UserNum)^ | 12 | 12.00 | not yet | |
Unlike the action function max(), ^max does not compare strings |
^max(children(/data/fruit),Name)^ | pear | 0.00 | not yet |
mean( group , attribute[, precision] )
Returns the arithmetical mean value of an attribute in the designated group, with an optional precision.
Examples are based on the following data:
| Name | UserFlag | UserNum |
|---|---|---|
| apple | true | 12 |
| pear | false | 3 |
| lemon | false | 3 |
| lime | true | 2 |
Deprecated - use ^value(avg())^
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^mean(children(/data/fruit),UserNum)^ | 5 | 5.00 | not yet |
min( group , attribute[, precision] )
Returns the minimum value of an attribute in the designated group, with an optional precision.
Examples are based on the following data:
| Name | UserFlag | UserNum |
|---|---|---|
| apple | true | 12 |
| pear | false | 3 |
| lemon | false | 3 |
| lime | true | 2 |
Deprecated - use ^value(min())^
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^min(children(/data/fruit),UserNum)^ | 2 | 2.00 | not yet |
not( condition )
If the enclosed condition is normally false, this makes it true and vice versa. Most commonly used with ^if statements.
Deprecated - use the != inequality operator.
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^not(true)^ | false | false | not yet | |
| ^not(false)^ | true | true | not yet | |
| ^not(^equal(2,2)^)^ | false | false | not yet | |
| ^not(^equal(2,frogs)^)^ | true | true | not yet |
opmlEncode( data )
opmlEncode() encodes all of the following to HTML entities: left angle bracket, right angle bracket, ampersand, (straight) double quote, (straight) apostrophe, and line feed character (ASCII #10).
Deprecated - use ^value(attributeEncode())^
| description | try | expect | result | ok |
|---|---|---|---|---|
This is paragraph 1. This is paragraph 2. |
^opmlEncode(^text(plain)) | This is paragraph 1. This is paragraph 2. | This is paragraph 1. This is paragraph 2. | not yet |
$MyString's value: This 'is" <paragraph 1. This & is >paragraph 2. |
^opmlEncode(^value($MyString)^)^ | This 'is" <paragraph 1. This & is >paragraph 2. | This 'is" <paragraph 1. This & is >paragraph 2. | not yet |
paragraphs( [item,] N )
Exports the first N paragraphs of the text of specified item (note). If item is not specified, content is drawn from 'this' note.
Deprecated - use ^value($Text.paragraphs(N))^
sum( group , attribute[, precision] )
Returns the sum of an attribute in the designated group, with an optional precision.
Examples are based on the following data:
| Name | UserFlag | UserNum |
|---|---|---|
| apple | true | 12 |
| pear | false | 3 |
| lemon | false | 3 |
| lime | true | 2 |
Deprecated - use ^value(sum())^
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^sum(children(/data/fruit),UserNum)^ | 20 | 20.00 | not yet |
today( [item] [, format] )
The current date and time. If item is supplied, it is ignored; it is accepted for consistency with other date operators like ^created and ^modified. The format argument is also optional.
Deprecated - use ^value(format(date("today")))^
| description | try | expect | result | ok |
|---|---|---|---|---|
|
Today is 18/01/2018 |
^today^ | 18/01/2018 | 18/01/2018 | not yet |
|
Today is Thursday |
^today("W")^ | Thursday | Thursday | not yet |
|
Today is in January |
^today(this,"MM")^ | January | January | not yet |
uppercase( data )
Transforms a string or attribute to use all upper case.
Deprecated - use ^value(uppercase())^
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^uppercase(frost)^ | FROST | FROST | not yet |
urlEncode( data )
item encodes URLs in accordance with RFC1738.
Deprecated - use ^value(urlEncode())^
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^urlEncode(http://example.com/cgi.bin?search=two words)^ | http://example.com/cgi.bin?search%3dtwo%20words | http://example.com/cgi.bin?search=two%20words | not yet |