-
The root element is required. It may have the following
attributes:
-
-
language="language-name"
-
The name of the target language. This value must
correspond to a language supported by Dynamator.
The following names are currently supported:
This value affects formatting of the
output file. It also determines the availability
and behavior of features requiring
language-awareness such as 'if' and 'foreach'.
If not present or "none", content is assumed to
be static; no language-aware features are
supported.
-
suffix="output-file-suffix"
-
The suffix to be given to the output file. The
output file name is the same as that of the input
file name, except that the suffix is replaced with
this attribute's value. If this attribute is not
supplied, the suffix defaults to the value of the
language attribute. If the language attribute is
also not supplied, the suffix defaults to the
suffix of the template file.
-
template="template-name"
-
The filename of the template to be used with this
Dynamator file. This attribute is required if the
Dynamator file is used as the argument to
dynamate. It is ignored if the template file is
used as the argument to dynamate.
-
comment-start="comment start string"
-
The string used by the target programming language
to begin a comment. If not specified, "<--" is
used.
-
comment-end="comment end string"
-
The string used by the target programming language
to end a comment. If not specified, "-->" is
used. If comment-start is specified but comment-end
is not, comments are assumed to end at the
following newline.
-
filename="output-file-name"
-
The name of the output file to be created. This
attribute overrides the 'suffix' attribute.
Default Overrides
The Dynamator file may contain overrides to default
values provided by Dynamator. The syntaxes below show the
default value. In all cases, a Dynamator file may contain
zero or one override to any default value; if more than
one is specified, the results are undefined.
exclusive iteration tags
-
<exclusiveIterationTags>dl</exclusiveIterationTags>
|
Exclusive iteration tags identify tags that must be
placed outside iteration blocks associated with them.
In most cases, generated iteration constructs place the
tag associated with the iteration within the iteration
block. For example, when producing HTML table rows, the
'foreach' expression is associated with the 'tr' tag,
which is repeated for each element of an indexed
property.
In exceptional cases, generated iterations must place the
tag outside the iteration block. For example, when
producing HTML dictionary lists, the 'foreach' expression
must be associated with the 'dl' tag, not the 'dt' or
'dd' tag (because there are two of them), but the 'dl'
tag is not repeated for each element.
If this element is present in the Dynamator file, the
default values are ignored; to add to the default values,
specify them in the list for this element.
If more than one value is specified, values should be
space-separated.
preformatted tags
-
<preformattedTags>pre script</preformattedTags>
|
The 'preformattedTags' element identifies tags for which
whitespace is significant.
Dynamator automatically indents child elements and
program blocks for readability. This is not a problem for
normal HTML or XML, which are not affected by whitespace.
But within some tags, whitespace is significant. For
example, the HTML 'pre' tag causes text to be rendered
as-is, reflecting any whitespace within the block.
If this element is present in the Dynamator file, the
default values are ignored; to add to the default values,
specify them in the list for this element.
If more than one value is specified, values should be
space-separated.
flag attributes
-
<flagAttributes>
border checked compact declare disabled ismap
multiple nohref noresize noshade nowrap readonly
selected showgrid showgridx showgridy usemap
</flagAttributes>
|
The 'flagAttributes' element identifies names of
attributes to be treated as flagAttributes.
A flag attribute is an attribute that requires no value.
If provided, the value of a flag attribute is always the
same as the name of the attribute. XML does not allow
flag attributes; they are only valid for HTML.
If this element is present in the Dynamator file, the
default values are ignored; to add to the default values,
specify them in the list for this element.
If more than one value is specified, values should be
space-separated.
id attribute name
-
<idAttribute>id</idAttribute>
|
The idAttribute override causes the attribute named in
its content to be treated like 'id'.
HTML 4.0 defines 'id' as an attribute of most elements.
But XML does not. When working with an XML DTD that
already defines 'id', it may be useful to ask Dynamator
to use another name.
This element causes 'id' elements in the Dynamator file
to apply to attributes having the name indicated in the
content of this element. For example,
"<idAttribute>id_</idAttribute>"
causes <id> tags in this document to
apply to matching id_ attributes in the
corresponding XML file.
class attribute name
-
<classAttribute>class</classAttribute>
|
The classAttribute override causes the attribute named in
its content to be treated like 'class'.
HTML 4.0 defines 'class' as an attribute of most
elements. But XML does not. When working with an XML DTD
that already defines 'class', it may be useful to ask
Dynamator to use another name.
This element causes 'class' elements in the Dynamator
file to apply to attributes having the name indicated in
the content of this element. For example,
"<classAttribute>class_</classAttribute>"
causes <class> tags in this document
to apply to matching class_ attributes in
the corresponding XML file.
-
The prolog contains text to be placed as-is at the
beginning of the generated file.
A Dynamator file may contain zero or more prologs. Each
prolog is placed in the generated file in the order
encountered in the Dynamator file. All whitespace within
the prolog is retained, including whitespace immediately
following the <prolog> tag and whitespace
immediately preceding the </prolog> tag.
Program lines are transferred as-is into the output file.
In particular, characters that are special to XML, such
as '<', do not need to be escaped.
-
The epilog contains material to be placed as-is at
the end of the generated file.
A Dynamator file may contain zero or more epilogs.
Each epilog is placed in the generated file in the
order encountered in the Dynamator file. All
whitespace within the epilog is retained, including
whitespace immediately following the <epilog>
tag and whitespace immediately preceding the
</epilog> tag.
-
<before-extracts>
<!-- Content: ( program-lines )* -->
</before-extracts>
|
The before-extracts element is used with the extract element to specify
program lines to be placed immediately before the set
of extracts.
A Dynamator file may contain zero or one
before-extracts element.
-
<after-extracts>
<!-- Content: ( program-lines )* -->
</after-extracts>
|
The after-extracts element is used with the extract element to specify
program lines to be placed immediately after the set
of extracts.
A Dynamator file may contain zero or one
after-extracts element.
-
<include file="filename" />
|
The include element causes the content of the
referenced file to be included in the referencing
file at the location of the include. The referenced
file must be a Dynamator file.
filename may be an absolute or relative name.
If relative, it is assumed to be relative to the
directory containing the Dynamator file.
The include element must be an immediate child of the
<dynamator> element.
The included file may contain <include>
elements.
-
The 'id' element controls processing of the HTML element
associated with a certain id. An 'id' element maps to an
'id' attribute declared within the HTML page or XML file.
The content of the 'id' element is applied to the HTML or
XML element having a matching 'id' attribute.
The 'id' element must have the following attribute:
-
-
name="name"
-
(Required)
The value of the 'id' attribute within the HTML or
XML page. It is not an error if an id with this
name does not appear in the HTML or XML document.
-
The 'class' element controls processing of HTML elements
associated with a certain class. A 'class' element maps
to 'class' attributes declared within the HTML page or
XML file. The content of the 'class' element is applied
to any HTML or XML element having a matching 'class'
attribute. If more than one element ('class' or 'id') in
the Dynamator file applies to the same HTML or XML
element, the effect is additive, with overrides having
the same name applied so that 'id' has precedence over
'class', and earlier classes listed within the element's
attribute value have precedence.
The 'class' element must have the following attribute:
-
-
name="name"
-
(Required)
The value of the 'class' attribute within the HTML
or XML page. Class attribute values defined in the
HTML or XML page must be space-separated. It is not
an error if a class with this name does not appear
in the HTML or XML document.
-
The 'tag' element identifies elements by tag name and
attributes. It is especially useful for tags for which
'id' or 'class' is invalid, where it is possible to
identify a single tag occurrence based on attribute
values.
The 'tag' element must have at least one of the following
attributes:
-
-
tag="name"
-
(Optional)
The tag name of an element within the HTML or XML
template. If multiple 'tag' elements specify the
same value for this attribute, earlier elements
have precedence. If the value of this attribute is
'*', this element applies to every element in the
template. It is not an error if a tag with this
name does not appear in the HTML or XML document.
It is not an error if multiple tags with this name
appear in the HTML or XML document.
-
with-attr="name1 name2 ..."
-
(Optional)
A space-separated list of one or more attribute
names that must be specified by an element within
the HTML or XML template for this tag element to
match.
-
without-attr="name1 name2 ..."
-
(Optional)
A space-separated list of one or more attribute
names that must not be specified by an element
within the HTML or XML template for this tag
element to match.
-
attrname="value"
-
(Optional)
Any attribute name, with any value. The 'tag'
element is applied only to tags in the template
file having an attribute with the name and value
specified. (Note that "attrname" above is not a
specific attribute name, but is replaced with the
name of the attribute to be matched.)
A 'tag' element applies to any tag in the template file
for which all of the following are true:
-
If the value of the 'tag' attribute is not "*", the
name of the HTML/XML tag matches the value of the 'tag'
attribute.
-
For each attribute of the tag element in the Dynamator
file (except for the 'tag' attribute), the HTML/XML tag
has a corresponding attribute with the same value. The
HTML/XML tag may have other attributes not specified in
the tag element.
-
For each word in the 'with-attr' attribute of the tag
element, the HTML/XML tag has a corresponding attribute
with the same name. The HTML/XML tag may have other
attributes not specified in the 'with-attr' attribute.
-
For each word in the 'without-attr' attribute of the
tag element, the HTML/XML tag does not have a
corresponding attribute with the same name.
For example:
-
-
<tag tag="title">
-
Applies to all 'title' tags in the template
file.
-
<tag tag="meta"
http-equiv="Refresh">
-
Applies to any tag in the template file having a
name of 'meta' and an 'http-equiv' attribute with a
value of 'Refresh'.
-
<tag tag="a" with-attr="href">
-
Applies to all <a href="..."> tags, but no
<a name="..."> tags.
-
<tag tag="td" with-attr="class"
without-attr="id">
-
Applies to all <td> tags that have a class
attribute but do not have an id attribute.
-
The 'attr' element specifies behavior for an attribute of
an HTML tag. An attribute may be added, removed, changed,
or made conditional. An 'attr' element must be
immediately subordinate to an id, class, or tag
element.
An 'attr' element maps to an attribute of the tag
identified by the parent 'id', 'class', or 'tag' element.
The attribute does not need to exist in the template
file.
The 'attr' element has the following attributes:
-
-
name="name"
-
(Required)
The name of the attribute. If multiple 'attr'
elements within the same parent element specify the
same value for this attribute, results are
undefined.
-
The 'content' element specifies dynamic content to be
substituted for the original content of an HTML element
or attribute. A 'content' element must be immediately
subordinate to an id,
class, tag, or
attr element.
The content of an element is everything between the
element's start and end tags. Dynamator replaces the
content of the HTML/XML element corresponding to the
'content' element's parent with program code that at
runtime outputs the value of program-expression.
An HTML flag attribute (i.e. an attribute that has no
value) may be added to a tag by specifying the flag
attribute name as the content value.
If a 'content' and a 'raw-content' element are specified
for the same template element, the results are undefined.
A 'content' element must not be empty.
When used within an 'id', 'class', or 'tag' element, the
content of the corresponding element is replaced with the
content of this element.
When used within an 'attr' element, the value of the
corresponding attribute is given the content of this
element. If the attribute is not in the original HTML, it
is added.
Text within a 'content' element is treated as CDATA; that
is, it may contain special characters such as '<'.
Template Attribute Value Substitution
When used within an 'attr' element, the content and
raw-content elements may contain references to the
original attribute value. This can be especially useful
for href's, which often change between a static site and
a live site.
[[@]]
|
Replaced by the original value of the
attribute.
|
[[@/a/b/]]
|
Replaced by the original value of the attribute, with
all occurrences of string 'a' replaced with string
'b'. For example, if the attribute value is
'index.html', and the content value is
'response.encodeURL("[[@/.html/.jsp]]")', the result
is 'response.encodeURL("index.jsp")'.
|
[[@/a/b/+/c/d/]]
|
Replaced by the original value of the attribute, with
all occurrences of string 'a' replaced with string
'b', then all occurrences of string 'c' replaced with
string 'd'. An unlimited of replacement pairs may be
specified. Replacement is performed in the order
listed.
|
-
The 'discard' element causes the referenced template
element and its children to be removed from the output
file.
A 'discard' element must be immediately subordinate to an
id, class, tag, or attr element.
-
The 'discard-tag' element causes an HTML or XML tag, but
not its content, to be removed from the output file. The
element's start and close tags are removed, but the
element's content is retained.
A 'discard-tag' element must be immediately subordinate
to an id, class,
or tag element.
-
The 'rename' element causes the name of an HTML or XML
element or attribute to be changed upon output. The
attribute or tag and optional close-tag for the element
are output with the name new-name.
A 'rename' element must be immediately subordinate to an
id, class, tag, or attr element.
If more than one 'rename' element applies to the same tag
or attribute, results are undefined.
-
<extract { to-file="extract-file-name"}>
<!-- Content: ( program-lines )* -->
</extract>
|
The 'extract' element causes an HTML or XML element or
attribute to be moved to the end of the file,
or to another file entirely.
If the 'to-file' attribute is present, the extracted
element is moved to the file named by its value.
If the file is a relative path, the path is relative to
the current output file.
If the 'to-file' attribute is not present, the extracted
element is moved to the end of the file, immediately before
the epilog. The content of the before-extracts element, if
present, is placed before the first extract, and the
content of the
after-extracts element, if present, is placed after
the last extract.
The content of the 'extract' element consists of optional
program lines that replace the extracted element.
The 'extract' element is useful for program logic
requiring recursion, when the language does not allow
inline function definition. It is ideal for XSL, which
often requires recursion. The 'extract' element without
'to-file' is incompatible with JSP, because JSP does not
convert static content outside of the main template block.
(Use a recursively invoked inline class instead.)
An 'extract' element must be immediately subordinate to
an id, class, or
tag element.
-
The 'if' element causes the referenced template element
and its children to be output by the server page only if
program-conditional-expression evaluates to 'true'
at run-time.
An 'if' element must be immediately subordinate to an id, class, tag, or attr element.
As a special case, the value "<if>false</if>"
causes the element and all its children to be omitted
from the generated file. (This provides the creator of
the Dynamator file a mechanism similar to that provided
to the template author through the "Discard" class.)
Text within an 'if' element is treated as CDATA; that is,
it may contain special characters such as '<'.
for
-
<for>
<!-- Content:
for-statement-remainder
<if>conditional-expression</if> -->
</for>
|
A 'for' element outputs a 'for' block in the target
language, causing the referenced template element and its
content to be output multiple times.
A 'for' element must be immediately subordinate to an id, class, or tag element.
The content of the element is the text that appears after
the target language's 'for' keyword. The content may
optionally contain an <if> element specifying a
conditional expression. If present, this condition is
evaluated for each iteration; the referenced template
element and its content are output only if the condition
is true.
-
A 'foreach' element causes the referenced template
element and its children to be output once for each
element of a collection.
A 'foreach' element must be immediately subordinate to an
id, class, or tag element.
The target collection is identified by the content of the
'foreach' element, which must be a program expression
that evaluates to a collection.
The 'foreach' element's content may optionally contain an
<if> element specifying a conditional expression.
If present, this condition is evaluated for each
iteration; the referenced template element and its
content are output only if the condition is true.
Most of the attributes of this element specify variable
names for generated code. Although Dynamator can generate
variable names when none are supplied, readability of the
generated code is greatly improved if names are supplied.
The 'foreach' element may have the following attributes:
-
-
type="program-collection-type-name"
-
(Required for typed target languages such as Java;
not available for all languages)
Identifies the type of the
program-collection-expression. The value of
this attribute is target-language-specific.
-
element="program-variable-name"
-
(Required for most languages; not available for all
languages)
Identifies the name of the program variable that
refers to the current element of the collection.
-
i="iteration-variable-name"
-
(Optional; not available for all languages)
Identifies the name of the iteration variable. The
iteration variable is in scope for the duration of
the iteration. Its value is the number of times the
iteration block has been completed (i.e. the offset
into the collection).
Dynamator generates code that uses this variable
only for sequences that can be accessed using a
numeric index. If not specified, Dynamator
generates a name.
If specified for a collection type that does not
require it, Dynamator generates code to declare
and increment the variable so that it is
available within the iteration block.
-
collection="collection-variable-name"
-
(Optional; not available for all languages)
Identifies the name of the program variable that
references the collection. If this attribute is not
specified, Dynamator generates a name from
program-collection-expression.
foreach (sequenced)
The sequenced form of the 'foreach' element has been
deprecated. Use the
for element instead.
-
The sequenced form of the 'foreach' element allows
generation of a 'for' construct in languages that support
it. Since different languages use different forms of this
construct, the specific meaning of an element depends on
the target language.
For C-like languages, the form is
for ( first; last;
step )
For VB-like languages, the form is
for i = first to
last step step
The sequenced values form of the 'foreach' element takes
no element content. It takes the following attributes:
-
-
i="iteration-variable-name"
-
(Used only if supported by
the target language's generator.)
The name of the iteration variable. The value of
the iteration variable changes with each iteration.
It is initialized to 'first' and incremented by the
value of 'step'.
-
first="initial-value-expression"
-
(Required)
A program language string identifying the value to
which the iteration variable will be initialized
for the first iteration. In C-like languages, this
should take a form like 'i = n'. In VB-like
languages, this should be a program language
expression yielding a value that can be assigned to
'i'.
-
last="final-value-expression"
-
(Required)
A program language string identifying the value of
the iteration variable for the last iteration. In
C-like languages, this should take a form like 'i
< n'. In VB-like languages, this should be a
program language expression yielding a value that
can be compared against 'i'.
-
step="collection-variable-name"
-
(Required for C-like
languages; optional for VB-like languages)
A program language string identifying the means of
incrementing the iteration variable between
iterations. In C-like languages, this should take a
form like '++i'. In VB-like languages, this should
be a program expression yielding a value that can
be added to 'i'.
Low-level tags provide the ability to directly insert
code before and after tags and their corresponding end
tags. They are provided for completeness, but they should
be avoided if a higher-level tag will do.
-
<before { indent="yes" } { indent-program="yes" }>
<!-- Content: target-file-text -->
</before>
|
The 'before' element is a low-level element that places
its contents directly before the referenced tag and any
generated code that may be placed before the tag. It may
be used to directly insert code in front of a tag. The
content of the 'before' element is copied as-is to the
generated file.
A 'before' element must be immediately subordinate to an
id, class, or tag element.
Text within a 'before' element is treated as CDATA; that
is, it may contain special characters such as '<'.
The 'before' element has the following attribute:
-
-
indent="yes"
-
(Optional)
Indents the element referenced by the 'before'
element, and its content.
-
indent-program="yes"
-
(Optional)
Indents the program lines that output the element
referenced by the 'before' element, and the program
lines that output the element's content. Has effect
only for target languages that support program
lines that may be indented. (For example, this
attribute affects Java, but not JSP, output.)
-
<before-content { indent="yes" } { indent-program="yes" }>
<!-- Content: target-file-text -->
</before-content>
|
The 'before-content' element is a low-level element that
places its contents directly after the referenced tag and
before any content or generated code after the tag. It
may be used to directly insert code or text immediately
after a tag. The content of the 'before-content' element
is copied as-is to the generated file.
A 'before-content' element must be immediately
subordinate to an id,
class, or tag element.
Text within a 'before-content' element is treated as
CDATA; that is, it may contain special characters such as
'<'.
The 'before-content' element has the following attribute:
-
-
indent="yes"
-
(Optional)
Indents the content of the element referenced by
the 'before' element.
-
indent-program="yes"
-
(Optional)
Indents the program lines that output the content
of the element referenced by the 'before' element.
Has effect only for target languages that support
program lines that may be indented. (For example,
this attribute affects Java, but not JSP, output.)
-
<raw-content { indent="yes" } >
<!-- Content: target-file-text -->
</raw-content>
|
The 'raw-content' element is a low-level element that
replaces the content of the corresponding template
element with its content. It may be used to directly
insert code or text to replace the original content of
the element. The content of the 'raw-content' element is
copied as-is to the generated file.
When used within an 'id', 'class', or 'tag' element, the
content of the corresponding element is replaced with the
content of this element. When used within an 'attr'
element, the value of the corresponding attribute is
given the content of this element. If the attribute is
not in the original HTML, it is added.
If a 'content' and a 'raw-content' element are specified
for the same template element, the results are undefined.
An 'raw-content' element must be immediately subordinate
to an id, class,
or tag element.
Text within an 'raw-content' element is treated as CDATA;
that is, it may contain special characters such as
'<'.
-
The 'after' element is a low-level element that places
its contents directly after the end-tag corresponding to
the referenced tag and any generated code that may be
placed after the tag. It may be used to directly insert
code following an end-tag. The content of the 'after'
element is copied as-is to the generated file.
An 'after' element must be immediately subordinate to an
id, class, or tag element.
Text within an 'after' element is treated as CDATA; that
is, it may contain special characters such as '<'.
after-content
-
The 'after-content' element is a low-level element that
places its contents directly after the contents of the
end-tag corresponding to the referenced tag and before
any generated code associated with the end tag
corresponding to the referenced HTML tag. It may be used
to directly insert code immediately before an end tag.
The content of the 'after-content' element is copied
as-is to the generated file.
An 'after-content' element must be immediately
subordinate to an id,
class, or tag element.
Text within an 'after-content' element is treated as
CDATA; that is, it may contain special characters such as
'<'.
-
The 'raw-attrs' element is a low-level element that
places its contents at the end of the attribute list for
a tag. It may be used to add attributes to a tag at
run-time.
No checking is provided for invalid attribute list syntax
or duplicate attribute names.
A 'raw-attrs' element must be immediately subordinate to
an id, class, or
tag element.
Text within an 'raw-attrs' element is treated as CDATA;
that is, it may contain special characters such as
'<'. (However, note that such characters are invalid
as attribute values.)
The 'raw-attrs' element has the following attribute:
-
-
space="no"
-
(Optional)
Indicates that a space should not be inserted
before the content of the raw-attrs element. Use
this attribute when the content of the raw-attrs
element is a program expression that may not output
any attributes. This ensures that an HTML tag does
not have a space before the close '>', which
would be invalid.
Expressions
This document uses the following special terms to denote
varieties of expressions allowed within a Dynamator file:
-
-
program-expression
-
A program expression. Text within a
program-expression is treated as CDATA; that is, it
may contain special characters such as
'<'.
-
program-collection-expression
-
A program-expression that evaluates to a
value with a type of Object[], Enumeration, Vector,
Dictionary, or Properties.
-
program-conditional-expression
-
A program-expression that evaluates to a
value with a type of boolean.
-
target-file-text
-
Text that is output as-is to the target file.
Target file text is treated as CDATA; that is, it
may contain special characters such as '<'.
