Plugin API » Interfaces » XMLCursor

XMLCursor interface

The XMLCursor interface is used for reading and writing data to an XMLDocument object.

XMLCursor objects are namespace and schema aware, and will only allow you to write valid XML.

All functions on the interface return a cursor object for chaining unless otherwise specified.

Movement

function up()

Move the cursor to the parent of the current element.

function nextSiblingMaybe()

Attempts to move the cursor to the next sibling of the current element, returning the result as a boolean.

function nextSibling()

Moves the cursor to the next sibling of the current element.

function nextSiblingElementMaybe(name)

Attempts to move the cursor to the next sibling with name name, returning the result as a boolean.

function nextSiblingElement(name)

Moves the cursor to the next sibling with name name.

function firstChildMaybe()

Attempts to move the cursor to the first child of the current element, returning the result as a boolean.

function firstChild()

Moves the cursor to the first child of the current element.

function firstChildElementMaybe()

Attempts to move the cursor to the first child element with name name, returning the result as a boolean.

function firstChildElement()

Moves the cursor to the first child element with name name.

Reading the DOM

function isElement()

Returns true if the cursor is on an element node.

function isText()

Returns true if the cursor is on a text node.

function getNodeType()

Returns the type of the current node.

function getNodeName()

Returns the name of the current node.

function getLocalName()

Returns the local name of the current node.

function getNamespaceURI()

Returns the namespace URI of the current node.

function getNodeValue()

Returns the value of the current node.

function getAttribute(name)

Returns the value of the named attribute.

function getAttributeWithNamespace(namespaceURI, attributeName)

Returns the value of the named attribute in the specified namespace.

function forEachAttribute(iterator)

Calls the iterator function with the name and value of each attribute.

function getText()

Returns the text value of the current node.

function getTextOfFirstChildElementMaybe(name)

Returns the text value of the first child element with name name, or null if no such child exists.

function getTextOfFirstChildElement(name)

Returns the text value of the first child element with name name.

Iterators

function eachChildElement(fn)

Will call fn for each child of the current element.

function eachChildElement(name, fn)

Will call fn for each child of the current element with name name.

Modifying the DOM

function element(name)

Create a new element name at this cursor position.

function addSchemaLocation(namespaceURI, schemaLocation)

Add a new schema location to this element. This schema will be defined for this element and all child elements.

function addNamespace(namespaceURI, preferredPrefix, schemaLocation)

Add a new schema location to this element, with a namespace prefix for elements from this schema. Cursors set to this namespace will add the preferredPrefix automatically.

function attribute(name, value)

Add an attribute to this element.

function attributeMaybe(name, value)

Add an attribute to this element, if value is not null or undefined.

function attributeWithNamespace(namespaceURI, attributeName, value)

Add an attribute using a specific namespace to this element. The namespace must have been previously defined.

function text(value)

Set the text of this element.

Cloning cursor and namespace manipulation

function cursor()

Returns a clone of the current cursor.

function cursorSettingDefaultNamespace(namespaceURI)

Returns a new cursor, setting the default namespace for elements in this cursor, and all clones of this cursor, to the passed in namespaceURI.

function cursorWithNamespace(namespaceURI)

Returns a new cursor with the specified namespace.

h3(function)cursorWithControlCharacterPolicy(policy)

Returns a new cursor with a policy on how to replace control characters.

Available policies are:

"entity-encode"	Encodes the control characters as escaped strings
"remove"	Deletes control characters
"replace-with-space"	Replaces control characters with a single space
"replace-with-question-mark"	Replaces control characters with a question mark