This version is out of date, covering development from v9.5.0 to v9.7.3. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

Tinderbox v9 Icon

Export: 'envelope and letter' technique

For export of multi-level listings such as section indexes, OPML or full HTML site maps, it is usual to use a pair of templates. The 'Envelope' is the actual full page, in the appropriate export format. This template includes in its body an include call to a second, recursing 'letter' template. A recursing template is one which calls itself. In effect is say "do something and if there are any children include each of them using this template. Thus the children of the original include call their children and so on down to the lowest outline level descendants of every branch of the starting container note. The 'letter' template should be designed so that each included note's output data is a legitimate piece of code within the overall exported page, e.g. in HTML <li> list element or an OPML <outline> item element

This technique is the mechanism used to provide aTbRef's site map of every page in the exported HTML site. The 'envelope' is created and a 'letter' of however many sheets as needed is placed within. For those with aTbRef's source TBX, the source code for the envelope and letter templates may be viewed.

Another issue with recursing template export is that a given note can only export itself once, other than as an include. However, it may be desirable to export date in more than one configuration or format. A note's alias shares the same template attributes, although the alias is exported as a discrete copy (into its outline location). Thus an alias, for reasons cited, cannot be used to help in this context. The solution is to anchor the export from another note.

Again as an example, consider aTbRef's site map. The root note of this TBX is already exported as an HTML page but it is also needed as the seed of the site map page. So, instead, another note is used to export the 'envelope' template. In the case of the site map, the template is used only the one across the site, so in this case the include for the root note is in the envelope template. If the envelope/letter templates were needed for several different exports from the same TBX, the envelope template's include code could be replaced by ^text^ and the include code be moved into the $Text of the note exporting the 'envelope'.

Although perhaps intimidating at first side to those without any coding experience, the principle is very simple once understood and solves a lot of export-related problems.