xsl:document


The <xsl:document> instruction creates a document node and adds it to the result sequence. The most likely reason for using it is to perform document-level validation on a temporary tree.

Changes in 2.0

This instruction is new in XSLT 2.0. It should not be confused with the <xsl:document> instruction described in the abandoned XSLT 1.1 working draft, which was the precursor to the <xsl:result-document> instruction in XSLT 2.0. The document created by <xsl:document> is a temporary document that becomes available for further processing within the stylesheet; the document created by <xsl:result-document> is a final output from the transformation.

Format

 <xsl:document   validation? = "strict"  "lax"  "preserve"  "strip"   type? = qname>   <!-- Content: sequence-constructor --> </xsl:document> 

Position

<xsl:document> is used as an instruction within a sequence constructor.

Attributes

Name

Value

Meaning

validation

optional

«strict » , «lax » , «preserve » , or «skip »

Indicates whether and how the document should be subjected to schema validation

type

optional

lexical QName

Identifies a type declaration (either a built-in type, or a user -defined type imported from a schema) against which the outermost element of the new document is to be validated

The type and validation attributes are mutually exclusive: If one is present, the other must be absent.

Content

A sequence constructor.

Effect

The following sections describe firstly, how the content of the document node is constructed , and secondly how document-level validation works.

The Content of the Document

The <xsl:document> instruction creates a new document node. The content of the document is constructed by evaluating the sequence constructor within the <xsl:document> element.

The child nodes of the new document node are constructed in a process that is very similar to that used for constructing the content of an element node, described under <xsl:element> on page 263. There are differences, however, because unlike an element node, a document node cannot have attribute or namespace nodes.

Although the XML specification requires a well- formed document to contain exactly one element node, optionally preceded or followed by comments and processing instructions, this restriction is not carried forward into the XPath data model. In this model, a document node can contain any sequence of elements, text nodes, comments, and processing instructions (including an empty sequence) as its children. In fact, a document node can have any content that is allowed for an element node, except for the namespaces and attributes.

The process of forming the content of the document node is described below.

The first stage is to evaluate the sequence constructor contained in the <xsl:document> instruction (or in any other instruction that is being used to create a new document node, for example, <xsl:copy> , <xsl:message> , <xsl:result-document> , or <xsl:variable> ). The sequence constructor is a sequence of instructions, and as its name implies, the result of evaluating these instructions is a sequence of items. Usually these values will all be newly constructed nodes but the sequence might also contain atomic values and/or references to existing nodes.

The way that the instructions in the sequence constructor are evaluated is described in the rules for each instruction; the items produced by each instruction are concatenated together (in the order in which the instructions appear in the stylesheet) to produce the final result sequence.

The second stage of the process is to use the result sequence delivered by evaluating the sequence constructor to create the content of the new document node. This process works as follows :

  1. If there are any atomic values in the sequence, they are converted to strings using the XPath casting rules. Errors may arise if the value has a data type that cannot always be cast to a string, specifically xs:NOTATION and xs:QName .

  2. Any sequence of adjacent strings is converted to a single text node, using a single space as a separator between adjacent strings.

  3. If there is a document node in the sequence, then it is replaced in the sequence by its children (this may produce an arbitrary sequence of elements, text nodes, comments, and processing instructions).

  4. Adjacent text nodes within the sequence are combined into a single text node, without any space separator. Zero-length text nodes are removed completely.

It is an error if the resulting sequence contains an attribute or namespace node. The processor has the choice of reporting this error, or ignoring these nodes.

Finally, the nodes in the sequence are attached to the document node as its children. Officially, this involves making a deep copy of each node: This is because nodes in the data model are immutable, so you cannot change the parent of an existing node. In practice, making a copy at this stage is very rarely necessary, because in most cases the node being attached has only just been created and will never be used independently of its new parent. The only case where it is necessary is where the result sequence contains references to existing nodes, which can be produced using the <xsl:sequence> instruction:

  <xsl:document>   <xsl:sequence select="//email[@date=current-date()]"/>   </xsl:document>  

Even in this case, copying the nodes can be avoided if the result tree is to be immediately serialized.

Validating and Annotating the Document

The validation and type attributes control whether and how the new document is validated. They are available only if you are using a schema-aware processor. As usual, validation has two effects: It triggers a failure if the result document is invalid according to the schema, and it creates type annotations on the nodes in the tree.

The validation attribute has the same four values as on other elements: «strip » , «preserve » , «strict » , and «lax » . If the validation attribute is not specified, then the default is provided by the default-validation attribute on the <xsl:stylesheet> element, which in turn defaults to «strip » .

  • «strip » removes all type annotations, replacing them with xs:untyped for elements and xs:untypedAtomic for attributes.

  • «preserve » leaves the type annotations as they are, determined by the validation and type attributes on the instructions that created individual elements and attributes.

  • «strict » and «lax » firstly check that the tree represents a well-formed XML document, that is, that the children of the document node comprise exactly one element node, no text nodes, and any number of comments and processing instructions. If not, a failure is reported . Then the top-level element node (the document element) is validated against the schema definitions, with the difference being that «lax » validates an element only if a schema definition for that element can be found, while «strict » fails if no declaration of this element can be found.

  • Validation of a document node works in the same way as validation of individual elements but with one important exception: Identity constraints defined in the schema are checked when validation is done at the document level, but not when it is done at element level. Identity constraints are those defined by the <xs:key> , <xs:keyref> , and <xs:unique> elements in XML Schema, as well as checking that xs:ID values are unique and that xs:IDREF and xs:IDREFS values reference an ID value somewhere in the document.

The «type » attribute gives the required type of the document element (not the document node). For example, if «type="mf:invoiceType" » is specified, then the single element child of the document node is validated against the schema type «mf:invoiceType » .

Usage and Examples

The most likely reason for using <xsl:document> is to invoke validation of a temporary tree.

It is possible to perform element-level validation of the document element in a tree without using <xsl:document> , for example by writing:

  <xsl:variable name="temp">   <invoice xsl:type="mf:invoiceType">   <xsl:call-template name="build-invoice"/>   </invoice>   </xsl:variable>  

However, this does not perform document-level validation: It doesn't check the <xs:key> and <xs:keyref> constraints defined in the schema, for example. To perform these extra checks, it is necessary to write the <xsl:document> instruction explicitly:

  <xsl:variable name="temp">   <xsl:document type="mf:invoiceType">   <invoice>   <xsl:call-template name="build-invoice"/>   </invoice>   </xsl:document>   </xsl:variable>  

There are certain other situations where <xsl:document> might be needed. For example, this is the only way of producing a sequence containing several new document nodes. It is also necessary if you want the value of a variable, or the default value of a parameter, to be a document node, and you also want to use the «as » attribute of <xsl:variable> or <xsl:param> to define the type of the variable, for example «as="document(element(*, mf:invoiceType))" » .

See Also

<xsl:result-document> on page 414

<xsl:message> on page 343




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