Understanding HTML export (including values)

Lots of challenging learning curves in Tinderbox, but so far the most challenging for me has been understanding how to export documents. What I thought was going to be the easiest module has turned out to be the opposite.

I don’t claim to have figured it out, but I thought I would share what I (think) I have figured out, in the hope it might be corrected or simplified by wiser heads than mine, and might help any still befuddled. I have benefitted hugely from several guides and tutorials by other Tinderboxers, but none quite worked for me, so I’m hoping this might be the start of a tutorial which makes the process easier. (Or someone can point me to a tutorial that is simpler than this one, and doesn’t leave vital steps and definitions out!).

This is what I understand is the process for exporting documents that can include values from the documents’ attributes.

You need three documents to make this work:

  1. A format template . This can be one of the built in templates or one you create.
  2. An export template — what you want the document to look like, with values for the various bits you want to insert from Attributes)
  3. the source document — where the text and values are coming from

So:

Make sure you have the Built in HTML template (Click File/Built in Templates /HTML) loaded. This should create a prototype called HTML Template , in a folder called, confusingly, Prototypes .

Create an Export template as you’d like to see your finished document (with all the attribute values) exported. It’s wise to just create the document as you’d like to see it with all the actual values in, then save it as an export template (say, Letter Template , or Note Template . This is not a prototype . It seems to be best saved in a Container called Templates because that’s where Tinderbox will look.)

Once you’ve saved that document, replace ^value()^ for any attribute where the brackets contained the attribute, eg ^value($FullName)^ . Where you want the text of the source document to be reproduced, just put ^text^ .

Once that’s done, you now have a template. You can confirm this is the case by clicking on the Inspector’s Properties Inspector tab. Of the three buttons below the Prototype drop-down menu, Template should be checked.

Now set this as the template for the source document you want to export (open the Inspector, go to HTML Inspector, choose Export, then Template . The drop-down list should include the template you just made.)

Back in the text pane, you should then be able to preview what the document will look like once exported by clicking on the button Preview and in HTML (if you can’t see these buttons at the top of the pane, select Text Pane Selector from the Window menu. ) I don’t believe, contrary to some guides, you need to change the prototype of the document at any point.

To export you can just copy and paste the result in preview or HTML into whatever document you’re working on. Or you can choose Export Selected Note from the File menu.

If you want to export a series of documents , put them in the same container, ensure they all have the right template assigned, and then for the container note, create a separate template with one line: ^children^ in it. Assign that template to the container and then just export that as the selected note. There won’t be a gap between them but that should work.

(My post was misleading. Deleted.)

I found this a bit confusing to follow as there are a number of misunderstandings here and you are perhaps overthinking the process. In a new document with notes you wish to export, just add the built-in ‘HTML page’ template (via the main File menu) and Tinderbox will _automatically add the necessary template(s) and prototype(s). If only one export template is present it is used as the default (HTML export) template for all notes - until and unless you add and set other template(s). Now use FileExport and all notes bar your Templates and Prototypes folders will be exported. That’s the default - you can configure the document to export fewer notes as there are controls (attribute settings) built into the app to allow export control down to per-note level. Assuming there is an HTML template in the document, Export selected note will export only the currently selected note.

The only purpose of the ‘HTML page’ prototype is to make sure template notes are best configured for adding export code - a good example is that the prototype suppresses auto-correction of straight quotes (which HTML browsers recognises) to ‘curly’ typographic quotes (which they don’t†). It also sets a monospace font so you can see whitespace accurately as this can be important in some export contexts. If unclear as to the role of prototypes see here and here.

† Web browser HTML code parsing is beyond Tinderbox’s control.

Also note that the prototype for export templates was renamed in v8.1.1. If added for the first time in a doc using v8.1.1+ the name of the prototype is now ‘HTML’. This change does not affect pre-existing documents with an existing ‘HTML Template’. Both do the same thing. The naming was changed because some users misinterpreted the prototype’s [sic] name as meaning it was a template rather than a configuration prototype for a template.

So, the number of items needed for export is just two and not three (as you have suggested). Thus:

  • a source document (the thing you wish exported).
  • an export template.

Even if you subsequently delete the template, adding the built in
If you haven’t already try this demo: TB7-HTML-export.dmg. Although written when v7 was the Tinderbox current version, the same processes hold true.

Tinderbox’s ‘HTML’ export is very powerful, but the app is a toolbox. You tell it which tools to use, rather than it only allowing you certain tasks (as might be true in other apps). The term ‘HTML’ is used as back in 2001, blogging & HTML page creation were seen as one of the likely uses of the app. The Web, or use of it, and text-based code have come a long way. aTbRef’s templates (in its source TBX) give an indication as to how quite powerful and nuanced export templates can be made.

Notwithstanding Preview mode in the text pane, this is not an app for WYSWYG HTML page design.

I strongly suggest working through the exercises in the DMG linked to above as it shows most of the basic processes and should help clarify some of your miss-assumptions‡ as to how export works in Tinderbox.

‡ That’s not meant in an offhand way. We all make assumptions when forced to guess, and sometimes these are incorrect.

