SLAX Templates Overview

Unnamed (Match) Templates

Unnamed templates, also known as match templates, contain a match statement with an XPath expression to specify the criteria for nodes upon which the template should be invoked. In the following commit script sample, the template matches the top-level element in the configuration hierarchy:

match configuration {
    /* ...body of the  template goes here */
}

By default, the processor recursively traverses the entire document hierarchy, inspecting each node and looking for a template that matches the current node. When a matching template is found, the contents of that template are evaluated.

The apply-templates statement can be used inside an unnamed template to limit and control the default, hierarchical traversal of nodes. This statement accepts an optional XPath expression, which is equivalent to the select attribute in an <xsl:apply-templates> element. If an optional XPath expression is included, only nodes matching the XPath expression are traversed. Otherwise, all children of the context node are traversed. If the XPath expression is included but does not match any nodes, nothing is traversed and nothing happens.

In the following example, the template rule matches the <route> element in the XML hierarchy. All the nodes containing a changed attribute are processed. All route elements containing a changed attribute are replaced with a new element.

match route {
    <new> {
        apply-templates *[@changed];
    }
}

The XSLT equivalent:

<xsl:template match="route">
    <new>
        <xsl:apply-templates select="*[@changed]"/>
    </new>
</xsl:template>

Using unnamed templates allows the script to ignore the location of a tag in the XML hierarchy. For example, if you want to convert all <author> tags into <div class="author"> tags, using templates enables you to write a single rule that converts all <author> tags, regardless of their location in the input XML document.

Named Templates

Named templates operate like functions in traditional programming languages. When the complexity of a script increases or a code segment appears in multiple places, you can modularize the code and create named templates. Like functions, named templates accept arguments and run only when explicitly called.

In SLAX, the named template definition consists of the template keyword, the template name, a set of parameters, and a braces-delimited block of code. Parameter declarations can be inline and consist of the parameter name, and, optionally, a default value. Alternatively, you can declare parameters inside the template block using the param statement. If a default value is not defined, the parameter defaults to an empty string.

The following example creates a template named my-template and defines three parameters, one of which defaults to the string false, and one of which defaults to the contents of the element node named name that is a child of the current context node. If the script calls the template and does not pass in a parameter, the default value is used.

template my-template ($a, $b = "false", $c = name) {
    /* ... body of the template ... */
}

An alternate method is to declare the parameters within the template using the param statement. The following code is identical to the previous example:

template my-template {
    param $a;
    param $b = "false";
    param $c = name;
    /* ... body of the template ... */
}

In SLAX, you invoke named templates using the call statement, which consists of the call keyword and template name, followed by a set of parameter bindings. These bindings are a comma-separated list of parameter names that are passed into the template from the calling environment. Parameter assignments are made by name and not by position in the list. Alternatively, you can declare parameters inside the call block using the with statement. Parameters passed into a template must match a parameter defined in the actual template; otherwise the parameter is ignored. Optionally, you can set a value for each parameter. If you do not define a value for the parameter in the calling environment, the script passes in the current value of the parameter if it was previously initialized, or it generates an error if the parameter was never declared. For more information about passing parameters, see SLAX Parameters Overview.

In the following example, the template my-template is called with the parameter c containing the contents of the element node named other-name that is a child of the current context node:

call my-template {
    with $c = other-name;
}

In the following example, the name-servers-template declares two parameters: name-servers and size. The size parameter is given a default value of zero. The match template, which declares and initializes name-servers, calls the name-servers-template three times.

The first call to the template does not include any parameters. Thus name-servers will default to an empty string, and size will default to a value of zero as defined in the template. The second call includes the name-servers and size parameters, but only supplies a value for the size parameter. Thus name-servers has the value defined by its initialization in the script, and size is equal to the number of name-servers elements in the configuration hierarchy. The last call is identical to the second call, but it supplies the parameters using the with statement syntax.

match configuration {
    param $name-servers = name-servers/name;
    call name-servers-template();
    call name-servers-template($name-servers, $size = count($name-servers));
    call name-servers-template() {
        with $name-servers;
        with $size = count($name-servers);
    }
}
    template name-servers-template($name-servers, $size = 0) {
        <output> "template called with size " _ $size;
    }

The XSLT equivalent is:

<xsl:template match="configuration">
    <xsl:variable name="name-servers" select="name-servers/name"/>
    <xsl:call-template name="name-servers-template"/>
    <xsl:call-template name="name-servers-template">
        <xsl:with-param name="name-servers" select="$name-servers"/>
        <xsl:with-param name="size" select="count($name-servers)"/>
    </xsl:call-template>
    <xsl:call-template name="name-servers-template">
        <xsl:with-param name="name-servers" select="$name-servers"/>
        <xsl:with-param name="size" select="count($name-servers)"/>
    </xsl:call-template>
</xsl:template>
 
<xsl:template name="name-servers-template">
    <xsl:param name="name-servers"/>
    <xsl:param name="size" select="0"/>
    <output>
        <xsl:value-of select="concat('template called with size ', $size)"/>
    </output>
</xsl:template>