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