Thanks, @mwra, appreciate it. I did actually go thro your export examples, they were a great starting point, but unfortunately I struggled with them. I think probably the problem is that I’m trying to include attribute values in the output, rather than simply printing out/saving a text document, which I agree is relatively straightforward. (I’ve taken another look at your demo and I’m sure I’m missing something, but I can’t see any example of or reference to including any values (except ^text^, ^title^ and ^children^ which I agree are simple).

It’s not being able to, or not finding a straightforward way to, include any or all the key attribute values of a document by default in the export process which has led me to try to outline the steps to do this. (The most helpful I found were Brian Crane’s (@bcrane) excellent posts but I did find myself missing some steps and not getting the desired result.

Anyway, I do agree my explanation is confusing, not least the title of the post, and I’m sure you can point out an easier way to include fields in the outputted document than the way I proposed. I agree that this does look to be an extremely powerful aspect of Tinderbox which could make preparing reports, stories etc a really useful adjunct.

Ah - sorry, that didn’t come across from your opening post.

OK, if I now understand correctly, you want to include in the exported HTML page some/all of a note’s KeyAttributes? Did you look at the aTbRef templates? Consider how this page is generated:

So the ‘KA table’ part is added by ‘including’ content for the current note using a different template ‘5-basic_item_attribute’. I won’t post all the code for the latter here, but you can look it up in the aTbRef TBX doc. You will note that the table items, i.e. the number of ‘KA’ rows is hard-coded. At the time I wrote it it would not have been possible to live parse a note’s $KeyAttribute values but I suspect it could be done - albeit in fairly byzantine fashion - using ^action()^ calls to wrap list.each() loops. Both the latter’s usage is described in aTbRef.

If the included values need to be in the ‘body’ of the text, then you have no choice but to put the export code, e.g. ^value($SomeAttribute)^ into the the source $Text. So you will see the export code when looking at the note in the app.

Anyway, give the above a try, and ask here if stuck.

I’ve made a note to extend my export demo to better cover this aspect - although the more complex the export the harder it is to generalise for the new (export) user. :grinning:

Thanks, I’ll take a look at this @mwra. I’ve also changed the title of the post to hopefully make clearer for others what the exercise is about.

1 Like

Meanwhile, I’m updating my export demo files(above) to use the new v8.1.1+ ‘HTML’ template prototype and to fix the colour schemes so they render correctly in OS dark mode - something I’d overlooked (basically (re-)apply the built-in ‘Tinderbox 78’ colour scheme via doc settings).

You are welcome to try this (experimental) key attribute export ‘parser’. I make a template called ‘ka-table’ with this code:

^action(
$MyExportString=;
$KeyAttributes.each(X){
var xValue(eval('$'+X));
$MyExportString=$MyExportString+'<tr class="kaRowAttr">'+"\n";
$MyExportString=$MyExportString+'<td class="kaAttribute">$'+X+'</td>';
$MyExportString=$MyExportString+'<td class="kaRowValue">'+xValue+'</td>'+"\n";
$MyExportString=$MyExportString+'</tr>'+"\n"
})^
<table id="kaTable">
^value($MyExportString)^</table>

Note the need to use single quotes to wrap strings that need double-quoted HTML attribute values (e.g. CSS class names). I’ve discovered that \n line break codes used within an ^action()^ must (as at v8.2.1) be double-quote enclosed or they are not parsed correctly. Thus the \n codes are ‘added’ as discrete strings in the code above.

The output (for a note with 2 KAs) is like so:

<table id="kaTable">
<tr class="kaRowAttr">
<td class="kaAttribute">$MyString</td><td class="kaRowValue">A Test</td>
</tr>
<tr class="kaRowAttr">
<td class="kaAttribute">$MyNumber</td><td class="kaRowValue">42</td>
</tr>
</table>

To add this table into a page-reporting HTML template, put the code ^include(this,ka-table)^ into the <body> of the HTML. for instance:

<body>
<h1>^title^</h1>
^include(this,ka-table)^
^text^
</body>

This is a rather nice example of the flip side of not having a simple HTML export. Some assembly is required, but it puts a lot of power in one’s hands. If the user doesn’t understand HTML, they can always ask here in the forum.

As I say, I’ve stated work on an improved set of export demo files. Plus some other regulars here have expressed some interesting ideas for a better interactive primer on export - but that’s “jam tomorrow”.

1 Like

My go-to source for HTML quick reference is W3 School’s site:

I know some purists do not like W3 Schools’ examples, etc., but the site always delivers what I need to know.

2 Likes

Apparently people who like this:

are called purists, so perhaps I am one of those ? :slight_smile:

(Reading two accounts of the same thing can, of course, be clarifying too)

Just following up on this please. Some years down the line. Have the new demo’s been published for version 9?
Thanks.

Have you by any chance published the export demos for version 9? Thanks.

Export hasn’t changed—in the contexts covered—since then but it looks like I last updated the demo files at v8. see: https://www.acrobatfaq.com/tbdemos/TB8-HTML-export.zip.

The demo doesn’t cover Markdown, which post-dates the above, and ‘Markdown export’ is just a method to make HTML.

A point to bear in mind is that in recent versions people are making more in-app use of the Text pane’s ‘Preview’ sub-pane, i.e. without exporting. But, regardless of whether you actually export files, the preview content still uses HTML export. So, you still need to understand the export template process to use in-app preview beyond its basic zero-configuration use. This latter aspect isn’t covered in the above as it is out of scope of the intent of the demo.

†. The fact some apps read ‘.md’ files code to render (via HTML) text—as in some PKM apps it is still just a pre-mark-up for HTML. I’d recommend learning how HTML export from Tinderbox works then how Markdown use alters that process will make the whole easier to understand. I’ve no intention of adding Markdown to the above as it is written to cover the basics of export. I’d rather someone expert in Markdown tackled the latter in depth (i.e. at a level beyond ticking a boc to use Markdown, which is already covered in aTbRef (here).