DOM_Node

## 3. DOM_Node

Table 1. Values of nodeName, nodeValue, and attributes according to node type
Node Interface | nodeName | nodeValue | nodeType
--- | --- | --- | ---
`DOM_Attr` | name of attribute | value of attribute | `DOM_ATTRIBUTE_NODE`
`DOM_CDATASection` | `"#cdata-section"` | content of the CDATA Section | `DOM_CDATA_SECTION_NODE`
`DOM_Comment` | `"#comment"` | content of the comment | `DOM_COMMENT_NODE`
`DOM_Document` | `"#document"` | `NULL` | `DOM_DOCUMENT_NODE`
`DOM_DocumentFragment` | `"#document-fragment"` | `NULL` | `DOM_DOCUMENT_FRAGMENT_NODE`
`DOM_DocumentType` | document type name | `NULL` | `DOM_DOCUMENT_TYPE_NODE`
`DOM_Element` | tag name | `NULL` | `DOM_ELEMENT_NODE`
`DOM_Entity` | entity name | `NULL` | `DOM_ENTITY_NODE`
`DOM_EntityReference` | name of entity referenced | `NULL` | `DOM_ENTITY_REFERENCE_NODE`
`DOM_Notation` | notation name | `NULL` | `DOM_NOTATION_NODE`
`DOM_ProcessingInstruction` | target | content excluding target | `DOM_PROCESSING_INSTRUCTION_NODE`
`DOM_Text` | `"#text"` | content of the text node | `DOM_TEXT_NODE`

The `DOM_Node` type is the primary datatype of the Document Object Model. Most of the other DOM interfaces inherit this interface. All `DOM_Nodes` have `nodeName`, `nodeValue`, and `nodeType` members. The vaules of these members depends on the node type. For example the `DOM_Element` node has a `nodeValue` corresponding to the tag name and a `NULL` `nodeValue`.

Only the `DOM_Element` node type has attributes. All other node types have a `NULL` `attributes` member. Child nodes are accessable through the `childNodes` `DOM_NodeList` member and the `firstChild`, `lastChild`, `previousSibling`, and `nextSibling` members. Not all element types have child nodes.

In DOMC node inheritance is emulated with simple `typedef` statements and a `union` that contains all possible subclass attributes. To access a child interface specific attribute it may be necessary to access it through this union. For example the `systemId` of a notation node is currently only accessible through the `union` like:

      DOM_String *sysid;
      ...
      sysid = node->u.Notation.systemId;

Care must be taken when modifing these union members (this is not well defined yet). Attributes accessible through the `union` that may need to be modified have helper methods to make this less awkward. The `DOM_Node_setNodeValue` function must be used to set the `nodeValue` member.

Table 2. Functions to get and set certain node members
`DOM_Node_getNodeValue` | get `nodeValue` attribute
`DOM_Node_setNodeValue` | set `nodeValue` and corresponding value in child interface
`DOM_Document_getDoctype` | get the `doctype` node of the document
`DOM_Document_getDocumentElement` | get the `documentElement` of the document
`DOM_CharacterData_getLength` | get the `length` of a `DOM_Text`, `DOM_Comment`, `DOM_CDATASection`, or `DOM_ProcessingInstruction`

The all-important `DOM_Node` structure follows although some fields are left out in the interest of brevity. It may be necessary to look at this structure in the `domc.h` header.

      struct DOM_Node {
      	DOM_String *nodeName;
      	DOM_String *nodeValue;
      	unsigned short nodeType;
      	DOM_Node *parentNode;
      	DOM_NodeList *childNodes;
      	DOM_Node *firstChild;
      	DOM_Node *lastChild;
      	DOM_Node *previousSibling;
      	DOM_Node *nextSibling;
      	DOM_NamedNodeMap *attributes;
      	DOM_Document *ownerDocument;
      	union {
      		struct {
      			DOM_DocumentType *doctype;
      			DOM_Element *documentElement;
      			DOM_String *version;
      			DOM_String *encoding;
      			int standalone;
      		} Document;
      		struct {
      			DOM_NamedNodeMap *entities;
      			DOM_NamedNodeMap *notations;
      			DOM_String *publicId;
      			DOM_String *systemId;
      			DOM_String *internalSubset;
      		} DocumentType;
      		struct {
      			int specified;
      			DOM_Element *ownerElement;
      		} Attr;
      		struct {
      			int length;
      		} CharacterData;
      		struct {
      			DOM_String *publicId;
      			DOM_String *systemId;
      		} Notation;
      		struct {
      			DOM_String *publicId;
      			DOM_String *systemId;
      			DOM_String *notationName;
      		} Entity;
      		struct {
      			DOM_String *target;
      			DOM_String *data;
      		} ProcessingInstruction;
      	} u;
      };

