Deprecated

This is Tinderbox Cookbook version 2.0.0, created in conjunction with Tinderbox 5.11.2.

The locale settings used to export this document: en-GB. 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:

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

brightness()

return the relative brightness, on a scale of 0-100, of a color.

Deprecated - use Color.brightness.

description try expect result ok
brightness(white) 100 100 not yet
brightness(#000) 0 0 not yet
brightness(bright red) 100 100 not yet

compute the color that is 50% as bright as white

brightness(#ffffff,50) #7f7f7f #808080 not yet
brightness(#808080,150) #c0c0c0 #c0c0c0 not yet

hue()

computers the hue of a color, expressed as a color-wheel angle from 0 to 360°. Also, transforms a color by changing its hue while leaving its brightness and saturation unchanged.

Deprecated - use Color.hue.

description try expect result ok
hue(bright red) 0 0 not yet
hue(#004000) 120 120 not yet
hue(rgb(0,0,255)) 240 240 not yet

leave bright red unchanged

hue("bright red",0) #ff0000 #ff0000 not yet

shift "red" slightly toward yellow and green

hue("bright red",20) #ff5500 #ff5500 not yet

shift "red" slightly toward blue

hue("bright red",340) #ff0055 #ff0055 not yet

shift "red" slightly toward blue, using a negative angle

hue("bright red",-20) #ff0055 #ff0055 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("white") 0 0 not yet
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,frost)^ true true not yet
^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

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 system 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
^min(children(/data/negatives),UserNum)^ -4 -4.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 12/07/2012

^today^ 12/07/2012 12/07/2012 not yet

Today is Thursday

^today("W")^ Thursday Thursday not yet

Today is in July

^today(this,"MM")^ July July 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%3dtwo%20words not yet