p:set-attributes (3.1) 

Add (or replace) attributes on a set of elements.

Summary

<p:declare-step type="p:set-attributes">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="xml html" sequence="false"/>
  <option name="attributes" as="map(xs:QName, xs:anyAtomicType)" required="true"/>
  <option name="match" as="xs:string" required="false" select="'/*'"/>
</p:declare-step>

The p:set-attributes step adds (or replaces) attributes as specified in the attributes option map. This is done for the element(s) matched by the match option.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

xml html

false

The document to add (or replace) the attributes on.

result

output

true

xml html

false

The resulting document.

Options:

Name

Type

Req?

Default

Description

attributes

map(xs:QName, xs:anyAtomicType)

true

 

A map with entries (attribute name, attribute value).

If this map is empty, nothing will happen and the step acts as a p:identity step.

match

xs:string (XSLT selection pattern)

false

/*

The XSLT match pattern that selects the element(s) to add (or replace) the attributes on. If not specified, the root element is used.

This must be an XSLT match pattern that matches an element. If it matches any other kind of node, error XC0023 is raised.

Description

The p:set-attribute step:

  • Takes the document appearing on its source port.

  • Processes the elements that match the pattern in the match option:

    • If a selected element does not contain an attribute with a name that is a key in the attributes option map, an attribute with this name and a value as associated in the map is added to it.

    • If a selected element already has such an attribute, its value is replaced with the value as associated in the map.

  • The resulting document appears on its result port.

If you just want to set a single attribute, you can also use the p:add-attribute step.

Examples

Adding/replacing multiple attributes

This example adds the type="special" and a level="2" attributes to all <text> elements. One of the input <text> elements already has a type attribute, but with a different value. This existing attribute is replaced.

Source document:

<texts>
   <text>Hello there!</text>
   <text>This is funny…</text>
   <text type="normal">And that's normal.</text>
</texts>

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:set-attributes match="text" attributes="map{'type': 'special', 'level': 2}"/>

</p:declare-step>

Result document:

<texts>
   <text type="special" level="2">Hello there!</text>
   <text type="special" level="2">This is funny…</text>
   <text type="special" level="2">And that's normal.</text>
</texts>

Additional details

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

  • If an attribute called xml:base is added or changed, the base URI of the element is updated accordingly. See also category Base URI related.

  • You cannot use this step to add or change a namespace declaration. Attempting to do so will result in error XC0059.

    Note, however, that it is possible to add an attribute whose namespace is not in scope on the element it is added to. The XProc namespace fixup mechanism will take care of handling this and add the appropriate namespace declarations.

Errors raised

Error code

Description

XC0023

It is a dynamic error if that pattern matches anything other than element nodes.

XC0059

It is a dynamic error if the QName value in the attribute-name option uses the prefix “xmlns” or any other prefix that resolves to the namespace name http://www.w3.org/2000/xmlns/.

Reference information

This description of the p:set-attributes 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:set-attributes step can be found here.

The p:set-attributes step is part of categories:

The p:set-attributes step is also present in version: 3.0.