,TITLE.15229 Page i Wednesday, September 12, 2001 1:12 PM

XML Pocket Reference

, ,TITLE.15229 Page ii Wednesday, September 12, 2001 1:12 PM, ,TITLE.15229 Page iii Wednesday, September 12, 2001 1:12 PM

XML Pocket Reference Second Edition Robert Eckstein

with Michel Casabianca Beijing • Cambridge • Farnham • Köln • Paris • Sebastopol • Taipei • Tokyo, ,COPYRIGHT.15383 Page iv Wednesday, September 12, 2001 1:12 PM

XML Pocket Reference, Second Edition

by Robert Eckstein with Michel Casabianca Copyright © 2001, 1999 O’Reilly & Associates, Inc. All rights reserved. Printed in the United States of America. Published by O’Reilly & Associates, Inc., 101 Morris Street, Sebastopol, CA 95472. Editor: Ellen Siever Production Editor: Jeffrey Holcomb Cover Designer: Hanna Dyer Printing History: October 1999: First Edition April 2001: Second Edition Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly & Associates, Inc. The use of the image of the peafowl in association with XML is a trademark of O’Reilly & Associates, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly & Associates, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher assumes no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. 0-596-00133-9 [C] [5/01],

Table of Contents

Intr oduction ... 1 XML Ter minology ... 2 Unlear ning Bad Habits ... 3 An Overview of an XML Document ... 5 A Simple XML Document ... 5 A Simple Document Type Definition (DTD) ... 9 A Simple XSL Stylesheet ... 10 XML Reference ... 13 Well-For med XML ... 14 Special Markup ... 14 Element and Attribute Rules ... 17 XML Reserved Attributes ... 19 Entity and Character References ... 20 Document Type Definitions ... 21 Element Declarations ... 22 ANY and PCDATA ... 22 Entities ... 26 Attribute Declarations in the DTD ... 29 Included and Ignored Sections ... 34 The Extensible Stylesheet Language ... 37 For matting Objects ... 38 XSLT Stylesheet Structure ... 39 v, Templates and Patterns ... 40 Parameters and Variables ... 43 Stylesheet Import and Rules of Precedence ... 44 Loops and Tests ... 45 Numbering Elements ... 46 Output Method ... 47 XSLT Elements ... 48 XPath ... 70 Axes ... 73 Pr edicates ... 74 Functions ... 76 Additional XSLT Functions and Types ... 79 XPointer and XLink ... 81 Unique Identifiers ... 81 ID References ... 82 XPointer ... 83 XLink ... 87 Building Extended Links ... 90 XBase ... 96 vi,

XML Pocket Reference Introduction

The Extensible Markup Language (XML) is a document- pr ocessing standard that is an official recommendation of the World Wide Web Consortium (W3C), the same group respon- sible for overseeing the HTML standard. Many expect XML and its sibling technologies to become the markup language of choice for dynamically generated content, including non- static web pages. Many companies are alr eady integrating XML support into their products. XML is actually a simplified form of Standar d Generalized Markup Language (SGML), an international documentation standard that has existed since the 1980s. However, SGML is extr emely complex, especially for the Web. Much of the credit for XML’s creation can be attributed to Jon Bosak of Sun Micr osystems, Inc., who started the W3C working group responsible for scaling down SGML to a form mor e suitable for the Internet. Put succinctly, XML is a meta language that allows you to cre- ate and format your own document markups. With HTML, existing markup is static: and , for example, ar e tightly integrated into the HTML standard and cannot be changed or extended. XML, on the other hand, allows you to cr eate your own markup tags and configure each to your lik- ing — for example, , , , or . Each of these elements can be defined through your own document type definitions and stylesheets and applied to one or more XML documents. XML schemas pro- vide another way to define elements. Thus, it is important to Introduction 1, realize that there are no “corr ect” tags for an XML document, except those you define yourself. While many XML applications currently support Cascading Style Sheets (CSS), a more extensible stylesheet specification exists, called the Extensible Stylesheet Language (XSL). With XSL, you ensure that XML documents are for matted the same way no matter which application or platform they appear on. XSL consists of two parts: XSLT (transfor mations) and XSL-FO ( for matting objects). Transfor mations, as discussed in this book, allow you to work with XSLT and convert XML docu- ments to other formats such as HTML. Formatting objects are described briefly in the section “Formatting Objects.” This book offers a quick overview of XML, as well as some sample applications that allow you to get started in coding. We won’t cover everything about XML. Some XML-related specifications are still in flux as this book goes to print. How- ever, after reading this book, we hope that the components that make up XML will seem a little less foreign.

XML Ter minolog y

