Back to Contents

The DomNode class

Summary:

See also: Built-in Classes, XML Utils, NodeList

Basics

Purpose:

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 a 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 a DomNode just before the existing 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.
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:

To create an instance of the DomNode class from scratch, you must use a method to instantiate the object, like DomNode.createChild(), for example. Other methods to create DomNode objects are available from the DomDocument class.

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, like the DomNode.getAttribute() or DomNode.setAttribute() methods.

To create a text node, use the DomDocument.createChars() method.

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, like DomNode.getFirstChild(), for example.

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

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

The DomNode.selectByTagName() and DomNode.selectByPath() methods allow 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.

Warnings:

  1. Tag and attribute names are case sensitive; "Wheel" is not the same as "wheel".
  2. Text nodes cannot have attributes, but they have plain text.
  3. In text nodes, the characters can be accessed with the @chars attribute name.
  4. 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'.

Tips:

  1. If you need to identify an element, use a common attribute like "name".
  2. 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!
   </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
17   LET n = r.createChild("Bus")
18   CALL n.setAttribute("name","Maxibus")
19   CALL n.setAttribute("color","yellow")
20   CALL n.setAttribute("weight","5278")
21   FOR i=1 TO 4
22     LET w = n.createChild("Wheel")
23     CALL w.setAttribute("width","315")
24     CALL w.setAttribute("diameter","925")
25   END FOR
26
27   CALL r.writeXml("Vehicles.xml")
28
29 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