Export Codes
|
This version is out of date, covering development as far as v4.2.5. It is maintained here only for inbound reference links from elsewhere. Jump to the current version of aTbRef. |
| A Tinderbox Reference File : Export Codes |
Export Codes |
|
Tinderbox has a number of codes associated with HTML and text export, though they may also be used in macros, actions, queries and rules. Over time, the move has been to provide non-export-code alternatives for 'internal' use, i.e. in queries/action/rules as opposed for actual export from Tinderbox . Thus in v3.0.0 an internal alternative if-else usage was introduced. The arrival of v4.0.0 saw 'internal' syntax massively expanded and so in v4.0+ use, internal use of export codes is deprecated (though usually still supported) in favour of the new syntax.
These codes can be used anywhere in the template HTML (or other format) file, though bear in mind the above developments and guidance. The codes all start with a caret (^) and optionally 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 ^ Tinderbox has to make a guess and will wrap the link list in
tags creating code that won't validate (if meeting such a criterion is required).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.
Tinderbox uses ^ as a delimiter for export elements such as
^title^
^getFor(parent,Name)^
Sometimes, however, a caret is simply a caret. Two common cases appear:
^titte^, ^gft(parent,Name)^Starting in Tinderbox 3.6.0, Tinderbox exported 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^).
Exporting the extra space works well in some contexts, but not when the caret is part of a regular expression in, for example, JavaScript. In Tinderbox 4.0.0, the additional space is exported only if the name could be a markup element:
^Name^ -> ^[space]Name^
^Tutle^ -> ^[space]Tutle^
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, ""). Doing this will tend to pre-empt unexpected failures of user code.
| Up: A Tinderbox Reference File | |
| Previous: Actions & Rules | Next: Visual Styling |
Licensed under Creative Commons Attribution-Noncommercial-Share Alike 3.0 License
[See aTbRef CC licence Attribution/Waiver info info]
