# Export Templates

Tinderbox placeholders begin with a caret (^). On typical English keyboards, carets are entered by typing Shift+6.

> `^title^`

> `^value($Color)^`

The placeholder continues from the opening caret and ends with white space, an optional closing caret, or a closing parenthesis. Although the closing caret is optional, it is best to include one unless familiar with exporting - the closing caret saves Tinderbox having to make assumptions about where a particular code ends.

A placeholder ends with a closing parenthesis, white space, or a caret; the closing caret is only required if the placeholder directly abuts a printing character.

Most placeholders refer to the note that is currently being exported, but some placeholders can extract information from different notes.

`^title^` : the name of this note

`^title(this)^` : equivalent to ^title

`^title(parent)^` : the title of this note's container

`^title(/tasks/132)^` : the title of the note "132" inside the container "tasks"

Placeholders that refer to other notes can refer to them in several ways:

- The name of the note
- The path to the note — especially useful if several notes might share the same name— such as /Configuration/PriceList
- A designator, such as "parent" or "nextSibling"

### Paths

Export templates allow you to identify notes by relative or absolute paths. For example:

> /news is the top-level note named "news"

> /news/local is the note named "local", inside the top-level note "news"

The file name "." stands for this note, and ".." stands for the parent of this. Thus,

> ../Chicago is the note named "Chicago" that is a sibling of this note

> ../.. is the grandparent of this note

If a path begins with "/", the path begins at the top level of the document. If it does not begin with "/", it begins inside this.

## Designators

The most common and useful designators include:

`this` - the note being exported immediately

`current` - the note Tinderbox is currently exporting. If a note includes other notes, this is the most immediate note, and current is the note that ultimately includes it.

`next` - the note that follows this note in outline order

`previous` - the note that precedes this note in outline order

`prevSibling` - the next older sibling of the this note

`nextSibling` - the next younger sibling of the this note

`parent` - the parent of this note

`child` - the first child of this note

`lastChild` - the last child of this note

## Placeholders

To export the title of a note, we simply include the placeholder

> `^title^`

> `^title(object)^`

For example, we might want to show the title and the parent's title:

> `<h2> ^title(parent)^ : ^title(this)^ </h2>`

Similarly, we can use `^text^` to convert a note’s text into HTML and insert it into our page.

> `^text^`

> `^text(note)^`

> `^text(note,max_words)^`

While the note’s text and title are most likely to be of interest, we can export any attribute.

> `^value($attribute)^`

gets the value of any attribute you specify, for this note.

> `^value($attribute(parent))^`

gets the value of any attribute of this note’s parent.

^value^ also evaluates expressions, permitting more complex forms:

> `Total Price: ^value($Price*$Quantity)^`

### Placeholders In Text

While export template codes are most often found in export templates, you may also type them directly into your note’s text. For example, if the text reads

> `This note, ^value($Name)^, contains ^value($WordCount)^ words`

the exported HTML for a particular note might read:

> `<p>This note, Objections To Operation TORCH, contains 731 words.</p>`

We can also include information from other notes within the text.

> `^include(object)^`

will format another note, using its own export template, and insert the results into our page. Alternatively, we might specify a special template

> `^include(object,summaryTemplate)^`

Or, we can simply include some other note’s text:

> `Please keep in mind the following warnings:`

> `^text(/warnings/fragile)^`

> `^text(/warnings/inflammable)^`

> `^text(warnings/heady)^`

`^include^` and the related code `^children^` can help you to assemble complex pages and weblogs, pulling information from dozens or hundreds of notes into a single layout. These techniques are discussed in a chapter on Complex Pages.

## Macros

Macros provide a convenient shorthand, helping you save typing and making your work easier to keep up-to-date.

> `^do(disclaimer, show, contact, phone)^`

might expand into a lengthy, customized passage that might need to appear in many notes, and that would be tedious to retype.

> `<h3>DISCLAIMER</h3>`

> `<p>These notes regard production plans for show, a projected production of Imaginary Studios, Inc. All plans are preliminary and strictly confidential. Writers are cautioned that all details are subject to change, and that final budgets are not approved until signed by contact. If you have questions, please call contact at phone. </p>`

Note that, if the legal department wants to change the wording of the disclaimer, we need only change the macro. If we had typed the disclaimer in several places, we would need to search and correct each occurrence. A macro is a text pattern that, when invoked, expands into a larger element.

> `^do(...)^`

To define a macro, use the Macro pane of the HTML Inspector (⌘-2).

For example:

> Name: dot

> Value: <img src="anImage.gif" height="16" width="16">.

Defines a macro that will replace `^do(dot)^` with the specified 16-pixel image.

The ^do^ command may take additional arguments that are passed to the macro. Wherever the macro contains the substring `$1`, that substring will be replaced by the first additional argument. The substring `$2` will be replaced by the second additional argument.

If a paragraph consists entirely of a macro, paragraph markup is not applied. This is useful, for instance, as it makes it easy to use a macro to insert an element like an image (<img>) which requires no enclosing paragraph.

## Group Designators

Most HTML markup elements concern an individual note, either this or a designated note. Some element consolidate information from a group of notes.

For example

> ^every(children,$Urgent)^

is true if each child of this note is has a true value for its Urgent attribute.

Group designators include

- `children` - all immediate children of this note
- `descendants` - all notes descended from this note
- `sibling` - all siblings of this note
- `ancestor` - all notes from which this note is descended
- `all` - all notes in the document

### Export Operators And Groups

`^every(group,attribute)^`

`^every(group,attribute,value)^`

true if every member of the group (such as every child) is true (if two arguments are supplied) or if every member of the group has a specific value for that argument (if three arguments are supplied). Always true if there are no examples of that group

`^any(group,attribute)^`

`^any(group,attribute,value)^`

true if any member of the group is true (two arguments) or if any member of the group has an attribute with the specific value (three arguments). Always false if there are no members of the group.

`^count(group)^`

counts the number of elements in the group

`^min(group,attribute[,precision])^`

the smallest value in the group.

`^max(group,attribute[,precision])^`

the largest element in the group

`^sum(group,attribute[,precision])^`

computes the sum of all elements in the group.

`^mean(group,attribute[,precision])^`

computes the arithmetic average of the group

Several group codes allow an optional argument, precision; if supplied, it indicates the number of decimal places desired in the result.

Note that most group codes can also be expressed using ^value^. For instance:

> `^value(any(children,$IsOverdue))^`