Intro to Templates
Pages and Templates
STT is a tool for working with HTML pages and templates that control the general structure of those pages. Since both the templates and the pages that depend on them are files that contain HTML code, we use the following convention to avoid confusion:
Creating a Template
To use STT you must first create a template. A template is an HTML file that includes special regions called editable regions that contain text that may vary from page to page. You can create a template using whatever editing tool you normally use to create HTML pages --- either an HTML editor, or by typing the HTML directly using a text editor. Each editable region in the template should begin with a line like:
where NAME is the name of the editable region. (Don't type the word NAME into the template --- replace it with a name you're assigning to the editable region.) The name can be anything, as long as no two editable regions in a template have the same name. For example, you might use the name body for the main body of text.<!-- #BeginEditable "NAME" -->
Each editable region should end with a line like
Notice that the name of the editable region does not appear in the EndEditable line.<!-- #EndEditable -->
These #BeginEditable and #EndEditable directives are examples of HTML comments. Web browsers ignore anything between <!-- and -->. That way STT can use them to keep track of where the editable regions in your template are, without interfering with the way your page appears in a browser.
A template can contain any number of editable regions, but they may not be nested; in other words, each BeginEditable must have its corresponding EndEditable before the next BeginEditable. The BeginEditable / EndEditable directives do not actually have to appear on lines by themselves; it's OK to do something like
<!-- #BeginEditable "title" -->My Title<!-- #EndEditable -->all on one line if you want.
When you use STT to update a page that uses your template, STT replaces the text in the template that appears bewteen the BeginEditable and EndEditable directives with the corresponding text from the page itself. So it doesn't really matter what text you put in the editable regions in the template, since it will be replaced with different content in different pages. It's a good idea to use some meaningful placemarker text, though, so that you can tell where the editable regions are if you preview the template itself in a browser.
Creating a Page from a Template
Once you have a template, you can create a new page from that template by giving the command
where TEMPLATE is the name of the template, and PAGE is the name of the page you want to create. STT will refuse to create the new page if PAGE already exists.stt -c TEMPLATE PAGE
Once you have created a new page from a template you can edit it as if it where a normal HTML page, but you should only change text that is inside the page's editable regions. If you make changes outside of an editable region, your changes will be lost when you update the page from the template. If you want to make a change to a part of the page that is outside an editable region, edit the template itself, not the page that depends on it. Remember that this change will affect all the pages that depend on the template, not just this page (see below for details of how to edit a template and update the pages that depend on it).
Web editing programs like DreamWeaver that support templates are usually written to prevent you from making changes to a page outside of its editable regions; the parts of the page that are not inside an editable region might be showed with a different color background to signal that they are not editable. STT can't do this, since it relies on you to use your own editor to make changes. If you use DreamWeaver to edit pages created with STT it will prevent you from making page changes outside of editable regions. (But if you have DreamWeaver, you probably don't need STT!)
Editing a Template
When you want to make a change to a template, just edit it as you would any HTML file. You can change any part of the template. After you change a template, you'll need to update any pages that depend on it.
Updating Pages from a Template
After you have edited a template, run STT to update the pages that depend on it by giving a command like
where PAGE is the name of the page you want to update. Note that you do not have to mention the name of the template; STT reads the name of the template from the page itself. You can list several pages all at once if you have more than one:stt PAGE
stt PAGE1 PAGE1 ...
Using Make to Automate Page Updates
If you're comfortable with the unix make program, you can use it to keep track of which pages depend on which templates, and to take care of updating the relevant pages whenever you edit a template. Here's a sample Makefile that contains instructions telling you how to adapt it to your needs.
Using make in this way greatly simplifies the job of keeping track of which pages need to be updated when; simply maintain a list of your pages and templates in the Makefile (you don't have to specify which pages depend on which templates; the Makefile uses STT to do that for you), and run make whenever you edit a template. Make will figure out which pages depend on that template and will update only those pages.
The example directory contains a simple example of a web site constructed using an STT template. You can: