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.xmlTo 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.
1.3.1.1 The XML declarationBefore 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.
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 XalanTo 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 ProcessorsThere 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:
I'll demonstrate here how to use one of these graphical editors: xRay2. 1.3.5 Using xRay2Architag'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:
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 xRay2Figure 1-3. message.xsl in xRay2Figure 1-4. Result of transforming message.xml with message.xsl in xRay2 |