Befor e we move further, we need to standardize some termi- nology. An XML document consists of one or more elements. An element is marked with the following form: This is text formatted according to the Body element . This element consists of two tags: an opening tag, which places the name of the element between a less-than sign (<) and a greater-than sign (>), and a closing tag, which is identi- cal except for the forward slash (/) that appears before the element name. Like HTML, the text between the opening and closing tags is considered part of the element and is pro- cessed according to the element’s rules. 2 XML Pocket Reference, Elements can have attributes applied, such as the following: 25.43 Her e, the attribute is specified inside of the opening tag and is called curr ency. It is given a value of Eur o, which is placed inside quotation marks. Attributes are often used to further refine or modify the default meaning of an element. In addition to the standard elements, XML also supports empty elements. An empty element has no text between the opening and closing tags. Hence, both tags can (optionally) be com- bined by placing a forward slash before the closing marker. For example, these elements are identical: Empty elements are often used to add nontextual content to a document or provide additional information to the application that parses the XML. Note that while the closing slash may not be used in single-tag HTML elements, it is mandatory for single-tag XML empty elements.

Unlear ning Bad Habits

Wher eas HTML browsers often ignore simple errors in docu- ments, XML applications are not nearly as forgiving. For the HTML reader, ther e areafew bad habits from which we should dissuade you: XML is case-sensitive Element names must be used exactly as they are defined. For example, and ar e not the same. Attribute values must be in quotation marks You can’t specify an attribute value as , an err or that HTML browsers often overlook. An attribute value must always be inside XML Ter minolog y 3, single or double quotation marks, or else the XML parser will flag it as an error. Her e is the correct way to specify such a tag: A non-empty element must have an opening and a closing tag Each element that specifies an opening tag must have a closing tag that matches it. If it does not, and it is not an empty element, the XML parser generates an error. In other words, you cannot do the following: This is a paragraph. This is another paragraph. Instead, you must have an opening and a closing tag for each paragraph element: This is a paragraph. This is another paragraph. Tags must be nested correctly It is illegal to do the following: This is incorrect The closing tag for the element should be inside the closing tag for the element to match the near- est opening tag and preserve the correct element nesting. It is essential for the application parsing your XML to pro- cess the hierarchy of the elements: This is correct These syntactic rules are the source of many common errors in XML, especially because some of this behavior can be ignor ed by HTML browsers. An XML document adhering to these rules (and a few others that we’ll see later) is said to be well-for med. 4 XML Pocket Reference,

An Overview of an XML Document

Generally, two files are needed by an XML-compliant applica- tion to use XML content: The XML document This file contains the document data, typically tagged with meaningful XML elements, any of which may con- tain attributes. Document Type Definition (DTD) This file specifies rules for how the XML elements, attributes, and other data are defined and logically related in the document. Additionally, another type of file is commonly used to help display XML data: the stylesheet. The stylesheet dictates how document elements should be for- matted when they are displayed. Note that you can apply dif- fer ent stylesheets to the same document, depending on the envir onment, thus changing the document’s appearance with- out affecting any of the underlying data. The separation between content and formatting is an important distinction in XML.

A Simple XML Document

Example 1 shows a simple XML document. Example 1. sample.xml XML Pocket Reference 12.95 Let’s look at this example line by line. In the first line, the code between the is called an XML declaration. This declaration contains special XML Ter minolog y 5, infor mation for the XML processor (the program reading the XML), indicating that this document conforms to Version 1.0 of the XML standard and uses UTF-8 (Unicode optimized for ASCII) encoding. The second line is as follows: This line points out the root element of the document, as well as the DTD validating each of the document elements that appear inside the root element. The root element is the outer- most element in the document that the DTD applies to; it typi- cally denotes the document’s starting and ending point. In this example, the element serves as the root ele- ment of the document. The SYSTEM keyword denotes that the DTD of the document resides in an external file named sam- ple.dtd. On a side note, it is possible to simply embed the DTD in the same file as the XML document. However, this is not recommended for general use because it hampers reuse of DTDs. Following that line is a comment. Comments always begin with . You can write whatever you want inside comments; they are ignor ed by the XML processor. Be awar e that comments, however, cannot come before the XML declaration and cannot appear inside an element tag. For example, this is illegal: > Finally, the elements , , and ar e XML elements we invented. Like most ele- ments in XML, they hold no special significance except for whatever document rules we define for them. Note that these elements look slightly differ ent than those you may have seen pr eviously because we are using namespaces. Each element tag can be divided into two parts. The portion before the colon (:) identifies the tag’s namespace; the portion after the colon identifies the name of the tag itself. 6 XML Pocket Reference, Let’s discuss some XML terminology. The and elements would both consider the element their par ent. In the same manner, ele- ments can be grandpar ents and grandchildr en of other ele- ments. However, we typically abbreviate multiple levels by stating that an element is either an ancestor or a descendant of another element. Namespaces Namespaces wer e cr eated to ensure uniqueness among XML elements. They are not mandatory in XML, but it’s often wise to use them. For example, let’s pretend that the element was simply named . When you think about it, it’s not out of the question that another publisher would create its own element in its own XML documents. If the two publishers combined their documents, resolving a single (cor- rect) definition for the tag would be impossible. When two XML documents containing identical elements from dif ferent sources are merged, those elements are said to col- lide. Namespaces help to avoid element collisions by scoping each tag. In Example 1, we scoped each tag with the OReilly name- space. Namespaces are declar ed using the xmlns:something attribute, where something defines the prefix of the name- space. The attribute value is a unique identifier that differ enti- ates this namespace from all other namespaces; the use of a URI is recommended. In this case, we use the O’Reilly URI http://www.or eilly.com as the default namespace, which should guarantee uniqueness. A namespace declaration can appear as an attribute of any element, in which case the namespace remains inside that element’s opening and closing tags. Here are some examples: ... XML Ter minolog y 7, ... You are allowed to define more than one namespace in the context of an element: ... If you do not specify a name after the xmlns pr efix, the name- space is dubbed the default namespace and is applied to all elements inside the defining element that do not use a name- space prefix of their own. For example: 0-596-00133-9 18231 Her e, the default namespace (repr esented by the URI http://www.or eilly.com) is applied to the elements , , , and . However, it is not applied to the element, which has its own namespace. Finally, you can set the default namespace to an empty string. This ensures that there is no default namespace in use within a specific element:

