Concept

The idea here is that you have made a series of text notes and imported then into Tinderbox. Each note added has been tagged with one or more 'tags' in a Set-type user attribute. You now want a quick way to review the notes based on a given tag.

The set-up that follows involves many steps you can leave out but they take little time and make the result much more usable. By the same token, feel free to use more colour or badges, shapes, etc to assist with review.

Colophon: this tutorial was planned and illustrated using Tinderbox v5.11.2.

In a hurry? Files for this tutorial can be obtained in ZIP form (including this article in PDF form) from http://www.acrobatfaq.com/tbdemos/review-demo.zip.

A sneak preview - Outline

A sneak preview - Outline

A rough idea of what you'll see when done, in Outline view…

A sneak preview - Map

A sneak preview - Map

…and Map view, and finally…

A sneak preview - review of matched tag content

A sneak preview - review of matched tag content

…and the review text for inspection on screen or export to text. This is using the Nakakoji (Text Export) view for the agent.

aTbRef Reference: Nakakoji view.

A new file & User Attributes

A new file & User Attributes

Start a new Tinderbox document. First you need to add two user atributes. Cmd+2 opens the Attributes palette. Click Create to make a new attribute and make appropriate settings in dialog. $SearchTag is a String-type attribute. $TagSet is a Set-type attribute.

Feel free to use different attribute names if you prefere, though don't forget to also adjust any code you see later on that uses these names.

aTbRef Reference: Attributes palette.

A container for Prototypes

A container for Prototypes

Add a note. Call it 'Prototypes'. It will become the container for the document's prototypes. Open the Rename dialog and add this code to the 'OnAdd Action' box then click OK:

$IsPrototype=true; $RuleDisabled=true; $DisplayExpressionDisabled=true; $ShowTitle=true;

This does four things. Any child note you add to this container is turned into a prototype (saves coding this manually!). Next, both the notes Display Expression and Rule are turned off as we won't need these running in the prototype. The Attributes for the latter two effects don't inherit ,so they will work in notes using the prototype. Lastly, this sets any prototype so the note shows it't title as a banner at the top of the text window.

Side note. For the prototypes, the names you'll use with have a 'p' prefix. You don't have to do this but this or some similar naming pattern will make prototypes easy to spot and ensure their names don't clash with the notes holding your analysis.

Now, save your TBX document as "Tag Reviewer.tbx". Don't forget to keep saving as you complete each step.

aTbRef References: $IsPrototype, $RuleDisabled, $DisplayExpressionDisabled, $ShowTitle.

A prototype for each source note - pJotting_note

A prototype for each source note - pJotting_note

Add a child note to the Prototypes container called 'pJotting_note'. The only setting you need here is to set $TagSet as a Key Attribute for the note. This makes it easy to set/review the tags allotted to the note.

A prototype for a tag listing - pTag_note

A prototype for a tag listing - pTag_note

Add another prototype, 'pTag_note'. Add both $TagSet and $SearchTag attributes as key attributes. Also give the note this $Rule:

$SearchTag=$Name; $TagSet=$Name;

It won't run here as you've disabled the $Rule for this note (only). The rule means that the two user attributes will automatically take the value of the note title (its $Name). If you add the Tag notes before you analyse/mark-up your source data, this step ensures that you have pre-populated pop-up lists of all tags to use with both attributes.

A prototype for analysis agent(s) - pAgents

A prototype for analysis agent(s) - pAgents

Whether your document uses just one agent to review tagged data or several, it is still useful to set up a prototype. Add another one, 'pAgents' . Add a $DisplayExpression:

"Jottings matching: "+$SearchTag+" ("+$ChildCount+")"

As the sneak peek above shows, the agent Display Expresion will report the tag being matched and the number of matches.

Set $SearchTag as the KeyAttribute. The value you type or (select from a pop-up list) here will be used by the agent query.

Though this next might seem counter-intuitive as the prototype is a note, use the Inspector or Info view to set $AgentQuery for the prototype, giving it this code:

$Prototype=="pJotting_note" & $TagSet.icontains($SearchTag(agent))

