HTML Templates
| Tinderbox User's Manual : HTML Templates |
HTML Templates |
|
An HTML export template need not be complicated. Here is a very simple possible template:
<!-- Begin the Web page -->
<html>
<!-- Put the title of the note into the browser title bar -->
<head><title>^title^</title></head>
<!-- Begin the body of the Web page -->
<body>
<!-- Place the content (text and images) of the note -->
^text^
<!-- End the Web page -->
</body>
</html>Tinderbox offers a great variety of export template codes, giving you immense flexibility. You can export Tinderbox notes as HTML, XML, or in many other formats. You can easily control nearly every aspect of the process, making Tinderbox a convenient front end to a host of systems and services.
The full array of export codes are described in Appendix 4.
In this chapter, we will discuss the much smaller number of export codes that you are likely to use frequently.
Tinderbox placeholders begin with a caret (^).
^title
^get(Color)^
The placeholder continue from the opening caret and ends with white space, an optional closing caret, or a closing parenthesis.
Most placeholders refer to the note that is currently exported, but others can extract information from different notes. Placeholders that refer to other notes can refer to them in several ways:
Paths
Tinderbox export templates allow you to identify notes by relative or absolute paths, not just name.
If a tag's request matches neither a keyword nor a note, Tinderbox tries to interpret it as a path. 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 note. 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 the current container.
A number of keywords are available to refer to other notes by context rather than name. The full set of keywords is listed in Appendix 4.
The most common and useful keywords include:
this - the current note
current - the note Tinderbox is currently exporting. Where a note is exported to its own page, current is the same as this. If a note includes children or other notes, however, current differs from this in the included notes.
next - the note after the current note, in outline order
previous - the note preceding the current note, in outline order
prevSibling - the next older sibling of the current note
nextSibling - the next younger sibling of the current note
parent - the parent of this note
child - the first child of this note
lastChild - the last child of this note
To export the title of a note, we simply include the placeholder
^title^
If we want instead to include the title of another note, we write
^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(object)^
^text(object,max_words)^
While the note’s text and title are most likely to be of interest, we can export any attribute.
^get(attribute [,format] )^
gets the value of any attribute you specify, for this note.
^getFor(object,attribute [,format])^
gets the value of any attribute you specify, for this note. The optional argument format is used chiefly with dates, and tells Tinderbox how you wish the date to be formatted. Date formats are discussed in Appendix 5.
^value evaluates an expression — any expression you could use in an action or rule. Tinderbox frequently gives you several ways to do the same thing; for example, the following three placeholders are equivalent
^title^
^get(Name)^
^value($Name)^
^value^ is sometimes more flexible than ^get^. For example, if a note has numeric attributes Price and Quantity, we could write:
Total Price: ^value($Price*$Quantity)^
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 easily 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 are especially useful when embedded in text. A simple macro.
^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, too, that by using a macro, we make it easy to update the document. If the legal department wants to change the wording of the disclaimer, we need only change the macro instead of searching for each occurrence of the (slightly-different) disclaimer.
A macro is a text pattern that, when invoked, expands into a larger element.
^do(...)^
To define a macro, use the fields in the Macros pane of the Attributes menu. For example, Name: dot and Value: <img src="anImage.gif" height="16" width="16">. Now whenever Tinderbox encounters the markup ^do(dot)^ in a template or in exported text, Tinderbox will replace the do command with the specified value.
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. If you want to add paragraph markup, add one or more spaces after the macro.
Occasionally, you may want to export some information for some notes, but not for others. Of course, you could use two different templates. But if the changes are small, you can use ^if to export different information if certain conditions are met.
^if( condition ) ...... ^endif
^if (condition) ... ^else^ ..... ^endif
if the condition is true, then include everything from the ^if^ statement to the ^else^ or the ^endif^.
The condition may be an export code — several export codes are specifically designed for this purpose
^if(^any(child,Status,urgent))^<b>urgent</b>^endif^
Or the condition may be an agent query.
^if($Qty=1)^ item ^else^ items ^endif^
Be careful to ensure that every ^if^ is balanced by a corresponding ^endif^.
Conditional logic can greatly reduce the number of templates you need, at the cost of increasing their complexity. Conversely, if your templates are becoming a tangle of ^ifs, consider breaking them into several separate templates.
Some HTML Export markup codes operate on groups of notes such as child, descendant, ancestor, and sibling. For example
^every(child,Urgent)^
is true if each child of this note is has a true value for its Urgent attribute.
^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.
Valid group codes include:
child - all immediate children of this note
descendant - 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
Note that most group codes can also be expressed using ^value. For instance:
^value(any(child,IsOverdue))^
<html>
<!-- Put the title of the note into the browser title bar -->
<head><title>^title^</title></head>
<body bgcolor="#FFFFFF">
<!-- The content (text and images) of the note -->
^text^
<!-- if this is not the cover page, -->
^if(^not(^equal(^url(this)^, ^url(cover)^)^)^)^
<!-- add a horizontal rule -->
<hr height=3 width=75% align=center>
<!-- a link to the cover page, attached to the button image “homebut.gif” -->
<a href="^url(cover)^">
<img src="^root^homebut.gif" alt="Home" vspace="2"></a>
<!-- end of the if condition -->
^endif
<!-- if this note has children, -->
^if(^exists(childLinks)^)^
<!-- add a horizontal rule -->
<hr height=3 width=75% align=center>
<!-- a list of links to the child notes, formatted as an ordered list -->
<h5>Children:</h5> ^childLinks("<ol>", "<li>", "</li>", "</ol>")^
<!-- end of the if condition -->
^endif
<!-- if this note has basic links leading from it, -->
^if(^exists(basicLinks)^)^
<!-- a list of the basic links, formatted as a table -->
^basicLinks(<table border="2" cellspacing="0" cellpadding="3" width="100%">
<caption><strong>Related pages:</strong></caption><tr>,
<td>,
</td>,
</tr></table>)^
<!-- end of the if condition -->
^endif^
<!-- a horizontal rule -->
<hr height="3" width="75%" align="center">
<!--some export and credit information -->
<cite>This page was last modified on ^lastModified^, by ^creator^, and was exported to HTML on ^today^ using ^version^</cite>
</body>
</html>| Up: Tinderbox User's Manual | |
| Previous: HTML View | Next: Complex Pages |
