Export 1

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 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 v5112 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 '&amp;'

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 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 custom_separator.html not yet

$HTMLFileName has been manually set to "mytest".

^file(this)^ mytest.html 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 7 not yet
^sectionNumber(/data/fruit)^ 7.1 7.1 not yet
^sectionNumber(/data/fruit/apple)^ 7.1.1 7.1.1 not yet
^sectionNumber(/data/fruit/pear)^ 7.1.2 7.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 15/08/2011 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, 15 Aug 2011 14:44:00 +0100 Mon, 15 Aug 2011 14:44:00 +0100 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. "4.6.0" not "v4.6.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^ 5.11.2 5.11.2 not yet