p:add-attribute (3.1)

Add (or replace) an attribute on a set of elements.

Summary
Description
Examples
- Adding/replacing an attribute
Additional details
Errors raised
Reference information

Summary

<p:declare-step type="p:add-attribute">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="xml html" sequence="false"/>
  <option name="attribute-name" as="xs:QName" required="true"/>
  <option name="attribute-value" as="xs:string" required="true"/>
  <option name="match" as="xs:string" required="false" select="'/*'"/>
</p:declare-step>

The p:add-attribute step adds (or replaces) an attribute. This is done for the element(s) matched by the match option.

Ports:

Type	Port	Primary?	Content types	Seq?	Description
`input`	`source`	`true`	`xml html`	`false`	The document to add (or replace) the attribute on.
`output`	`result`	`true`	`xml html`	`false`	The resulting document.

Options:

Name	Type	Req?	Default	Description
`attribute-name`	`xs:QName`	`true`		The name of the attribute. This may contain a namespace specification.
`attribute-value`	`xs:string`	`true`		The value of the attribute.
`match`	`xs:string` (XSLT selection pattern)	`false`	`/*`	The XSLT match pattern that selects the element(s) to add (or replace) the attribute 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.

Name

Type

Req?

Default

Description

attribute-name

xs:QName

true

The name of the attribute. This may contain a namespace specification.

attribute-value

xs:string

true

The value of the attribute.

match

xs:string (XSLT selection pattern)

false

/*

The XSLT match pattern that selects the element(s) to add (or replace) the attribute 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:add-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 the name given in the attribute-name option, an attribute with this name and a value as given in the attribute-value option is added to it.
- If a selected element already has such an attribute, its value is replaced with the value given in the attribute-value option.
The resulting document appears on its result port.

The p:add-attribute step can only set a single attribute. The p:set-attributes step can be used to set multiple attributes at once.

Examples

Adding/replacing an attribute

This example adds a type="special" attribute to all <text> elements. One of the input <text> elements already has such an 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:add-attribute match="text" attribute-name="type" attribute-value="special"/>

</p:declare-step>

Result document:

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

Additional details

p:add-attribute 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 the selection pattern matches a node which is not an element.
`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:add-attribute 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:add-attribute step can be found here.

The p:add-attribute step is part of categories:

The p:add-attribute step is also present in version: 3.0.