Actions
| Tinderbox User's Manual : Actions |
Actions |
|
Actions make your Tinderbox document smarter and more helpful by automatically doing things that you might forget, or things that you might not have time to do yourself. For example, an agent could search for especially interesting and urgent notes that might interest you, and perform the action Color=red to bring them to your attention.
Several different kinds of notes can perform actions.
Actions are simple: an action sets the value of an attribute. But because almost every facet of your Tinderbox document is, in fact, the value of an attribute, actions are flexible and powerful.
Tinderbox is a personal content assistant; you can arrange for Tinderbox to perform chores on your behalf. The Tinderbox system of attributes and values makes it easy for your assistant to perform a wide range of tasks for you, helping to organize and tag information and bringing especially interesting or urgent items to your attention.
At the same time, it is important for assistants to understand some boundaries. Tinderbox actions never create new notes, and never move or delete notes you made. The assistant can suggest you move or delete a note that seems out of place or obsolete, but the final decision is always yours.
This chapter describes the most commonly-encountered and useful Tinderbox actions. See Appendix 3 for details on all Tinderbox actions.
Actions make your Tinderbox document more personal — more specifically adapted to your immediate needs and work style. At the same time, actions make Tinderbox a more effective assistant, shouldering a greater share of the work and letting you concentrate on the more interesting and demanding aspects of your work.
For example, it is often convenient to tag notes with an indication of topic, forming a sort of index to our notebook. Using conventional tools or paper, it might be tempting to organize topics very carefully at the outset, taking steps to make sure that every kind of note we require is anticipated, and that every topic is unique. In time, though, elaborate systems like this break down. Some notes seem to fit into two or three topics, others into none. Some topics accumulate too many notes because they were too broad, or because more information on the topic is discovered than you originally anticipated. Sometimes, notes are misclassified by accident. Sometimes, your understanding of a definition changes, so that a note you classified one way at the beginning of the project would later be classified a different way. And, sometimes, you just don’t have time to classify a note, or you can’t figure out the best way to classify it, and so the category of Unfiled notes grows until you can no longer fully trust the index.
No classification system is likely to be perfect, but actions can help you keep things organized and can make it easy to reclassify notes as your understanding changes. Agents can search for unfiled notes that contain significant words and phrases; these can be gathered for your attention or even automatically classified. Containers can automatically propose classifications for the notes created inside them; the container of notes from the History of United States Naval Operations in World War II might automatically propose keywords or tags “WW2” and “Navy”. Rules can enforce workflow requirements or business logic; for example, if you expand a Task into a container holding several subtasks, a Rule could automatically change the Task into a Project.
if($ChildCount>1){ Prototype=Project;}
Actions are themselves stored at attributes of notes. They can be inherited from prototypes, so each member of a class of notes can share the same actions. Actions can even create and modify other actions.
Keep in mind, however, that as assistant’s purpose is to help you to accomplish your work more quickly and pleasantly. It is not essential to arrange for the assistant to do everything! Instead, let your agents and containers do what seems easiest and most helpful.
Tinderbox is designed for organic growth; it is usually best to start with a simpler Tinderbox document and gradually add more active assistance as you need. Little is gained by making a large initial investment in complex infrastructure. The nascent Agile Methods approach to software development proposed the useful slogan, "You Aren't Going To Need It", to encourage deferring the construction of more elaborate infrastructure until its utility is clearly evident.
Finally, it is not essential or desirable to use every Tinderbox feature and facility in every project. Assistants render assistance when their help is useful; sometimes, it may be best and most efficient to do a task yourself.
Tinderbox provides different kinds of actions — agent actions, container actions, adornment actions, and rules. Each kind of action has a subtly different meaning.
Container actions set a note’s values when the note is moved to the container, or when a note is created inside that container. A container action suggests a sensible or typical value, which you can then change if the situation is atypical. For example, a weblog’s archives might set PublicationDate=today when a new note is moved into the Public container, but you remain free to backdate the post if you wish.
Adornment actions are usually tools. An adornment with an action is a special tool that let’s you do something conveniently. (You could also use a Stamp, of course)
Agent actions are usually instrumental, gathering notes into categories to bring them to your attention or setting values on the basis of search criteria. An agent uses its query to select a set of notes, and performs its action on each note that satisfies the query. Agents do simple tasks that you might forget; for example, they can automatically assign general topics to some notes for which you hastily overlooked jotting down a topic.
Rules enforce constraints and business rules. If a container says that "$PublicationDate=today", that’s a suggestion. When a rule says it, it’s the law. If you change the value, the rule will simply change it back; if that’s not what you want, you either need to remove the conditions that trigger the rule, or you need to change the rule itself. For example, if a rule says that
if(!$FinalReportDate) {$Status="incomplete"}
then, if this note has no FinalReportDate, its status will be incomplete, whatever we day. Either we have to file that final report, or we have to change the FinalReportDate; until we do, or the Status will remain incomplete.
In summary, Agent actions act on the notes that the agent gathers. Container actions act on notes added to the container, or notes created inside the container. Adornment actions act on notes that are placed on top of the adornment. Rules act constantly, but apply to the note itself.
From anywhere,
A rule is an action attached to a note (or container) that acts only on that note. Rules run periodically. You may use the same operators for a rule as for an agent. For example, the rule
$Urgent = any(child,$Urgent)
will make a note Urgent if any of its children are urgent.
To create a rule
Two search expression operators, |=(or) and &=(and), make it
easier to write rules.
$TheAttribute |= expression;
sets TheAttribute to true if it is already true, or if the expression is true. If TheAttribute is a number, it sets TheAttribute only if its current value is zero; if TheAttribute is a string, it sets TheAttribute only if the current value is empty.
Similarly,
$TheAttribute &= expression;
sets TheAttribute to be true only if it is currently true AND the
expression is also true.
You may use quoted strings to assign compound values, for
example:
OnAdd="$Priority=$Priority(parent);$Color=red;...."
Rules may also use simple arithmetic and logical expressions.
$Width=5+2;
$Width=$Height(parent)*1.5;
$Urgent= ("Overdue" | "Essential");
Width = ($Width(/Configuration/sample)+1)*$Scale;
Rules can be inherited from prototypes just like other attributes. Inheritance is powerful: you can easily find yourself asking Tinderbox to evaluate thousands of rules. Tinderbox constantly evaluates rules in the background, so using lots of rules is not necessarily impractical, but sometimes an agent may be a better and more efficient solution.
Contradictory actions may lead to constant document changes and should be avoided. For example, two different agents might each be trying to set the color of different notes. The first agent looks for Urgent notes, and sets their color to be Red. A rule checks notes for internal consistency, verifying that all required information is filled in. If the note is not valid, it is colored Orange. What will happen if a note is both urgent and invalid? The rule will turn it Orange, then the agent will turn it Red, and then the Rule will make it Orange again.
attribute= value
Sets that attribute to that value, for all the notes the agent finds. Recall that attribute names are case-sensitive.
For instance, $Color="red" turns the note red. To remove a value from a note’s attribute, leave the right-hand side of the assignment empty.
$Color=;
removes any special value assigned to note’s color; after this action is performed, the note’s color will be whatever color it inherits from its Prototype, or the default value of Color if the note has no prototype.
Actions may be combined in a list, separated by semicolons.
$Color="red";$BorderColor="blue";
Each attribute has a single type, which determines what kind of information that attribute contains. Some attributes are dates, some numbers, some are strings. Details about types are discussed in Appendix 3.
Tinderbox automatically converts types as needed, so you usually don’t need to worry about types. When in doubt, it is a good practice to use quoted strings to remove ambiguity
Color=red; OK: Tinderbox converts "red" to a color
$Color="red" Better!
$Name="red" OK: Tinderbox treats "red" as a string
$Name=3+4 OK: Tinderbox sets the name to "7"
$Name="3+4" OK: Tinderbox sets the name to "3+4"
The format()operator converts various types of attributes to text strings, giving you control of exactly how the string is formatted.
format(value,format_string)
For example:
format($Created,"L")
takes the note’s creation date and formats it as a "long local date", such as "Sunday, March 23, 2007 1:26pm".
If value is a date, format_string may be any date export code.
L: local time, in long format, using the system format settings
l: local time, in short format, using the system format settings
d: day of the month
D: date 01-31, with leading zero
m: number of month
M: abbreviation of month
MM: name of month
M0: numeric month 01-12, with leading 0
w: abbreviation of weekday
W: name of weekday
y: year
t: time, in local format
h: hour of the day on a 24-hour clock
H: hour of the day on a 12-hour clock
mm: minute of the hour
s: second
p: AM or PM
=: date in ISO 8601 format (example: 2004-02-18)
If value is a set, the format string is the delimiter used to separate items in the set. Alternatively, you may supply five arguments to format the set as an HTML, XML, or xoxo list:
format(value,list-prefix,item-prefix,item-suffix,list-suffix)
For example, to format a set $Topics as an unordered HTML list:
format($Topics,"<ul>","<li>","</li>","</ul>")
If value is a number, the arguments are numeric and specify the precision and width of the decimal number:
format(what,precision, width)
For example, if $myNum is 3.1415927, then
format($myNum,2,7) is " 3.14"
format($myNum,2) is 3.14
format($myNum,0) is 3
Actions may assign one attribute’s value to another attribute. If we have a user attribute named Title, then we could write
Name=$Title;
to automatically move the value of Title to the note’s Name
attribute. The '$' indicates that this is an attribute reference; the action
Name=Title
would rename the note to the string, "Title".
Attribute references may refer to other notes through keywords such as "parent", "child", "next" and "previous". A full list of keywords is found in Appendix 3. For example:
Status=$Status(parent)
makes the status of this note the same as the status of the parent, while
Status(parent)=$Status
sets that status of this note’s parent to match its worn.
Attribute references may also refer to a note through its unique name, or through a path expression:
$ChildCount(/London/monuments)
refers to the note named “monuments” inside the top-level container named "London".
$Color=$1
sets an attribute to the first subexpression from the agent query.
For example, if the agent query looked for notes that have a line of the form
Color: red;
using the query
Text(Color: (.+)\r)
then the action
$Color=$1
sets the Color of the note from the color specified in the text.
Actions may be conditional:
if(query) {action}
if(query) {action} else {action}
The query may be any query that could appear in an agent. See the chapter on Agents for a full discussion.
A very common conditional action is a suggestion, assigning a value only if no value has yet been assigned. For example,
if(!$Status) {$Status="waiting for action"}
A more compact way to write this in Tinderbox is the conditional assignment |=:
$Status |= "waiting for action"
Tinderbox actions can perform interesting and useful computations as they pass information within and between notes.
Common binary operators include
+ adds two numbers, concatenates two strings, or computes the union of two sets
- subtracts two numbers, or removes an item or a set from a larger set
* multiplies two numbers
/ divides two numbers
& logical and of two boolean values
| logical or of two boolean values
Unary operators include:
! logical not
- numeric negation
Conventional operator precedence is used, and expressions with equal precedence are evaluated from left to right. Parenthesis may be used to group expressions as desired.
Many additional actions are discussed in Appendix 3.
Two additional kinds of actions provide additional power for special needs.
Shell actions provide access to the operating systems and onward to the files and applications of your computer and to the resources of enterprise servers and the Internet.
Template actions let you use the export template system to compose the result of your action. Though template actions are no longer common, the export template system excels at building HTML, XML, and specialized text strings, and template actions may sometimes be handy when you need to build a complex string value.
SHELL ACTIONS: ` AND RUNCOMMAND
The shell operator ` passes the rest of the action to the operating system command processor and runs that action as a separate process. For example,
$Text = `ls -l
will replace the text of this note with a listing of your home directory, while
$Text=`curl $URL
will replace the text of a note whatever information can be fetched from the URL stored in the note’s URL attribute.
For more complex actions, the runCommand function is often more convenient.
$Text = runCommand(command_line, input)
Execute the specified command line, passing it the result of evaluating input. The standard output of the command, if any, is the value of the completed action. For example:
$Status=runCommand(“sendmail -f address@example.com”,$Text)
will send the note’s text as an email message.
TEMPLATE ACTIONS
Export template markup may also be used in actions. This feature was formerly popular, but is now seldom useful. Export codes in actions are now deprecated.
Export codes are introduced by a caret (^) following the = sign. The remainder of the expression, up to the next semicolon or the end of the action, is interpreted as an export template.
myString=^ Note ^get(Name): ^linkTo(/someNote);
For more information on template actions, refer to Appendix 3.
If you wish to use the template mechanism to construct a complex string, a cleaner approach is the exportedStringfunction.
exportedString(note,templateFile)
exportedString(note,templateString)
The first form of exportedString takes a reference to a note and the name of a file in the HTML Export Template folder, and returns the result of applying the template to the note. The second form requires no external file; instead, its second argument is the template string itself.
exportedString(this,"^getFor(parent,Name)")
or
exportedString(this,$MyTemplate)
For more information about HTML Export and markup Tinderbox uses for this process, see the HTML Templates chapter of this manual and Appendix 4.
Actions never create or delete notes.
Actions never change a note's parent or move the note in the outline. (Actions can set the note's Xpos and Ypos coordinates, but otherwise actions never move notes.)
| Up: Tinderbox User's Manual | |
| Previous: Agents | Next: Fetching from the Web |
