dynamate

Synopsis

Description

File Types

Options

Diagnostics

Bugs

Requirements

See Also

Identification

NAME

dynamate - apply a Dynamator file to an XML or HTML file, creating a server page or program file.

SYNOPSIS

java dynamate options template-file-name ...
java dynamate options dynamator-file-name ...

DESCRIPTION

dynamate applies a Dynamator file to an HTML or XML file, producing a merged file. Typically, the output file is a server page or program, but it also may be another HTML or XML file.

dynamate uses three kinds of files:

Template file: An HTML or XML file containing static content.
Dynamator file: A file containing changes to be applied to the template file. The structure of this file is described in DynamatorFile.html. Dynamator files have the suffix ".dyn".
Output file: The file produced by dynamate. The name of this file is determined by the DynamatorFile.

The behavior of dynamate is slightly different depending on whether the argument file is template file or a Dynamator file. If the argument file is a template file, dynamate locates a Dynamator file with the same basename as the template file and a suffix of ".dyn". If the argument file is an Dynamator file, dynamate locates a template file based on a name supplied within the Dynamator file.

dynamate can generate files in potentially many different output file languages. Currently, dynamate can generate Java, JSP, XSL, PHP, and ASP (VB).

dynamate copies the input template file to the output file, applying each transformation in the Dynamator file that matches an element in the input template.

dynamate uses the following search path to find directives that apply to template file elements:

<id> elements with name attribute matching the value of the current element's id attribute.
<class> elements with name attribute matching one of the classes of the current element. If the current element has more than one class, the list of classes is searched in order.
<tag> elements with tag attribute matching the tag of the current element and attributes and attribute values matching the specified attributes in the tag element. If more than one tag element matches, the first tag element in the Dynamator file that contains the sought override directive is used.

This search order is similar to CSS, except that with CSS, later entries with the same specificity have greater precedence.

dynamate treats template file comments that start with "div" or "/div" as <div> tags to allow identification of element groups where <div> elements would be invalid. For example:

  <table>
    <!-- div id="row-group" -->
      <tr class="data-row">
        <td>...</td>
        <td>...</td>
      </tr>
      <tr class="delimiter-row">
        <td colspan="2">
          <img src="line.png" height="1" width="100"></td>
      </tr>
    <!-- /div -->
  </table>

dynamate automatically removes template elements that belong to certain classes. If such an element has an 'id' or another 'class' attribute for which an element is defined in the Dynamator file, Dynamator directives applying to the element are still applied. This allows hooks for iteration or selection to be placed in the HTML or XML file and removed from the generated file.

Elements belonging to the following classes are discarded:

Discard	Causes the element and its children to be discarded.
DiscardTag	Causes the element to be discarded. The element's children, including text, are transferred to the output file.

TEMPLATE FILE TYPES

The core dynamate process requires input template files to conform to XML syntax. When dynamate detects that an input file is an HTML file, it preprocesses the input file in order to transform it into XML. dynamate uses JTidy to convert the input HTML file into valid XML. The resulting XML file is stored in the same directory as the input HTML file under the name "X.asxml", where X is the basename of the file.

Because converting HTML to XML is somewhat time-consuming, dynamate only performs the conversion if the asxml file does not exist or is older than the HTML file, or if the -a command line flag is used.

dynamate determines the type of a template file in the following way:

If the '-H' flag or '-B' flag was previously found on the command line, the file is assumed to be HTML.
If the '-X' flag was previously found on the command line and the file suffix is "html" or "htm", the file is assumed to be XHTML.
If the '-X' flag was previously found on the command line and the file suffix is not "html" or "htm", the file is assumed to be XML.
If the suffix of the file is ".html" or ".htm", the file is assumed to be HTML. (The test is case-insensitive.)
If the suffix of the file is ".xhtml", the file is assumed to be XHTML. (The test is case-insensitive.)
Otherwise, the file is assumed to be XML.

OPTIONS

Each option must be indicated separately; i.e. "-C -N", not "-CN".

-a: Always convert HTML to XML, even if the asxml file is newer than the HTML file.
-B: Force all subsequent template files to be processed as Body-Only HTML. This option generates server page files that output HTML fragments to be inserted into the body of a page. The template file is processed by JTidy, but the <html>, </html>, <body>, and </body> tags and the <head> element are all removed.
-C: Strip all HTML/XML comments from the output template. This reduces the page size of generated server pages, but may make the generated server pages less maintainable.
-d dir: The directory in which to put the output file. If not specified, the output file is placed in the current directory.
-e encoding: Use the Java character encoding specified to read the input file. If not specified, ASCII is used.
-f dir: The directory from which to obtain files corresponding to the files specified on the command line. If the argument file is a template file, this directory will be used to obtain the corresponding Dynamator file; if the argument file is a Dynamator file, this directory will be used to obtain the corresponding template file. If not specified, corresponding files are obtained from the current directory.
-F file: The Dynamator file to apply to all subsequent argument template files. This option allows the Dynamator file to be specified explicitly instead of implicitly through file name matching.
-G: Don't output a file generation comment. The generation comment typically appears at the beginning of the file. It identifies the file as generated by Dynamator and includes the date and time of generation.
-H: Force all subsequent template files to be processed as HTML. Template files not ending in ".xhtml" are converted to XML using Tidy. Template files ending in ".xhtml" are processed as-is. In both cases, HTML processing rules are observed. (See also -X.)
-I dir: Add directory dir to the Dynamator include file path. The include path consists of all directories specified using the -I option, in the order specified on the command line, followed by the directory containing the top-level Dynamator file. It applies to files referenced in Dynamator <include> directives.
-N: Don't indent output. This reduces the download size of generated server pages, but makes the generated server pages less readable.
-T{filename}: Output an execution trace. If filename is specified, the trace is output to filename; otherwise it is output to STDERR. There must be no space between the 'T' and the filename.
-v: Report the Dynamator version.
-V: Don't validate Dynamator files.
-X: Force all subsequent template files to be processed as XML. Template files with names ending in ".xhtml" are processed without HTML rules. (See also -H.)

DIAGNOSTICS

dynamate diagnostics are output to STDERR. When processing an HTML file, Tidy diagnostics are written to STDERR.

BUGS

When Tidy is used to convert HTML to XML, the formatting of the resulting HTML file is different. The differences are not visible in a browser, but they are visible to readers of the source file. This is because Tidy does not retain whitespace, but recreates it based on the document structure.

REQUIREMENTS

dynamate has been tested with the Xerces 1.1.3 SAX2 and DOM parsers, and with JTidy version 1.11 dated Aug 4, 2000.

IDENTIFICATION

Author:	Jay Dunning
Version:	1.5
Copyright:	2000-2004, Jay Dunning