DOM_Element

4. DOM_Element

The DOM_Element interface represents an element in an XML document. The following is a description of each DOM_Node member in the context of a DOM_Element:

nodeName This DOM_String * corresponds to the tag name of the element. It is read-only and cannot be modified.
nodeValue This is always NULL
childNodes This DOM_NodeList * contains the child nodes of this element.
attributes This DOM_NamedNodeMap * contains the DOM_Attr attribute nodes of this element.
firstChild This DOM_Node * points to the first child of this element or NULL if the element currently has no children.
lastChild This DOM_Node * points to the last child of this element or NULL if the element currently has no children.
previousSibling This DOM_Node * points to the previous node in the childNodes list of the parent element of this element.
nextSibling This DOM_Node * points to the next node in the childNodes list of the parent element of this element.

Example 1. Enumerating the children of an Element using sibling pointers
This example illustrates how to enumerate each child node of a DOM_Element node. This is a more efficient method of enumerating children than indexing each with the DOM_NodeList(elem->childNodes, idx) technique.


  for (child = elem->firstChild; child; child = child->nextSibling) {
  	if (child->nodeType == DOM_COMMENT_NODE) {
  		printf("comment: %s\n", child->nodeValue);
  	}
  }

In addition to the functions provided by the DOM_Node interface this interface provides additional functions mainly for manipulating attributes.

The DOM specifications require support for entity references which may result in the childNodes of an attribute containing a potentially complex subtree of DOM nodes. DOMC currently has very weak support for entity references and as a result attributes will never have children. The default module for loading and storing XML documents uses the Expat XML parser which expands entity references by default. Expat recently added support for parsing external entities but DOMC does not yet use this functionalty.

4.1. The DOM_Element functions

The DOM_Element_getAttribute function
Synopsis


  #include <domc.h>
  DOM_String *DOM_Element_getAttribute(DOM_Element *this, DOM_String *name);

Description
The DOM_Element_getAttribute function returns the nodeValue of the named attrbute or an empty string if this element does have an attribute by that name.

The DOM_Element_setAttribute function
Synopsis


  #include <domc.h>
  void DOM_Element_setAttribute(DOM_Element *this,
           DOM_String *name,
           DOM_String *value);

Description
The DOM_Element_setAttribute method adds a new attribute or sets the nodeValue of an existing attribute. Take care not to pass markup characters in the name and value parameters. It will be accepted and the resulting serialized XML may be incorrect.

The DOM_Element_removeAttribute function
Synopsis


  #include <domc.h>
  void DOM_Element_removeAttribute(DOM_Element *this, DOM_String *name);

Description
The DOM_Element_removeAttribute function removes and frees the named attribute.

Note the W3C specifications require that an attribute with a default DTD value should automatically be repopulated if a user supplied attribute value is removed. DOMC does not support default DTD values. This function will simply remove the attribute regarless of whether or not the attribute value was specified in the DTD. The Expat XML parser just released support for parsing external entities. DOMC will likely support external entities and default attribute values in a future version.

The DOM_Element_getAttributeNode function
Synopsis


  #include <domc.h>
  DOM_Attr *DOM_Element_getAttributeNode(DOM_Element *this, DOM_String *name);

Description
The DOM_Element_getAttributeNode function returns the DOM_Attr * by name. If this element does not have an attibute with that name a null pointer is returned.

The DOM_Element_setAttributeNode function
Synopsis


  #include <domc.h>
  DOM_Attr *DOM_Element_setAttributeNode(DOM_Element *this, DOM_Attr *newAttr);

Description
The DOM_Element_setAttributeNode function adds the attribute newAttr to the attributes of this element. If this element already has an attribute with the same name it will be replaced with the new attribute and returned.
Returns
The DOM_Element_setAttributeNode function returns the attribute being replaced if one with the same name already exists in the map. Otherwise a null pointer is returned.

The DOM_Element_removeAttributeNode function
Synopsis


  #include <domc.h>
  DOM_Attr *DOM_Element_removeAttributeNode(DOM_Element *this, DOM_Attr *oldAttr);

Description
The DOM_Element_removeAttributeNode function removes and returns a pointer to the attribtue oldAttr.

DOMC does not support default DTD values. This function will remove an attribute regarless of whether or not a default attribute value was specified in the DTD.

The DOM_Element_getElementsByTagName function
Synopsis


  #include <domc.h>
  DOM_NodeList *DOM_Element_getElementsByTagName(DOM_Element *this, DOM_String *name);

Description
The DOM_Element_getElementsByTagName function allocates memory for a DOM_NodeList object, performs a preorder traversal of the subtree specified by this, and adds a pointer to the node list for each DOM_Element node with a nodeName that matches the name parameter. Because elements are added to the list as they are encountered during preoder traversal the effect is that elements will be listed in "document order".

After the DOM_NodeList object will no longer to be used it must be freed with the DOM_Document_destroyNodeList function with a free_nodes parameter of 0 (the nodes in this list should not be freed or all other references to them will be invalid).
Returns
A new DOM_NodeList object containing pointers to the matching DOM_Elements.

The DOM_Element_hasAttribute function
Synopsis


  #include <domc.h>
  int DOM_Element_hasAttribute(DOM_Element *this, DOM_String *name);

Description
The DOM_Element_hasAttribute function returns 1 if this element has an attribute with the specified name or 0 if there is no such element.