p:label-elements (3.1) 

Labels elements by adding an attribute.

Summary

<p:declare-step type="p:label-elements">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="xml html" sequence="true"/>
  <option name="attribute" as="xs:QName" required="false" select="'xml:id'"/>
  <option name="label" as="xs:string" required="false" select="'concat("_",$p:index)'"/>
  <option name="match" as="xs:string" required="false" select="'*'"/>
  <option name="replace" as="xs:boolean" required="false" select="true()"/>
</p:declare-step>

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

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

xml html

false

The document to label.

result

output

true

xml html

true

The resulting document.

Options:

Name

Type

Req?

Default

Description

attribute

xs:QName

false

xml:id

The name of the attribute that contains the label

label

xs:string (XPath expression)

false

concat("_",$p:index)

An XPath expression that computes the value for the label.

This expression is evaluated with a matched element as context item. A variable $p:index is available that holds the index (sequence number) of the match.

match

xs:string (XSLT selection pattern)

false

*

An XSLT match expression that matches the elements to label.

replace

xs:boolean

false

true

Whether to replace existing attributes. If this value is false, existing attributes with the same name as mentioned in the attribute option are left in peace. If true (default), they are replaced.

Description

The p:label-elements step performs the following actions:

  • It takes the document appearing on its source port and finds all the elements matched by the expression in the match option.

  • For every matched element, it evaluates the expression in the label option. This is done with the matched element as context item (so accessible using the dot . operator). An additional variable $p:index is available that holds the index (sequence number) of the match.

  • If the replace option is true (default), an attribute is added/replaced on the matched element. The name of this attribute is in the attribute option. Its value comes from the evaluation of the expression in the label option.

    If the replace is false, an existing attribute with the same name is not replaced.

  • After all matches are handled, the resulting document appears on the result port.

Examples

Basic usage

The following example uses all the default values of the options of p:label-elements. This means an attribute called xml:id is added to every element. Values become an underscore followed by the index of the element. Existing xml:id attributes are replaced.

Source document:

<movies>
   <movie title="Apocalypse now"/>
   <movie title="Dune" xml:id="1234"/>
</movies>

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:label-elements/>

</p:declare-step>

Result document:

<movies xml:id="_1">
   <movie title="Apocalypse now" xml:id="_2"/>
   <movie title="Dune" xml:id="_3"/>
</movies>

To make this a little more interesting, let’s label the <movie> elements only and compute their label based on a generated identifier (using generate-id()) and the movie’s name (replacing whitespace using replace()). We keep existing xml:id attributes. The source document is the same as in the previous example.

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:label-elements match="movie" label="generate-id() || '_' || replace(@title, '\s', '-')" replace="false"/>

</p:declare-step>

Result document:

<movies>
   <movie title="Apocalypse now" xml:id="id2135690571_Apocalypse-now"/>
   <movie title="Dune" xml:id="1234"/>
</movies>

Additional details

  • p:label-elements preserves all document-properties of the document(s) appearing on its source port.

Errors raised

Error code

Description

XC0023

It is a dynamic error if the selection pattern matches a wrong type of node.

Reference information

This description of the p:label-elements step is for XProc version: 3.1. This is a required step (an XProc 3.1 processor must support this).

The formal specification for the p:label-elements step can be found here.

The p:label-elements step is part of categories:

The p:label-elements step is also present in version: 3.0.