xsl:attribute-set


The <xsl:attribute-set> element is a top-level XSLT declaration used to define a named set of attribute names and values. The resulting attribute set can be applied as a whole to any output element, providing a way of defining commonly used sets of attributes in a single place.

Changes in 2.0

None.

Format

 <xsl:attribute-set   name = qname   use-attribute-sets? = qnames>   <!-- Content: xsl:attribute* --> </xsl:attribute-set> 

Position

<xsl:attribute-set> is a declaration, so it must always occur as a child of the <xsl:stylesheet> element.

Attributes

Name

Value

Meaning

name

mandatory

QName

The name of the attribute set

use-attribute-sets

optional

Whitespace-separated list of QNames

The names of other attribute sets to be incorporated into this attribute set

Content

Zero or more <xsl:attribute> elements.

Effect

Named attribute sets provide a capability similar to named styles in CSS.

The name attribute is mandatory, and defines the name of the attribute set. It must be a lexical QName: a name with or without a namespace prefix. If the name uses a prefix, it must refer to a namespace declaration that is in scope at this point in the stylesheet, and as usual it is the namespace URI rather than the prefix that is used when matching names. The name does not need to be unique; if there are several attribute sets with the same name, they are effectively merged.

The use-attribute-sets attribute is optional. It is used to build up one attribute set from a number of others. If present, its value must be a whitespace-separated list of tokens each of which is a valid lexical QName that refers to another named attribute set in the stylesheet. For example:

  <xsl:attribute-set name="table-cell"   use-attribute-sets="small-font gray-background centered"/>   <xsl:attribute-set name="small-font">   <xsl:attribute name="font-name">Verdana</xsl:attribute>   <xsl:attribute name="font-size">6pt</xsl:attribute>   </xsl:attribute-set>   <xsl:attribute-set name="gray-background">   <xsl:attribute name="bgcolor">#xBBBBBB</xsl:attribute>   </xsl:attribute-set>   <xsl:attribute-set name="centered">   <xsl:attribute name="align">center</xsl:attribute>   </xsl:attribute-set>  

The references must not be circular: If A refers to B, then B must not refer directly or indirectly to A. The order is significant: Specifying a list of named attribute sets is equivalent to copying the <xsl:attribute> elements that they contain, in order, to the beginning of the list of <xsl:attribute> elements contained in this <xsl:attribute-set> element.