### 3.1. The DOM_Node functions

The `DOM_Node_insertBefore` function
Synopsis

      #include <domc.h>
      DOM_Node *DOM_Node_insertBefore(DOM_Node *this,
               DOM_Node *newChild,
               DOM_Node *refChild);

Description
The `DOM_Node_insertBefore` function inserts the node `newChild` into this node directly before the existing child `refChild`. If `refChild` is a null pointer, `newChild` will be appended to the list. If `newChild` is a `DOM_DocumentFragment` node, all children are moved into `this` node in the same order before `refChild`. If `newChild` is already in the list it will first be removed.
Returns
The `DOM_Node_insertBefore` function returns a pointer to the node that was inserted.

The `DOM_Node_replaceChild` function
Synopsis

      #include <domc.h>
      DOM_Node *DOM_Node_replaceChild(DOM_Node *this,
               DOM_Node *newChild,
               DOM_Node *oldChild);

Description
Replaces the child node `oldChild` with `newChild` in the list of children, and returns the `oldChild` node.

If `newChild` is a `DocumentFragment` object, `oldChild` is replaced by all of the `DocumentFragment` children, which are inserted in the same order. If the `newChild` is already in the tree, it is first removed.
Returns
The node replaced.

The `DOM_Node_removeChild` function
Synopsis

      #include <domc.h>
      DOM_Node *DOM_Node_removeChild(DOM_Node *this, DOM_Node *oldChild);

Description
Removes the child node indicated by `oldChild` from the list of children, and returns it.
Returns
The node removed.

The `DOM_Node_appendChild` function
Synopsis

      #include <domc.h>
      DOM_Node *DOM_Node_appendChild(DOM_Node *this, DOM_Node *newChild);

Description
The `DOM_Node_appendChild` function appends `newChild` at the end of the `childNodes` list of `this` node. If `newChild` is already in the list, it is first removed.
Returns
The `DOM_Node_appendChild` function returns a pointer to `newChild` or a null pointer if the operation failed in which case `DOM_Exception` will be set appropriately.

The `DOM_Node_hasChildNodes` function
Synopsis

      #include <domc.h>
      int DOM_Node_hasChildNodes(DOM_Node *this);

Description
The `DOM_Node_hasChildNodes` function returns 1 if `this` node contains children and 0 if `this` node does not support child nodes or currently does not have any child nodes.

The `DOM_Node_cloneNode` function
Synopsis

      #include <domc.h>
      DOM_Node *DOM_Node_cloneNode(DOM_Node *this, int deep);

Description
The `DOM_Node_cloneNode` function creates a copy of `this` node. If the `deep` parameter is not 0 all children will be cloned as well. The cloned node's `parentNode` pointer is `NULL`. Cloning a `DOM_Element` node copies all attributes regardless of what the `deep` parameter is. It is possibly to clone every node type with DOMC whereas the W3C specifications do not require cloning `DOM_Document`, `DOM_DocumentType`, `DOM_Entity`, and `DOM_Notation` nodes.

The DOM specification requires that cloning an attribute node directly will return a specified attribute opposed to an attribute resulting from a default value specified in the DTD. Currently DOMC does not consider DTD default values. The value of `attr->u.Attr.specified` will always be 0.
Returns
The `DOM_Node_cloneNode` function returns the new cloned node or a null pointer if the operation failed in whhich case `DOM_Exception` will be set appropriately.

The `DOM_Node_normalize` function
Synopsis

      #include <domc.h>
      void DOM_Node_normalize(DOM_Node *this);

Description
The `DOM_Node_normalize` function merges adjecent `DOM_Text` node content into "normal" form in the subtree of `this` node. Empty `DOM_Text` nodes will also be removed. When a document is first loaded it is in "normal" form.

Copyright 2003 Michael B. Allen <mballen@erols.com> Generated by CStyleX 0.1.1