As I've mentioned several times before, Frank Tansey, Bill Humphries and I collaborated during the second day of Tinderbox Weekend SF to develop a bit of agent code designed to help automatically assign metadata to Tinderbox notes. Having read James Vornov's post tonight about his efforts to add a "Section" attribute to his Tinderbox white board, I thought it was high time to write this up. James, I think this may be a shortcut to what you're after.

What is Category Factory?

Assume you have a large collection of Tinderbox notes on diverse subjects, and you want to easily categorize these notes. One solution would be to create some sort of keyword or category attribute, and manually assign categories or keywords to each note. This process is actually what I've always done in Tinderbox, and exactly the way I assign categories for DSD.

As soon as one starts to assign categories, however, it's possible to encounter notes that fit in more than one category. Again, a solution might be to add another category or keyword attribute, or manually append another keyword to the list of keywords in each note's keyword attribute.

Obviously, this can quickly get out of hand, with multiple category fields, or take a lot of time as you manually sort through a subset of notes and add keywords. This can get particularly ugly if you have a large collection of notes that you decide you want to add new categories/keywords to after the fact. Fortunately, there's a means of getting Tinderbox to add any number of keywords or categories to your notes with a minimum of effort on your part. This is what Category Factory does.

Setting It Up

First, all your notes need to have some attribute that you want to assign meta data to. In the case of this example I'm going to call that attribute Keywords, though it could as easily be called "categories" or "Sections" or anything else. If your notes don't have this attribute already, use the "Attributes" window (Command-2) to create a User Attribute of the proper type, create a prototype that does have the attribute (along with any other key attributes you want displayed in each note), select all your notes and use the Quick Stamp tool (Command-1) to set the prototype of all your notes to the new prototype. If your notes already have prototypes, simply add this new attribute to the key attributes for those prototypes.

Next, open up the macro editor (Command-2 again, and select the "Macros" tab), and create a macro named categoryFactory with the following syntax:

^get(Keywords) ^if(^contains(^get(Keywords), $1))^else^ $2^endif

What we have here is a bit of code that would normally go into the Action section of an agent, but we're going to make it a macro to make it easier to reuse in multiple agents. The first bit "^get(Keywords)," checks the Keywords attribute of each note, and returns the string it finds there (if any). The next section, "^if(^contains(^get(Keywords),$1))^", tells Tinderbox to check the Keywords returned in the first part of the macro to see if the string "$1" is already contained in those Keywords. In the case of this macro "$1" is a variable for the actual metadata we want our eventual agent to look for, for example the word "Apple." If the Keyword attribute already contains "$1" (whatever it may be), the macro exits, doing nothing.

However, if Keywords doesn't already contain "$1," the final part of the macro "^else^ $2^endif" executes. This bit tells Tinderbox to insert the string represented by the "$2" variable into the Keywords attribute, appended to whatever else might already be contained in that attribute.

In most cases, "$1" and "$2" are going to be the same word - you'll want to check if a particular term such as "Apple" is already in the keywords for the note, and if it isn't, you'll want to add "Apple" to the keywords. Having two distinct variables simply increases the flexibility so you can check for a term, and if it isn't there, insert a different (but probably related) term instead (i.e. check for 'Apple", and if it isn't there, insert the string "Macintosh").

Once your macro is set up, it's time to make the agent. Create an agent to search for a particular term or content you want to find in your notes. Let's again use "Apple," so we'll want to set up an agent to search Text or Name for the term "Apple." In the Action field in the agent, set up the following action:

Keywords=^do(categoryFactory,Apple,Apple)^

This tells the agent to set the Keywords attribute to the result of the macro "categoryFactory" that we set up above. The first occurrence of "Apple" is what we want "$1" to be in the macro, and the second is what we want "$2" to be. Save the macro by clicking "OK," and if you have any notes that contain the term "Apple" in either the note text or the note name, you should see the agent collect these notes. If you open up the notes and look at the Keyword attribute, you should see that "Apple" has been added to the content of the attribute.

Create a second agent and do the same as above, but this time use "OS X" for "$1" and "$2" (Keywords=^do(categoryFactory,OS X,OS X)^). You should see the agent collect all the notes that contain "OS X" in the text or name, and "OS X" added to the Keywords attribute. If a note contains both "Apple" and "OS X" it will show up in both agents, and have both keywords assigned to it.

Using this technique, you can build as many Category Factories as you want, for whatever terms you want, and have Tinderbox merrily assign keywords (or categories, or whatever) to all your notes. As you add notes, these agents will automatically categorize them based on their content, possibly in several different categories or with multiple keywords. If you chose to add a new keyword or category, Tinderbox will automatically assign it to the appropriate notes without your intervention.

Extending Category Factory

There are any number of ways to extend Category Factory, most of which I leave up to the Tinderbox community to develop and surprise me with! Some thoughts I've had along these lines involve setting up the agents to search on an attribute rather than the text or name of a note - for example, all notes created during the past year might be assigned a Keyword of "2004." Category Factory also seems ideal for creating ad hoc and automatic weblog categories and per topic content for RSS feeds. Play with it and let us all know what you come up with!

• CategoryFactory