2.
Tinderbox mechanics 2: Attributes, action code, and agents
Notes are bundles of attributes
A Tinderbox note is a bundle of information. For example, a note has rich text and a name. If we export the note with an appropriate template, these data will be printed to an html file. We have seen that the export code for exporting a note’s rich text is ^text^, while the code for the note’s name is ^title^.
So if I export target_note with a template_note that contains nothing but
<!DOCTYPE html>
<html>
<head>
<title>^title^</title>
</head>
<body>
<p>^text^</p>
</body>
</html>
… then the exported file will be a valid html file showing title and rich text.
Besides title and rich text, a Tinderbox note contains many other pieces of information. A note is in fact a collection of variables—305, to be precise. Formally speaking, a note is a struct data type: a grouped collection of variables that can be accessed by a single pointer. In Tinderbox-speak, these variables are the note’s attributes.
Action code and export code
Attributes are the matter of Tinderbox action code. Any attribute can be accessed in Tinderbox code using the following:
$AttributeName(designator)
Code gets divided into two domains—action code and export code. Action code is code used by agents, rules, stamps, and during the act of placing a note inside another. It can also be performed by a template, by using the ^action(code)^ export code.
Action code can be used inside templates when its embedded inside ^if(condition)^ and ^value(expression)^. For example, you can print the outline depth of target_note to the exported html file by putting ^value($OutlineDepth)^ somewhere inside your export template. Thus any attribute can be exportedu sing the following:
^value($AttributeName(designator))^
There are over 300 system attributes built into Tinderbox, organized under headings such as General and Appearance. You can also create your own attributes, and these will appear under the heading User.
Action code in agents
A Tinderbox agent is a note that collects aliases of other notes that meet a certain condition, called a query. An agent is a search-and-collect mechanism—akin to what we call a “smart group” these days. But besides collecting an agent can also change the notes that it collects.
The query of an agent (stored in the attribute $AgentQuery) is action code. The attributes of the notes that an agent collects are then manipulated by another piece of action code, stored in the attribute $AgentAction.
Agents are what makes Tinderbox an intelligent note-keeper. You can do things to notes—basically anything—“if” some condition is true. An agents collects (aliases of) notes that meet some query, and then changes the values of their attributes (and the agent’s action can require other conditions to be met as well).
Action code in $DisplayExpression
Action code can also be the value of certain attributes. For example, I can prepend the created date of a note to its displayed name while keeping its actual name hidden and intact. I do this by entering action code into the $DisplayExpression attribute. When $DisplayExpression is empty, Tinderbox displays the note’s $Name. But when $DisplayExpression has a non-nil value, this gets evaluated and becomes the note’s new $DisplayName, which is the name you see in all the views. In other words, $DisplayName is $Name unless $DisplayExpression is set.