Oracle® Outside In HTML Export Developer's Guide Release 8.4.0 Part Number E12884-03 |
|
|
View PDF |
Before you begin this tutorial, it is recommended that you read and familiarize yourself with Chapter 10, "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:
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 Section 11.4, "Tutorial 3: toc2").
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
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
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)
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)
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.
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.
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.
This template exports documents with its pieces labeled with XML tags. In order to use this template, the output "flavor" option must be set to a non-CSS enabled flavor of HTML, such as HTML 3.0. Additionally, the output from this template can only be viewed in a browser or application that can handle XSL (for example, Microsoft Internet Explorer 5.0 or higher). The ie5.xsl file in the template directory is a style sheet required when viewing the output from this template.
It should be noted that although the output from this template is functional, Oracle's Outside In XML Export product provides far more robust XML conversion than can be achieved using this template. Please contact Oracle for more information about XML Export if converting documents to XML is a priority for you.
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.
The internal template produces output that is essentially identical to the output created when no template is specified during an export.