Learn XML in a Week 10.00

Her e, the and elements have no default names- pace. 8 XML Pocket Reference,

A Simple Document Type Definition (DTD)

Example 2 creates a simple DTD for our XML document. Example 2. sample.dtd The purpose of this DTD is to declare each of the elements used in our XML document. All document-type data is placed inside a construct with the characters . Each construct declares a valid element for our XML document. With the second line, we’ve specified that the element is valid: The parentheses group together the requir ed child elements for the element . In this case, the and elements must be included inside our element tags, and they must appear in the order specified. The elements and ar e ther efor e consider ed childr en of . Likewise, the and elements are declar ed in our DTD: Again, parentheses specify requir ed elements. In this case, they both have a single requir ement, repr esented by #PCDATA. This is shorthand for parsed character data, which means that any characters are allowed, as long as they do not include XML Ter minolog y 9, other element tags or contain the characters < or &, or the sequence ]]>. These characters are forbidden because they could be interpreted as markup. (We’ll see how to get around this shortly.) The line indicates that the attribute of the element defaults to the URI associated with O’Reilly & Associates if no other value is explicitly speci- fied in the element. The XML data shown in Example 1 adheres to the rules of this DTD: it contains an element, which in turn contains an element followed by an element inside it (in that order). Therefor e, if this DTD is applied to the data with a statement, the document is said to be valid.

A Simple XSL Stylesheet

XSL allows developers to describe transformations using XSL Transfor mations (XSLT), which can convert XML documents into XSL Formatting Objects, HTML, or other textual output. As this book goes to print, the XSL Formatting Objects specifi- cation is still changing; therefor e, this book covers only the XSLT portion of XSL. The examples that follow, however, are consistent with the W3C specification. Let’s add a simple XSL stylesheet to the example: 10 XML Pocket Reference, The first thing you might notice when you look at an XSL stylesheet is that it is formatted in the same way as a regular XML document. This is not a coincidence. By design, XSL stylesheets are themselves XML documents, so they must adher e to the same rules as well-formed XML documents. Br eaking down the pieces, you should first note that all XSL elements must be contained in the appropriate outer element. This tells the XSLT processor that it is describing stylesheet information, not XML content itself. After the opening tag, we see an XSLT dir ective to optimize output for HTML. Following that are the rules that will be applied to our XML document, given by the elements (in this case, there is only one rule). Each rule can be further broken down into two items: a tem- plate pattern and a template action. Consider the line: This line forms the template pattern of the stylesheet rule. Her e, the target pattern is the root element, as designated by match="/". The / is shorthand to repr esent the XML document’s root element. The contents of the element: specify the template action that should be perfor med on the target. In this case, we see the empty element located inside a element. When the XSLT pro- cessor transforms the target element, every element inside the root element is surrounded by the tags, which will likely cause the application formatting the output to increase the font size. In our initial XML example, the and elements are both enclosed inside the tags. Therefor e, the font size will be applied to XML Ter minolog y 11, the contents of those tags. Example 3 displays a more realistic example.

Example 3. sample.xsl

Books:

Price: $ + tax
12 XML Pocket Reference, In this example, we target the element, print- ing the word Books: befor e it in a larger font size. In addition, the element applies the default font size to each of its children, and the tag uses a slightly larger font size to display its children, overriding the default size of its parent, . (Of course, neither one has any children elements; they simply have text between their tags in the XML document.) The text Price: $ will precede each of ’s children, and the characters + tax will come after it, formatted accordingly. Her e is the result after we pass sample.xsl thr ough an XSLT pr ocessor: Books:
XML Pocket Reference
Price $12.95 + tax And that’s it: everything needed for a simple XML document! Running the result through an HTML browser, you should see something similar to Figure 1.

