xHarbour Reference Documentation > Class Reference (textmode)

TXmlNode()

Creates a new TXmlNode object.

Syntax

TXmlNode():new( [<nType>]      , ;
                 <cTagName>    , ;
                [<hAttributes>], ;
                [<cData>]        ) --> oTXmlNode

Arguments

<nType>

This is an optional numeric value indicating the type of the XML node. XML node types are distinguished by the folloing #define constants listed in Hbxml.ch:

Types of XML nodes

Constant	Value	Description
HBXML_TYPE_TAG *)	0	Regular XML node
HBXML_TYPE_COMMENT	1	XML comment
HBXML_TYPE_PI	2	XML processing instruction
HBXML_TYPE_DIRECTIVE	3	XML directive
HBXML_TYPE_DATA	4	Parsed XML data section (PCDATA)
HBXML_TYPE_CDATA	5	Unparsed XML data section (CDATA)
HBXML_TYPE_DOCUMENT	6	XML document
*) default type

<cTagName>

This is a character string holding the tag name of the XML node to create.

<hAttributes>

Optionally, the attributes of the XML node to create can be passed as a Hash. The Hash key is the attribute name and the Hash value is the attribute value. Note that both, Hash values and keys, must be of data type Character.

<cData>

This is an optional character string holding the textual data of the TXmlNode object. If this parameter is used, the TXmlNode object represents a leaf, not a node. <cData> is the text appearing between the opening and closing XML <cTagName>.

Return

The function returns a TXmlNode object and method :new() initializes the object.

Description

Objects of the TXmlNode class represent a single node, or a leaf, in an XML document. XML documents are maintained by the TXmlDocument() class which builds a tree of XML nodes when reading an XML document. A TXmlDocument object creates this tree and fills it with TXmlNode objects.

One TXmlNode object contains in its instance variables the XML tag name, an optional list of XML atttributes, and the textual content of an XML node, when it is a leaf node.

The XML node hierarchy of an XML document is reflected in instance variables of an TXmlNode object. These are :oParent and :oChild holding TXmlNode objects of the next higher or lower level in the XML tree, plus :oNext and :oPrev holding the next or previous TXmlNode object of the same level in the XML tree. The nesting level of a TXmlNode object can be queried with method :depth().

Note:  the beforementioned instance variables allow for traversing an XML tree programmatically. Before doing so, the search and scan capabilities of the classes TXmlIterator(), TXmlIteratorRegEx() and TXmlIteratorScan() should be investigated. They are designed to aid in traversing an XML document and extracting information from it.

Instance variables

:aAttributes

Contains attributes of an XML node.

:cData

Contains textual data of an XML node.

:cName

Contains the tag name of an XML node.

:nBeginLine

Contains the line number of an XML node.

:nType

Contains the type number of an XML node.

:oChild

Contains the child node of an XML node.

:oNext

Contains the next XML node in the XML document.

:oParent

Contains the parent XML node.

:oPrev

Contains the previous XML node in the XML document.

Methods for attributes

:getAttribute( <cAttribute> ) --> cValue | NIL

Retrieves an attribute from an XML tag by name.

:setAttribute( <cAttribute>, <cValue> ) --> cValue

Sets a named attribute and its value for an XML tag.

Methods for nodes

:addBelow( <oTXmlNode> ) --> oChildNode

Adds a new XML node below the current XML node.

:clone() --> oXmlClone

Clones an XML node.

:cloneTree() --> oXmlCloneWithSubNodes

Clones an XML node with all sub-nodes.

:insertAfter( <oTXmlNode> ) --> oParentNode

Inserts an XML node after the current node.

:insertBefore( <oTXmlNode> ) --> oPreviousNode

Inserts an XML node before the current node.

:insertBelow( <oTXmlNode> ) --> self

Inserts a new XML node below the current XML node.

:nextInTree() --> oNextNode | NIL

Retrieves the next XML node in the XML tree.

:unlink() --> self

Removes an XML node from the XML tree.

Methods for XML code

:toString( <nStyle> ) --> cXmlString

Creates an XML formatted character string.

:write( <nFileHandle>, <nStyle> ) --> lSuccess

Writes an XML formatted character string to a file.

Informational methods

:depth() --> nDepth

Determines the depth of an XML node.

:path() --> cXmlPath

Determines the complete path of an XML node.

:toArray() --> aXmlNodeInfo

Creates an array holding all XML information of a TXmlNode object.

Info

See also:	TXmlDocument(), TXmlIterator()
Category:	Object functions , xHarbour extensions
Header:	hbxml.ch
Source:	rtl\txml.prg
LIB:	xhb.lib
DLL:	xhbdll.dll

