This document describes the language-specific
format and code generation behavior of a Dynamator File with
language specified as "xsl".
A Dynamator File with a root element of
"<dynamator language="xsl">"
identifies a file containing transformations to be
applied to an HTML or XML template in order to
produce an XSL source file (i.e. a file with
filetype ".xsl"). Dynamator applies the Dynamator
file to an HTML or XML file (the "template") to
create an XSL template that outputs an HTML or XML
file with structure corresponding to the template
and behavior specified by the Dynamator file.
XSL Elements
Where a Dynamator File allows program lines, any
XSL code may be used. Unlike other programming
languages supported by Dynamator, XSL code is
placed as-is in the generated file. Because XSL
syntax varies depending on the context, annotations
file authors must take care to use the correct XSL
expression for the affected context. For example,
an <xsl:value-of...> element must not be used
within the content of a <attr> element,
because XML attributes may not contain XML
elements. Instead, the value of an attribute must
be specified using an attribute value template
expression ('{...}'). (Curly braces cannot be
automatically inserted around an expression because
an attribute value might be built from multiple
attribute value templates.)
-
|
How to produce an invalid XSL
template:
|
<attr name="value">
<!-- don't do this! -->
<content>
<xsl:value-of select="@myvalue"/>
</content>
</attr>
|
<!-- the above produces:
<... value="<xsl:value-of select="@myvalue">">
-->
|
|
How to produce a valid XSL template:
|
<attr name="value">
<!-- do this instead! -->
<content>
{@myvalue}
</content>
</attr>
|
<!-- the above produces:
<... value="{@myvalue}">
-->
|
A Dynamator XSL file is structured in the following
way:
Prolog
The prolog contains the xsl stylesheet element,
output method element, and template match element.
In some cases it may also contain the beginning of
the HTML template.
The prolog must not contain an xml declaration
(e.g. <?xml version="1.0"?>), because
Dynamator will not place the declaration at the
first character of the output file.
The following is a typical Dynamator XSL file
prolog:
-
<prolog>
<xsl:stylesheet
version="1.0"
>
<xsl:output method="html"/>
<xsl:template match="/">
</prolog>
|
Epilog
The epilog contains the xsl template-end element
and the xsl stylesheet-end element.
The following is a typical Dynamator XSL file
epilog:
-
<epilog>
</xsl:template>
</xsl:stylesheet>
</epilog>
|
An 'if' element within a Dynamator XSL file has the
following structure:
-
<if>
<!-- Content: xsl-boolean-expression -->
</if>
|
The content of the 'if' element must be an XSL
boolean expression. The boolean expression is
inserted into the xsl:if element as the value of
the 'test' attribute:
<xsl:if test="xsl-boolean-expression">
An 'if' element may only be applied to an XSL
element, not to an attribute. To conditionally
output an attribute, discard the attribute, then
conditionally add it using <before-content>
and the <xsl:attribute> element.
<id name="optional-attribute-example">
<attr name="optional-attribute">
<discard/>
</attr>
<before-content>
<xsl:if test="$optional-attribute-should-be-output">
<xsl:attribute name="optional-attribute">
optional attribute value
</xsl:attribute>
</xsl:if>
</before-content>
</id>
A 'foreach' element within a Dynamator XSL file has
the following structure:
-
<foreach>
<!-- Content: xsl-node-set-expression -->
</foreach>
|
Unlike other languages supported by Dynamator, no
attributes are supported within the 'foreach'
element.
The content of the 'foreach' element must be an XSL
node-set expression. The node-set expression is
inserted into an xsl:for-each element as the value
of the 'select' attribute:
<xsl:for-each select="xsl-node-set-expression">
An XSL template must be a valid XML file. When an
HTML file (that isn't XHTML) is input to Dynamator,
the output is not a valid XML file. Although
Dynamator processing would succeed, the generated
XSL template may fail at runtime. Therefore, to
create an XSL template from an HTML file, the HTML
file must first be converted to a valid XML file
outside of Dynamator, and processed as an XML file.
As long as the XSL template contains the
<xsl:output method="html"> tag, the output of
the template will be valid HTML.
This may be done using a tool such as tidy, with
the following commands:
tidy -asxml --tidy-mark no --doctype omit filename.html > filename.tidy
java dynamate -X filename.tidy
