Previous Up Next


p:insert

p:insert — Inserts content into a document.

Synopsis

<p:declare-step type="p:insert">
     <p:input port="source" primary="true"/>
     <p:input port="insertion" sequence="true"/>
     <p:output port="result"/>
     <p:option name="match" select="'/*'"/>                        <!-- XSLTMatchPattern -->
     <p:option name="position" required="true"/>                   <!-- "first-child" | "last-child" | "before" | "after" -->
</p:declare-step>

Description

The p:insert step inserts content into a document at the positions identified by the match pattern.

Multiple matches are allowed, in which case multiple copies of the insertion documents will occur. If no elements match, then the document is unchanged.

The value of the position option determines how the insertionis performed:

first-child

The insertion is made as the first child of the matched element.

last-child

The insertion is made as the last child of the matched element.

before

The insertion is made before the matched node.

after

The insertion is made after the matched node.

In the case of first-child and last-child, it is an error if the matched node is not an element (because the other kinds of nodes don't have children).

Errors

Error Description
err:C0023 Occurs if the pattern matches anything other than element, text, processing-instruction, or comment nodes.
err:C0025 Occurs if the match pattern matches anything other than an element node and the value of the position option is “first-child” or “last-child”.

Examples

The p:insert step inserts one document into another. You select where and at what position to make the insertion, before the matched location:

  1 <p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
                version="1.0">
    
      <p:insert match="/doc/div" position="before">
  5     <p:input port="insertion">
          <p:inline>
            <p>Hello world.</p>
          </p:inline>
        </p:input>
 10   </p:insert>
    </p:pipeline>
Input Output
1 <doc>
<div>
<p>Play.</p>
</div>
5 </doc>
 
1 <doc>
<p>Hello world.</p>
<div>
<p>Play.</p>
5 </div>
</doc>

After the matched location:

  1 <p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
                version="1.0">
    
      <p:insert match="/doc/div" position="after">
  5     <p:input port="insertion">
          <p:inline>
            <p>Goodbye, cruel world.</p>
          </p:inline>
        </p:input>
 10   </p:insert>
    </p:pipeline>
Input Output
1 <doc>
<div>
<p>Play.</p>
</div>
5 </doc>
 
1 <doc>
<div>
<p>Play.</p>
</div>
5 <p>Goodbye, cruel world.</p>
</doc>

As the first child:

  1 <p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
                version="1.0">
    
      <p:insert match="/doc/div" position="first-child">
  5     <p:input port="insertion">
          <p:inline>
            <p>Work.</p>
          </p:inline>
          <p:inline>
 10         <p>Sleep.</p>
          </p:inline>
          <p:inline>
            <p>Eat.</p>
          </p:inline>
 15     </p:input>
      </p:insert>
    </p:pipeline>
Input Output
1 <doc>
<div>
<p>Play.</p>
</div>
5 </doc>
 
1 <doc>
<div>
<p>Work.</p>
<p>Sleep.</p>
5 <p>Eat.</p>
<p>Play.</p>
</div>
</doc>

Or as the last child:

  1 <p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
                version="1.0">
    
      <p:insert match="/doc/div" position="last-child">
  5     <p:input port="insertion">
          <p:inline>
            <p>Work.</p>
          </p:inline>
          <p:inline>
 10         <p>Sleep.</p>
          </p:inline>
          <p:inline>
            <p>Eat.</p>
          </p:inline>
 15     </p:input>
      </p:insert>
    </p:pipeline>
Input Output
1 <doc>
<div>
<p>Play.</p>
</div>
5 </doc>
 
1 <doc>
<div>
<p>Play.</p>
<p>Work.</p>
5 <p>Sleep.</p>
<p>Eat.</p>
</div>
</doc>