Tinderbox Action and Export Cookbook
This is Tinderbox Cookbook version 2.0.1, created in conjunction with Tinderbox 7.3.2. The locale settings used to export this document: en-US. Most date tests were written/tested on a UK day/month order system and thus tests may fail if exported using different locale settings.Tinderbox is a tool for making, analyzing, and sharing notes. Tinderbox works on Macintosh computers; a version for Microsoft Windows is under development.
One of Tinderbox's interesting features is that you can make notes that take an active role in helping you keep your work organized. For example, Tinderbox agents can automatically add tags to new notes that contain specified words or phrases, or can change the color of overdue tasks. These actions may be simple, but Tinderbox can also communicate with many powerful Web services.
Tinderbox also provides very flexible export facilities for HTML, XML, and other formats.
This Cookbook site provides brief examples of some of the many commands that Tinderbox provides for actions and exporting. It provides actual usage examples which were actually evaluated by Tinderbox when this document was exported. (Occasionally, improvements in the program may change the way Tinderbox hands an expression; this cookbook should also help to identify and confirm such changes).
This page collects some useful examples of common tasks and may serve as an introduction to the most common and useful tools. Other pages in the Cookbook examine Tinderbox expressions, operators, and export elements, providing examples of each element in use.
You can download the Tinderbox file that creates this site here. Want to contribute? We'd love a hand!
The final column in the test table is green if the result matched what we expected, red if the result didn’t match, and yellow if we don’t care. (For example, a random number might be any number, so we don’t know what to expect) In some cases, a red bar may indicate a testing problem rather than a problem with Tinderbox.
Deprecation. Some codes are now marked 'deprecated'. This means that while they may still work, such syntax should be avoided. New documents should not use such syntax and existing documents in regular use should be have their code reviewed to avoid retaining deprecated usage.Coping with HTML
Writing about HTML while using HTML can be tricky! Tinderbox provides tools that help technical writers, instructors, and developers.
Wiki: WritingAboutHtml
| description | try | expect | result | ok |
|---|---|---|---|---|
When output is HTML code that normally renders invisibly, how do I get to see the actual tags being output? In this example, $TestName is <p>!</p> |
escapeHTML($TestName) | <p>!</p> | <p>!</p> | not yet |
Counting things
In general, the best way to count things in Tinderbox is to create an agent; the count is simply the agent’s $ChildCount.
Sometimes, though, we simply want to count items in order to set an attribute or to include the count in an exported file. In this case, we can simply use sum_if to create the count “on the fly”.
The data for this example are taken from the following:
| Name | Urgent | Completed | Groceries | false | false |
|---|---|---|
| apple | false | true |
| garlic | false | true |
| lemons | false | true | Calls | false | false |
| Jackson | false | false | Letters | false | false |
| Dr. Bryan | true | false |
| Edmund Morris | false | false |
| Mike Bonifer | false | true | Work | false | false |
| back up hard disk | true | false |
| write chapter 17 | true | false |
| pay bills | true | true |
Wiki: CountingThings
| description | try | expect | result | ok |
|---|---|---|---|---|
Count the number of tasks in Letters that are urgent |
sum_if(children(/data/todo/Letters),$Urgent,1) | 1 | 1 | not yet |
Count the number of tasks in Letters that are not urgent |
sum_if(children(/data/todo/Letters),!$Urgent,1) | 2 | 2 | not yet |
Count the number of urgent tasks |
sum_if(descendants(/data/todo),$Urgent,1) | 4 | 4 | not yet |
Count the number of tasks in the entire list that are urgent and completed |
sum_if(descendants(/data/todo),$Completed&$Urgent,1) | 1 | 1 | not yet |
Count the number of tasks in the entire list that are urgent and completed |
sum_if(descendants(/data/todo),(!$Completed)&$Urgent,1) | 3 | 3 | not yet |
“Inheriting” from notes that aren’t your prototype
Tinderbox notes inherit from the note’s Prototype. At times, however, you may want the attribute of a note to depend on the attribute of the note's children, its parent, or on a separate container.
In this example, we have a container of Projects, each of which can hold some Tasks. Some notes are marked as Urgent. When a task has been finished, it is marked as Completed.
The data for this example are taken from the following:
| Name | Urgent | Completed | Groceries | false | false |
|---|---|---|
| apple | false | true |
| garlic | false | true |
| lemons | false | true | Calls | false | false |
| Jackson | false | false | Letters | false | false |
| Dr. Bryan | true | false |
| Edmund Morris | false | false |
| Mike Bonifer | false | true | Work | false | false |
| back up hard disk | true | false |
| write chapter 17 | true | false |
| pay bills | true | true |
Wiki: Inheritance
| description | try | expect | result | ok |
|---|---|---|---|---|
Do we need any Groceries? |
every(children(/data/todo/Groceries),$Completed) | true | true | not yet |
Is every task in Letters urgent? |
every(children(/data/todo/Letters),$Urgent) | not yet | ||
Does Letters hold any urgent tasks? |
any(children(/data/todo/Letters),$Urgent) | true | true | not yet |
Is every task in Work urgent? |
every(children(/data/todo/Work),$Urgent) | true | true | not yet |
| any(children(/data/todo/Work),$Urgent&(!$Completed) ) | true | true | not yet |
Working With Dates
Many Tinderbox agents and actions need to consider dates. Date arithmetic can be tricky — especially when different notations of date and time may be involved. This section describes some common tasks.
Many examples here use the following data:
| Name | Date |
|---|---|
| Bread and Roses strike settled | 12/03/1912, 11:00 |
| Titanic sinks | 15/04/1912, 15:00 |
| Fenway Park opens | 20/04/1912, 11:30 |
| August Strindberg dies | 14/05/1912, 22:00 |
| Holbrook, AZ meteor | 19/07/1912, 03:00 |
| Election Day | 05/11/1912, 00:00 |
Wiki: WorkingWithDates
IMPORTANT NOTE re date formats: tests below were written/exported on a day/month order OS. Exporting these tests (or copying/pasting tests to other TBXs) should work for all locales except the USA which must reverse day/month order in literal date strings in tests.
| description | try | expect | result | ok |
|---|---|---|---|---|
$Date is 29/11/2008. Note that == is true even if the time of date differs, as long as the two dates are within 24 hours of each other. |
$Date==date("11/29/2008 5:00 PM") | true | true | not yet |
Comparison date is "4/1/1912" (testing on dd/mm format OS). |
collect_if(children(/data/dates), $Date| Bread and Roses strike settled |
Bread and Roses strike settled |
not yet |
|
$Date is 15/04/1912. |
between($Date,date("1/4/1912"),date( "1/5/1912")) | true | true | not yet |
$Date is 15/04/1912. Note that parentheses may be necessary to ensure that operators are grouped as you expect. |
collect_if(children(/data/dates),($Date>=date("12/4/1912")) & ($Date| Titanic sinks;Fenway Park opens |
Titanic sinks;Fenway Park opens |
not yet |
|
between() can be more concise that writing out the comparisons |
collect_if(children(/data/dates), between($Date, date("1/4/1912"), date("1/5/1912")),$Name) | Titanic sinks;Fenway Park opens | Titanic sinks;Fenway Park opens | not yet |