stm

Home > Books > NetKernel API and Services Reference > Accessor Listing > XML Accessors > stm

Module

The stm accessor is exported by the urn:org:ten60:netkernel:ext:xml:ura module. Import this module to gain access to the accessor.

Syntax

URI

active:stm

Argument	Rules	Description
operand	Mandatory Fragment OK	the resource to which operations are applied
operator	Mandatory	the resource containing the stm operations
param	Optional Fragment OK	a resource to pass parameter subsitutions into stm operations

Example Usage

DPML

<instr>
  <type>stm</type>
  <operand>foo.xml</operand>
  <operator>stm.xml</operator>
  <param>par.xml</param>
  <target>this:response</target>
</instr>

NetKernel Foundation API

req=context.createSubRequest("active:stm");
req.addArgument("operand", [resource representation, aspect, or URI] );
req.addArgument("operator", [resource representation, aspect, or URI] );
result=context.issueSubRequest(req);

Purpose

The stm accessor is used to perform Simple Tree Manipulation operations on the operand document. STM is a language that performs XML operations at XPath locations in a processed document.

STM concentrates on tree manipulation operations only. Unlike XSLT, whose operations are defined in the transform domain, STM operations are defined in the document domain. This frequently has advantages.

STM operations are iterative with respect to the xpath target in the operand. That is if the xpath reference is multivalued the STM operation will be applied to all targets.

STM operations can incorporate substitutions from an optional param document. A <stm:param xpath="xxxx"> child element of an stm instruction is replaced by the fragment of the param document referenced by the xpath attribute of the param element.

The combination of STM and XSLT is very useful. For example STM template filling for XSLT generated templates is a common pattern, where XSLT is used to transform a document into a template and STM used to dynamically substitute documents into the template - this document was created using this pattern.

STM operations

stm:copy Used to copy a document fragment into the operand document

stm:replace Used to replace a document fragment in the operand document with child fragment

stm:get-fragment Used to obtain a document fragment from the operand document

stm:create-path Generate and attach a document fragment from an xpath expression at a given location

stm:append Used to append a document fragment to the operand document at a given location

stm:insert-before Used to insert a document fragment to the operand document before a given location

stm:insert-after Used to insert a document fragment to the operand document before a given location

stm:set Used to set a text element or attribute at a given location to a given value

stm:delete Used to delete a text element or attribute at a given location

stm:regex Used to return a regex results document of all fragments matching a regex expression

stm:apply-ns Apply a namespace to the subtree below a given location

stm:remove-ns Remove a namespace from the subtree below a given location

stm:replace-for-text A matched element is replaced by a text node.

stm:rename Rename an element or attribute retaining all children

stm:append-text Append text to an element or attributes text value

A detailed tutorial of the STM language is available here

Example

Replace an Element

<idoc>
  <seq>
    <instr>
      <type>stm</type>
      <operand>vardoc.xml</operand>
      <operator>
        <stm:group xmlns:stm="http://1060.org/stm">
          <stm:replace xpath="/a/b[1]/c">
            <x>
              <y>zebra</y>
            </x>
          </stm:replace>
        </stm:group>
      </operator>
      <target>this:response</target>
    </instr>
  </seq>
</idoc>

An example of using stm to replace an element in the operand document with a document fragment. Here document vardoc.xml contains a tree a/b/c. This operation replaces the <c> element of the first <b> element with the fragment x/y enclosed by the stm:replace operation.

Delete Elements and Generate new Sub-Tree

<idoc>
  <seq>
    <instr>
      <type>stm</type>
      <operand>vardoc.xml</operand>
      <operator>
        <stm:group xmlns:stm="http://1060.org/stm">
          <stm:delete xpath="/a/b" />
          <stm:create-path newpath="d/e/f" xpath="/a" />
        </stm:group>
      </operator>
      <target>this:response</target>
    </instr>
  </seq>
</idoc>

An example of using stm to delete all <b> elements below <a>. Then create a new sub-tree d/e/f attached below <a>.

References

STM By Example