Examples

Creating XML nodes

// The example creates an XML document with two nodes of different
// nesting level, or depth. The inner XML node is a leaf node. Both
// XML nodes have the same attribute. Note that the starting point of
// the node creation is the root node of the XML document.

   #include "HbXml.ch"

   PROCEDURE Main
      LOCAL oXmlDoc  := TXmlDocument():new( '<?xml version="1.0"?>' )
      LOCAL oXmlNode := oXmlDoc:oRoot
      LOCAL oXmlSubNode

      oXmlSubNode := TXmlNode():new( , "AAA", ;
                                     { "id" => "1" },
                                       "NOT A LEAF NODE" )
      oXmlNode:addBelow( oXmlSubNode )

      oXmlNode    := oXmlSubNode
      oXmlSubNode := TXmlNode():new(, "BBB", {"id" => "1"}, "Leaf node" )
      oXmlNode:addBelow( oXmlsubNode )

      ? oXmlDoc:toString( HBXML_STYLE_INDENT )

      ** Output
      // <?xml version="1.0"?>
      // <AAA id="1">
      //  <BBB id="1">Leaf node</BBB>
      //  NOT A LEAF NODE</AAA>
   RETURN

Inserting XML nodes

// The example creates an XML document and inserts XML nodes
// before and after the current node.

   #include "HbXml.ch"

   PROCEDURE Main
      LOCAL oXmlDoc      := TXmlDocument():new( '<?xml version="1.0"?>'  )
      LOCAL oXmlNode     := oXmlDoc:oRoot
      LOCAL oXmlSubNode1, oXmlSubNode2

      oXmlSubNode1 := TXmlNode():new(, "AAA" )
      oXmlNode:addBelow( oXmlsubNode1 )

      oXmlNode     := oXmlSubNode1
      oXmlSubNode1 := TXmlNode():new(, "BBB", {"id" => "1"}, "Leaf node" )
      oXmlNode:addBelow( oXmlsubNode1 )

      oXmlSubNode2 := TXmlNode():new(, "BBB", {"id" => "2"}   , ;
                                               ":insertBefore()" )
      oXmlSubnode1:insertBefore( oXmlSubNode2 )

      oXmlSubNode2 := TXmlNode():new(, "BBB", {"id" => "3"}   , ;
                                               ":insertAfter()" )
      oXmlSubnode1:insertAfter( oXmlSubNode2 )

      ? oXmlDoc:toString( HBXML_STYLE_INDENT )

      ** Output
      // <?xml version="1.0"?>
      // <AAA>
      //  <BBB id="2">:insertBefore()</BBB>
      //  <BBB id="1">Leaf node</BBB>
      //  <BBB id="3">:insertAfter()</BBB>
      // </AAA>

   RETURN

Deleting XML nodes

// The example creates an XML document with a nesting level, or depth,
// of 3. The XML node at nesting level 2 is removed from the XML document.

   #include "HbXml.ch"

   PROCEDURE Main
      LOCAL oXmlDoc      := TXmlDocument():new( '<?xml version="1.0"?>'  )
      LOCAL oXmlNode     := oXmlDoc:oRoot
      LOCAL oXmlSubNode1, oXmlSubNode2

      oXmlSubNode1 := TXmlNode():new(, "AAA", { "id" => "1" }, "1st level" )
      oXmlNode:addBelow( oXmlsubNode1 )

      oXmlNode     := oXmlSubNode1
      oXmlSubNode1 := TXmlNode():new(, "BBB", { "id" => "1" }, "2nd level" )
      oXmlNode:addBelow( oXmlsubNode1 )


      oXmlSubNode2 := TXmlNode():new(, "CCC", { "id" => "1" }, "3rd level" )
      oXmlSubnode1:addBelow( oXmlSubNode2 )

      ? oXmlDoc:toString( HBXML_STYLE_INDENT )
      ** Output
      // <?xml version="1.0"?>
      // <AAA id="1">
      //  <BBB id="1">
      //   <CCC id="1">3rd level</CCC>
      //   2nd level </BBB>
      //  1st level</AAA>

      // delete this node from the XML document
      oXmlSubNode1:unlink()

      ? oXmlDoc:toString( HBXML_STYLE_INDENT )

      ** Output (only one node is left)
      // <?xml version="1.0"?>
      // <AAA id="1">1st level</AAA>

      ? oXmlSubNode1:toString( HBXML_STYLE_INDENT )

      ** Output (deleted node has a sub-node)
      // <BBB id="1">
      //  <CCC id="1">3rd level</CCC>
      // 2nd level</BBB>
   RETURN