Problem

You want to transform an XML document using an XSLT stylesheet.

Solution

Use the Xalan library. First, construct an instance of the XSTL engine xalanc::XalanTransformer. Next, construct two instances of xalanc::XSLTInputSourceone to represent the document to be transformed and the other to represent your stylesheetand an instance of xalanc::XSLTResultTarget to represent the document to be generated by the transformation. Finally, call the XSLT engine's transform( ) method, passing the two XSLTInputSources and the XSLTResultTarget as arguments.

For example, suppose you want to be able to view the list of circus animals from Example 14-1 with your web browser. An easy way to do this is with XSLT. Example 14-19 shows an XSLT stylesheet that takes an XML document like animals.xml as input and generates an HTML document containing a table with one data row per animal listing the animal's name, species, date of birth, veterinarian, and trainer. Example 14-20 shows how to use the Xalan library to apply this stylesheet to the document animals.xml. The HTML generated by the program in Example 14-20 is shown in Example 14-21, reformatted for readability.

Example 14-19. Stylesheet for animals.xml

Feldman Family Circus Animals

Feldman Family Circus Animals

Example 14-20. Applying the stylesheet animals.xsl to the file animals.xml using Xalan

#include #include // cout #include #include #include #include #include #include "xerces_strings.hpp" // Example 14-4 using namespace std; using namespace xercesc; using namespace xalanc; // RAII utility that initializes the parser and frees resources // when it goes out of scope struct XalanInitializer { XalanInitializer( ) { XMLPlatformUtils::Initialize( ); XalanTransformer::initialize( ); } ~XalanInitializer( ) { XalanTransformer::terminate( ); XMLPlatformUtils::Terminate( ); } }; int main( ) { try { XalanInitializer init; // Initialize Xalan. XalanTransformer xslt; // XSLT engine. XSLTInputSource xml("animals.xml"); // XML document from // Example 14-1. XSLTInputSource xsl("animals.xsl"); // Stylesheet from // Example 14-19. XSLTResultTarget html("animals.html"); // xslt's output. // Perform transformation. if (xslt.transform(xml, xsl, html) != 0) { cout << "xml error: " << xslt.getLastError( ) << " "; } } catch (const XMLException& e) { cout << "xml error: " << toNative(e.getMessage( )) << " "; return EXIT_FAILURE; } catch (const exception& e) { cout << e.what( ) << " "; return EXIT_FAILURE; } }

Example 14-21. HTML document generated by the program in Example 14-20

Feldman Family Circus Animals

Feldman Family Circus Animals

Discussion

XSL Transformations (XSLT) is a language for transforming XML documents into other XML documents. XSLT is a component of the Extensible Stylesheet Language (XSL) family of specifications, which provides a framework for specifying visual representations of XML documents. XSLT is useful for more than formatting, however; for example, it is used by web servers to generate HTML documents on-the-fly and by documentation generation systems such as DocBook.

XSLT transformations are expressed as XML documents called stylesheets. A stylesheet acts on a source document to produce a result document. A stylesheet consists of a collection of templates, which match nodes in the source document and are applied to produce fragments of the result document. Templates are applied recursively to the source document, generating fragments of the result document incrementally until no more matches remain. Pattern matching is governed by the XPath language, a language designed to extract informationstrings, numbers, boolean values, and sets of nodesfrom XML documents.

The stylesheet in Example 14-19 contains three templates. The primary template has a match attribute equal to /, indicating that it matches the root of the source document, meaning the node that is the parent of the source document's root element and any top-level processing instructions and comments. When this template is applied, it generates a fragment of an HTML document containing the heading "Feldman Family Circus Animals" and a table with a single row consisting of five th elements containing the labels Name, Species, Date of Birth, Veterinarian, and trainer. This template contains an apply-templates element with match attribute equal to animal. This causes the stylesheet's second templatewith match attribute animal--to be applied once for each of the animal children of the document root, generating a table row for each child. The row generated for an animal element consists of five td elements. The first three td elements contain the text value of the animal element's name, species, and dateOfBirth children, extracted using XSLT's value-of instruction. The last two td elements contains table elements created by applying the stylesheet's third templatewith match attribute veterinarian|trainer--to the animal element's veterinarian and trainer children.

Although I chose to specify local files for the stylesheet, source document, and result document in Example 14-20, XSLTInputSources and XSLTResultTargets can be constructed from C++ standard library streams, allowing a XalanTransformer to accept input and generate output at arbitrary locations. Furthermore, instead of accepting input as instances of XSLTInputSource, a XalanTransformer can operate on a precompiled stylesheet, represented as an instance of xalanc::XalanCompiledStylesheet, and a preparsed source document, represented as an instance of xalanc::XalanParsedSource. This is illustrated in Example 14-22. If you need to apply a single stylesheet to multiple source documents, using a XalanCompiledStylesheet can be much more efficient than using an XSLTInputSource.

Example 14-22. Performing an XSLT transformation with a precompiled stylesheet

/* * Same includes as Example 14-20 */ using namespace std; using namespace xercesc; using namespace xalanc; /* * Define XalanInitializer as in Example 14-20 */ int main( ) { try { XalanInitializer init; // Initialize Xalan. XalanTransformer xslt; // XSLT engine. XSLTResultTarget html("animals.html"); // xslt's output. // Parse source XSLTInputSource xml("animals.xml"); XalanParsedSource* parsedXml = 0; if (xslt.parseSource(xml, parsedXml) != 0) { cout << "xml error: " << xslt.getLastError( ) << " "; } // Compile stylesheet. XSLTInputSource xsl("animals.xsl"); XalanCompiledStylesheet* compiledXsl = 0; if (xslt.compileStylesheet(xsl, compiledXsl) != 0) { cout << "xml error: " << xslt.getLastError( ) << " "; } // Perform transformation. if (xslt.transform(xml, xsl, html)) { cout << "xml error: " << xslt.getLastError( ) << " "; } } catch (const XMLException& e) { cout << "xml error: " << toNative(e.getMessage( )) << " "; return EXIT_FAILURE; } catch (const exception& e) { cout << e.what( ) << " "; return EXIT_FAILURE; } }

See Also

Recipe 14.8