4 Template Tutorials
This chapter provides tutorials for using the HTML Export templates.
Before you begin this tutorial, it is recommended that you read and familiarize yourself with Templates.
When you install this product, a set of tutorial templates in HTML format are installed in templates\html\tutorial (HTML Export) or template\export\tutorial directory (Transformation Server). These templates include in-depth commentary explaining how they work. Aspiring template authors should examine the comments within these templates to gain a fuller understanding of how to implement the template language.
This chapter includes the following sections:
4.1 Template Comments
The template comments are contained within {## comment} macro statements, which are themselves contained within standard HTML comment tags. The {## comment} macro is used in the tutorial templates to prevent the software from writing the template comments to the output file when these templates are used. The HTML comment tags are included so that all comments will be highlighted when the template is open in a syntax-coloring editor. The HTML comment tags are also useful for masking the macros from HTML editors such as Microsoft FrontPage. A side effect of adding the HTML comment tags outside of the {## comment} macros is that any output generated using these templates will contain empty comment tags.
The following is an example of one of the comments in the templates:
<!--{## comment}
To tell the browser what character set the HTML file is
using, add a <meta> tag with the "content" attribute and
use the {## insert} macro to insert the pragma.charset
element. Export will insert the name of the character set
specified by the SCCOPT_EX_OUTPUTCHARACTERSET
(Transformation Server: outputCharacterSet) option.
{## /comment}-->
The macro statements in the tutorial templates are formatted for readability. Because the product does not ignore template whitespace, output generated from these templates contains whitespace wherever there were macros in the templates. When using {## repeat} loops, the amount of whitespace added to the output can be substantial. Browsers ignore this whitespace, so from a viewing standpoint, it should not be an issue. However, if you are concerned with file size or readability of the output HTML, you should format the macros to minimize the amount of whitespace, which includes both spaces and carriage returns.
The following sections offer an overview of these tutorial templates. The order in which they are discussed is a recommended sequence for examining the templates and learning about the template language and its implementation.
The actual template file is a .htm file and it is generally named based on the directory in which it is found (i.e., the simple template is the file simple.htm in the \tutorial\simple directory). However, if a template references other files within the same directory, the primary template file for that directory is always called main.htm (for examples, see Tutorial 3: toc2).
4.2 Tutorial 1: simple
The simple template, as its name implies, produces a simple, single-page rendition of the source document without a table of contents.
This template is an introduction to the following techniques:
-
The use of templates in general
-
Simple inserts of document pieces
-
The character set selection mechanism
-
Use of CSS files
-
Using the {## repeat} macro
-
Setting the title of the HTML output file based on the input file's content
4.3 Tutorial 2: toc1
Files generated with the toc1 template are similar to those produced with the simple template. However, the toc1 template also creates a simple table of contents (TOC) that displays hyperlink headers up to two levels deep at the start of the file. Clicking on a header moves the browser to the corresponding section.
This template is an introduction to the following techniques:
-
Generating a simple TOC
-
Using {## link} to create internal links
-
Conditional statements based on input file type
-
A more extensive introduction to elements in the Document Tree
-
Integration of macros with HTML
4.4 Tutorial 3: toc2
This template creates a TOC in a separate frame to the left of the body text of the document. As in the output generated when using the toc1 template, the TOC is two levels deep. As is the case with the toc1 template, the headers shown in the TOC frame are hyperlinks to the sections they reference. However, when these hyperlinks are activated, the browser displays the relevant section of the document in the frame to the right of the TOC frame.
The other thing to note about this template is that it is the first in the tutorial that references other templates. The primary template file, main.htm, uses {## link} statements to reference the other template files in the toc2 directory. The process of evaluating the {## link} statements generates the remaining output files for the document.
For the purposes of this tutorial, start by reading the comments in the main.htm file and then read the comments in the referenced templates when they are discussed within main.htm.
This template is an introduction to the following techniques:
-
Using the {## option} macro
-
{## link} statements involving elements, templates, or both elements and templates
-
Archive files processed using this template output such that the archived file names appear as links in the TOC frame (left) that point to that file's content, which appears in the body frame (right)
4.5 Tutorial 4: unit
The unit template is capable of breaking a document into multiple output files based on size. The size of the output files is determined by the value in the SCCOPT_EX_PAGESIZE (Transformation Server: pageSize) option.
This template is an introduction to the following techniques:
-
Using the {## unit}, {## header}, and {## footer} macros
-
Using {## anchor} for navigation
-
Using the truncate attribute of the {## insert} macro
-
Archive files processed using this template output such that the archived file names appear as links in the TOC frame (left) that point to that file's content, which appears in the body frame (right)
4.6 Tutorial 5: misc
This tutorial template covers a variety of template features not covered in the preceding tutorials. It is an introduction to the following techniques:
-
JavaScript tab implementation
-
Use of the step attribute to provide "fast-forward/rewind" capability
-
Use of the {## copy} macro to copy files into the output directory (in this case, a .gif image) (Embedded and standalone versions only)
-
Processing the input document by iterating through the Document Tree, providing a unique look into how the Document Tree handles the different parts of a document
-
Using the{## graphic} macro
-
Using the{## include} macro
Transformation Server users should note that this template uses the {## copy} macro. This macro is not recognized by Transformation Server and is ignored when encountered in a template.
4.7 Tutorial 6: grids1
The grids1 directory contains a template that demonstrates one method for breaking spreadsheet or database files based on size.
The grids1.htm template creates multiple output files that maintain the spatial relationships of the original file. In other words, depending on how many rows and columns make up a grid (set by the SCCOPT_EX_GRIDROWS (Transformation Server: gridRows) and SCCOPT_EX_GRIDCOLS (Transformation Server: gridCols) options, or in the template itself using {## option gridrows=value} or {## option gridcols=value} statements), the template will create multiple files that can be navigated using links in an "up/down/left/right" navigation table. For example, in a spreadsheet that is 10 columns by 10 rows with a grid defined as 5 columns by 5 rows, the main section of the output document will have links to view the grids to the right (the next 5 columns) and down (the next 5 rows). The "up" and "left" navigation links will be inactive in the main section.
4.8 Tutorial 7: grids2
The grids2 directory contains another template that demonstrates an alternate method for breaking spreadsheet or database files based on size to the one used by the grids1 template.
The grids2.htm template creates multiple output files, but instead of maintaining the spatial relationships of the original file, it simply adds "next" or "previous" links, where applicable, above or below the currently displayed section of the document. Whether the "next" and "previous" links traverse from left to right or up and down through the grid is determined by the setting in the SCCOPT_EX_GRIDADVANCE (Transformation Server: gridAdvance) option.