This version is out of date, covering development from v8.0.0 to v8.x.x. 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 v8 Icon

Exploding Notes

A note's text ($Text) can be 'exploded' (split) into a container holding a number of discrete smaller notes by specifying where Tinderbox should divide the current text. The newly created notes contain an appropriate segment of the original note, using part of the same text as the note title. The basic default behaviour is to split the source by paragraph, using the paragraph of text as the note's text and the first sentence of the paragraph as the note's title. However, there are a number of option, described below that control the title and content of the new notes. There will (should!) be no empty notes, such as those that might arise where two hard line returns are used as faux paragraph breaks, as these unwanted 'empty' outputs are automatically deleted as part of the Explode process. Empty notes will not be emitted for sequences of multiple paragraph breaks, i.e. sequences of greater than two breaks.

This process can be used to help with the import of data as well as for existing notes. For imports, drag, a plain text format file into an Outline or Map view, so as to create a new note. Note with that, or with a large existing note, selected in the view pane, choose Explode… from the Note menu. The option is available regardless of which pane has focus (prior to this, be aware that the Explode menu option is disabled if the input cursor is in the text pane).

Calling Note ▸ Explode presents the Explode pop-over. There are essentially three discrete sets of options to set before committing the explode.

Finally, the Explode button closes the pop-over and starts the Explode process using the choices set above. Focus remains on the exploded note. The Return keypress will act like a button press and start the Explode.

Custom delimiters

This is a either a literal string (i.e. the actual characters to match) or a regular expression pattern. For instance:

What results from an Explode?

The exploded (source) note itself remains unchanged and a new child container of the selected note is created, called 'exploded notes', and which contains the resulting new notes (i.e. the individual exploded notes are grandchildren of the source note). Each note contains as its text a section of the original text with the notes being titled according to the choices (described above) made before exploding. Using a secondary container for the notes might seem odd until realising this allows for the fact, more so for exploding existing notes than for new import, that the note being exploded might already have children; thus the new notes are separated from existing children of the exploded note.

Also notice that the 'exploded notes' container is added to the outline order after any pre-existing child notes for the exploded note, i.e. it is the last child (and thus easily accessible via the lastChild designator, amongst others).

The 'exploded notes' container does not inherit anything from the source note. However, the Action box allows the 'exploded notes' $OnAdd to be set afresh for each explode. Also, the 'Exploded Notes' prototype (see below) is added to the 'exploded notes' child container of the exploded source note. Either the action or the prototype can be used to read values from the parent note or to set values in the newly exploded notes.

'Exploded Notes' prototype

When a note is exploded the 'exploded notes' container has a prototype added and applied from '/Prototypes/Exploded Notes' (The /Prototypes container is created if needed before the new prototype is aded to it). Note the case sensitive spelling of the post explode container's title vs. that of the prototype's; this avoids naming collisions. By default, the only customisation of this prototype is to add $ChildCount as a Displayed Attribute. The prototype make it easy to set up things like counts and such if doing repeat explodes in the same document. This prototype can be added manually, for instance to customise it before doing an explode. By contrast, to 're-install' the default version, simply delete the any existing version of the prototype and do another explode.

Working with exploded notes

Of course, the constant name of the container holding the new notes ('exploded notes') makes it easy for agents to find and work on the new notes' actions. Be aware that unless the 'exploded notes' is cleaned up or renamed after an explode, there may be more than one container of that name. A benison of this is that it is possible to write a generic agent to act on the contents of all explode results using an $AgentQuery:

$Name(parent)=="exploded notes" 

By adding a preceding descendedFrom() query argument to the above query, the scope of action can be reduced to items descended from a given container.

descendedFrom(To Do) & ($Name(parent)=="exploded notes") 

This might be done because of the nature of the resulting agent action to be applied or simply to reduce agent update cycle time.

In summary:

The explode action is applied after the text of the newly-created note is set, allowing the action to modify or depend on the exploded text. Explode also remembers the most recently-used delimiter, which can be convenient when using complicated regular expression delimiters.



A Tinderbox Reference File : Import : Exploding Notes