XML Typehandler plugin reference

Wiki
1

XML Typehandler Functions Reference

A complete guide to all built-in functions for manipulating XML documents in the XML Typehandler plug-in.

Contents

GetOrCreateNodeAction

Description

Adds the provided attributes under a specified node. If the node does not exist, it is created based on the given configuration.

Behavior

  • Locates the parent node based on parentxpath. If none is provided, an exception is thrown.
  • Finds or creates the child node by combining nodename + nodematch.
  • If no matching child is found, nodename is appended to the parent.
  • Attributes are applied. If overwrite = false and attribute exists, nothing changes. Otherwise values are updated or new attributes added.

Example

Input XML:

<catalog>
  <book id="bk101" />
</catalog>

Params:

parentxpath = "catalog"
nodename = "book"
nodematch = "@id='bk101'"
attrs = [[<"name","category">,<"value","tech">,<"overwrite",false>],
         [<"name","id">,<"value","bk202">,<"overwrite",false>]]

Result:

<catalog>
  <book id="bk101" category="tech" />
</catalog>

Parameters

xml: XmlDocument (required)
parentxpath: string (optional)
nodename: string (required)
nodematch: string (optional)
attrs: list of 3-tuples (name: string, value: mixed, overwrite: bool) (optional)

InsertXmlAfterAction

Description

Inserts a given XML fragment after a node identified by an XPath expression.

Behavior

Checks XPath. Inserts fragment after each matched node. Errors if node type disallows insertion.

Example

Input:

<catalog>
  <book id="bk101" />
  <book id="bk102" />
</catalog>

Params:

node_to_insert_after = "/catalog/book[@id='bk101']"
xml_to_insert = <book id="bk201" />

Result:

<catalog>
  <book id="bk101" />
  <book id="bk201" />
  <book id="bk102" />
</catalog>

Parameters

xml: XmlDocument (required)
node_to_insert_after: string (required)
xml_to_insert: XmlDocument (required)
error_on_no_match: bool (optional, default false)

LoadAction

Description

Parses an XML document from either a file path, uploaded file, or raw XML string.

Example

Input:

xmlstring = "<catalog><book id='bk101'/></catalog>"

Result:

success = true
xml = parsed document with root <catalog>

Parameters

xmlfile: mixed (optional) — file path or uploaded file
xmlstring: string (optional)

RemoveNodeAction

Description

Removes all XML nodes matching the provided XPath.

Example

Input:

<catalog>
  <book id="bk101" />
  <book id="bk102" />
</catalog>

Param:

node_to_remove = "/catalog/book[@id='bk102']"

Result:

<catalog>
  <book id="bk101" />
</catalog>

Parameters

xml: XmlDocument (required)
node_to_remove: string (required)
error_on_no_match: bool (optional)

ReplaceInnerTextAction

Description

Replaces the inner text of XML nodes matched by XPath expressions.

Example

Input:

<catalog><book id="bk101">Old Title</book></catalog>

Param:

replace = [["/catalog/book[@id='bk101']", "New Title"]]

Result:

<catalog><book id="bk101">New Title</book></catalog>

Parameters

xml: XmlDocument (required)
replace: list of tuples (xpath, value) (required)
error_on_no_match: bool (optional, default false)

SelectNodesAction

Description

Evaluates an XPath expression against an XML document and returns all matches.

Example

Input:

<catalog>
  <book id="bk101">Title 1</book>
  <book id="bk102">Title 2</book>
</catalog>

Param:

xpath = "/catalog/book/@id"

Result:

{"success": true, "matches": ["bk101","bk102"]}

Parameters

xml: XmlDocument (required)
xpath: string (required)
error_on_no_match: bool (optional)

SelectSingleNodeAction

Description

Evaluates an XPath expression and returns the first matching node.

Example

Input:

<catalog>
  <book id="bk101">Title 1</book>
  <book id="bk102">Title 2</book>
</catalog>

Param:

xpath = "/catalog/book[@id='bk101']"

Result:

{"success": true, "match": "Title 1"}

Parameters

xml: XmlDocument (required)
xpath: string (required)
error_on_no_match: bool (optional)

WriteAction

Description

Serializes the provided XML document to text using encoding/indent and writes it to DB, file path, or string.

Example

Input:

<catalog><book id="bk101">Title 1</book></catalog>

Param:

write_to_string = true

Result:

{"success": true, "string": "<catalog>\r\n  <book id=\"bk101\">Title 1</book>\r\n</catalog>"}

Parameters

xml: XmlDocument (required)
write_to_db: string (filename) (optional)
write_to_path: string (absolute path) (optional)
write_to_string: bool (optional, default false)
encoding: string (optional, default “utf-8”)
indent: bool (optional, default true)