Applying a custom stylesheet

You can provide XSLT stylesheets for any resource. If you do not provide one, a default stylesheet is used. Using custom XSLT, you can transform XML representations into another XML document, HTML, WML, CSV (comma-separated values), and other text formats. You may need some knowledge of XSLT to understand this section. However, the XSLT shown is quite basic.

Matching stylesheets to resources

Default match

By default, the server matches a stylesheet to a resource based on the resource type. For example, the default HTML rendering of a <http://waterken.com/adt/hashed/Map>, seen in the previous section, was created by the stylesheet at: xslt/html/en-US/waterken.com/adt/hashed/Map.xsl. All XSLT stylesheets are kept in the xslt/ directory of your installation.

All XML generated by the Waterken^TM server specifies the resource type, as well as any compatible resource types. When asked to generate HTML output, the server searches for a stylesheet matching the most specific type. If one is not found, it tries to match the more general types. If no match is found, the server uses a general stylesheet that can handle any type of resource. For most resources, this stylesheet prints out each branch in a table. For invokable resources, a default HTML FORM is created. This default rendering is useful during application development.

Forced match

Sometimes different views are needed for displaying different representations of the resource. You can force the server to use a stylesheet other than its default one. For the weekly sales resource, we would like to create a rendering that is specific to a map containing the weekly sales data, rather than rendering the weekly sales as a generic map. We can easily apply any stylesheet to a resource by using a "stylesheet" argument in the resource's capability URL. The value of the argument is the stylesheet identifier.

View the custom rendering of the weekly sales resource by appending this query string to the URI: ?stylesheet=http://waterken.com/coffeebreak/WeeklySales. Click here to see the custom rendering on your machine. This rendering is created by the XSLT stylesheet located at: xslt/html/en-US/waterken.com/coffeebreak/WeeklySales.xsl. Note that you will often be providing this sort of link from another resource, so the stylesheet parameter is easy to add on. We will look at creating higher-level resources later in the tutorial.

Viewing server-generated XML

The XML representation of the weekly sales map looks like:

You can view the actual XML in your browser. To do so, open the weekly sales in your browser. In your browser location bar, substitute ".xml" for the ".html" file extension and press "return". If you are using Mozilla, you may need to view the source code to see the XML.

Matching templates by element type

The preferred style for Waterken^TM application XSLT is to match templates to elements using the element's type, or "schema" attribute. Matching on the type ensures that the XML is compatible with the stylesheet. Since you can force a stylesheet match, you can mistakenly feed incompatible XML to a stylesheet. Matching on type handles this situation.

All stylesheets should have at least three templates. The first template strips off the <list> element that usually appears around the generated XML.

<xsl:template match="list">
    <xsl:apply-templates select="doc" />
</xsl:template>
            

Having stripped off the <list> element, we are left with a <doc> element that contains a "schema" attribute. This attribute is the resource type. Two templates deal with this attribute: one matches a <doc> element that has the expected schema type, the other matches on any unexpected type.

The template that matches on the unexpected type has two functions. It tests for an element named <super>. If no <super> exists, it prints out an error message. The <super> element indicates that the resource contains a compatibility chain. One of the super elements might contain the expected type. Therefore, an apply-templates is used to determine if the <super> contains the correct type. The code that produces the error page is very basic XSLT which is not reproduced here. View the XSLT document itself for details.

<xsl:template match="*[@schema != 'http://waterken.com/adt/hashed/Map']">
    <xsl:choose>
        <!-- Compatible? -->
        <xsl:when test="super">
            <xsl:apply-templates select="super" />
        </xsl:when>
        <xsl:otherwise>
            <!-- Constructs error page -->
        <xsl:otherwise>
    </xsl:choose>
</xsl:template>
            

The map in HTML

The template that matches on the expected type creates an HTML table that prints out the coffee names and sales amounts. The XML is simple, so the XSLT is quite simple as well. This code excerpt contains the highlights of this template.

<xsl:template match="*[@schema = 'http://waterken.com/adt/hashed/Map']">
    ...
    <xsl:for-each select="element">
        <tr bgcolor="#FFFFFF"> 
            <th align="left">
                <!-- Coffee name. -->
                <span class="arial">
                    <xsl:value-of select="normalize-space(key)" />
                </span>
            </th>
            <td align="right">
                <!-- Coffee sales. -->
                <span class="arial">
                    <xsl:value-of select="normalize-space(value)" />
                </span>
            </td>
        </tr>
    </xsl:for-each>
    ...
</xsl:template>
            

We will look at some more stylesheet examples as we build other resources. The next section describes a query that uses composite datatypes.

Copyright 2002 - 2003 Waterken Inc. All rights reserved.