importNode (W3C DOM Core method)

Spec
Version Depr. Static
DOM2 No No
Browser support (more…)
IE7 FF3+ SA1.3+ OP9+
None Full Buggy Buggy
Returns
Node
Throws
NOT_SUPPORTED_ERR

Example

var xmldoc = request.responseXML;

var node = document.importNode(xmldoc.getElementsByTagName('foo').item(0), true);

document.getElementsByTagName('body').item(0).appendChild(node);

The code above refers to the responseXML of an XMLHttpRequest, which itself is an an XML document. The example imports the first Element node called foo from that document — including its subtree — and then appends it to the body of this document.

CAUTION: importNode must be called on this document

Note that importNode must be called on this document, not the document you're importing from.

//THIS IS WRONG!
var node = xmldoc.importNode(xmldoc.getElementsByTagName('foo').item(0), true);

Doing so may cause some version of Safari to crash (see Compatibility notes below).

Arguments

node (Node) required

The node to import.

deep (Boolean) required

If true then the subtree underneath the specified node is also imported; if false then only the node itself is imported.

For Attr and EntityReference nodes this argument is ignored (see notes above). For Text, CDATASection, Comment, ProcessingInstruction and Notation nodes this argument is redundant because these types of node cannot have children.

Description

Imports a node from another document into this one, optionally including all its children. The imported node is owned by the importing document (ownerDocument is equal to document), and has no parent until it's attached.

The imported node can then be added to the document using Node methods such as appendChild or insertBefore.

The original node is not altered or removed from the document it came from — this method creates a copy of the node in this document. The new node has the same nodeName and nodeType as the original node, as well as any namespace information (prefix, localName and namespaceURI) if applicable.

Additional information is also copied as appropriate so that the new node mirrors the properties of the same type of node in this document (for example, if the node is an Element it will now have any default attributes that apply to that element in this document type).

Here are the specifics of behavior for each type of node:

Attr

The ownerElement is null and the specified property is true. The descendants of the attribute are imported recursively to form the same subtree as the original. The deep argument has no effect on attribute nodes — their children are always included when importing.

CDATASection
Comment
Text

These nodes are imported along with their data and length properties; the deep argument has no effect because these types of node cannot have children.

DocumentFragment

If the deep argument is true then the document fragment's subtree is imported intact; otherwise an empty DocumentFragment node is created.

Document
DocumentType

These types of node cannot be imported.

Element

Explicitly defined attributes are imported along with the element. Attributes which are not defined but have a default value in the original document are not included, but attributes which have a default value in this document are created and assigned to the imported element. If the deep argument is true then the element's subtree is also imported.

Entity

Although Entity nodes can be imported, they cannot be assigned to this document type, because DocumentType nodes are readonly. All properties of the original entity are imported (publicId, systemId and notationName); if the deep parameter is true then the subtree is also imported.

EntityReference

Only the entity reference itself is imported — its descendants are never included, even if the deep argument is true, because the original document and this document may defined the entity differently. If this document type has a definition for this entity name, its value is assigned.

Notation

Although Notation nodes can be imported, they cannot be assigned to this document type, because DocumentType nodes are readonly. All properties of the original notation are imported along with it (publicId and systemId); the deep parameter has no effect because Notation nodes cannot have children.

ProcessingInstruction

The processing instruction is imported along with its target and data properties; the deep parameter has no effect because ProcessingInstruction nodes cannot have children.

Return value

The new node in this document

Compatibility

Internet Explorer Firefox Safari Opera
5.5 6.0 7.0 1.5 2.0 3.0 1.3 2.0 3.0 9.0 9.5
None None None Buggy Buggy Full Buggy Buggy Buggy Buggy Buggy

Internet Explorer doesn't implement this method (it returns undefined).

Tip: importNode for Internet Explorer

A cross-browser recreation of importNode can be found in the ALA article Cross-Browser Scripting with importNode(), by Anthony Holdener. It doesn't actually import nodes — it re-creates them — but the end result is the same for most purposes.

In all supported browsers, event-handling attributes on imported elements are not active, and will need to be re-assigned.

Opera imports CDATASection nodes as Text nodes (ie. the node in this document has the nodeName #text and the nodeType 3).

Firefox 1.5 and 2 allow the import of Document and DocumentType nodes, an operation that should throw a DOMException (code 9: NOT_SUPPORTED_ERR code 9).

Safari won't import Attr or DocumentFragment nodes — it throws a DOMException as though the operation were not allowed (code 9: NOT_SUPPORTED_ERR code 9).

Additionally, Safari 3 in HTML mode1 won't import Element nodes from XML that isn't XHTML if the deep argument is true, with the same exception. It does work for XHTML. It also works for other XML if importNode is called on the document you're importing from, however ...

DANGER: Crash bug in Safari 1.3 and 2

In Safari 1.3 and 2, calling importNode on the document you're importing from (rather than this document), and with the deep parameter set to true, will cause the browser to crash.

Footnotes

1 On XHTML or HTML pages served as text/html.

User-contributed notes

There are no comments yet.

Related Products