Labels elements by adding an attribute.
<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 |
---|---|---|---|---|---|
|
|
|
|
| The document to label. |
|
|
|
|
| The resulting document. |
Options:
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.
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="id1466663486_Apocalypse-now"/> <movie title="Dune" xml:id="1234"/> </movies>
p:label-elements
preserves all document-properties of the document(s) appearing on its source
port.
Error code | Description |
---|---|
It is a dynamic error if the selection pattern matches a wrong type of node. |
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.