xsl:processing-instruction

The <xsl:processing-instruction> instruction is used to write a processing instruction node to the result sequence.

Changes in 2.0

A select attribute has been added.

Format

 <xsl:processing-instruction   name = { NCName }   select? = expression>   <!-- Content: sequence-constructor --> </xsl:processing-instruction> 

Position

<xsl:processing-instruction> is an instruction. It is always used as part of a sequence constructor.

Attributes

Name	Value	Meaning
name mandatory	Attribute value template returning an NCName	The name (target) of the generated processing instruction
select optional	Expression	Used to compute the string value (the data part) of the generated processing instruction

Content

If the select attribute is present, the element must be empty. If the select attribute is absent, the element may contain a sequence constructor.

Effect

The name of the generated processing instruction (in XML terms, the PITarget ) is determined by the name attribute. This may be expressed as an attribute value template. The name must be valid as a PITarget as defined in the XML specification, and XSLT imposes the additional rule that it must be a valid NCName, as defined in the XML Namespaces Recommendation. This means it must be an XML Name that doesn't contain a colon (to make it an NCName ) and that isn't the name «xml » in any mixture of upper and lower case (to make it a PITarget ).

The specification is quite explicit that <xsl:processing-instruction> cannot be used to generate an XML declaration at the start of the output file. The XML declaration looks like a processing instruction, but technically it isn't one; and the ban on using the name «xml » makes this quite explicit. The XML declaration in the output file is generated automatically by the XSLT processor, and can be controlled to a limited extent using the <xsl:output> element.

The string value of the processing instruction (which corresponds to the data part of a processing instruction in XML terms) is generated using either the select attribute or the contained sequence constructor. If neither is present, the string value of the processing instruction node will be a zero-length string.

The space that separates the PITarget from the data is produced automatically when a processing instruction node is serialized. It is not present in the tree model.

The sequence produced by evaluating the select attribute or the contained sequence constructor is first atomized, and each item in the atomized sequence is then converted to a string. If the select attribute is present, these strings are concatenated with a single space between adjacent strings; if a sequence constructor is used, they are concatenated with no separator. The resulting string forms the string value of the new processing instruction. For more details of this process, including error conditions that can arise, see <xsl:attribute> on page 211, which works in exactly the same way.

The resulting string value must not contain the string «?> », which terminates a processing instruction. Implementations are allowed to trap the «?> » and replace it by «?> » (with an embedded space); unfortunately they are also allowed to report this as an error, so if you want your stylesheet to be portable, you need to make sure this condition can't happen.

The data part of a processing instruction cannot contain character references such as «&#x20A4; », so it is an error to output any characters that can't be represented directly in the chosen character encoding of the output file. Some processing instructions may accept data that looks like a character reference, but this is an application-level convention, not something defined in the XML standard, so the XSLT processor will never generate such a reference automatically.

Usage

Use this instruction when you want to output a processing instruction.

Processing instructions are not widely used in most XML applications, so you will probably not need to use this instruction very often. They are used even less in HTML, though HTML 4.0 does recommend that any vendor-specific extensions should be implemented this way. In HTML the terminator for a processing instruction is «> » rather than «?> », and this difference is handled automatically during serialization by the HTML output method; see <xsl:output> on page 375.

Note that you cannot generate a processing instruction in the output by writing a processing instruction in the stylesheet. Processing instructions in the stylesheet are ignored completely. You can, however, use <xsl:copy> or <xsl:copy-of > to copy processing instructions from the source tree to the result tree.

Examples

The following example outputs an <?xml-stylesheet?> processing instruction at the start of the output file:

  <xsl:processing-instruction name="xml-stylesheet">   <xsl:text>href="housestyle.css" type="text/css"</xsl:text>   </xsl:processing-instruction>  

The generated output is:

  <?xml-stylesheet href="housestyle.css" type="text/css"?>  

Writing an XSLT stylesheet that produces an XML document that itself refers to a CSS stylesheet isn't such a crazy thing to do as it might seem. It often makes sense to do the first stage of processing of an XML file on the server, and the second stage on the client (in other words, in the browser). The first stage will extract the data that users want to see-and, most importantly, remove any information they are not allowed to see. The second stage applies the detailed rules for output formatting. The second stage can often be done just as easily with CSS as with XSLT, because anything CSS can't cope with, such as adding or reordering textual content, can be done in the first stage with XSLT.

One point to watch out for in generating an <?xml-stylesheet?> processing instruction, and which might well apply to other processing instructions, is the use of pseudoattributes and pseudo character and entity references. The text «href="housestyle.css" » in the above example is designed to look like an XML attribute, but it is not actually an XML attribute; it is purely part of the processing instruction data. It is parsed by the application, not by the XML parser. As it is not a true XML attribute, you cannot generate it as an attribute node using the <xsl:attribute> instruction; rather, it is generated as text.

The rules for the <?xml-stylesheet?> processing instruction are defined in a short W3C Recommendation called Associating Style Sheets with XML Documents, available at http://www.w3.org/TR/xml-stylesheet . In addition to defining the data part of this processing instruction in the form of pseudoattributes, the rules also allow the use of numeric character references such as «&#x20A4; » and predefined entity references such as «&gt; » and «&amp; » . Again, these are not true character references and entity references that the XML parser will recognize, and as a result they will not be generated by the XSLT processor either. If you want to include «&#x20A4; » as part of the data of the processing instruction, you can write, for example,

  <xsl:processing-instruction name="xml-stylesheet">   <xsl:text>href="housestyle.css" type="text/css" </xsl:text>   <xsl:text>title="A title containing &amp;#x20A4;" </xsl:text>   </xsl:processing-instruction>  

Another way of generating this processing instruction, which might be more suitable if the contents are highly variable, is to write a general template that takes the required information as a parameter. This parameter might be supplied in the form of an element:

  <pi-data name="xml-stylesheet">   <href>housestyle.css</href>   <type>text/css</type>   <title>a title</title>   </pi-data>  

and the processing instruction might be generated by the template:

  <xsl:template name="make-pi">   <xsl:param name="pi-data" required="yes"/>   <xsl:processing-instruction name="{$pi-data/@name}"   select="for $att in $pi-data/* return   concat(name($att), '=&quot;', string($att), '&quot;')"/>   </xsl:template>  

This does not attempt to deal with the problems that arise if there are special characters in the data that need to be escaped. Note that the space that is needed between pseudoattributes is generated automatically, because each pseudoattribute is produced as one item in the result of the select attribute.