Complex Pages
| Tinderbox User's Manual : Complex Pages |
Complex Pages |
|
Tinderbox has a very powerful facility for building Web pages built out of many notes. This is useful because even a simple personal page may have links to archives on the left edge, recent articles on the right, a headline at the top, and daily updates in the center. Tinderbox could build such a page by gathering each article (each one a separate note) and sorting them by date. If you decide that sorting by title would be more useful, it's an easy change. If you need to revise the entry for one article, we just open that note, without needing to worry about complex tables or stylesheets.
This feature, particularly when combined with the power of agents, is a very powerful way to create dynamic Web content. Tinderbox can build new lists automatically using agents that scan your document continuously, searching for notes that fit criteria you specify. One agent might look for new notes, another might look for anything marked Urgent, a third agent might search for old notes that have not yet been acted upon. To build a web page from many notes, you'll create or use HTML export templates which pull lots of notes together into a page Web page, and control exactly how the pieces fit together. For example, a note could use a template that exports the text of the note, followed by a table containing the text of each of its children. Or an agent could find all the notes created since yesterday, and export into a template which puts the title and text of each of those new notes into a list. You can download HTML templates designed for Tinderbox weblogs at:
http://www.eastgate.com/Tinderbox/GetTemplates.html
This code tells Tinderbox to include the descendants of the current note or agent in the current Web page instead of including them on separate pages. If a template is specified, that template is used for every note; otherwise each child's template is used for that child.
Using ^children in an agent’s export template is a very powerful way to create dynamic Web content. An agent’s children are aliases of all the notes that satisfy its criteria. An agent could gather all the notes that have been added since a certain date, or that belong to a certain category, and use ^children to export all of them as a list .
^children^
^children(template-file)^
^children(template file, count)^
The argument template_file should be the name of an HTML template file. This file will be applied to each child in turn, regardless of the child's own template.
If supplied, a second argument, count, specifies the maximum number of children to be exported.
Tip:the template file used by ^children will be very different from a template file intended to export a single note. Since the children are being included in a single Web page, the children’s template file should not include opening and closing codes such as ,
, and . The children’s template file can be very brief, containing only the code to make the desired elements from each child appear correctly in the context of the overall Web page.Note: in older versions of Tinderbox, ^children was called ^justChildren. The old name continues to function, but the new name is clearer. A new code ^descendants, replaces the previous function of ^children.
Tinderbox will look for the file template_file by name in the HTML Templates folder (choosing this folder is described in the chapter on Exporting to HTML).
This example of using ^children in an HTML template will work together with the template file “child-item.html” to place each child note in its own row of a table:
<table width="100%" border="3" cellpadding="2"> start a table
^children(child-item.html)^ include each descendant of the note,
formatted with the template "child-item.html"
</table> end the table
The template "child-item.html" needs to contain only the code to begin and end each cell of the table, and place the text for that child in the cell of the table:
<tr><td> begin the row and cell of the table
<h4>^title()^</h4> include the title of each child
^text(plain)^ include the text of each child
</tr></td> end the row and cell of the table
The ^include template code includes a specified note in the Web page for the current note. ^include adds a single note. That note's export template might include other notes as well. It's common to ^include several different notes in the same template.
Be careful not to ^include a note in itself!
^include( note_name [, template_file])^
The argument note_name indicates which note is to be included. The optional argument template_file should be the name of an HTML template file.
If you do not specify a template file to use, the note note_name is formatted with the HTML export template assigned to it with its HTMLExportTemplate attribute. (You set this via the Info window or the HTML view window for note_name.)
An included note can use ^children and/or ^include to include yet more notes in the page. This is a very powerful way to format and structure Web content.
For example: you may want to include two different lists of notes in a single Web page. You can’t use ^children for this, because one note only has one set of children. But let’s say you have two notes, one named NEWS and one named OPINION: the former’s children are notes containing brief news items, the latter’s children contain paragraphs of opinion. A third note entirely could use a template incorporating the following use of ^include:
<table> start a table
<tr> with one row
<td>^include(NEWS)^</td> put the note NEWS in the left-hand cell
<td>^include(OPINION)^</td> put the note OPINION in the right-hand cell
</tr> end the one row
</table> end the table
Then, the note NEWS could have a template something like this:
<p>Check out these hot news items:</p><list> start a list
^children(child-item.html)^ include each descendant of NEWS in the list,
formatted with the template "child-item.html"
</list> end the list
This fills the left-hand column of the table in the overall Web page with the sentence "Check out these hot news items:", followed by a list of the descendants of NEWS—that is, a list of news items.
A similar template for the note OPINION would fill the right-hand column of the table with a list of opinion items. This combined use of ^include and ^children allows you to combine two (or more) sets of notes within one Web page. Different sets of notes can even be formatted differently or include different information, by using a different template for each set of notes.
This template code allows you to export a randomly selected child of a specified note, using a specified HTML template (if desired). The syntax is very similar to the syntax for ^include:
^randomChildOf( note_name[, template_file])^
The argument note_name selects the note whose random child is to be exported. The optional argument template_file should be the name of an HTML template file; if no template is specified, the note’s own template is used.
Tinderbox offers great flexibility in date formatting, including trying to recognize date conversions in any country where it is being used. In all these examples, theDate is used in place of an actual date attribute such as ^get(Created)^ or ^get(Modified)^
To include a date
^get(theDate)
^get(theDate,format-string)^
The optional argument "format-string" describes the way you want the date to appear.
Format strings let you present dates and times in exactly the way you wish. They can appear in any language or style. The complete repertoire of format strings is described in Appendix 5: some common formats include the following:
Format strings
Remember that colons are not part of the codes.
L: local time, in long format, using the system format settings (example: Tuesday, April 29, 2003.)
l: local time, in short format, using the system format settings (example: 4-29-03)
d: day of the month (example:29)
D: formats date 01-31, with leading zero
m: number of month (example:4)
M: abbreviation of month (example:Apr)
MM: name of month (example:April) w: abbreviation of weekday (example:Tue)
M0: formats month numerically 01-12, with leading 0
W: name of weekday (example:Tuesday)
y: year (example:2003)
t: time, in local format (example:2:32 pm)
h: hour of the day on a 24-hour clock (example:13:39)
H: hour of the day on a 12-hour clock (example:1:39)
mm: minute of the hour (example:05 for five minutes after the hour)
s: second
p: AM or PM
*: date/time in RFC 822 format (example:Thu, 18 Feb 2004 19:12:08 0500)
=: date in ISO 8601 format (example:2004-02-18)
Tinderbox also accepts expressions such as today, yesterday, tomorrow, yesterday + 1 week, tomorrow + 1 year, and never (later than any other date).
To find and compare dates
When Tinderbox agents compare dates, they always consider both date and time.
So an agent that looks for notes Created=today will only find notes that were created at this very moment.
Instead, let agents search for a range of times. For example, $Created>today-24 hours finds notes created in the last 24 hours.
Better still, $Published > yesterday & $Published <= today finds notes that were published within the last 24 hours, but not notes whose publication date is scheduled for some point in the future.
Dates and agents
Agents can use dates to good effect. A container for weblog items, for example, might automatically timestamp a note whenever it's added, whether freshly-created or moved from another place. Or an agent could collect all news items whose ReleaseDate has already arrived, but not items whose ReleaseDate is still in the future.
Agents regard two dates as being equal if they share the same year, month, and day -- regardless of the time of day. The comparison operators >, >=, < and <= compare both date and time, so the same note could be found by an agent that locates theDate < today and another that searches for theDate = today.
Dates and attributes
Tinderbox automatically records two dates as read-only attributes: Created (the date and time when a note was first made), and Modified (the date and time when the note was most recently changed). You can create your own date attributes, too; for example, Published might be the date when a note was first added to the public version of your Web site.
You can now automatically "ping" Technorati, Feedster, and weblogs.com from Tinderbox to announce that your weblog has been updated, which in turn helps notify other systems of the change. If you upload your site by FTP, you should ping after uploading revised files.
To enable pinging
To ping after updating your weblog
Tinderbox supports posting to Blogger, MovableType, and Radio Userland weblogs. This will be easy after the initial seup, which you will only have to do once:
To set up remote blogging
Tip: Radio Userland users must enable remote Internet access in Radio Userland Preferences, and must enable the Blogger API. These may be off in default installations.
To post to remote weblogs
To download the most recent posts
If notes for these posts already exist, their contents will be updated to match the weblog.
Warning: you will lose any changes you have made to these notes. New notes will be made for any weblog posts for which corresponding notes do not currently exist. (If the document already contains notes posted to the weblog, the newlycreated notes will appear in the same container. Otherwise, the newly-created notes will appear at the top level of the document.)
| Up: Tinderbox User's Manual | |
| Previous: HTML Templates | Next: Exporting text |
