Back to Contents

The DomNode class

Summary:

See also: Classes and Objects, XML Utilities, NodeList

Syntax

The DomNode class provides methods to manipulate a node of a data tree, following the DOM standards.

Syntax:

om.DomNode

Notes:

  1. A DomNode object is a node (or element) of a DomDocument.

Methods:

Object Methods
Name Description
Node creation
appendChild( src om.DomNode ) Adds an existing DomNode at the end of the list of children in this node.
createChild( tag STRING )
  RETURNING om.DomNode		 Creates a DomNode and adds it to the children list of this node.
insertBefore( new om.DomNode, exn om.DomNode ) Inserts an existing DomNode just before the node referenced by exn.
removeChild( node om.DomNode ) Removes the child node referenced by node and removes any of its descendents.
replaceChild( new om.DomNode, old om.DomNode ) Replaces the child node referenced by old by the node new.
In/Out Utilities
loadXml( file STRING )
  RETURNING om.DomNode		 Creates a new DomNode object by loading an XML file and attaches it to this node as a child.
The new created node object is returned from the function.
parse( source STRING )
  RETURNING om.DomNode		 Creates a new DomNode object by parsing a source string in XML format and attaches it to this node as a child.
The new created node object is returned from the function.
toString()
  RETURNING STRING		 Serializes the DomNode to a string in XML format.
writeXml( file STRING ) Writes an XML file with the current node.
write( shd om.SaxDocumentHandler ) Outputs an xml-tree to a sax document handler.
Node identification
getId( )
  RETURNING INTEGER		 Returns the internal integer identifier automatically assigned to an Abstract User Interface DomNode. Returns -1 for nodes that are not part of the Abstract User Interface tree.
getTagName( )
  RETURNING STRING		 Returns the tag name of the node.
Attributes management
setAttribute( att STRING, val STRING ) Sets the attribute att with value val.
getAttribute( att STRING )
  RETURNING STRING		 Returns the value of the attribute having the name att.
getAttributeInteger(att STRING, def INTEGER )
  RETURNING INTEGER		 Returns the value of the attribute having the name att as an integer value. Returns def if the attribute is not defined.
getAttributeString(att STRING, def STRING )
  RETURNING INTEGER		 Returns the value of the attribute having the name att as a string value. Returns def if the attribute is not defined.
getAttributeName( pos INTEGER )
  RETURNING STRING		 Returns the name of the attribute at the position pos (1 = first).
getAttributesCount()
  RETURNING INTEGER		 Returns the number of attributes of this DomNode.
getAttributeValue( pos INTEGER )
  RETURNING STRING		 Returns the value of the attribute at the position pos (1 = first).
removeAttribute( att STRING ) Deletes the attribute identified by att.
Tree navigation
getChildCount()
  RETURNING INTEGER		 Returns the number of children.
getChildByIndex( pos INTEGER )
  RETURNING om.DomNode		 Returns the child node at index pos (1 = first).
getFirstChild()
  RETURNING om.DomNode		 Returns the first child node.
getLastChild()
  RETURNING om.DomNode		 Returns the last DomNode in the list of children.
getNext()
  RETURNING om.DomNode		 Returns the next sibling DomNode of this node.
getParent()
  RETURNING om.DomNode		 Returns the parent DomNode of this node.
getPrevious()
  RETURNING om.DomNode		 Returns the previous sibling DomNode of this node.
selectByTagName( name STRING )
  RETURNING om.NodeList		 Creates a list of nodes by recursively searching nodes by tag name.
selectByPath( path STRING )
  RETURNING om.NodeList		 Creates a list of nodes by recursively searching nodes matching an XPath-like pattern.

Usage:

Node creation/removal

To create an instance of the DomNode class from scratch, you must instantiate the object using one of the methods provided in the DomNode class:

createChild() creates a child node and adds it to the children list.

appendChild() adds an existing node to the end of the children list. The appended node must have been created with a document method such as DomDocument.createElement().

insertBefore() inserts an existing node before the node specified as second parameter. The inserted node must have been created with a document method such as DomDocument.createElement().

replaceChild() replaces the specified child node with a different child node. The replacing node must have been created with a document method such as DomDocument.createElement(). The replaced node will be dropped from the document.

Other methods to create DomNode objects are available from the DomDocument class. For example, to create a text node, use the createChars() method of a DomDocument object; to create an entity node, use the createEntity() method of a DomDocument object.

removeChild()  removes the specified child node.

In/Out utilities

The DomNode class provides the writeXml() method to save the DOM tree into a file in XML format.

The method write() outputs an xml-tree to a sax document handler.

The method loadXml() creates a new DomNode object by loading an XML file and attaches it to this node as a child.

Use the toString() method to generate a string in XML format from the DomNode. To scan an XML source string and create a DomNode from, use the parse() method.

Attributes management

A DomNode object can have attributes with values, except if it is a text node. In this case, you can only get/set the text of the node, since text nodes cannot have attributes. The DomNode class provides a complete set of methods to modify attribute values:

getAttribute() returns the value of the attribute having the specified name.

setAttribute() sets the value of the specified attribute.

getAttributeInteger() returns the value of the specified attribute as an integer value.

getAttributeString() returns the value of the specified attribute as a string value.

getAttributeName() returns the name of the attribute at the specified position.

