HTML 4.01 strict HTML
Visit Sourceforge.net

This page contains the XML for <SCRIPT> DOMNamedNodeMap object documentation.

Return to W3C DOM Parser Documentation Main Page

NOTE: DOMNamedNodeMap descends from DOMNodeList and inherits all of the properties and methods of the DOMNodeList object

CONTENTS
DOMNamedNodeMap - object description
 
Native Methods:
DOMNamedNodeMap - getNamedItem method
DOMNamedNodeMap - setNamedItem method
DOMNamedNodeMap - removeNamedItem method
DOMNamedNodeMap - getNamedItemNS method
DOMNamedNodeMap - setNamedItemNS method
DOMNamedNodeMap - removeNamedItemNS method
 
Inherited Methods:
DOMNodeList - getLength method
DOMNodeList - item method
DOMNamedNodeMap - object description

Objects implementing the DOMNamedNodeMap interface are used to represent collections of nodes that can be accessed by name.

NamedNodeMap objects in the DOM are live - meaning modifications to DOMNamedNodeMap objects are visible as soon as they happen in the DOMDocument.

NOTE: XML for <SCRIPT>'s DOMNamedNodeMap descends from DOMNodeList - a derivation from the W3C Specification. According to the W3C Specification, a DOMNamedNodeMap should implement its own item and getLength methods. XML for <SCRIPT>'s DOMNamedNodeMap implementation inherits these methods from its DOMNodeList parent.

DOMNamedNodeMap - getNamedItem method
W3C DOM Level 1

namedNodeMap.getNamedItem(<nodeName>)

accepts:
nodeName - the name of the node to return

returns:
DOMNode object - A Node (of any type) with the specified nodeName, or null if it the name does not identify a node in the queried DOMNamedNode map.

throws:
N/A

The getNamedItem method searches through the queried DOMNamedNodeMap for a node with the name passed in. If it finds a node with the nodeName passed in, getNamedItem returns that node. Otherwise, getNamedItem returns null.

Example:
function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1 foo=\"goo\" id=\"tag1_id\">"
+ "Hello World"
+ "</TAG1>"
+ "</ROOTNODE>";

//instantiate the W3C DOM Parser
var parser = new DOMImplementation();

//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);

//get the root node
var docRoot = domDoc.getDocumentElement();

//find tag1 by searching by its id
var tag1 = domDoc.getElementById("tag1_id");

//get a DOMNamedNodeMap of the attributes for tag1
var namedNodeMap = tag1.getAttributes();

//get the DOMAttr node with the name of "foo"
var fooNode = namedNodeMap.getNamedItem("foo");

//the following should be "goo"
alert(fooNode.getValue());

}// end function xmljsDOMExample

DOMNamedNodeMap - setNamedItem method
W3C DOM Level 1

namedNodeMap.setNamedItem(<newNode>)

accepts:
DOMNide newNode - the node to add to the DOMNamedNodeMap

returns:
null (if newNode does not replace another node) or the replaced DOMNode object.

throws:
DOMException.WRONG_DOCUMENT_ERR - Raised if newNode was created from a different document than the one that created this map.
DOMException.NO_MODIFICATION_ALLOWED_ERR - Raised if this NamedNodeMap is readonly
DOMException.INUSE_ATTRIBUTE_ERR - Raised if newNode is a DOMAttr that is already an attribute of another DOMElement object. DOMAttr nodes must explicitly be cloned to re-use them in other elements.

The setNamedItem method searches through the named nodes in the DOMNamedNodeMap. If it finds a node with the same name as newNode, it replaces that node with newNode and returns the replaced node. If it does not find a node with the same name as newNode, it appends newNode to the DOMNamedNodeMap and returns null.

Example:
function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1 foo=\"goo\" id=\"tag1_id\">"
+ "Hello World"
+ "</TAG1>"
+ "</ROOTNODE>";

//instantiate the W3C DOM Parser
var parser = new DOMImplementation();

//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);

//get the root node
var docRoot = domDoc.getDocumentElement();

//find tag1 by searching by its id
var tag1 = domDoc.getElementById("tag1_id");

//get a DOMNamedNodeMap of the attributes for tag1
var namedNodeMap = tag1.getAttributes();
//create a new DOMAttr object
var newAttribute = domDoc.createAttribute("attribute");
newAttribute.setNodeValue("value");

//add the new attribute to the DOMNamedNodeMap
var retVal = namedNodeMap.setNamedItem(newAttribute);

