1.5. Element `transform`
Prev | 1. Reference | Next

### 1.5. Element `transform`

    <transform
      stylesheet = anyURI
      version = Non empty token : "1.0"
      cacheStylesheet = boolean : false
      file = Path
      to = Path
      pattern = boolean : false
      label = Non empty token
      documentation = anyURI possibly containing a %{parameter.name} variable
    >
      Content: [ parameter | parameterGroup ]*
    </transform>

    <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.

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`, a glob pattern is allowed in the `file` attribute.

  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`.

label

  Specifying this label allows to use the dialog box displayed by Options → Customize Configuration → Change Document Conversion Parameters in order to easily parametrize the XSLT style sheet. However, just specifying a `label` attribute for the `transform` element is not sufficient in order to use this facility. In addition, the last child element of the `transform` element must be a `parameterGroup`. XHTML example:

      <transform stylesheet="xsl/fo.xsl"
        file="__doc.xml" to="__doc.fo"
        label="Convert to PDF, PostScript">
        <parameterGroup name="xhtml.toPS.transformParameters" />
      </transform>

documentation

  Like `label`, this attribute is also used by the dialog box displayed by Options → Customize Configuration → Change Document Conversion Parameters. Specifying an URL here allows the dialog box to display the documentation of the XSLT style sheet in the web browser of the user.

  If the specified URL contains a `%{parameter.name}` variable, this variable is replaced by the name of the XSLT style sheet parameter (e.g. `paper.type`) currently selected by the user.

  If the specified URL contains a `%{parameter.name|`fallback_parameter_name`}` variable, this variable is replaced by the name of the XSLT style sheet parameter currently selected by the user. And if the user has not selected a parameter in the dialog box then `fallback_parameter_name` is used instead. DocBook example:

      <transform stylesheet="xsl/fo/docbook.xsl"
        file="__doc.xml" to="__doc.fo"
        label="Convert to RTF, WordprocessingML, OpenDocument, OOXML"
        documentation="http://docbook.sourceforge.net/release/xsl/current/¬
      doc/fo/%{parameter.name|paper.type}.html">
        ...
        <parameter name="paper.type">A4</parameter>
        ...
        <parameterGroup name="docb.toRTF.transformParameters" />
      </transform>

`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 17, “parameterGroup” in <ttl>XMLmind XML Editor - Configuration and Deployment</ttl>) 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 16, “property” in <ttl>XMLmind XML Editor - Configuration and Deployment</ttl>.)

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="xxe-config:docbook/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.

### Tip

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.

Prev | Up | Next
1.4. Element `copyProcessResources` | Home | 1.6. Element `processFO`