XML Reference

Now that you have had a quick taste of working with XML, her e is an overview of the more common rules and constructs of the XML language. XML Reference 13, Figur e 1. Sample XML output

Well-For med XML

These are the rules for a well-formed XML document: • All element attribute values must be in quotation marks. • An element must have both an opening and a closing tag, unless it is an empty element. • If a tag is a standalone empty element, it must contain a closing slash (/) befor e the end of the tag. • All opening and closing element tags must nest correctly. • Isolated markup characters are not allowed in text; < or & must use entity refer ences. In addition, the sequence ]]> must be expressed as ]]> when used as regular text. (Entity refer ences ar e discussed in further detail later.) • Well-for med XML documents without a corresponding DTD must have all attributes of type CDATA by default.

Special Markup

XML uses the following special markup constructs. 14 XML Pocket Reference, Although they are not requir ed to, XML documents typically begin with an XML declaration, which must start with the characters . Attributes include: version The version attribute specifies the correct version of XML requir ed to process the document, which is currently 1.0. This attribute cannot be omitted. encoding The encoding attribute specifies the character encoding used in the document (e.g., UTF-8 or iso-8859-1). UTF-8 and UTF-16 are the only encodings that an XML proces- sor is requir ed to handle. This attribute is optional. standalone The optional standalone attribute specifies whether an exter nal DTD is requir ed to parse the document. The value must be either yes or no (the default). If the value is no or the attribute is not present, a DTD must be declared with an XML instruction. If it is yes, no exter- nal DTD is requir ed. For example: A processing instruction allows developers to place attributes specific to an outside application within the document. Pro- cessing instructions always begin with the characters . For example: 15, You can create your own processing instructions if the XML application processing the document is aware of what the data means and acts accordingly. The instruction allows you to specify a DTD for an XML document. This instruction currently takes one of two for ms:

SYSTEM

The SYSTEM variant specifies the URI location of a DTD for private use in the document. For example:

PUBLIC

The PUBLIC variant is used in situations in which a DTD has been publicized for widespread use. In these cases, the DTD is assigned a unique name, which the XML pro- cessor may use by itself to attempt to retrieve the DTD. If this fails, the URI is used: Public DTDs follow a specific naming convention. See the XML specification for details on naming public DTDs. You can place comments anywhere in an XML document, except within element tags or before the initial XML process- ing instructions. Comments in an XML document always start 16 XML Pocket Reference, with the characters . In addition, they may not include double hyphens within the comment. The contents of the comment are ignor ed by the XML processor. For example: 2000 49.95

CDATA

You can define special sections of character data, or CDATA, which the XML processor does not attempt to interpret as markup. Anything included inside a CDATA section is treated as plain text. CDATA sections begin with the characters . For example: tag of documents 5 & 6: "Sales" and "Profit and Loss". Luckily, the XML processor wont apply rules of formatting to these sentences! ]]> Note that entity refer ences inside a CDATA section will not be expanded.

Element and Attribute Rules

An element is either bound by its start and end tags or is an empty element. Elements can contain text, other elements, or a combination of both. For example: Elements can contain text, other elements, or a combination. For example, a chapter might contain a title and multiple paragraphs, and a paragraph might contain text and emphasis elements. CDATA 17, An element name must start with a letter or an underscore. It can then have any number of letters, numbers, hyphens, peri- ods, or underscores in its name. Elements are case-sensitive : , , and ar e consider ed thr ee dif ferent ele- ment types. Element type names may not start with the string xml in any variation of upper- or lowercase. Names beginning with xml ar e reserved for special uses by the W3C XML Working Gr oup. Colons (:) are per mitted in element type names only for specifying namespaces; otherwise, colons are forbidden. For example: Example Comment Legal <_Budget> Legal Illegal: has a space <205Para> Illegal: starts with number Illegal: contains @ character Illegal: starts with xml Element type names can also include accented Roman charac- ters, letters from other alphabets (e.g., Cyrillic, Greek, Hebr ew, Arabic, Thai, Hiragana, Katakana, or Devanagari), and ideograms from the Chinese, Japanese, and Korean lan- guages. Valid element type names can therefor e include , , , and , plus a number of others our publishing system isn’t equipped to handle. If you use a DTD, the content of an element is constrained by its DTD declaration. Better XML applications inform you which elements and attributes can appear inside a specific element. Otherwise, you should check the element declara- tion in the DTD to determine the exact semantics. 18 XML Pocket Reference, Attributes describe additional information about an element. They always consist of a name and a value, as follows: The attribute value is always quoted, using either single or double quotes. Attribute names are subject to the same restric- tions as element type names.

