Previous Up Next

p:add-attribute

p:add-attribute — Adds a single attribute to the selected element (or elements).

Synopsis

<p:declare-step type="p:add-attribute">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>                      <!-- XSLTMatchPattern -->
     <p:option name="attribute-name" required="true"/>             <!-- QName -->
     <p:option name="attribute-prefix"/>                           <!-- NCName -->
     <p:option name="attribute-namespace"/>                        <!-- anyURI -->
     <p:option name="attribute-value" required="true"/>            <!-- string -->
</p:declare-step>

Description

The p:add-attribute step adds a single attribute to any matching element in the source document. The name of the attribute is computed from the attribute-name, attribute-prefix, and attribute-namespace options. The attribute-value option specifies its value.

If the attribute-name value contains a colon, then its value is interpreted as a QName and there must be an in-scope namespace declaration for that prefix in the pipeline document. It is an error in this case to specify either an attribute-prefix or attribute-namespace.

If you specify an attribute-namespace, you must also specify an attribute-prefix. In XML, attributes cannot be in a namespace unless they have a prefix.

If you attempt to add an attribute to an element that already has an attribute with that name, the attribute will remain on that element but will have the value specified in attribute-value.

Recall that in XML, namespace declarations are not attributes. You cannot add “attributes” named xmlns or xmlns:somename with p:add-attribute. However, if you add an attribute that appears in a namespace, the processor will add a namespace declaration for that namespace automatically, if one is needed.

If an attribute named xml:base is added or changed, the base URI of the element will be amended accordingly.

Related Steps

The p:add-attribute step uses the same attribute value everywhere that it inserts an attribute. If you need to vary the value depending on where it's inserted, p:label-elements may provide the flexibility that you need.

If you want to set multiple attributes on the same element (or elements), p:set-attributes can be used to set them all at once.

Errors

Error Description
err:C0023 Occurs if the match pattern matches anything other than an element.
err:D0034 Occurs if the attribute-name contains a colon and you attempt to specify either an attribute-prefix or attribute-namespace.
err:C0059 Occurs if any attempt is made to construct a namespace declaration using the p:add-attribute step.

Examples

This pipeline adds a class attribute to any HTML div that contains a pre.

  1 <p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
                xmlns:h="http://www.w3.org/1999/xhtml"
                version="1.0">
    
  5   <p:add-attribute match="h:div[h:pre]"
                       attribute-name="class"
                       attribute-value="example"/>
    </p:pipeline>
Input Output
1 <html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Some Document</title>
</head>
5 <body>
<div>
<p>Some text.</p>
<div>
<pre>Some example pre text.</pre>
10 </div>
</div>
<div>
<pre>Some more example pre text.</pre>
</div>
15 </body>
</html>
 
1 <html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Some Document</title>
</head>
5 <body>
<div>
<p>Some text.</p>
<div class="example">
<pre>Some example pre text.</pre>
10 </div>
</div>
<div class="example">
<pre>Some more example pre text.</pre>
</div>
15 </body>
</html>

The p:add-attribute step replaces attributes if they already exist:

Input Output
1 <html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Some Other Document</title>
</head>
5 <body>
<div class="original value">
<pre>Some example pre text.</pre>
</div>
</body>
10 </html>
 
1 <html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Some Other Document</title>
</head>
5 <body>
<div class="example">
<pre>Some example pre text.</pre>
</div>
</body>
10 </html>