1.5. Element transform

1.5. Element `transform`
	1. Reference

1.5. Element `transform`

<transform
  stylesheet = anyURI
  version = Non empty token : "1.0"
  cacheStylesheet = boolean : false
  file = Path
  to = Path
  pattern = boolean : false
>
  Content: [ info ]?
           [ parameter | parameterGroup ]*
</transform>

<info>
  Not documented.
</info>

<parameter
  name = Non empty token
  url = boolean
>
  Content: Parameter value
</parameter>

<parameterGroup
  name = Non empty token
/>

Converts a XML file to another format using built-in XSLT engine.

Attributes:

stylesheet

Specifies which XSLT style sheet to use. If this URL is relative, it is relative to the directory containing the XXE configuration file.

The URI specified in this attribute may be also resolved using XML catalogs.

version

Specifies the version of the XSLT style sheet and hence, which XSLT engine to use. Default value is "1.0". The only other supported value is "2.0".

If version="1.0", the bundled Saxon 6.5.5 XSLT 1 engine is used.

If version="2.0", the bundled Saxon 9.2+ XSLT 2 engine is used.

A version number may be followed by one or more fully qualified method names separated by semicolons (';'). Example: "2.0;com.xmlmind.ditac.xslt.ExtensionFunctions.registerAll".

Such methods are used to configure a javax.xml.transform.TransformerFactory prior to using it. They are typically used to add extension functions to Saxon 9.2+.

Such methods must be static and must have the following signature: void method_name(TransformerFactory factory) throws Exception.

cacheStylesheet

If this attribute is specified as true, a precompiled form of the XSLT style sheet is built and then cached for subsequent uses.

It is not recommended to cache an XSLT style sheet unless this style sheet is small and used in highly interactive process commands (like in example 1 below).

file

Input file.

When pattern="false", the value of the file attribute is expected to a simple file path. However, it's also possible to specify a glob pattern, but in such case, pattern mode is not enabled and this glob pattern must match exactly one file.

to

Output file or directory. When to specifies a directory, the basename of the output file is taken from the input file.

pattern

If this attribute is specified as true, transform operates in “pattern mode” and a glob pattern is allowed in the file attribute. Pattern mode is best explained by the two following examples:

Example 1: file="*.xml", to="temp". Glob pattern *.xml matches foo.xml and bar.xml. Attribute value temp specifies an existing directory. The XSLT transform will be invoked twice, first time with foo.xml as its input and the second with bar.xml as its input. The first time, the transform will generate temp/foo.xml and the second time it will generate temp/bar.xml.

Example 2: file="*.xml", to="any.htm". Glob pattern *.xml matches foo.xml and bar.xml. The XSLT transform will be invoked twice, first time with foo.xml as its input and the second with bar.xml as its input. The first time, the transform will generate foo.htm and the second time it will generate bar.htm.

Parameter and/or named parameterGroup child elements are used to parametrize the XSLT style sheet. Example: <parameter name="paper.type">A4</parameter>. Such parameters are described in the documentation of the XSLT style sheets (e.g. DocBook XSL Stylesheet Documentation).

If a transform element references a parameterGroup, this means that a parameterGroup configuration element (see Section 23, “parameterGroup” in XMLmind XML Editor - Configuration and Deployment) with the same name is defined elsewhere in this configuration file or in another configuration file. Note that it is not an error to reference a parameterGroup for which the configuration element is not found. Such reference to a possibly non-existent parameterGroup is useful as a placeholder.

1.5.1. Using a custom XSLT style sheet

A user can force the use of a custom style sheet of his own instead of the one normally specified in attribute stylesheet.

In order to do this, the user needs to specify a property called process_command_name.transform in any XXE configuration file. The value of this property must be the URL of the custom XSLT style sheet. (This property is typically specified in the user's customize.xxe file. See property configuration element in Section 22, “property” in XMLmind XML Editor - Configuration and Deployment.)

If a process command has several transform child elements, property process_command_name.transform specifies a style sheet for the first transform, process_command_name.transform.2 specifies a style sheet for the second transform, process_command_name.transform.3 specifies a style sheet for the third transform and so on.

Example: the process command to be customized is called docb.toPS (see XXE_install_dir/addon/config/docbook/xslMenu.incl). User has added the following property to his customize.xxe file.

<property name="docb.toPS.transform" url="true">fo_docbook.xsl</property>

Note that the URL is relative to the configuration file containing the definition of property docb.toPS.transform (here, it is relative to customize.xxe).

The custom XSLT style sheet fo_docbook.xsl contains:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<xsl:import href="docbook-config:xsl/fo/docbook.xsl"/>

<xsl:template match="bookinfo/author|info/author" mode="titlepage.mode">
  <fo:block>
    <xsl:call-template name="anchor"/>
    <xsl:call-template name="person.name"/>
    <xsl:if test="affiliation/orgname">
      <fo:block>
        <xsl:apply-templates select="affiliation/orgname"
                             mode="titlepage.mode"/>
      </fo:block>
    </xsl:if>
    <xsl:if test="email|affiliation/address/email">
      <fo:block>
        <xsl:apply-templates select="(email|affiliation/address/email)[1]"/>
      </fo:block>
    </xsl:if>
  </fo:block>
</xsl:template>

</xsl:stylesheet>

Note how the stock docbook.xsl is imported by this customized version.


	In our opinion, it is almost impossible to cope with the complexity of customizing Norman Walsh's DocBook XSLT style sheets without reading this excellent book: DocBook XSL: The Complete Guide by Bob Stayton.


1.4. Element `copyProcessResources`		1.6. Element `processFO`