The query has no effect in a note but when the prototype is used on a agent, the agent will use the above code. The $SearchTag(agent) in the query is whatever value is set in the agent's key attribute.

Optionally, add a $Rule:

$Text=values("TagSet").isort.format("\n")

If used this will make the $Text of the agent an alphabetical ist (one term per line) of the tags used in $TagSet. It can be useful to review that when looking at available tags. However, if you use the pTag_note set-up, arguably this code isn't needed. You might, for instance use it for HTML/OPML/formatted export of the data matched by the agent.

aTbRef References: $DisplayExpression, $ChildCount, $Prototype, List.icontains(), $Text, values(), List.isort, List.format().

Why two tag related attributes?

Now is a good moment to explain this. $TagSet is a Set as for the source notes it is likely any given note may have more than one tag value meaning the attribute must be list based. Set-type atributes differ from List-type ones in that the former de-dupe entries, i.e. if the same value is added twice in a note, it doesn't make a second entry.

However, the agent is predicated on searching for a single tag value. Sure, the agent could use $TagSet as the key attribute and query term. However, this opens lots of scope for user error. If $SearchTag in the agent has a value already set and another is selected, the first still remains. Easier therefore to use a String-type which will only allow one value, albeit as the cost of a bit more set-up work. Actually having a note peer tag, in a real-world document is now bad thing especially if used over a protracted period. The tag note's $Text can hold notes about the intent of and application of the tag.

A prototype for the data review templates.

The easiest way to add this is to adapt one of the built-in prototypes. Go to file menu -> Built-in Prototypes -> HTML Template. It will be added to your Prototypes container. Select the note and rename it 'pExport_Template'. Open the note, select all and delete, close the note.

Add a folder for you Templates

Select the Prototypes container and press return to create a sibling note. Call it 'Templates' and click Return again to exit title edit mode. Open it's Rename dialog and add this OnAdd Action code:

$Prototype="pExport_Template";

The latter will ensure any notes you add to this container will use the pExport_Template' prototype.

Adding templates 1 - the 'envelope'

Adding templates 1 - the 'envelope'

Review of matches will be via an agent's Export Text view. So, you need two templates that work as an envelope and letter. The 'envelope' is used by the agent and includes each & every child using the 'letter' template. Add a child note to Templates called 'tAgent_page'. Open the note and give it this code:

Tag being matched: ^value($SearchTag)^ (^value($ChildCount)^ matches)
################^children("tAgent_data")^

Note - no line return is needed after the second line of code.

This template code will list the value of the $SearchTag tag being matched and report the match count. A line of hashes actas a a separator. Then each match (if any) is included below using the other export template.

aTbRef Reference: ^value()^.

Adding templates 2 - the 'letter'

Adding templates 2 - the 'letter'

Add the code:

 

----------------------------------
Note: ^title^
Tag(s): ^value($TagSet.format(", "))^
~~~~
^text^

Note, there is a blank line before the line of hyphens and no line break after the last line of code.

This code adds a line return (the previous match may not end with one) and then hyphens as a ruler (this is a plain text format). The next line lists the title of the note being processed. The next line shows the tag(s) used for that note. Then follows all the note's text.

aTbREf References: ^title^, ^text^.

Setting the template for pAgents

Setting the template for pAgents

Now select the 'pAgents' prototype note, click Cmd+Opt+N and open Nakakoji view. Select /Templates/tAgent_page from the pop-up template selector.

The default font for the main pane of the view, where you'll eventually view your data, is 12-point Lucida Grane. If you prefer a different font size/face, open the document's preferences (Cmd+8) and on the Text Export pane make adjustments as desired.

aTbRef Reference: Preferences: Text Export.

A container for Tag notes.

A container for Tag notes.

Select Templates and add a new sibling container 'Tags'. Open the Rename dialog and give it a Display Expression:

$Name+"  ("+$ChildCount+")"

…and an OnAdd Action:

$Prototype="pTag_note"

The former gives the count of known tags (the children of the container) and the latter sets the correct prototype for tag notes when they are created.

