Tinderbox has 44 built-in 'export codes' associated with HTML and text export, including export macros. Although they may be used in actions, queries and rules such use outside an export context is strongly deprecated and likely to less well supported - or not supported at all - in forthcoming versions. Action code has been developed for 'internal' use, i.e. in queries/action/rules as opposed for actual export from Tinderbox and thus internal use of export codes is now strongly deprecated (though often still legacy-supported) in favour of the new syntax.
Export codes can be used anywhere in the template HTML (or other format) file, though bear in mind the above developments and guidance. Export codes are marked with a caret (^) symbol, entered by typing Shift+6. All export codes start with a caret and - optionally - also end with one. In many cases the closing caret can be omitted, e.g. for brevity in complex ^if()^ statements. However, to ensure Tinderbox emits 'clean' HTML (with proper tag nesting) always include the the closing caret if a code comes at the end of a paragraph or note and the is no whitespace after it. The advice here to new users is to always include the closing caret, regardless.
A typical scenario is putting ^childLinks^ at the end of a note; the HTML output will render but it is better to put ^childLinks^ to ensure correct nesting of HTML tags. Without the closing ^ mark-up Tinderbox has to make a guess and will wrap the link list in <p></p> tags creating code that won't validate (if meeting such a criterion is required). Although Tinderbox generally guesses export code closures correctly, it is better practice for the user expressly to close their codes to avoid any ambiguity during processing.
Arguments. Export codes usually have one or more arguments; there is a separate listing explaining the meaning of code arguments such as 'item', 'data', etc.
Evaluation of arguments. Individual code arguments may be evaluated - i.e. allowing substitution of export code or regular expressions, date placeholders, etc., for explicit argument values. However, at present there is no way to tell if a given code's arguments are evaluated (unless it says so here in aTbRef) other than by trial and error (or asking Eastgate directly). One, all or no arguments may be evaluated for any given code. It is safest to assume an argument is not evaluated unless there is clear evidence in the notes to the contrary. Unlike in action code where attributes references are marked by using a $ prefix with the attribute name, this is not done in export code, though such syntax may work if used.
Tinderbox uses ^ as a delimiter for export elements such as
^title^
^value($Name(parent))^
It is not a requirement to provide a closing caret at the end of the code, though not doing so leaves Tinderbox to have to guess the users intent. The guess is normally right, but for the sake of an extra character you can avoid the guesswork. New users, especially, are advised to always close their export codes with a caret, thus:
^title <-- works but deprecated for new users
^title^ <-- safer usage
Sometimes, however, a caret is simply a caret. Two common cases appear:
- errors, where we specify an export element that does not exist because we have mistyped the name:
^tite^,^value($Name(parant))^ - uses of carets that are not intended for Tinderbox, such a regular expressions in JavaScript scripts.
Tinderbox exports a space after an caret in an unrecognised export element, because expressions like
$MyName=^Name^ <--- wrong
could loop infinitely. (The user doubtless meant to write either $Name or ^title^; there is no export element ^Name^). Thus on saving the note or dialog, Tinderbox would insert a space, thus:
$MyName=^ Name^
Exporting the extra space works well in some contexts, but not when the caret is part of a regular expression in, for example, JavaScript. The additional space is exported only if the name could be a mark-up element:
^Name^ -> ^[space]Name^
^Title^ -> ^[space]Title^
but
^[a-z] -> ^[a-z]
In post-v4 use there is also a de facto move to expect explicit quoting of all string literals (with double-quotes, ""), a significant exception being path parameters (e.g. path, partial path or note name) and designators which by convention are not quoted. Doing this will tend to pre-empt unexpected failures of user code.
There are syntax considerations for colour and date type attributes when read:
- ^value($ColorAttribute/format())^. In HTML Export, named colours are exported as hex code strings which include the # prefix character, e.g. "#99ff00".
- ^value($DateAttribute.format("formatString"))^. The format string is optional. Tinderbox offers numerous date formats.