XML Reserved Attributes

The following are reserved attributes in XML. xml:lang xml:lang="iso_639_identifier" The xml:lang attribute can be used on any element. Its value indicates the language of the body of the element. This is use- ful in a multilingual context. For example, you might have: Hello Bonjour This format allows you to display one element or the other, depending on the user’s language prefer ence. The syntax of the xml:lang value is defined by ISO-639. A two- letter language code is optionally followed by a hyphen and a two-letter country code. Traditionally, the language is given in lowercase and the country in uppercase (and for safety, this rule should be followed), but processors are expected to use the values in a case-insensitive manner. In addition, ISO-3166 provides extensions for nonstandardized languages or language variants. Valid xml:lang values include notations such as en, en-US, en-UK, en-cockney, i-navajo, and x-minbari. xml:lang 19, xml:space xml:space="default|preserve" The xml:space attribute indicates whether any whitespace inside the element is significant and should not be altered by the XML processor. The attribute can take one of two enumer- ated values: pr eserve The XML application preserves all whitespace (newlines, spaces, and tabs) present within the element. default The XML processor uses its default processing rules when deciding to preserve or discard the whitespace inside the element. You should set xml:space to pr eserve only if you want an ele- ment to behave like the HTML element, such as when it documents source code.

Entity and Character References

Entity refer ences ar e used as substitutions for specific charac- ters (or any string substitution) in XML. A common use for entity refer ences is to denote document symbols that might otherwise be mistaken for markup by an XML processor. XML pr edefines five entity refer ences for you, which are substitu- tions for basic markup symbols. However, you can define as many entity refer ences as you like in your own DTD. (See the next section.) Entity refer ences always begin with an ampersand (&) and end with a semicolon (;). They cannot appear inside a CDATA section but can be used anywhere else. Predefined entities in XML are shown in the following table: 20 XML Pocket Reference, Entity Char Notes & & Do not use inside processing instructions. < < Use inside attribute values quoted with ". > > Use after ]] in normal text and inside processing instructions. " " Use inside attribute values quoted with ". ' Use inside attribute values quoted with . In addition, you can provide character refer ences for Unicode characters with a numeric character refer ence. A decimal char- acter refer ence consists of the string &#, followed by the deci- mal number repr esenting the character, and finally, a semicolon (;). For hexadecimal character refer ences, the string &#x is followed first by the hexadecimal number repr esenting the character and then a semicolon. For example, to repr esent the copyright character, you could use either of the following lines: This document is © 2001 by OReilly and Assoc. This document is © 2001 by OReilly and Assoc. The character refer ence is replaced with the “circled-C” (©) copyright character when the document is formatted.

Document Type Definitions

A DTD specifies how elements inside an XML document should relate to each other. It also provides grammar rules for the document and each of its elements. A document adhering to the XML specifications and the rules outlined by its DTD is consider ed to be valid. (Don’t confuse this with a well-formed document, which adheres only to the XML syntax rules out- lined earlier.) Document Type Definitions 21,

Element Declarations

You must declare each of the elements that appear inside your XML document within your DTD. You can do so with the declaration, which uses this format: This declares an XML element and an associated rule called a content model, which relates the element logically to the XML document. The element name should not include < > charac- ters. An element name must start with a letter or an under- scor e. After that, it can have any number of letters, numbers, hyphens, periods, or underscores in its name. Element names may not start with the string xml in any variation of upper- or lowercase. You can use a colon in element names only if you use namespaces; otherwise, it is forbidden.

ANY and PCDATA

The simplest element declaration states that between the opening and closing tags of the element, anything can appear: The ANY keyword allows you to include other valid tags and general character data within the element. However, you may want to specify a situation where you want only general characters to appear. This type of data is better known as parsed character data, or PCDATA. You can specify that an element contain only PCDATA with a declaration such as the following: Remember, this declaration means that any character data that is not an element can appear between the element tags. 22 XML Pocket Reference, Ther efor e, it’s legal to write the following in your XML docu- ment: However, the following is illegal with the previous PCDATA declaration: On the other hand, you may want to specify that another ele- ment must appear between the two tags specified. You can do this by placing the name of the element in the parenthe- ses. The following two rules state that a element must contain a Robert Eckstein with Michel Casabianca The previous example showed how to specify both elements in a declaration. You can just as easily specify that one or the other appear (but not both) by using the vertical bar (|): This declaration states that either a The Extensible Stylesheet Language 37,

Working with XML

Starting XML

If you havent used XML, then ...

If you look carefully, you can see a predefined hierarchy that remains from the source content to the resulting content. To ventureaguess, the element probably maps to the , ,

This is the first section of the text.

This is the second section of the text.

To transfor m this into HTML, we use the following template:

Templates and Patter ns 41

,