If several attribute sets have the same name, they are merged. If this merging finds two attributes with the same name, then the one in the attribute set with higher import precedence will take precedence. Import precedence is discussed under <xsl:import> on page 312. If they both have the same precedence, the XSLT processor has the option of using the one that came later in the stylesheet, or reporting an error. (Note that it isn't generally possible to detect this error at compile time, because the attribute names can be calculated at runtime using an attribute value template.)

The order in which this merging process takes place can affect the outcome. When use-attribute-sets appears on an <xsl:attribute-set> or <xsl:copy> element, or xsl:use-attribute-sets on a literal result element, it is expanded to create a sequence of attribute nodes. This is essentially done by a recursive process:

  • To expand an [xsl:] use-attribute-sets attribute, process all the attribute set names in the order they are listed.

  • To process an attribute set name, expand each of the <xsl:attribute-set> declarations having that name, taking them in increasing order of import precedence, and within each import precedence, in declaration order. For definitions of import precedence and declaration order, see <xsl:import> on page 312.

  • To expand an <xsl:attribute-set> declaration, first expand its use-attribute-sets attribute (if any) by a recursive application of these rules, then add the attribute nodes generated by evaluating the contained <xsl:attribute> instructions to the result sequence.

It's best to illustrate this by an example. Suppose you have the following attribute-set definition:

  <xsl:attribute-set name="B" use-attribute-sets="A1 A2">   <xsl:attribute name="p">percy</xsl:attribute>   <xsl:attribute name="q">queenie</xsl:attribute>   <xsl:attribute name="r">rory</xsl:attribute>   </xsl:attribute-set>  

If there is more than one attribute set named A1 these must be merged first (taking import precedence into account), and then the merged contents must be substituted into B .

Then the same process is applied to A2 . The referenced attribute sets are expanded in order. The attributes that result from expanding A1 are output before those that result from expanding A2 . This means that attributes from A2 take priority over those from A1 if there is a clash .

In turn , the attribute set B must be fully expanded before it is merged with any other attribute set called B . That is, the processor must replace the references to attribute sets A1 and A2 with an equivalent list of <xsl:attribute> instructions before it merges this B with other attribute sets of the same name.

When B is expanded, the attributes derived from A1 and A2 will be output before the attributes p , q , and r , so if expanding A1 and A2 generates any attributes called p , q , and r , these will be overwritten by the values specified within B ( percy , queenie , and rory ).

Normally when describing the processing model for XSLT instructions, we distinguish between the process of generating a sequence of nodes, and attaching these nodes to a tree. Eliminating attribute nodes with duplicate names is technically part of the second process. However, attribute sets can only be expanded from instructions that create elements, so the resulting attributes will always be attached to an element. This means we can treat it as if generating the attribute nodes and attaching them to an element are done as a single process.

In general, duplicate attribute names or attribute set names do not cause an error. If several attributes have the same name, the one that comes last (in the order produced by the merging rules given above) will take precedence. There is one situation only that is defined as an error, namely if two different attribute-sets with the same name and the same import precedence both produce attributes with the same name. Another way of saying this is: It is an error if the final result depends on the relative positions of the attribute-set definitions in the stylesheet. However, the processor is allowed to recover from this error by taking the definitions in stylesheet order, and in this particular case it's so much easier to take the recovery action than to detect the error that I suspect this is what most processors are likely to do.

Usage

The most common use of attribute sets is to define packages of attributes that constitute a display style, for example a collection of attributes for a font or for a table.

A named attribute set is used by referring to it in the use-attribute-sets attribute of the <xsl:element> or <xsl:copy> element, or in the xsl:use-attribute-sets attribute of a literal result element, or, of course, in the use-attribute-sets attribute of another <xsl:attribute-set> . The first three cases all create an element node, and have the effect of adding the attributes in the named attribute set to that element node. Any attributes added implicitly from a named attribute set can be overridden by attribute nodes added explicitly by the invoking code.

An attribute set is not simply a textual macro. The attributes contained in the attribute set each have a select attribute or sequence constructor to define the value, and although this will often return a fixed value, it may also, for example, declare variables or invoke other XSLT instructions such as <xsl:call-template> and <xsl:apply-templates> .

The rules for the scope of variables, described under <xsl:variable> on page 471, are the same as anywhere else, and are defined by the position of the definitions in the source stylesheet document. This means that the only way to parameterize the values of attributes in a named attribute set is by reference to global variables and parameters: There is no other way of passing parameters to an attribute set. However, the value of the generated attributes may depend on the context in the source document. The context is not changed when the attribute set is used, so the current item ( «. » ) and current position and size are exactly the same as in the calling instruction.

Examples

The following example defines an attribute set designed for generated HTML <table> elements:

  <xsl:attribute-set name="full-width-table">   <xsl:attribute name="border">1</xsl:attribute>   <xsl:attribute name="cellpadding">3</xsl:attribute>   <xsl:attribute name="cellspacing">0</xsl:attribute>   <xsl:attribute name="width">100%</xsl:attribute>   </xsl:attribute-set>  

This attribute set can be used when generating an output element, as follows :

  <table xsl:use-attribute-sets="full-width-table">   <tr>...</tr>   </table>  

This produces the following output:

  <table border="1" cellpadding="3" cellspacing="0" width="100%">   <tr>...</tr>   </table>  

Alternatively it is possible to use the attribute set while overriding some of its definitions and adding others, for example:

  <table border="2" rules="cols" xsl:use-attribute-sets="full-width-table">   <tr>...</tr>   </table>  

The output now becomes:

  <table border="2" rules="cols" cellpadding="3" cellspacing="0" width="100%">   <tr>...</tr>   </table>  

If this combination of attributes is also used repeatedly, it could be defined as an attribute set in its own right, as:

  <xsl:attribute-set name="ruled-table" use-attribute-set="full-width-table">   <xsl:attribute name="border">2</xsl:attribute>   <xsl:attribute name="rules">cols</xsl:attribute>   </xsl:attribute-set>  

Then this new attribute set could also be invoked by name from a literal result element, an <xsl:element> instruction, or an <xsl:copy> instruction.

The next example shows that the values of the attributes in an attribute set need not be constants.

Using an Attribute Set for Numbering
start example

Suppose you want to copy an XML file containing a poem, but with the <line> elements in the poem output in the form <line number="3" of="18"> within the stanza.

Source

The source file poem.xml has the following structure (I'm only showing the first stanza):

  <?xml version="1.0"?>   <poem>   <author>Rupert Brooke</author>   <date>1912</date>   <title>Song</title>   <stanza>   <line>And suddenly the wind comes soft,</line>   <line>And Spring is here again;</line>   <line>And the hawthorn quickens with buds of green</line>   <line>And my heart with buds of pain.</line>   </stanza>   </poem>  

Stylesheet

The stylesheet number-lines.xsl copies everything unchanged except the <line> elements, which are copied with a named attribute set:

  <xsl:transform   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"   version="2.0"   >   <xsl:strip-space elements="*"/>   <xsl:output method="xml" indent="yes"/>   <xsl:template match="*">   <xsl:copy>   <xsl:apply-templates/>   </xsl:copy>   </xsl:template>   <xsl:template match="line">   <xsl:copy use-attribute-sets="sequence">   <xsl:apply-templates/>   </xsl:copy>   </xsl:template>   <xsl:attribute-set name="sequence">   <xsl:attribute name="number" select="position()"/>   <xsl:attribute name="of" select="last()"/>   </xsl:attribute-set>   </xsl:transfom>  

Output

The output (again showing only the first stanza) looks like this:

  <poem>   <author>Rupert Brooke</author>   <date>1912</date>   <title>Song</title>   <stanza>   <line number="1" of="4">And suddenly the wind comes soft,</line>   <line number="2" of="4">And Spring is here again;</line>   <line number="3" of="4">And the hawthorn quickens with   buds of green</line>   <line number="4" of="4">And my heart with buds of pain.</line>   </stanza>   </poem>  
end example
 

See Also

  • <xsl:element> on page 260

  • <xsl:copy> on page 240

Literal Result Elements in Chapter 3, page 106




XSLT 2.0 Programmer's Reference
NetBeansв„ў IDE Field Guide: Developing Desktop, Web, Enterprise, and Mobile Applications (2nd Edition)
ISBN: 764569090
EAN: 2147483647
Year: 2003
Pages: 324

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net