p:insert (3.1) 

Inserts one document into another.

Summary

<p:declare-step type="p:insert">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="xml html text" sequence="false"/>
  <input port="insertion" primary="false" content-types="xml html text" sequence="true"/>
  <option name="match" as="xs:string" required="false" select="'/*'"/>
  <option name="position" as="xs:string" required="false" select="'after'" values="('first-child','last-child','before','after')"/>
</p:declare-step>

The p:insert step inserts the document(s) appearing on the insertion port into the document appearing on the source port.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

xml html

false

The base document to insert in.

result

output

true

xml html text

false

The resulting document

insertion

input

false

xml html text

true

The document(s) to insert.

Options:

Name

Type

Req?

Default

Description

match

xs:string (XSLT selection pattern)

false

/*

The XSLT match pattern that indicates where to insert.

position

xs:string

false

after

Where to insert, relative to what was matched by the match option. See The position option.

Description

The p:insert step can be used to insert one or more documents into another. It searches the document appearing on its source port for matches as indicated by the match option. It then inserts the document(s) appearing on its insertion port, as indicated by the position option. The result of the merge is emitted on the result port.

The position option

The position option tells p:insert where to insert the document(s) in the insertion port, relative to what was matched by the match option. There are 4 possible values:

Value

Description

first-child

The insertion is made as the first child of what was matched.

last-child

The insertion is made as the last child of what was matched.

before

The insertion is made directly before what was matched. In other words: the insertion becomes the immediate preceding sibling of the match.

after

The insertion is made directly after what was matched. In other words: the insertion becomes the immediate following sibling of the match.

Examples

Basic usage

This simple example shows how to insert a (for the example, fixed) document into another, as a first child of a match:

Source document:

<things>
   <thing id="123">USB adapter</thing>
   <thing id="456">Joystick</thing>
   <thing id="789">Mouse</thing>
</things>

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:insert position="first-child">
    <p:with-input port="insertion">
      <thing id="999">Keyboard</thing>
    </p:with-input>
  </p:insert>

</p:declare-step>

Result document:

<things>
   <thing id="999">Keyboard</thing>
   <thing id="123">USB adapter</thing>
   <thing id="456">Joystick</thing>
   <thing id="789">Mouse</thing>
</things>

Or, using the same source document, as the its last child:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:insert position="last-child">
    <p:with-input port="insertion">
      <thing id="999">Keyboard</thing>
    </p:with-input>
  </p:insert>

</p:declare-step>

Result document:

<things>
   <thing id="123">USB adapter</thing>
   <thing id="456">Joystick</thing>
   <thing id="789">Mouse</thing>
   <thing id="999">Keyboard</thing>
</things>

The following example, again using the same source document, inserts a new thing using the before value of the position option:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:insert match="/things/thing[@id eq '456']" position="before">
    <p:with-input port="insertion">
      <thing id="999">Keyboard</thing>
    </p:with-input>
  </p:insert>

</p:declare-step>

Result document:

<things>
   <thing id="123">USB adapter</thing>
   <thing id="999">Keyboard</thing>
   <thing id="456">Joystick</thing>
   <thing id="789">Mouse</thing>
</things>

Inserting multiple times

The following example shows that when the match option matches multiple times, the insertion occurs multiple times:

Source document:

<things>
   <thing id="123">
      <name>USB adapter</name>
   </thing>
   <thing id="456">
      <name>Joystick</name>
   </thing>
   <thing id="789">
      <name>Mouse</name>
   </thing>
</things>

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:insert match="thing" position="last-child">
    <p:with-input port="insertion">
      <description>TBD</description>
    </p:with-input>
  </p:insert>

</p:declare-step>

Result document:

<things>
   <thing id="123">
      <name>USB adapter</name>
      <description>TBD</description>
   </thing>
   <thing id="456">
      <name>Joystick</name>
      <description>TBD</description>
   </thing>
   <thing id="789">
      <name>Mouse</name>
      <description>TBD</description>
   </thing>
</things>

Inserting text

Starting XProc version 3.1, it is also possible to insert text into a document using the p:insert step:

Source document:

<things>
   <thing id="123">USB adapter</thing>
   <thing id="456">Joystick</thing>
   <thing id="789">Mouse</thing>
</things>

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:insert match="/things/thing[@id eq '456']" position="last-child">
    <p:with-input port="insertion">
      <p:inline content-type="text/plain"> (special!)</p:inline>
    </p:with-input>
  </p:insert>

</p:declare-step>

Result document:

<things>
   <thing id="123">USB adapter</thing>
   <thing id="456">Joystick (special!)</thing>
   <thing id="789">Mouse</thing>
</things>

Additional details

  • It must be possible to insert the document(s) at the indicated location(s). For instance, the match option cannot match an attribute and you cannot insert something before or after the document node. If this happens, an appropriate error is raised.

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

    The document-properties of the document(s) appearing on its insertion port are not used/preserved.

  • If the match option matches multiple times, multiple instances of the document(s) on the insertion port are inserted. See Inserting multiple times.

  • If the insertion port receives no document(s), nothing happens. The step will act as a p:identity step.

Errors raised

Error code

Description

XC0023

It is a dynamic error if the selection pattern matches a wrong type of node.

XC0024

It is a dynamic error if the selection pattern matches a document node and the value of the position is “before” or “after”.

XC0025

It is a dynamic error if the selection pattern matches anything other than an element or a document node and the value of the position option is “first-child” or “last-child”.

Reference information

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

The p:insert step is part of categories:

The p:insert step is also present in version: 3.0.