//retVal should be null
if (retVal == null) {
alert("newAttribute added successfully");
}
else {
alert("newAttribute not added successfully");
}

//create another new DOMAttr object,
//this time with a name of an attribute already
//in the DOMNamedNodeMap
var fooAttribute = domDoc.createAttribute("foo");
fooAttribute.setNodeValue("newFoo");

//add the new attribute to the DOMNamedNodeMap
//This will actually replace the original foo
//attribute with the new attribute
var retVal = namedNodeMap.setNamedItem(fooAttribute);

//retVal.getValue() should be "goo"
alert(retVal.getValue());

//the following should be
//<TAG1 foo="newFoo" id="tag1_id" attribute="value">
//Hello World
//</TAG1>

alert(tag1.getXML());

}// end function xmljsDOMExample

DOMNamedNodeMap - removeNamedItem method
W3C DOM Level 1

namedNodeMap.removeNamedItem(<nodeName>)

accepts:
nodeName - the name of the node to remove

returns:
The DOMNode object that was removed. If no node names in the DOMNamedNodeMap match those of nodeName, removeNamedItem will throw a DOMException.NOT_FOUND_ERR.


throws:
DOMException.NOT_FOUND_ERR - Raised if there is no node named nodeName in this map
DOMException.NO_MODIFICATION_ALLOWED_ERR - Raised if this NamedNodeMap is readonly

Example:
function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1 foo=\"goo\" id=\"tag1_id\">"
+ "Hello World"
+ "</TAG1>"
+ "</ROOTNODE>";

//instantiate the W3C DOM Parser
var parser = new DOMImplementation();

//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);

//get the root node
var docRoot = domDoc.getDocumentElement();

//find tag1 by searching by its id
var tag1 = domDoc.getElementById("tag1_id");

//get a DOMNamedNodeMap of the attributes for tag1
var namedNodeMap = tag1.getAttributes();

//remove the "foo" attribute
var retVal = namedNodeMap.removeNamedItem("foo");

//the following should be "goo"
alert(retVal.getValue());

//the following should be
//<TAG1 id="tag1_id">Hello World</TAG1>
alert(tag1.getXML());

}// end function xmljsDOMExample

DOMNamedNodeMap - getNamedItemNS method
W3C DOM Level 2

namedNodeMap.getNamedItem(<namespaceURI>, <localName>)

accepts:
namespaceURI - the URI of the namespace to search
localName - the local name of the node to return

returns:
DOMNode object - A Node (of any type) with the specified nodeName from the specified namespace, or null if it the name and namespace URI do not identify a node in the queried DOMNamedNode map.

throws:
N/A

The getNamedItemNS method searches through the queried DOMNamedNodeMap for a node that matches localName that is also in the namespaceURI. If it finds a node with nodeName in the namespaceURI passed in, getNamedItemNS returns that node. Otherwise, getNamedItemNS returns null.

NOTE: In order for getNamedItemNS to return a node, you must remember to append a prefix to the localName of the attribute since attributes do not automatically inherit the namespace of their containing element.

Example:
function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ns1:ROOTNODE xmlns:ns1=\"http://xmljs.sf.net/ns1\">"
+ "<ns1:TAG1 ns1:foo=\"goo\" id=\"tag1_id\">"
+ "Hello World"
+ "</ns1:TAG1>"
+ "</ns1:ROOTNODE>";

//instantiate the W3C DOM Parser
var parser = new DOMImplementation();

//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);

//get the root node
var docRoot = domDoc.getDocumentElement();

//find tag1 by searching by its id
var tag1 = domDoc.getElementById("tag1_id");

//get a DOMNamedNodeMap of the attributes for tag1
var namedNodeMap = tag1.getAttributes();

//get the DOMAttr node with the name of "foo" in the ns1 namespace
var ns1="http://xmljs.sf.net/ns1";
var fooAttr = namedNodeMap.getNamedItemNS(ns1, "foo");

//the following should be "goo"
alert(fooAttr.getValue());

}// end function xmljsDOMExample

DOMNamedNodeMap - setNamedItemNS method
W3C DOM Level 2

namedNodeMap.setNamedItemNS(<newNode>)

accepts:
DOMNide newNode - the node to add to the DOMNamedNodeMap

returns:
null (if newNode does not replace another node) or the replaced DOMNode object.

