1. General notes

OPML is an open standard for transferring outline-type data between applications. Apps like OmniOutliner can import OPML, allowing Tinderbox data to be exported to other outliners.

Format limitations: OPML is a plain text format. Text formatting, i.e. bold, underline, font face/colour, highlighting can't transfer via OPML, nor may Tinderbox links between notes.

This tutorial was made using Tinderbox v6.1.1 and OmniOutliner v3.10.6. The built-in templates referred to here are those shipping in Tinderbox v6.

Set up Tinderbox as suits your style - there is no one 'correct' way. In this tutorial you'l make a very simple to-do list including some nested items.

Even if you generally write/work in other views, for Tinderbox export it is suggested you use Outline view as it gives the clearest map of what you may expect in output terms.

2. Tinderbox initial set-up: add the necessary export templates

2.1 Add the necessary export templates

2.1 Add the necessary export templates

This action only needs doing once (per TBX document) - skip this step if you have already added these templates.

In Tinderbox, open the File menu, Built-in Templates, and then Scrivener from the sub-menu.

2.2 What gets added to your Tinderbox document

2.2 What gets added to your Tinderbox document

Two nested templates are added, 'OPML' and 'OPML item'. If a root-level 'Templates' container doesn't exist, Tinderbox will add one. As the templates use a built-in prototype 'HTML Template', the latter - and its container ('Prototypes') - are also added if necessary. In most mature documents, the templates and prototypes containers will likely already exist and so the new notes will be added into the existing relevant containers.

The default built-in 'OPML item' template exports a Tinderbox note's $Name, $Text and $Checked. Adding any further custom data requires editing the 'OPML item' template.

3. Add a simple to-do list

A new container 'Tasks' has been added - this is the container which will be exported as the OPML list. The list has items, one of which has sub-items. Tick-boxes for the $Checked attribute are displayed (View menu -> Use Checkboxes), as the state of these will be exported. Some items have some $Text and the last one has a web link embedded in its text.

4. Set the template for the OPML-exported container

Select the 'Tasks' container in the main view (left pane). If the HTML tab of the text pane is selected, notice that no export template is currently selected. You need to set the new 'OPML' template you just added above.

4.1 Selecting a template from the HTML tab.

4.1 Selecting a template from the HTML tab.

Open the HTML pane pop-up and select the 'OPML' template from the list. Mature documents may have a longer list. If the TBX document has already been given a document-wide default, this pane will use that and show code - likely from the wrong template - in the HTML pane. You will therefore need to use the HTML Inspector to set the correct template.

4.2 Selecting a template via the HTML Inspector

4.2 Selecting a template via the HTML Inspector

Open the Inspector (Cmd+1). Check in the top row of buttons that the HTML Inspector ('<>' button) is selected.

From the Template pop-up select the 'OPML' template. If the text pane of the main window has the HTML tab selected, the code shown (if any) will refresh to use the new template.

4.3 Setting the correct extension for the exported file

4.3 Setting the correct extension for the exported file

So that the app that will use the exported data can recognise it as OPML, set the export extension (stored as $HTMLExportExtension) to '.opml'. Note the value should include a full stop (period) at the beginning.

5. Reviewing the OPML

If you don't know OPML mark-up or don't like looking at code, skip to the next main step.

5.1 Note $Text becomes the OPML item _note value

The to-do item 'Change Oil' is now an OPML outline item. As the note has text, this is exported as the OPML item's _note attribute value.

Ideally, notes exported via the method should avoid really large amounts of text.

5.2 Formatting in $Text is not retained

5.2 Formatting in $Text is not retained

Paragraph breaks in $Text will be maintained but not text formatting or web links. For the latter the link anchor text exports but not data as the the link defined for it (compare this with the $Text seen in step #3). This issue is a limitation of the OPML format and not Tinderbox itself. In addition, the app receiving the OPML might not correctly understand HTML even if custom-embedded into the _note value. So the limitation is the combination of the OPML format + source app + receiving app.

6. Export the OPML file

This is only needed if the whole document has never been exported before, otherwise skip the next sub-step.

6.1 Setting the Export location

6.1 Setting the Export location

Open the HTML Inspector, and click the button next to Export to. A standard file chooser dialog will open. Navigate to the desired folder (and/or create new ones), select the folder and click the Open button. The dialog closes and the location is set.

Bear in mind, that unless you are exporting a note/container that is at root level (i.e. $OutlineDepth is 1), the single container export will export to a relative location within the specified export folder. If those sub-folders don't exists you will need to create them (as at v6.1.1, though that may change in later releases). If in doubt about this issue ask in the Tinderbox forums.

6.2 Exporting the container

6.2 Exporting the container

With the 'Tasks' container selected use File, Export Selected Note to create the OPML file in the previously specified location.

6.3 Data seen in another app

6.3 Data seen in another app

Here the OPML file exported from Tinderbox v6.1.1 has been opened in OmniOutliner Pro v3. Notice that the $Text and $Checked data has transferred correctly (though without text formatting and inline links).

7. Summary

This tutorial shows the basics of data transfer via OPML. Be aware that applications which support OML interchange do not necessarily support use of any/all non-standard attributes in OPML <outline> elements. so experimentation may be involved.

A copy of the TBX file used for the tutorial can be obtained from http://www.acrobatfaq.com/tbdemos/v6-OPML-demo.tbx.zip.