Previous Up Next


p:label-elements

p:label-elements — Adds an attribute (often xml:id) to matching elements.

Synopsis

<p:declare-step type="p:label-elements">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="attribute" select="'xml:id'"/>                <!-- QName -->
     <p:option name="attribute-prefix"/>                           <!-- NCName -->
     <p:option name="attribute-namespace"/>                        <!-- anyURI -->
     <p:option name="label" select="'concat("_",$p:index)'"/>      <!-- XPathExpression -->
     <p:option name="match" select="'*'"/>                         <!-- XSLTMatchPattern -->
     <p:option name="replace" select="'true'"/>                    <!-- boolean -->
</p:declare-step>

Description

The p:label-elements step generates a label for each matched element and stores that label in the specified attribute.

On each element that matches the specified match option, the value of the label option is interpreted as an XPath expression and evaluated with the context node set to the matched element. The string value of the result of that evaluation is the label.

The name of the attribute is computed from the attribute, attribute-prefix and attribute-namespace options.

An attribute with that name is added to the element using the label as its value. If the replace option is “true”, then any existing attribute with that name will be replaced, otherwise the existing attribute is left unchanged.

The XPath expression in the label option may refer to a special variable, p:index. The value of p:index is an integer, incremented for each matching element. On the first match, it will have the value “1”, on the second, “2”, etc.

Related Steps

The p:label-elements step computes a new value for the attribute each time it's inserted. If you only want to add a literal value, you might find p:add-attribute simpler. To set multiple (literal) values, see p:set-attributes.

Errors

Error Description
err:D0034 Occurs if the lexical value of the specified name contains a colon and either the attribute-prefix or attribute-namespace options are specified.
err:C0023 Occurs if the match pattern expression matches anything other than an element node.

Examples

The p:label-elements step is most often used to add xml:id attributes (or ID attributes with some other name) to elements. By default, it does this for all elements, replacing any existing values:

  1 <p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
                version="1.0">
    
      <p:label-elements/>
  5 </p:pipeline>
Input Output
1 <doc>
<p>One</p>
<p xml:id="second">Two</p>
<p>Three</p>
5 </doc>
 
1 <doc xml:id="_1">
<p xml:id="_2">One</p>
<p xml:id="_3">Two</p>
<p xml:id="_4">Three</p>
5 </doc>

You can be more selective by changing match and other options.

  1 <p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
                version="1.0">
    
      <p:label-elements match="p" replace="false"
  5                     label="concat(&#34;ID-&#34;,$p:index)"/>
    </p:pipeline>
Input Output
1 <doc>
<p>One</p>
<p xml:id="second">Two</p>
<p>Three</p>
5 </doc>
 
1 <doc>
<p xml:id="ID-1">One</p>
<p xml:id="second">Two</p>
<p xml:id="ID-2">Three</p>
5 </doc>