throws:
DOMException.WRONG_DOCUMENT_ERR - Raised if newNode was created from a different document than the one that created this map.
DOMException.NO_MODIFICATION_ALLOWED_ERR - Raised if this NamedNodeMap is readonly
DOMException.INUSE_ATTRIBUTE_ERR - Raised if arg is an Attr that is already an attribute of another Element object. DOMAttr nodes must explicitly be cloned to re-use them in other elements.

The setNamedItemNS method searches through the named nodes in the DOMNamedNodeMap. If it finds a node with the same name as newNode that is also in the same namespace as newNode, it replaces that node with newNode and returns the replaced node. If it does not find a node with the same name and namespace as newNode, it appends newNode to the DOMNamedNodeMap and returns null.

Example:
function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ns1:ROOTNODE xmlns:ns1=\"http://xmljs.sf.net/ns1\">"
+ "<ns1:TAG1 ns1:foo=\"goo\" >"
+ "Hello"
+ "</ns1:TAG1>"
+ "</ns1:ROOTNODE>";

//instantiate the W3C DOM Parser
var parser = new DOMImplementation();

//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);

//get the root node
var docRoot = domDoc.getDocumentElement();

//find tag1 by searching by name and namespace
var ns1="http://xmljs.sf.net/ns1";
var tag1 = docRoot.getElementsByTagNameNS(ns1, "TAG1").item(0);

//get a DOMNamedNodeMap of the attributes for tag1
var namedNodeMap = tag1.getAttributes();

//create a new DOMAttr node with
//the ns1 namespace
var newAttribute = domDoc.createAttributeNS(ns1, "ns1:att");
newAttribute.setNodeValue("val");

//append the new attribute
var retVal = namedNodeMap.setNamedItemNS(newAttribute);

//retVal should be null
if (retVal == null) {
alert("the new attribute was added successfully");
}
else {
alert("the new attribute was not added successfully");
}

//now create a new DOMAttr node with
//the ns1 namespace that will replace ns1:foo
var ns1="http://xmljs.sf.net/ns1";
var newFooAttr = domDoc.createAttributeNS(ns1, "ns1:foo");
newFooAttr.setNodeValue("newFoo");

//in this case newFooAttr will replace the original ns1:foo
//the original ns1:foo will be returned
var retVal = namedNodeMap.setNamedItemNS(newFooAttr);

//the following should be "goo" since the replaced node
//will be returned to us
alert(retVal.getValue());

//the following should be
//<ns1:TAG1 ns1:foo="newFoo" ns1:att="val">Hello</ns1:TAG1>
alert(tag1.getXML());

}// end function xmljsDOMExample

DOMNamedNodeMap - removeNamedItemNS method
W3C DOM Level 2

namedNodeMap.removeNamedItemNS(<namespaceURI>, <localName>)

accepts:
namespaceURI - the URI of the namespace to search
localName - the local name of the node to remove

returns:
The DOMNode object that was removed or null if no node is found in the DOMNamedNodeMap that matches namespaceURI and localName.

throws:
DOMException.NOT_FOUND_ERR - Raised if there is no node named nodeName in this map
DOMException.NO_MODIFICATION_ALLOWED_ERR - Raised if this NamedNodeMap is readonly

The removeNamedItemNS method searches through the named nodes in the DOMNamedNodeMap. If it finds a node with the same name as localName that is also in the namespaceURI namespace, it removes that node and returns a reference to that node. Otherwise, removeNamedItemNS returns null.

Example:
function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ns1:ROOTNODE xmlns:ns1=\"http://xmljs.sf.net/ns1\">"
+ "<ns1:TAG1 ns1:foo=\"goo\" id=\"tag1_id\" >"
+ "Hello World"
+ "</ns1:TAG1>"
+ "</ns1:ROOTNODE>";

//instantiate the W3C DOM Parser
var parser = new DOMImplementation();

//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);

//get the root node
var docRoot = domDoc.getDocumentElement();

//find tag1 by searching by its id
var tag1 = domDoc.getElementById("tag1_id");

//get a DOMNamedNodeMap of the attributes for tag1
var namedNodeMap = tag1.getAttributes();

//remove the foo node
var ns1 = "http://xmljs.sf.net/ns1";
var retVal = namedNodeMap.removeNamedItemNS(ns1, "foo");

//the following should be "goo" since the removed
//node will be returned to us
alert(retVal.getValue());

//the following should be
//<ns1:TAG1 id="tag1_id">Hello World</ns1:TAG1>
alert(tag1.getXML());

}// end function xmljsDOMExample