Now set the container to sort on $Name.

Optionally, add a $Rule:

$Text=collect("children",$Name).isort.format("\n")

As with the agent, this will give you a list of all the existing tags, though in this case, only those actually defined by tag notes for closer control over tag 'vocabulary'. In fact, both here and in the agent you can use either rule in both, one of each or none at all, as you so prefer.

aTbRef Reference: $Name.

Finishing the staging

Finishing the staging

Add a separator note, call it 'Back of house' and drag it above Prototypes. Save the file. It should look like the above. That's the behind the scenes prep done!

Set up for Review

Above the separator, add a new container 'Review' and give it a child note 'Jottings. Open Rename for the latter and give it the OnAdd Action:

$Prototype="pJotting_note"

The latter ensures all the source notes you put there use the right prototype - at this point it's mainly to show the $TagSet attribute so you can set/review values. You may, of course choose to add other customisations.

The 'Review' folder' is less critical if working in Outline view. For Map users, it helps as a map based on Review will hide all the back-of-house containers, as shown that the beginning of the document.

Set up your review agent

Set up your review agent

Select jottings and then Note menu -> Create Agent (there's no shortcut for this). Set the 'pAgents' prototype and click OK. The prototype takes care of the rest! If unsure, re-open the rename and see the query, display expression, etc., have been added.

Ready for analysis

Ready for analysis

Your new Tinderbox tool is ready! Just add tags, data and tag the data. Then open the agent, select a tag and then open Nakakoji view (Cmd+Opt+N) and review the data. The view can be dragged bigger if needed.

Worked example - a specimen note

This is an example source note with placeholder text. The note's title is shown in the back banner. The Key attributes table shows $TagSet in this case with two tag values. All this is set via an attribute, which you can see from the sidebar has been applied when the note was added to Jottings.

Worked example - Outline view

Worked example - Outline view

Here, four tags have been defined and six source notes have been placed in Jottings.

Worked example - the agent

Worked example - the agent

Here, in the agent text window, the desired $SearchTag value has been set. The shown title black bar still uses $Name but the window title uses $DisplayName telling you the search terms is 'Angeleso' and that there are two matches. The $Text pane lists the four existing tags (in a real document there would be more tags).

To review a different tag, select a different $SearchTag using the pop-up menu at right of the key attribute table.

aTbRef References: $DisplayName.

Worked example - the agent data in Nakakoji view

Worked example - the agent data in Nakakoji view

The view shows the summary (line #1 of the main pane) and information for two notes. This data can be copied or exported to file for use elsewhere. It could easily be pasted into another Tinderbox document and exploded out again into separate notes by using the 'ruler' line as a custom explode delimiter.

Worked example - Map view

Worked example - Map view

Here the map of the Review container is shown. The left container is the source data inside Jottings. On the right the analysis agent. Lots of scope here to customise to suit your own style of work. For instance the agent could alter the colour/shape/badge of matched notes.

Extending the model - more than one agent/tag?

More agents? Simply add more agents as siblings to the current one and set each up with a different $SearchTag value.

Querying more than one tag is possible but requires more set up. Imagine you want between 1 and 3 search terms. It would make sense to add a $SearchTag2 and $SearchTag3 and populate these via the Tag prototype. Now duplicate the agent prototype twice and in the copies add the extra attribute(s) to the key attributes table and amend the agent's query accordingly to add extra terms. Varying the join of terms (AND vs. OR) will still require manual adjustment of agent query. Prefer, prototypes - just make more variants with things like the join already set. Then, just pick the agent you want for the analysis.

Extending the model - harvesting tags?

Can Tinderbox auto-populate the tags folder? Not quite but with some action code and Explode most of that can be done. There are so many ways a tag might be defined within a source note that it's too much to include here. If interested, raise the topic in the Tinderbox forums.

Are there example files with which to experiment?

Yes, both the empty configured TBX file and the specimen data file plus this article in PDF form can be obtained in a ZIP file from http://www.acrobatfaq.com/tbdemos/review-demo.zip.