getAttributesCount()returns the number of attributes of this DomNode.

getAttributeValue() returns the value of the attribute at the specified position.

removeAttribute() deletes the specified attribute.

Node Identification

To get the tag name of the DOM node, use the getTagName() method.

The method getId() returns the internal integer identifier automatically assigned to an DomNode.

Tree navigation

A DomNode object can have zero or more DomNode children that can have, in turn, other children. The DomNode class provides a complete set of methods to manipulate DomNode child objects.

getChildCount() returns the number of children.

getChildByIndex() returns the child node at the specified index position.

getFirstChild() returns the first child node.

getLastChild() returns the last DomNode in the list of children.

getNext() returns the next sibling DomNode of this node.

getParent() returns the parent DomNode of this node.

getPrevious() returns the previous sibling DomNode of this node.

The selectByTagName() and selectByPath() methods allow you to search for children nodes according to a tag name (i.e. a type of node) or by using an XPath-like search criteria. See the NodeList class for more details.

General remarks

Tag and attribute names are case sensitive; "Wheel" is not the same as "wheel".

Text nodes cannot have attributes, but they have plain text. In text nodes, the characters can be accessed with the @chars attribute name. In XML representation, a text node is the text itself. Do not confuse it with the parent node. For example, <Item id="32">Red shoes</Item> represents 2 nodes: The parent 'Item' node and a text node with string 'Red shoes'.

If you need to identify an element, use a common attribute like "name". If you need to label an element, use a common attribute like "text".

Examples

Example 1:

To create a DOM tree with the following structure (represented in XML format):

<Vehicles>
   <Car name="Corolla" color="Blue" weight="1546">Nice car!&nbsp;Yes, very nice!
   </Car>
   <Bus name="Maxibus" color="Yellow" weight="5278">
      <Wheel width="315" diameter="925" />
      <Wheel width="315" diameter="925" />
      <Wheel width="315" diameter="925" />
      <Wheel width="315" diameter="925" />
   </Bus>
</Vehicles>

You write the following:

01 MAIN
02   DEFINE d om.DomDocument
03   DEFINE r, n, t, w om.DomNode
04   DEFINE i INTEGER
05
06   LET d = om.DomDocument.create("Vehicles")
07   LET r = d.getDocumentElement()
08
09   LET n = r.createChild("Car")
10   CALL n.setAttribute("name","Corolla")
11   CALL n.setAttribute("color","Blue")
12   CALL n.setAttribute("weight","1546")
13
14   LET t = d.createChars("Nice car!")
15   CALL n.appendChild(t)
16   LET t = d.createEntity("nbsp")
17   CALL n.appendChild(t)
18   LET t = d.createChars("Yes, very nice!")
19   CALL n.appendChild(t)
20
21   LET n = r.createChild("Bus")
22   CALL n.setAttribute("name","Maxibus")
23   CALL n.setAttribute("color","yellow")
24   CALL n.setAttribute("weight","5278")
25   FOR i=1 TO 4
26     LET w = n.createChild("Wheel")
27     CALL w.setAttribute("width","315")
28     CALL w.setAttribute("diameter","925")
29   END FOR
30
31   CALL r.writeXml("Vehicles.xml")
32
33 END MAIN

Example 2:

The following example displays a DOM tree content recursively:

01 FUNCTION displayDomNode(n,e)
02   DEFINE n om.DomNode
03   DEFINE e, i, s INTEGER
04
05   LET s = e*2
06   DISPLAY s SPACES || "Tag: " || n.getTagName()
07
08   DISPLAY s SPACES || "Attributes:"
09   FOR i=1 TO n.getAttributesCount()
10      DISPLAY s SPACES || "  " || n.getAttributeName(i) || "=[" || n.getAttributeValue(i) ||"]"
11   END FOR
12   LET n = n.getFirstChild()
13
14   DISPLAY s SPACES || "Child Nodes:"
15   WHILE n IS NOT NULL
16     CALL displayDomNode(n,e+1)
17     LET n = n.getNext()
18   END WHILE
19
20 END FUNCTION

Example 3:

The following example outputs a Dom tree without indentation.

01 MAIN
02   DEFINE d om.DomDocument
03   DEFINE r, n, t, w om.DomNode
04   DEFINE dh om.SaxDocumentHandler
05 
06   DEFINE i INTEGER
07 
08   LET dh = om.XmlWriter.createPipeWriter("cat")
09   CALL dh.setIndent(FALSE)
10
11   LET d = om.DomDocument.create("Vehicles")
12   LET r = d.getDocumentElement()
13
14   LET n = r.createChild("Car")
15   CALL n.setAttribute("name","Corolla")
16   CALL n.setAttribute("color","Blue")
17   CALL n.setAttribute("weight","1546")
18
19   LET t = d.createChars("Nice car!")
20   CALL n.appendChild(t)
21
22   LET n = r.createChild("Bus")
23   CALL n.setAttribute("name","Maxibus")
24   CALL n.setAttribute("color","yellow")
25   CALL n.setAttribute("weight","5278")
26   FOR i=1 TO 4
27     LET w = n.createChild("Wheel")
28     CALL w.setAttribute("width","315")
29     CALL w.setAttribute("diameter","925")
30   END FOR
31
32   CALL r.write(dh)
33
34 END MAIN