In order to access this site you need to enable JavaScript!

You are here: Reference > JavaScript > client-side > HTML DOM > methods > compareDocumentPosition

compareDocumentPosition method

Browser support:

9

Compares the placement of the specified node with the current node in the DOM hierarchy.

With this method, both element nodes and attribute nodes can be compared and the nodes may belong to different documents.

Another possibility to compare the placement of two element nodes is to use the compareBoundaryPoints method. Create Range objects from the elements first (see the createRange, selectNode and selectNodeContents methods) and use the compareBoundaryPoints method on them.

The compareDocumentPosition method is supported in Internet Explorer from version 9. In older versions, you can use the contains method that retrieves whether an element contains another element. If you need a complex comparison method for elements in Internet Explorer, create TextRange objects from the elements first (see the createTextRange and moveToElementText methods) and use the compareEndPoints method on them.

Syntax:

object.compareDocumentPosition (nodeToCompare);

You can find the related objects in the Supported by objects section below.

Parameters:

nodeToCompare

Required. Reference to the node to compare.

Return value:

Integer that retrieves the placement of the specified node relative to the current node in the DOM hierarchy.

Predefined constants are available for the possible returned values, in the scope of the <a href='/lagstsiq.php/#Node'>Node</a> interface. You can use them directly through the Node; interface (Node.DOCUMENT_POSITION_FOLLOWING) or through an instance of the Node object.

The return value can be a combination of the following values (the value of a predefined constant appears in parentheses after the constant in hexadecimal form):

DOCUMENT_POSITION_DISCONNECTED (0x0001)	The specified and the current nodes have no common container node (e.g. they belong to different documents, or one of them is appended to any document, etc.).
DOCUMENT_POSITION_PRECEDING (0x0002)	The specified node precedes the current node.
DOCUMENT_POSITION_FOLLOWING (0x0004)	The specified node follows the current node.
DOCUMENT_POSITION_CONTAINS (0x0008)	The specified node contains the current node.
DOCUMENT_POSITION_CONTAINED_BY (0x0010)	The specified node is contained by the current node.
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (0x0020)	The specified and the current nodes have no common container node or the specified and the current nodes are different attributes of the same node. It means that when the DOCUMENT_POSITION_DISCONNECTED flag is set then the DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC flag is also set, furthermore the DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC flag is specified for two different attribute nodes of an element.

Example HTML code 1:

This example illustrates the use of the compareDocumentPosition method:

<head>
    <script type="text/javascript">
        function GetPlacementFlags (node1, node2) {
            var flags = [];
            var relation = node1.compareDocumentPosition (node2);
            if (relation & Node.DOCUMENT_POSITION_PRECEDING) {
                flags.push (" preceding");
            }
            if (relation & Node.DOCUMENT_POSITION_FOLLOWING) {
                flags.push (" following");
            }
            if (relation & Node.DOCUMENT_POSITION_CONTAINS) {
                flags.push (" contains");
            }
            if (relation & Node.DOCUMENT_POSITION_CONTAINED_BY) {
                flags.push (" contained by");
            }
            if (relation & Node.DOCUMENT_POSITION_DISCONNECTED) {
                flags.push (" disconnected");
            }
            if (relation & Node.DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
                flags.push (" implementation specific");
            }
            return flags.toString ();
        }

        function TestPlacement () {
            if (document.compareDocumentPosition) {
                var info = document.getElementById ("info");

                var container = document.getElementById ("container");
                var idAttr = container.getAttributeNode ("id");
                var alignAttr = container.getAttributeNode ("align");
                var firstChild = document.getElementById ("first");
                var secondChild = document.getElementById ("second");

                var flags = GetPlacementFlags (container, firstChild);
                info.innerHTML = "Comparing the 'First child' with the 'container': <b>" + flags + "</b>";
                var flags = GetPlacementFlags (firstChild, secondChild);
                info.innerHTML += "<br />Comparing the 'Second child' with the 'First child': <b>" + flags + "</b>";
                var flags = GetPlacementFlags (secondChild, container);
                info.innerHTML += "<br />Comparing the 'container' with the 'Second child': <b>" + flags + "</b>";
                var flags = GetPlacementFlags (idAttr, alignAttr);
                info.innerHTML += "<br />Comparing the 'align' attribute with the 'id' attribute: <b>" + flags + "</b>";
            }
            else {
                alert ("Your browser does not support the compareDocumentPosition method.");
            }
        }
    </script>
</head>
<body onload="TestPlacement ()">
    <div id="container" align="center">
        <div id="first">First child</div>
        <div id="second">Second child</div>
    </div>
    <br /><br />
    <div id="info" style="background-color:#c0e0d0;"></div>
</body>