1.3 Using apply-templates

One possible element that can be contained inside of a template element is apply-templates. Because apply-templates is contained in template, it is called a child element of template. In XSLT, apply-templates is also termed an instruction element. An instruction element in XSLT is always contained within something called a template. A template is a series of transformation instructions that usually appear within a template element, but not always. A few other elements can contain instructions, as you will see later on. XSLT 1.0 has a number of instruction elements that will eventually be explained and discussed in this book.

The apply-templates element triggers the processing of the children of the node in the source document that the template matches. These children (child nodes) can be elements, attributes, text, comments, and processing instructions. If the apply-templates element has a select attribute, the XSLT processor searches exclusively for other nodes that match the value of the select attribute. These nodes are then subject to being processed by other templates in the stylesheet that match those nodes.

Let's not fret about what all that means right now. It's hard to follow exactly what XSLT is doing when you are just starting out. I'll cover more about how apply-templates works in the next chapter.

1.3.1 Analysis of message.xml

To understand how apply-templates works, first take a look at the document message.xml in examples/ch01:

<?xml version="1.0"?>    <message priority="low">Hey, XSLT isn't so hard after all!</message>

The message element in message.xml has an attribute in its start tag: the priority attribute with a value of low. Also, this element is not empty; it holds the string Hey, XSLT isn't so hard after all! In the terminology of XML, this text is called parsed character data, and in the terminology of XPath, this text is called a text node.

Character Data and Unicode

Character data, indeed any character that appears in an XML document, must be a Unicode character that falls within XML's overall legal subset of Unicode. XML supports ISO/IEC 10646-1 Universal Multi-Octet Character Set, or USC, which is roughly but not strictly interchangeable with Unicode. When referring to the characters that XML supports, most people talk about these characters as Unicode, and so that's what I'll do, too.

Unicode is slowly and surely extending its reach to include, as near as possible, all the character-based writing systems in the world. This obviously goes way beyond the 128-character range of the basic Latin 7-bit ASCII standard. (ASCII, or the American Standard Code for Information Interchange, is a standard of the American National Standards Institute, or ANSI.) Because XML embraces Unicode, it is being used all over the world. In fact, XML is sometimes affectionately referred to as "Unicode with pointy brackets."

It is important to note that a number of Unicode characters are prohibited from XML for example, most C0 control characters are not allowed characters such as null (0x0000), backspace (0x0008), and form feed (0x000C). The C0 characters comprise the first 32 characters of Unicode, in the hexadecimal range 0000 through 001F. Sections 2.2, 2.3, and 2.4, and Appendix B, of the XML specification go into painstaking detail about what characters can go where in an XML document. You can find out more about Unicode at http://www.unicode.org and about ISO/IEC specs at http://www.iso.ch.

1.3.1.1 The XML declaration

Before the message element, at the beginning of this document, is something that looks like a processing instruction, but it's not. It's called an XML declaration.

The XML declaration is optional. You don't have to use one if you don't want to, but it's generally a good idea. If you do use one, however, it must be on the first line to appear in the XML document. Because it must appear before the document element, that also means that an XML declaration is part of the prolog, like the XML stylesheet PI.

If present, an XML declaration must provide version information. Version information appears in the form of a pseudoattribute, version, with a value representing a version number, which is almost always 1.0. Other values are possible, but none are authorized at the moment because an XML version later than 1.0 has not yet been approved.

XML 1.1, which mainly adds more characters to the XML Unicode character repertoire, is currently under consideration, and may become a W3C recommendation by the time you read this book or shortly thereafter. You can see the XML 1.1 spec at http://www.w3.org/TR/xml11/.

You can also declare character encoding for a document with an XML declaration, and whether a document stands alone. The XML declaration will be covered in more detail in Chapter 3. See Section 2.8 of the XML specification for more information on XML declarations.

The stylesheet message.xsl in examples/ch01 includes the apply-templates element:

<stylesheet version="1.0" xmlns="http://www.w3.org/1999/XSL/Transform"> <output method="text"/>    <template match="message">  <apply-templates/> </template>    </stylesheet>

Now you'll get a chance to apply this stylesheet to message.xml and see what happens. Instead of using a browser as you did earlier, this time you'll have a chance to use Xalan, an open source XSLT processor from Apache, written in both C++ and Java. The C++, command-line version of Xalan runs on Windows plus several flavors of Unix, including Linux. (When I refer to Unix in this book, it usually applies to Linux; when I refer to Xalan, I mean Xalan C++, unless I mention the Java version specifically.)

1.3.2 Running Xalan

To run Xalan, you also need the C++ version of Xerces, Apache's XML parser. You can find both Xalan C++ and Xerces C++ on http://xml.apache.org. After downloading and installing them, you need to add the location of Xalan and Xerces to your path variable. If you are unsure about how to install Xalan or Xerces, or what a path variable is, you'll get help in the appendix.

