Export 1
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 export elements, used in export templates. Export templates can also be used in some actions, but this syntax is now deprecated. Export template elements begin with the character ^. This page covers all the export codes except those relating to creation of links, which are covered in part 2 of the page.
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.^action( action )^
Perform the specified action code, possibly changing the values of one or more attributes. Nothing is exported.
Deprecated - use ^value(action())^
See the original tests on the deprecated code page.
^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.
Deprecated - use ^value(any())^
See the original tests on the deprecated code page.
^backslashEncode( data )^
Prefaces single and double quotation marks in data with a single backslash.
| description | try | expect | result | ok |
|---|---|---|---|---|
Note source string's double set of quotes as the outer pair are the parameter string delimiters. The inner pair are part of the string actually ecoded for output |
^backslashEncode(""Fiddlesticks!"")^ | \"Fiddlesticks!\" | \"Fiddlesticks!\" | not yet |
UserString is "Fiddlesticks!". |
^backslashEncode("^get(UserString)^")^ | \"Fiddlesticks!\" | \"Fiddlesticks!\" | not yet |
UserString is \"Fiddlesticks!\". |
^backslashEncode("^get(UserString)^")^ | \\\"Fiddlesticks!\\\" | \\\"Fiddlesticks!\\\" | not yet |
^beginsWith(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))^
See the original tests on the deprecated code page.
^capitalize( data )^
Transforms a string or attribute to use initial capitals.
Deprecated - use ^value(capitalize())^
See the original tests on the deprecated code page.
^children( [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.
In Tinderbox versions prior to 4.6, ^children() exported all descendants and ^justChildren exported immediate children. From 4.6 on, ^children exports immediateChildren and is a synonym for ^justChildren, whole ^descendants exports all the descendants of a note.
^cloud( item, count] )^
Exports the information displayed in the Common Words view, note tab.
^comment( data )^
All of the data within the parentheses of the comment is ignored when using the template to create Web pages.
| description | try | expect | result | ok |
|---|---|---|---|---|
Exports a standard HTML comment. |
^comment(This is a comment)^ | <!-- This is a comment --> | <!-- This is a comment --> | 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))^
See the original tests on the deprecated code page.
^count( group )^
Counts the number of notes within the specified group (container or group placeholder).
Deprecated - use ^value(count())^
See the original tests on the deprecated code page.
^creator( item )^
Name of the creator of the specified note as in $Creator (derived from Preferences).
Deprecated - use ^value($Creator)^
See the original tests on the deprecated code page.
^days( date, N )^
Tests if date is within N days of today.
Deprecated - use ^value(days())^
See the original tests on the deprecated code page.
^descendants( [template] )^
Includes all descendants (children, children of those children, etc.) of the current note (or agent) in the current Web page using their default template file or with the specified template file.
^directory( item )^
Name of the exported directory (i.e. parent folder name) of the note specified.
| description | try | expect | result | ok |
|---|---|---|---|---|
Test with no parameters - 'this' implied. |
^directory^ | Export1/directory/ | Export1/directory/ | not yet |
Explicit 'this' reference. |
^directory(this)^ | Export1/directory/ | Export1/directory/ | not yet |
Explicit reference to another note. Note 'Tinderbox Action and Export Cookbook' has its HTMLExportFilename set to 'index'. |
^directory(Coping with HTML output)^ | index/ | index/ | not yet |
^do( theMacro [,argument, anotherArgument, etc.] )^
Execute the named macro (macro must already be defined in the current TBX).
Deprecated - use ^value(do())^
See the original tests on the deprecated code page.
^docTitle^
The name of the current Tinderbox document (i.e. the OS filename). The '.tbx' file extension is omitted if present.
| description | try | expect | result | ok |
|---|---|---|---|---|
Show the Mac OS X filename of the current Tinderbox document. |
^docTitle^ | Tinderbox Cookbook | Tinderbox Cookbook v7-1-0b263 | not yet |
^documentCloud( [count] )^
Exports the information displayed in the Common Words view, document tab.
^else^
Branching code for ^if conditional statements. See also ^else^ and ^endIf^.
^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())^
See the original tests on the deprecated code page.
^endIf^
Closing code for ^if statements, use being optional. See ^if and ^else^
^endsWith( 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))^
See the original tests on the deprecated code page.
^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.
Deprecated - use ^value(every())^
See the original tests on the deprecated code page.
^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.
See the original tests on the deprecated code page.
^file( item )^
The filename of the file for the web page of a item (or note), i.e. $HTMLExportFileName+$HTMLExportExtension.
Note that the value of $HTMLExportFileName cannot be evaluated internally. It is calculated only on export to allow for naming collisions, etc. The following is not a valid substitution unless $HTMLExportFileName has a user-set value: ^value($HTMLExportFileName+$HTMLExportExtension)^
| description | try | expect | result | ok |
|---|---|---|---|---|
Here the name is taken from the note $Name "filename test". The space will be suppressed. |
^file(this)^ | filenametest.html | /Export1/file/filenametest.html | not yet |
Here the name is taken from the note $Name "filename test". The space will be suppressed. In this test, $HTMLExportFileNamespacer has been set to an underscore. |
^file(this)^ | custom_separator.html | /Export1/file/custom_separator.html | not yet |
$HTMLFileName has been manually set to "mytest". |
^file(this)^ | mytest.html | /Export1/file/mytest.html | not yet |
^firstWord( data )^
Extracts the first word from the data string.
Deprecated - use ^value(firstWord())^
See the original tests on the deprecated code page.
^get( )^
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"))^
See the original tests on the deprecated code page.
^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"))^
See the original tests on the deprecated code page.
^host^
The host of the site of this Web page, derived from HTML preferences' URL.
A trailing backslash is supplied, if one is not supplied in the source preference (q.v. ^root^).
| description | try | expect | result | ok |
|---|---|---|---|---|
URL in TBX's HTML preferences is 'http://www.example.com'. No host is set in the TBX as doing so breaks other tests. |
^host^ | http://www.example.com/ | not yet |
^if( condition )^
Tests if condition is true. The condition may use agent query syntax for expressions
^include( item[, template] )^
Includes a single item or note (with its default template) in the web page for the current note; or may return every item in a group, e.g. through a find(). If template is supplied, that will be used to process the included material)
^indent( data )^
Exports the data as a string (sequence of characters) for each ancestor of the currently exported note, i.e. one indent per outline level, except the root. If data is not supplied a tab character is emitted per indent.
^isDescendedFrom( item )^
Boolean test if item is a descendant of the object in current scope.
Deprecated - use ^value(descendedFrom())^
See the original tests on the deprecated code page.
^isInside( item )^
Boolean test if item is a direct child of the object in current scope.
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^isInside(parent)^ | true | true | not yet | |
| ^isInside(../..)^ | false | false | not yet | |
| ^isInside(nextSibling)^ | false | false | not yet | |
| ^isDescendedFrom(/NoSuchNote)^ | false | false | 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.
See the original tests on the deprecated code page.
^lastModified( item[, format] )^
Date/time (with optional formatting) of the creation of specified note based on $Modified.
Deprecated - use ^value(format($Modified,"formatString"))^
See the original tests on the deprecated code page.
^lastWord( data )^
Extracts the final word from the argument
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^lastWord(We the people)^ | people | people | not yet | |
Alternative: use lastWord() |
^value(lastWord("We the people"))^ | people | people | not yet |
^lowercase( data )^
Transforms a string or attribute to use all lower case.
Deprecated - use ^value(lowercase())^
See the original tests on the deprecated code page.
^max( group , attribute[, precision] )^
Returns the maximum value of an attribute in the designated group, with an optional precision.
Deprecated - use ^value(max())^
See the original tests on the deprecated code page.
^mean( group , attribute[, precision] )^
Returns the arithmetical mean value of an attribute in the designated group, with an optional precision.
Deprecated - use ^value(avg())^
See the original tests on the deprecated code page.
^min( group , attribute[, precision] )^
Returns the minimum value of an attribute in the designated group, with an optional precision.
Deprecated - use ^value(min())^
See the original tests on the deprecated code page.
^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.
See the original tests on the deprecated code page.
^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())^
See the original tests on the deprecated code page.
^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))^
See the original tests on the deprecated code page.
^path^
The relative path for this web page's file from the top-level directory you selected for storing HTML files to this file.
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^path(/data/fruit/apple)^ | data/fruit/apple.html | data/fruit/apple.html | not yet |
^randomChildOf( item [, template] )^
Includes an export of a random child of the specified item or note through its default template or supplied named template.
^randomLine( item )^
Scans the text of a designated item or note (or, if no argument is supplied, the current note). The text is split at paragraph breaks (e.g. carriage returns), and one line (i.e. a paragraph) is chosen at random.
^root^
Returns the relative path from the current file to the directory that contains the cover page. A trailing backslash is supplied (q.v. ^host^).
^sectionCloud( [item, count] )^
Exports the information displayed in the Common Words view, section tab.
^sectionNumber( item )^
The hierarchical number of the item (note) based on the present hierarchy and outline sort order; it items is omitted scope is 'this'.
| description | try | expect | result | ok |
|---|---|---|---|---|
| ^sectionNumber(/data)^ | 7 | 8 | not yet | |
| ^sectionNumber(/data/fruit)^ | 7.1 | 8.1 | not yet | |
| ^sectionNumber(/data/fruit/apple)^ | 7.1.1 | 8.1.1 | not yet | |
| ^sectionNumber(/data/fruit/pear)^ | 7.1.2 | 8.1.2 | not yet |
^setRoot( [newRoot] )^
tells Tinderbox to use its first argument (newRoot) as the value of ^root^ until either another ^setRoot^ is found or the current file being exported is complete. To restore relative URLs, use ^setRoot()^ with no arguments.
^sum( group , attribute[, precision] )^
Returns the sum of an attribute in the designated group, with an optional precision.
Deprecated - use ^value(sum())^
See the original tests on the deprecated code page.
^text( item[, N, plain] )^
Returns the body (text and graphics) of the item or note, i.e. includes any existing mark-up. If a note name is not specified, 'this' is assumed as the focus. If the note only contains an image, the image's tag (<img>) is exported.
Optionally, just the first N words of the text of the item or note may be returned and/or the the text can be returned plain without added HTML mark-up.
^title( item )^
The title of the item or note, i.e. the contents of $Name.
^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")))^
See the original tests on the deprecated code page.
^uppercase( data )^
Transforms a string or attribute to use all upper case.
Deprecated - use ^value(uppercase())^
See the original tests on the deprecated code page.
^urlEncode( data )^
item encodes URLs in accordance with RFC1738.
Deprecated - use ^value(urlEncode())^
See the original tests on the deprecated code page.
^value( expression )^
Evaluates an expression and returns it as a string.
| description | try | expect | result | ok |
|---|---|---|---|---|
Mathematical addition. |
^value(2+3)^ | 5 | 5 | not yet |
UserString is "42" |
^value($UserString)^ | 42 | 42 | not yet |
UserString is "42". Since "UserString" is a string, "+" concatenates strings |
^value($UserString+7)^ | 427 | 427 | not yet |
UserNum is "42". Since "UserNum" is a number, "+" adds two numbers. |
^value($UserNum+7)^ | 49 | 49 | not yet |
$MyColor is named color "bright blue ". Without formatting a named color is exported as a name string and not hexadecimal value. This may not be suitable for uses like HTML/CSS so you may need to use .format(), see other tests below. |
^value($MyColor)^ | bright blue | bright blue | not yet |
$MyColor is color value "#00ff00 ". Without formatting a hexadecimal color is exported as a hexadecimal value |
^value($MyColor)^ | #00ff00 | #00ff00 | not yet |
$MyColor is named color "bright blue ". With formatting a named color is exported as a hexadecimal value. For colors, no formatting string is needed. Alternate valid syntax: ^value($MyColor.format())^, ^value(format($MyColor))^. Dot operators are recommended as best usage. |
^value($MyColor.format)^ | #0000ff | #0000ff | not yet |
$MyColor is color value "#00ff00 ". Without formatting a named color is exported as a name string and not hexadecimal value |
^value($MyColor)^ | #00ff00 | #00ff00 | not yet |
$Test date is 15/08/2011, 14:44. If the Date attribute is not formated, the local OS short date format plus the hor/minute time is returned. The exact form will thus vary by locale. |
^value($TestDate)^ | 15/08/2011 14:44 | 15/08/2011, 14:44 | not yet |
$Test date is 15/08/2011, 14:44. The default unformatted string equates to using a format string of "l h:mm". compare this with the test above. N.B. this may vary by locale. |
^value($TestDate.format("l h:mm"))^ | 15/08/2011 14:44 | 15/08/2011 14:44 | not yet |
$Test date is 12/03/2012, 14:44. Date is now formatted in RFC 822. An error may occur is this is exported in winder as the offset given will not be for summer time. |
^value($TestDate.format("*"))^ | Mon, 12 Mar 2012 14:44:00 +0000 | Mon, 12 Mar 2012 14:44:00 -0500 | not yet |
^version^
Exports the version number of Tinderbox used to create this Web page. The number is exported as a string without a prefix, i.e. "6.0.0" not "v6.0.0".
| description | try | expect | result | ok |
|---|---|---|---|---|
The version string may vary as fixes and test versions are released. As such means the 'Expected' value needs to be updated for the current version. If the 'result' column shows a valid (later) version number this test is, in effect, passed. Test here uses a 'begins with' comparison so export using betas doesn't give a fail. |
^version^ | 6.3.1 | 7.3.2 | not yet |