Export Codes
|
This version is out of date, covering development from v4.6.0 to v4.7.1. It is maintained here only for inbound reference links from elsewhere. Jump to the current version of aTbRef. |
|
| A Tinderbox Reference File : Export Codes | aTbRef Site Map |
Export Codes |
|
Tinderbox has 72 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 is deprecated and likely to less well supported - or not supported at all - in forthcoming versions. Over time, action code has been developed for 'internal' use, i.e. in queries/action/rules as opposed for actual export from Tinderbox and internal use of export codes is now deprecated (though usually still 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. 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.
Export codes can be used in test export (Nakakoji view) templates but only use codes that make sense - e.g. exporting a bulleted HTML list won't help when exporting plain text.
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 practive for the user to expressly 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^
^getFor(parent,Name)^
Note the lack of 4 prefix for 'Name' in the last example. 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:
^titte^, ^gft(parent,Name)^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^). 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^
^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, ""), a significant exception being path parameters (e.g. path, partial path or note name) which by convention are not quoted. Doing this will tend to pre-empt unexpected failures of user code.
There are syntax considerations for color and date type attributes when read:
More about export codes:
| 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]