Let’s look at how this stylesheet works. As processing begins, the current node is the document root (not to be confused with the element, which is its only descendant), des- ignated as / (like the root directory in a Unix filesystem). The XSLT processor searches the stylesheet for a template with a matching pattern in any children of the root. Only the first template matches (). The first tem- plate is then applied to the node, which becomes the current node. The transformation then takes place: the , ,

Sample text

First section

This is the first section of the text.

Second section

This is the second section of the text.

As you will see later, patter ns ar e XPath expressions for locat- ing nodes in an XML document. This example includes very basic patterns, and we have only scratched the surface of what can be done with templates. More infor mation will be found in the section “XPath.” In addition, the element has a mode attribute that can be used for conditional processing. An template is tested only when it is called by an element that matches its mode. This functionality can be used to change the processing applied to a node dynamically.

Parameters and Variables

To finish up with templates, we should discuss the name attribute. These templates are similar to functions and can be called explicitly with the ele- ment, where name matches the name of the template you want to invoke. When you call a template, you can pass it Templates and Patter ns 43, parameters. Let’s assume we wrote a template to add a footer containing the date the document was last updated. We could call the template, passing it the date of the last update this way: The call-template declar es and uses the parameter this way: today

---

Last update: The parameter is declared within the template with the element whose content (today) pro- vides a default value. We can use this parameter inside the template by placing a dollar sign ($) in front of the name. We can also declare variables using the element, where the content of the element gives the variable its value. The variables are used like parameters by placing a dollar sign ($) in front of their names. Note that even though they are called variables, their values are con- stant and cannot be changed. A variable’s visibility also depends on where it is declar ed. A variable that is declared dir ectly as a child element of can be used thr oughout the stylesheet as a global variable. Conversely, when a variable is declared in the body of the template, it is visible only within that same template.

Stylesheet Import and Rules of Precedence

Stylesheets may be imported using the element, where the hr ef attribute indicates the path of the stylesheet to be imported. Note that an statement must be a direct child of the element. 44 XML Pocket Reference, Imported stylesheet templates have lower precedence than templates contained in the file into which they are incorpo- rated. This means that if two templates compete for the pro- cessing of an element, the template of the original file takes pr ecedence over the template of the imported file. Thus, imported templates can be overridden by redefining them in the original stylesheet. The rules of precedence can be changed in two ways: • The element can be used to give imported templates precedence in the body of a tem- plate. • The priority="level" attribute can be given in the opening tag. Therefor e, the level of precedence defined for the template is a real number. The larger the number, the more precedence the template has. A value of +1 ensures that the template has precedence over other templates for which no precedence has been defined (0 is the default). A value of –1 guarantees that any other unprioritized template has precedence. Priority values overrule import precedence. Stylesheets can also be included in an XSL file with the element. The precedence of an included template is the same as that of the calling stylesheet templates.

Loops and Tests

To process an entire list of elements at the same time, use the loop. For example, the following template adds a table of contents to our example:
Templates and Patter ns 45, The body of this loop processes all the elements that are childr en of the current node. Within the loop, we output the value of each section’s title attribute, followed by a line break. XSL also defines elements that can be used for tests: The body of this element is executed only if the test expr ession is true. This element allows for several possible conditions. It is comparable to switch in the C and Java languages. The element is illustrated as follows: The body of the first element whose test expr ession is true will be executed. The XSL processor then moves on to the instructions following the closing element tag, skipping the remaining tests. The element is optional; its body is exe- cuted only if none of the preceding elements were exe- cuted.

Numbering Elements

XSL provides a simple method for numbering elements with the element. Let’s assume we want to number the sections and paragraphs in a document. We can do this by 46 XML Pocket Reference, adding the following code before displaying the section titles and the content of the paragraphs: - The result is: 1 - First section 1.1 - This is the first section of text. 2 - Second section 2.1 - This is the second section of text. The count attribute decides which elements should be num- ber ed. Elements must be separated by a |. The level attribute specifies the level of numbering and may take one of three string values: single, multiple, or any. single tells the processor to number only one level. In this case, paragraph numbers will not indicate the section number. multiple numbers several levels, meaning that the first part of the paragraph number is the section number in our previous example. any tells the pro- cessor to add numbering without regard to level. Here, the numbers of the sections and paragraphs are consecutive. The format attribute indicates the style of numbering. Letters or numbers may be used, with a separator in between. The letters may be A or a (for alphabetical numbering in upper- or lowercase), I or i (for numbering in upper- or lowercase Roman numerals), or 1 (for numbering in Arabic numerals). For example, to number sections with Roman numerals and paragraphs with lowercase letters, use this format attribute: format="I.a"

Output Method

An XSLT processor can be instructed to produce a specific type of output with the element. For example, causes the processor to execute certain transformations needed for the resulting document to Templates and Patter ns 47, be valid HTML. Specifically, it transforms empty tags. For example, the XML