Once Xalan and Xerces are installed, while still working in examples/ch01 directory, type the following line in a Unix shell window or at a Windows command prompt:

xalan message.xml message.xsl

If successful, the following results should be printed on your screen:

Hey, XSLT isn't so hard after all!

So what just happened? Instead of the processor writing content from the stylesheet into the result tree by using instructions in the stylesheet message.xsl, Xalan grabbed content from the document message.xml. This is because, once the template found a matching element (the message element), apply-templates processes its children. The only child that message had available to process was a child text node the string Hey, XSLT isn't so hard after all!

The reason why this works is because of a built-in template that automatically renders text nodes. You'll learn more about how apply-templates and built-in templates work in more detail in later chapters. If you want to go into more depth, you can read about apply-templates in Section 5.4 of the XSLT specification.

1.3.3 More About Xalan C++

If you enter the name xalan on a command line, without any arguments, you will see a response like this:

Xalan version 1.5.0 Xerces version 2.2.0 Usage: Xalan [options] source stylesheet Options:   -a                  Use xml-stylesheet PI, not the 'stylesheet' argument   -e encoding         Force the specified encoding for the output.   -i integer          Indent the specified amount.   -m                  Omit the META tag in HTML output.   -o filename         Write output to the specified file.   -p name expression  Sets a stylesheet parameter.   -u                  Disable escaping of URLs in HTML output.   -v                  Validates source documents.   -?                  Display this message.   -                   A dash as the 'source' argument reads from stdin.   -                   A dash as the 'stylesheet' argument reads from stdin.                       '-' cannot be used for both arguments.)

The command-line interface for Xalan offers you several options that I want to bring to your attention. For example, if you want to direct the result tree from the processor to a file, you can use the -o option:

xalan -o message.txt message.xml message.xsl

The result of the transformation is redirected to the file named message.txt. Depending on your platform (Unix or Windows), use the cat or type command to display the contents of the file message.txt:

Hey, XSLT isn't so hard after all!

As with a browser, you can also use Xalan with a document that has an XML stylesheet PI, such as message-pi.xml:

<?xml version="1.0"?> <?xml-stylesheet href="message.xsl" type="text/xsl"?> <message priority="low">Hey, XSLT isn't so hard after all!</message>

To process this document with the stylesheet in its stylesheet PI, use Xalan's -a option on the command line, like this:

xalan -a message-pi.xml

The results of the command should be the same as when you specified both the document and the stylesheet as arguments to Xalan.

1.3.4 Using Other XSLT Processors

There are a growing number of XSLT processors available. Many of them are free, and many are available on more than one platform. In this chapter, I have already discussed the Xalan command-line processor, but I will also demonstrate others throughout the book.

Generally, I use Xalan on the command line, which runs on either Windows or Unix, but you can also choose to use a browser if you wish, or another command-line processor, such as Michael Kay's Instant Saxon a Windows executable, command-line application written in Java. Another option is Microsoft's MSXSL, which also runs in a Windows command prompt. You may prefer to use a processor with a Java interpreter, or you may want to use one of these XSLT processors with a graphical user interface, such as:

Victor Pavlov's CookTop (http://www.xmlcooktop.com)
Architag's xRay2 (http://architag.com/xray/)
Altova's xmlspy (http://www.xmlspy.com)
SyncRO Soft's <oXygen/> (http://www.oxygenxml.com)
eXcelon's Stylus Studio (http://www.stylusstudio.com)

I'll demonstrate here how to use one of these graphical editors: xRay2.

1.3.5 Using xRay2

Architag's xRay2 is a free, graphical XML editor with XSLT processing capability. It is available for download from http://www.architag.com/xray. xRay2 runs only on the Windows platform. Assuming that you have successfully downloaded and installed xRay2, follow these steps to process a source document with a stylesheet:

Launch the xRay2 application.
Open the file message.xml with File Open from your working directory, such as from C:\LearningXSLT\examples\ch01\.
Open the file message.xsl with File Open.
Choose File New XSLT Transform.
In the XML Document pull-down menu, select message.xml (see the result in Figure 1-2).
In the XSLT Program pull-down menu, select message.xsl (see what it should look like in Figure 1-3).
If it is not already checked, check Auto-update.
The result of the transformation should appear in the transform window (see Figure 1-4).

Those are the steps for transforming a file with xRay2. When I suggest transforming a document anywhere in this book, you can use xRay2 or any other XSLT processor you prefer instead of the one suggested in the example (unless there is a specifically noted feature of the processor used in the example).

Figure 1-2. message.xml in xRay2

Figure 1-3. message.xsl in xRay2

Figure 1-4. Result of transforming message.xml with message.xsl in xRay2