As at v6.0.2, Tinderbox 6 now has 'built-in' templates in the app but they must be added to a doc (or the user create their own) in order to export data. This walkthrough shows how to add the built-in HTML templates to a new document and to adjust them for simple export use.

Here the process starts with a blank file, though it can be applied to a TBX document that already has data. It is suggested you use Outline view for this task even if you normally do your work in other view types.

An explanation of the cascading method by which the built-in default includes the content of descendant notes is outside the scope of this document. If unfamiliar with the concept, please see aTbRef.

1. Add the built-in HTML template set

1. Add the built-in HTML template set

Open File menu, Built-in Template and click HTML from the fly-out menu.

2. Review what gets added.

2. Review what gets added.

Notice that two new containers are added to the document. They will be added to the root level of the TBX. If either container already exists in that location the new notes will be placed the existing same-named container(s).

3. Expand the new containers

3. Expand the new containers

Three new notes have been added into the new containers:

  1. Two nested templates have been added to the the Templates containers. The reason for this is that the pair of templates are used in an 'envelope & letter' fashion to recursively export just not a note but all its descendants. This is likely not the desired result for simple export. A fix will be made for this further below.
  2. Because notes acting as templates ideally want a number of non-default text-related configurations, it helps to do so via a template. Thus when adding a template, Tinderbox also adds the built-in 'HTML Template' prototype and the container normally used for built-in prototypes.

4. Improving the choice of templates

4.1 Duplicate the HTML template

4.1 Duplicate the HTML template

Select 'HTML page' and press Cmd+D to duplicate the note. The duplication doesn't include the child template but that is no problem as the new template doesn't need it.

4.2 Rename templates to use more explanatory titles

4.2 Rename templates to use more explanatory titles
  1. Rename 'HTML page' to 'HTML page cascade' to indicate that the export includes the content of other notes.
  2. Rename 'HTML page copy' to 'HTML page single'. This template will only export the contents of the note to which it applied - i.e. one page per note.

4.3 Correct the code of 'HTML page cascade'

4.3 Correct the code of 'HTML page cascade'

Find the line of code:

^children(/Templates/HTML page/HTML item)

Change it to:

^children(/Templates/HTML page cascade/HTML item)^

There are two changes:

  1. Adding " cascade" to the path of the child template, reflecting the name change of the parent template.
  2. Adding a closing caret symbol (^) to the code. This isn't mandatory but is good best practice will all export code. If you get used to always 'closing' export tags with a caret then you don't force Tinderbox to guess where the end of the code occurs.

4.4 Correct the code of 'HTML item'

4.4 Correct the code of 'HTML item'

Find the line of code:

^children(/Templates/HTML page/HTML item)

Change it to:

^children(/Templates/HTML page cascade/HTML item)^

There are two changes:

  1. Adding " cascade" to the path of the child template, reflecting the name change of the parent template.
  2. Adding a closing caret symbol (^) to the code.

4.5 Correct the code of 'HTML page single'

4.5 Correct the code of 'HTML page single'

Delete all the code indicated. This is a reference to a child template that will not now be used.

5. Choose your default export template

You now have a choice.  

  1. 'HTML page single'. A note using this exports only the current note's content into a single HTML page.
  2. 'HTML page cascade'. A note using this exports a single HTML page but the page includes the title (an H2 heading) and text of every descendant of the note. N.B with this choice you probably don't want to also export the child and descendant notes as separate pages is their ancestor has already exported the content.

It might be useful to consider the effect of the options on exporting Note X, that has a child Note Y and grandchild Note Z

5.1 Example of the cascade export

5.1 Example of the cascade export

See how the title and text of Note Y and Note Z are also included. The main note's title uses and H1 heading and those of the included notes use an H2 heading.

5.2 Example of single note/page export

5.2 Example of single note/page export

Here, only Note X's title and text are used

5.3 This tutorial uses single not/page.

For the rest of this document the single note/page template will be configured as the document default, but you are free to use the other template if you wish. amend the instructions accordingly.

6. Setting the document default template via $HTMLExportTemplate

6.1 Setting the Document Inspector, system tab to $HTMLExportTemplate

6.1 Setting the Document Inspector, system tab to $HTMLExportTemplate

As there is no document settings control, the only way to set a default export template for all notes is to set a new default value for $HTMLExportTemplate. With any note selected (this step is not note-specific), open the Document Inspector, System tab and type HTMLExportTemplate (no $ prefix) into the search box. When you see the right attribute auto-matched click the Return key and the Category and Attribute pop-ups will be correctly configured for you.

6.2 Set the path of the desired template

6.2 Set the path of the desired template

Add the path as indicated and click Return to commit the change. All notes will now use this template by default until/unless you set a different one.

If you are doing this process in a document with pre-existing notes, you may need to reset inheritance of $HTMLExportTemplate if any notes already have a locally set value.

7. Setting notes and containers for export

7.1 The Templates and Prototypes folders

7.1 The Templates and Prototypes folders

As part of Tinderbox's automatic creation of these containers, both the Export ($HTMLDontExport) and Export Children ($HTMLExportChildren) boxes are un-ticked. This ensures he prototypes and templates and their containers don not export themselves during HTML export.

7.2 Avoid content in the root of the document

7.2 Avoid content in the root of the document

If you are going to export, it makes sense to put all exporting content in one (or more) root level. One tick-box in the HTML Inspector can turn off export of all children/descendants (as in the last step). This is much more controllable than the scenario of a root level map with tens or hundreds of notes only some of which should export requiring them to all be reviewed and set manually. Here a container 'Data' has been added to the root into which all the actual document notes will now go. The container name is not significant - choose whatever is pertinent. You don't have to use this step of the process but experience shows that if you wil be exporting it saves frustration later on.

8. Get a specimen file

A file with the above process used can be downloaded. That file also has a 'read me' note  explaining the changes made to configure the file.

This document was written using Tinderbox v6.0.2. Exporting is due to be given a larger revision in v6.x so do check for changes as some of the above steps may become easier - or unneeded - in due course.