---

tag is converted to the HTML

---

tag (for horizontal rules) without a closing slash. It is also possible to indicate an XML output method (method="xml"), where the XSLT processor adds the standard XML header (). It may seem strange to pro- duce an XML document from another XML document, yet it is often helpful to convert a document from one DTD to a valid document for another DTD. Thus, XSLT is also a language for inter-DTD conversions. Finally, you can specify a text output method (method="text") to produce pure text. XSLT has built-in outputs for XML, HTML, and text, but some processors may support other out- put methods (sometimes identified by URLs). We should point out that when you choose the HTML or XML output method, the processor may remove or rearrange whitespace in blocks of text (spaces, tabs, and carriage retur ns). However, ther e ar e several solutions for preserving whitespace. The first is to indicate the list of elements to be pr eserved in the element. The second is to add the indent="no" attribute to the element to indicate that you do not want the resulting document to be indented. We should point out, however, that spaces are no longer preserved in elements where content is written as-is in the resulting document. No indent- ing is produced for the text output method.

XSLT Elements

The following list is an enumeration of XSLT elements. 48 XML Pocket Reference, This styles the current node and each of its children using the imported stylesheet rules, ignoring those in the stylesheet that per formed the import. Note that the rules don’t apply to the curr ent node’s siblings or ancestors. This specifies that the immediate children (default) or the selected nodes of the source element should be processed further. For example: This example processes the children of the selected

element after applying a bold tag. The optional select attribute deter mines which nodes should be processed:

---

---

---

This example processes only specific children of the selected

element. In this case, the first target is a element that is a descendant of a element that has defined an indent attribute. The second target is a ele- ment that is the direct child of a element that has defined an indent attribute. The optional mode attribute causes only templates with a matching mode to be applied. 49, ... This adds an attribute with the given name to an element in the result tree. Only one attribute with a particular name can be added to a specific element. The contents of the element form the value of the attribute: Moby Dick This is about a whale This creates the following element in the result tree: This is about a whale The optional namespace attribute specifies a namespace for the new attribute. This allows the naming of a collection of attributes that can be applied to elements. The following example creates an attribute set for images and applies them with a template: 0 120 60 50 XML Pocket Reference,

The use-attribute-sets option allows you to include a list of

other attribute sets in the one being defined. ...

This function invokes a template by its name. It is possible to

specify parameters in the body of this element. The following example calls the template image while passing the parameters width and height: 120 60 ...

The element, in conjunction with the elements

and , offers the ability to perfor m multiple condition tests. For example: Start Here: Then Read: 51, This example matches against each of the qualifying It was a dark and stormy night... Marcus found himself sleeping... Note there are two siblings in the document. Let’s assume we want to provide an HTML numbered list for each

This is a paragraph in the first section. More information about XLink can be found at the W3C .

This is a paragraph in the second section. You should go read the first section first.

The first link states that the text “the W3C” is linked to the URL http://www.w3.or g. How does the browser know? Simple. XPointer and XLink 87, An HTML browser knows that every element is a link because the browser has to handle only one document type. In XML, you can make up your own element type names, so the br owser needs some way of identifying links. XLink provides the xlink:type attribute for link identification. A br owser knows it has found a simple link when any element sets the xlink:type attribute to a value of simple. A simple link is like a link in HTML—one-way and beginning at the point in the document where it occurs. (In fact, HTML links can be recast as XLinks with minimal effort.) In other words, the con- tent of the link element can be selected for traversal at the other end. Returning to the source document is left to the browser. Once an XLink processor has found a simple link, it looks for other attributes that it knows: xlink:hr ef This attribute is deliberately named to be familiar to any- one who’s used the Web before. Its value is the URI of the other end of the link; it can refer to an entire docu- ment or to a point or element within that document. If the target is in an XML document, the fragment part of the URI is an XPointer. This attribute must be specified, since without it, the link is meaningless. It is an error not to include it. xlink:r ole This describes the nature of the object at the other end of the link. XLink doesn’t predefine any roles; you might use a small set to distinguish differ ent types of links in your documents, such as cross-r efer ences, additional reading, and contact information. A stylesheet might take a dif ferent action (such as presenting the link in a differ- ent color) based on the role, but the application won’t do anything automatically. 88 XML Pocket Reference, xlink:title A title for the resource at the other end of the link can be pr ovided, identical to HTML’s title attribute for the element. A GUI browser might display the title as a tool tip; an aural browser might read the title when the user pauses at the link before selecting it. A stylesheet might also make use of the information, perhaps to build a list of refer ences for a document. xlink:show This attribute suggests what to do when the link is tra- versed. It can take the following values: embed The content at the other end of the link should be retrieved and displayed where the link is. An exam- ple of this behavior in HTML is the element, whose target is usually displayed within the docu- ment. replace When the link is activated, the browser should replace the current view with a view of the resource targeted by the link. This is what happens with the element in HTML: the new page replaces the curr ent one. new The browser should somehow create a new context, if possible, such as opening a new window. other This value specifies behavior that isn’t described by the other values. It is up to the application to deter- mine how to display the link. none This specifies no behavior. You do not need to give a value for this attribute. Remember that a link primarily asserts a relationship between data; behavior is best left to a stylesheet. So XPointer and XLink 89, unless the behavior is paramount (as it might be in some cases of embed, it is best not to use this attribute. xlink:actuate The second of the behavioral attributes specifies when the link should be activated. It can take the following val- ues: onRequest The application waits until the user requests that the link be followed, as the element in HTML does. onLoad The link should be followed immediately when it is encounter ed by the application; this is what most HTML browsers do with elements, unless the user has turned off image loading. other The link is activated by other means, not specified by XLink. This is usually defined by other markup in the document. none This indicates no information about the activation of the link and may be used when the link has no cur- rent meaningful target or action.

