2.1.1 [DOM Level 1] Section 1.2, Fundamental Interfaces
V0001:
-
IDL Definition exception DOMException { unsigned short code; };
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The DOMException interface is not supported.
V0002:
-
While it is true that a Document object could fulfil this role, a Document object can potentially be a heavyweight object, depending on the underlying implementation. What is really needed for this is a very lightweight object. DocumentFragment is such an object.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The DocumentFragment interface is derived from the Document interface. The createDocumentFragment method returns a full Document object.
V0003:
-
IDL Definition interface DocumentFragment : Node { };
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The DocumentFragment interface is derived from the Document interface. The Document interface is derived from the Node interface.
V0004:
-
Method createElement Creates an element of the type specified. Note that the instance returned implements the Element interface, so attributes can be specified directly on the returned object. Parameters tagName The name of the element type to instantiate. For XML, this is case-sensitive. For HTML, the tagName parameter may be provided in any case, but it must be mapped to the canonical uppercase form by the DOM implementation. Return Value A new Element object. Exceptions DOMException INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The following variation apply:
The createElement method is overloaded with one that takes no parameters. When no parameters are given, this method returns an element with a tagName of null.
The createElement method accepts full element declaration strings that contain otherwise invalid characters for the tagName parameter. A parameter string such as
"<div id='div1'>"
would return a div element with an id ofdiv1
. An INVALID_CHARACTER_ERR exception is not raised in this case.
Quirks Mode, IE7 Mode, IE8 Mode, and IE9 Mode (All Versions)
When an element that contains an XMLNS declaration (such as
<html XMLNS:mns='http://www.contoso.com'>)
is specified for the tagName parameter, the value of the tagUrn property for the new element is set to the specified URI.
V0005:
-
interface Document : Node Method createCDATASection Creates a CDATASection node whose value is the specified string. Parameters data The data for the CDATASection contents. Return Value The new CDATASection object. Exceptions DOMException NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The createCDATASection method of the Document interface is not supported.
V0006:
-
interface Document : Node Method createProcessingInstruction Creates a ProcessingInstruction node given the specified name and data strings. Parameters target The target part of the processing instruction. data The data for the node. Return Value The new ProcessingInstruction object. Exceptions DOMException INVALID_CHARACTER_ERR: Raised if an invalid character is specified. NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The createProcessingInstruction method of the Document interface is not supported.
V0008:
-
IDL Definition interface Node { // NodeType const unsigned short ELEMENT_NODE = 1; const unsigned short ATTRIBUTE_NODE = 2; const unsigned short TEXT_NODE = 3; const unsigned short CDATA_SECTION_NODE = 4; const unsigned short ENTITY_REFERENCE_NODE = 5; const unsigned short ENTITY_NODE = 6; const unsigned short PROCESSING_INSTRUCTION_NODE = 7; const unsigned short COMMENT_NODE = 8; const unsigned short DOCUMENT_NODE = 9; const unsigned short DOCUMENT_TYPE_NODE = 10; const unsigned short DOCUMENT_FRAGMENT_NODE = 11; const unsigned short NOTATION_NODE = 12; readonly attribute DOMString nodeName; attribute DOMString nodeValue; // raises(DOMException) on setting // raises(DOMException) on retrieval readonly attribute unsigned short nodeType; readonly attribute Node parentNode; readonly attribute NodeList childNodes; readonly attribute Node firstChild; readonly attribute Node lastChild; readonly attribute Node previousSibling; readonly attribute Node nextSibling; readonly attribute NamedNodeMap attributes; readonly attribute Document ownerDocument; Node insertBefore(in Node newChild, in Node refChild) raises(DOMException); Node replaceChild(in Node newChild, in Node oldChild) raises(DOMException); Node removeChild(in Node oldChild) raises(DOMException); Node appendChild(in Node newChild) raises(DOMException); boolean hasChildNodes(); Node cloneNode(in boolean deep); };
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The following constants are not accessible by name:
ELEMENT_NODE
ATTRIBUTE_NODE
TEXT_NODE
CDATA_SECTION_NODE
ENTITY_REFERENCE_NODE
ENTITY_NODE
PROCESSING_INSTRUCTION_NODE
COMMENT_NODE
DOCUMENT_NODE
DOCUMENT_TYPE_NODE
DOCUMENT_FRAGMENT_NODE
NOTATION_NODE
V0009:
-
Definition group NodeType An integer indicating which type of node this is. Defined Constants ELEMENT_NODE The node is a Element. ATTRIBUTE_NODE The node is an Attr. TEXT_NODE The node is a Text node. CDATA_SECTION_NODE The node is a CDATASection. ENTITY_REFERENCE_NODE The node is an EntityReference. ENTITY_NODE The node is an Entity. PROCESSING_INSTRUCTION_NODE The node is a ProcessingInstruction. COMMENT_NODE The node is a Comment. DOCUMENT_NODE The node is a Document. DOCUMENT_TYPE_NODE The node is a DocumentType. DOCUMENT_FRAGMENT_NODE The node is a DocumentFragment. NOTATION_NODE The node is a Notation. The values of nodeName, nodeValue, and attributes vary according to the node type as follows: nodeName, nodeValue, attributes Element tagName, null, NamedNodeMap Attr name of attribute, value of attribute, null Text #text, content of the text node, null CDATASection #cdata-section, content of the CDATA Section, null EntityReference name of entity referenced, null, null Entity entity name, null, null ProcessingInstruction target, entire content excluding the target, null Comment #comment, content of the comment, null Document #document, null, null DocumentType document type name, null, null DocumentFragment #document-fragment, null, null Notation notation name, null, null
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The following constants are not supported:
ELEMENT_NODE
ATTRIBUTE_NODE
TEXT_NODE
CDATA_SECTION_NODE
ENTITY_REFERENCE_NODE
ENTITY_NODE
PROCESSING_INSTRUCTION_NODE
COMMENT_NODE
DOCUMENT_NODE
DOCUMENT_TYPE_NODE
DOCUMENT_FRAGMENT_NODE
NOTATION_NODE
A document type declaration is treated as a Comment object instead of a DocumentType object
V0010:
-
Attribute nodeName The name of this node, depending on its type; see the table above.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The nodeName property returns uppercase values except for elements with names that resemble namespaces (such as <test:elementName>) when a proprietary namespace has been declared. In this case, the nodeName property drops the element prefixes and does not return uppercase values.
V0011:
-
Attribute parentNode The parent of this node. All nodes, except Document, DocumentFragment, and Attr may have a parent. However, if a node has just been created and not yet added to the tree, or if it has been removed from the tree, this is null.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
When an element without a parent has child nodes, an HTMLDocument object is created and set as the parent of that element.
V0012:
-
Attribute childNodes A NodeList that contains all children of this node. If there are no children, this is a NodeList containing no nodes. The content of the returned NodeList is "live" in the sense that, for instance, changes to the children of the node object that it was created from are immediately reflected in the nodes returned by the NodeList accessors; it is not a static snapshot of the content of the node. This is true for every NodeList, including the ones returned by the getElementsByTagName method.
All Document Modes (Internet Explorer 8)
Splitting multiple text nodes under an element using the splitText method can cause the childNodes collection update to be delayed. Other tree modifications cause the childNodes collection to synchronize again.
V0013:
-
Method insertBefore Inserts the node newChild before the existing child node refChild. If refChild is null, insert newChild at the end of the list of children. If newChild is a DocumentFragment object, all of its children are inserted, in the same order, before refChild. If the newChild is already in the tree, it is first removed. Parameters newChild The node to insert. refChild The reference node, i.e., the node before which the new node must be inserted. Return Value The node being inserted. Exceptions DOMException HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to insert is one of this node's ancestors. WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node. NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. NOT_FOUND_ERR: Raised if refChild is not a child of this node.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The conditions to trigger the exceptions
HIERARCHY_REQUEST_ERR and WRONG_DOCUMENT_ERR both result in an HRESULT 0x80070057,
which creates a JavaScript Error message
"Invalid argument."
The following elements cause an exception when trying to dynamically insert or append new nodes:
APPLET
AREA
BASE
BGSOUND
BR
COL
COMMENT
EMBED
FRAME
HR
IFRAME
IMG
INPUT
ISINDEX
LINK
META
NEXTID
NOEMBED
NOFRAMES
NOSCRIPT
OBJECT
PARAM
SCRIPT
STYLE
WBR
V0014:
-
Method replaceChild Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node. If the newChild is already in the tree, it is first removed. Parameters newChild The new node to put in the child list. oldChild The node being replaced in the list. Return Value The node replaced. Exceptions DOMException HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or it the node to put in is one of this node's ancestors. WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node. NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. NOT_FOUND_ERR: Raised if oldChild is not a child of this node.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The conditions to trigger HIERARCHY_REQUEST_ERR,
WRONG_DOCUMENT_ERR, and NOT_FOUND_ERR all result in an HRESULT 0x80070057,
which creates a JavaScript Error message
"Invalid argument."
V0015:
-
Method removeChild Removes the child node indicated by oldChild from the list of children, and returns it. Parameters oldChild The node being removed. Return Value The node removed. Exceptions DOMException NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. NOT_FOUND_ERR: Raised if oldChild is not a child of this node.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
If the child node indicated by the oldChild parameter
is not from the list of child nodes, the removeChild method of the Node
interface raises a JSError exception with an error message of
"Invalid argument"and an HRESULT of 0x80070057
.
V0016:
-
Method appendChild Adds the node newChild to the end of the list of children of this node. If the newChild is already in the tree, it is first removed. Parameters newChild The node to add. If it is a DocumentFragment object, the entire contents of the document fragment are moved into the child list of this node Return Value The node added. Exceptions DOMException HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to append is one of this node's ancestors. WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node. NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The conditions to trigger HIERARCHY_REQUEST_ERR and
WRONG_DOCUMENT_ERR both result in an HRESULT 0x80070057,
which creates a JavaScript Error message "Invalid argument."
The following elements cause an exception when trying to dynamically insert or append new nodes:
APPLET
AREA
BASE
BGSOUND
BR
COL
COMMENT
EMBED
FRAME
HR
IFRAME
IMG
INPUT
ISINDEX
LINK
META
NEXTID
NOEMBED
NOFRAMES
NOSCRIPT
OBJECT
PARAM
SCRIPT
STYLE
WBR
V0017:
-
Method setNamedItem Adds a node using its nodeName attribute. As the nodeName attribute is used to derive the name which the node must be stored under, multiple nodes of certain types (those that have a "special" string value) cannot be stored as the names would clash. This is seen as preferable to allowing nodes to be aliased. Parameters arg A node to store in a named node map. The node will later be accessible using the value of the nodeName attribute of the node. If a node with that name is already present in the map, it is replaced by the new one. Return Value If the new Node replaces an existing node with the same name the previously existing Node is returned, otherwise null is returned. Exceptions DOMException WRONG_DOCUMENT_ERR: Raised if arg was created from a different document than the one that created the NamedNodeMap. NO_MODIFICATION_ALLOWED_ERR: Raised if this NamedNodeMap is readonly. INUSE_ATTRIBUTE_ERR: Raised if arg is an Attr that is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The following variations apply:
The WRONG_DOCUMENT_ERR exception is not raised if the arg parameter was created from a document other than the one that created NamedNodeMap.
Instead of the INUSE_ATTRIBUTE_ERR exception, if arg is an Attr that is already an attribute of another Element object, the setNamedItem method of the Node interface raises a JSError exception with an error message of "Invalid argument"and an HRESULT of
0x80070057
.
V0018:
-
Method item Returns the indexth item in the map. If index is greater than or equal to the number of nodes in the map, this returns null. Parameters index Index into the map. Return Value The node at the indexth position in the NamedNodeMap, or null if that is not a valid index. This method raises no exceptions.
Quirks Mode and IE7 Mode (All Versions)
Instead of returning null when the index parameter is
greater than the number of nodes in the map, the item method of the Node
interface throws a JSError exception with an error message of "Invalid argument"
and an HRESULT of 0x80070057
.
V0019:
-
Method substringData Extracts a range of data from the node. Parameters offset Start offset of substring to extract. count The number of characters to extract. Return Value The specified substring. If the sum of offset and count exceeds the length, then all characters to the end of the data are returned. Exceptions DOMException INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of characters in data, or if the specified count is negative. DOMSTRING_SIZE_ERR: Raised if the specified range of text does not fit into a DOMString.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The following variations apply:
No exception is raised if the offset is greater than the number of 16-bit units in the data.
Instead of the INDEX_SIZE_ERR DOMException, if the specified offset is negative or greater than the number of characters in the data or the specified count is negative, the substringData method of the Node interface raises a JScript Error exception with an error message of "Invalid argument"and an HRESULT of
0x80070057
.
V0020:
-
Attribute specified If this attribute was explicitly given a value in the original document, this is true; otherwise, it is false. Note that the implementation is in charge of this attribute, not the user. If the user changes the value of the attribute (even if it ends up having the same value as the default value) then the specified flag is automatically flipped to true. To re-specify the attribute as the default value from the DTD, the user must delete the attribute. The implementation will then make a new attribute available with specified set to false and the default value (if one exists). In summary: - If the attribute has an assigned value in the document then specified is true, and the value is the assigned value. - If the attribute has no assigned value in the document and has a default value in the DTD, then specified is false, and the value is the default value in the DTD.
Quirks Mode and IE7 Mode (All Versions)
The value of the specified attribute is not automatically flipped when the associated attribute is changed.
V0022:
-
Attribute tagName The name of the element. For example, in: <elementExample id="demo"> ... </elementExample> ,tagName has the value "elementExample". Note that this is case- preserving in XML, as are all of the operations of the DOM. The HTML DOM returns the tagName of an HTML element in the canonical uppercase form, regardless of the case in the source HTML document.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The tagName property returns uppercase values except for elements with names that resemble namespaces (such as <test:elementName>) when a proprietary namespace has been declared. In this case, the tagName property drops the element prefixes and does not return uppercase values.
V0023:
-
Method getAttribute Retrieves an attribute value by name. Parameters name The name of the attribute to retrieve. Return Value The Attr value as a string, or the empty string if that attribute does not have a specified or default value. This method raises no exceptions.
Quirks Mode and IE7 Mode (All Versions)
The getAttribute method supports a second parameter
called iFlags. The iFlags parameter controls case sensitivity and
object interpolation. By default, iFlags is set to 0
, which indicates that the property search done by the
getAttribute method is not case-sensitive and returns an interpolated
value if the property is found.
V0024:
-
Method setAttribute Adds a new attribute. If an attribute with that name is already present in the element, its value is changed to be that of the value parameter. This value is a simple string, it is not parsed as it is being set. So any markup (such as syntax to be recognized as an entity reference) is treated as literal text, and needs to be appropriately escaped by the implementation when it is written out. In order to assign an attribute value that contains entity references, the user must create an Attr node plus any Text and EntityReference nodes, build the appropriate subtree, and use setAttributeNode to assign it as the value of an attribute. Parameters name The name of the attribute to create or alter. value Value to set in string form. Exceptions DOMException INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character. NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. This method returns nothing.
Quirks Mode and IE7 Mode (All Versions)
The following variations apply:
The setAttribute method assigns attributes in a case-sensitive manner (expected case-insensitive for HTML).
The second parameter of the setAttribute method accepts only strings, not objects. An optional third parameter controls case sensitivity.
Attributes that apply a boolean initial state to the associated DOM properties (for example, value and checked) are incorrectly associated with their live property rather than their default property. For example, the setAttribute method ('checked', 'checked') toggles the DOM checked property (the live view of a check box) rather than the defaultChecked property (initial value).
The HTML style attribute and attributes that are event handlers do not apply their conditions when used with setAttribute.
The setAttribute method requires DOM property names to apply effects for certain attribute names, such as className (instead of 'class'), htmlFor (instead of 'for'), and httpEquiv (instead of 'http-equiv').
V0025:
-
Method removeAttribute Removes an attribute by name. If the removed attribute has a default value it is immediately replaced. Parameters name The name of the attribute to remove. Exceptions DOMException NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. This method returns nothing.
Quirks Mode and IE7 Mode (All Versions)
The following variations apply:
The removeAttribute method supports an additional parameter called iCaseSensitive. The iCaseSensitive parameter specifies whether to use a case-sensitive search to find the attribute. Removal of event handler attributes (such as onClick) or the style attribute does not cause the actual event handler to be removed, or the inline style to be removed.
Default attributes are not re-created after the attribute is removed.
IE7 Mode, IE8 Mode, IE9 Mode, IE10 Mode, and IE11 Mode (All Versions)
The following variations apply:
The removeAttribute method of the Element interface exists on CSSStyleDeclaration objects that are used for inline styles, runtime styles, and style rules.
The removeAttribute method returns a Boolean value that indicates whether the operation has succeeded or failed. The removeAttribute method is also available on the following objects: element.currentStyle, element.runtimeStyle, element.style, and stylesheet.style.
V0026:
-
Method removeAttributeNode Removes the specified attribute. Parameters oldAttr The Attr node to remove from the attribute list. If the removed Attr has a default value it is immediately replaced. Return Value The Attr node that was removed. Exceptions DOMException NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. NOT_FOUND_ERR: Raised if oldAttr is not an attribute of the element.
Quirks Mode and IE7 Mode (All Versions)
Default attributes are not re-created after an attribute is removed with the removeAttributeNode method. Removal of event handler attributes (such as onclick) or the style attribute does not cause the actual event handler or the inline style to be removed.
V0027:
-
Method getElementsByTagName Returns a NodeList of all descendant elements with a given tag name, in the order in which they would be encountered in a preorder traversal of the Element tree. Parameters name The name of the tag to match on. The special value "*" matches all tags. Return Value A list of matching Element nodes. This method raises no exceptions.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The following variations apply:
When called on an object element, where the value "*" is passed in as the value of the name parameter, the getElementsByTagName method returns an empty NodeList.
When called on an OBJECT element, where
param
is passed in as the value of the name parameter, the getElementsByTagName method returns a NodeList that contains all the PARAM elements in the document.
V0028:
-
Method splitText Breaks this Text node into two Text nodes at the specified offset, keeping both in the tree as siblings. This node then only contains all the content up to the offset point. And a new Text node, which is inserted as the next sibling of this node, contains all the content at and after the offset point. Parameters offset The offset at which to split, starting from 0. Return Value The new Text node. Exceptions DOMException INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of characters in data. NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
Quirks Mode, IE7 Mode, and IE8 Mode (All Versions)
The offset parameter is treated as though it is optional. If no offset is provided, then a default offset of 0 is used.
All Document Modes (Internet Explorer 8)
The childNodes objects are kept in a cache and are invalidated whenever there is a modification to the markup. Calling the splitText method of the Text interface does not trigger a markup modification. The childNodes collection does not show changes made by splitText until the markup is modified, for example, by changing the text of a DIV element anywhere on the page.