Building Extended Links

XLink has much more to offer, including links to multiple doc- uments and links between disparate documents (where the XML document creating the links does not even contain any links). Extended links An XLink application recognizes extended links by the pres- ence of an xlink:type="extended" attribute that distinguishes it fr om a simple link (such as those used in HTML). An extended link may have semantic attributes (xlink:r ole and xlink:title) that function just as they do for a simple link. 90 XML Pocket Reference, In addition, an extended link may be one of four types as defined by its xlink:type="type" attribute: resour ce Supplies the local resource for the link (generally the text used to materialize the link) locator Supplies a URI for the remote document participating in the link ar c Supplies a description of the potential paths among the documents participating in the extended link title Supplies a label for the link Consider this example of an extended link supplying an XML bibliography: XML Bibliography The extended link will probably be repr esented graphically as a menu with an entry for each element, except for the last one (arc), which has no graphical repr esentation. However, the graphical repr esentation of the link is the application’s responsibility. Let’s look at the role of each of the elements. XPointer and XLink 91,

Resource elements

Resource elements, which include the xlink:type="r esource" attribute, define a local resource that participates in a link. An extended link that includes a resource is considered inline because the file in which it is found participates in a link. A link that has no resource is called out-of-line. XLink applications use the following attributes: Attr ibute Descr iption xlink:type resource (fixed value) xlink:r ole Role of this resource in the link (used by arcs) xlink:title Text used by the XLink application to repr esent this resource In our example, the element supplies the text to be dis- played to repr esent the link.

Locator elements

Locator elements have the xlink:type="locator" attribute and use a URI to point to a remote resource. XLink applications use the following locator attributes: Attr ibute Descr iption xlink:type locator (fixed value) xlink:hr ef URI of the resource pointed to xlink:role Role resource pointed to (used by arcs) xlink:title Text the XLink application uses to graphically repr esent the resource In our example, we use two kinds of locators: those with a role of book that point to documents describing publications, and those with a role of author that point to a biography. Her e, the role is important because it tells the XLink applica- tion the potential traversals among resources. 92 XML Pocket Reference,

Arc elements

Arc elements have the xlink:type="arc" attribute and determine the potential traversals among resources, as well as the behav- ior of the XLink application during such traversals. Arc ele- ments may be repr esented as arrows in a diagram, linking resources that participate in an extended link. XLink applications use the following arc attributes: Attr ibute Descr iption xlink:type arc (fixed value) xlink:fr om Indicates the role of the resource of the originating arc xlink:to Indicates the role of the resource of the destination arc xlink:show new, replace, embed, other, or none: tells the XLink application how to display the resource to which the arc is pointing xlink:actuate onLoad, onRequest, other, or none: tells the XLink appli- cation the circumstances under which the traversal is made xlink:arcr ole Role of the arc xlink:title Text that may be used to repr esent the arc The values of the xlink:show and xlink:actuate attributes have the same meaning as they do with simple links. Let’s go back to our example of the bibliography, where we could define the following arc: The arc creates a link from the text displayed by the navigator (a resource where the role is text) to the descriptive page from the book (remote resource where the role is book). It also indicates that the page must be displayed in a new window (xlink:show="new") when the user clicks the mouse button (xlink:actuate="onRequest"). XPointer and XLink 93, To include the author’s biography in the card for the book, we will define the following arc: xlink:show="embed" indicates that the destination of the arc (the biography) must be included in the card for the book (origin of the arc) and that the destination must be included when the book page is loaded (xlink:actuate="onLoad"). Finally, we need to indicate that the absence of the xlink:fr om or xlink:to attribute indicates that the origin or destination of the arc corr esponds to all the roles defined in the link. Thus, the arc in our example () authorizes all the traversals possible among the resources of the extended link.

Title elements

Elements with a type of