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

You are here: Reference > JavaScript > client-side > xml handling > properties > async (XMLDocument)

async property (XMLDocument)

Browser support:

Specifies or retrieves whether downloading an XML file should be performed asynchronously or not.

An XML file can be downloaded with the load method of the XMLDocument object.

In case of synchronous loading, the load method does not return until the download is complete. After the load method returns and the returned value is true, you can start working with the downloaded XML file. See Example 1 for details.
In case of asynchronous loading, the load method starts the download in the background and returns. You must register an event handler to be informed about the state of the download. In Internet Explorer, use the onreadystatechange property, in Firefox, Opera, Google Chrome and Safari, use the addEventListener method to register the event handler for the 'load' event. See Example 2 for details.

The load method of the XMLDocument object is not supported by Google Chrome and Safari. If you need a cross-browser solution for downloading and opening XML files, use the XMLHttpRequest object. The open method of the XMLHttpRequest object is similar to the load method of the XMLDocument object.

Syntax:

object.async;

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

This property is read/write.

Possible values:

Boolean, one of the following values:

false

The caller gets the control back only after the download is complete.

true

The caller gets the control back before the download is complete.

Default: this property has no default value.

Example HTML code 1:

This example shows how to use an external XML file to insert data into a table:

Code

ajax.js

news.xml

<head>
    <script type="text/javascript" src="ajax.js"></script>
    
    <script type="text/javascript">
        function FillTable () {
            var xmlDoc = CreateXMLDocumentObject ();    // defined in ajax.js
            if (!xmlDoc) {
                return;
            }

            if (typeof (xmlDoc.load) === "undefined") { // Google Chrome and Safari
                alert ("Your browser does not support the load method for XML documents!");
                return;
            }

            var url = "news.xml";
            xmlDoc.async = false;
            
            if (xmlDoc.load (url)) {
                var resTable = document.getElementById ("resTable");
                var xmlNodes = ["title", "description", "pubDate", "link"];

                var itemTags = xmlDoc.getElementsByTagName ("item");
                for (i = 0; i < itemTags.length; i++) {
                    resTable.insertRow (i);
                    for (j = 0; j < xmlNodes.length; j++) {
                        var recordNode = itemTags[i].getElementsByTagName (xmlNodes[j])[0];
                        resTable.rows[i].insertCell (j);
                        if ('textContent' in recordNode)
                            resTable.rows[i].cells[j].innerHTML = recordNode.textContent;
                        else
                            resTable.rows[i].cells[j].innerHTML = recordNode.text;
                    }
                }
            }
            else {
                    // display error message
                var errorMsg = null;
                if (xmlDoc.parseError && xmlDoc.parseError.errorCode != 0) {
                    errorMsg = "XML Parsing Error: " + xmlDoc.parseError.reason
                              + " at line " + xmlDoc.parseError.line
                              + " at position " + xmlDoc.parseError.linepos;
                }
                else {
                    if (xmlDoc.documentElement) {
                        if (xmlDoc.documentElement.nodeName == "parsererror") {
                            errorMsg = xmlDoc.documentElement.childNodes[0].nodeValue;
                        }
                    }
                }
                if (errorMsg) {
                    alert (errorMsg);
                }
                else {
                    alert ("There was an error while loading XML file!");
                }
            }
        }
    </script>
</head>
<body onload="FillTable ()">
    <table border="1px">
        <thead style="font-weight: bold;">
            <tr>
                <td>Title</td>
                <td>Description</td>
                <td>PubDate</td>
                <td>Link</td>
            </tr>
        </thead>
        <tbody id="resTable">
        </tbody>
    </table>
</body>


function CreateHTTPRequestObject () {
        // although IE supports the XMLHttpRequest object, but it does not work on local files.
    var forceActiveX = (window.ActiveXObject && location.protocol === "file:");
    if (window.XMLHttpRequest && !forceActiveX) {
        return new XMLHttpRequest();
    }
    else {
        try {
            return new ActiveXObject("Microsoft.XMLHTTP");
        } catch(e) {}
    }
    alert ("Your browser doesn't support XML handling!");
    return null;
}

function CreateMSXMLDocumentObject () {
    if (typeof (ActiveXObject) != "undefined") {
        var progIDs = [
                        "Msxml2.DOMDocument.6.0", 
                        "Msxml2.DOMDocument.5.0", 
                        "Msxml2.DOMDocument.4.0", 
                        "Msxml2.DOMDocument.3.0", 
                        "MSXML2.DOMDocument", 
                        "MSXML.DOMDocument"
                      ];
        for (var i = 0; i < progIDs.length; i++) {
            try { 
                return new ActiveXObject(progIDs[i]); 
            } catch(e) {};
        }
    }
    return null;
}

function CreateXMLDocumentObject (rootName) {
    if (!rootName) {
        rootName = "";
    }
    var xmlDoc = CreateMSXMLDocumentObject ();
    if (xmlDoc) {
        if (rootName) {
            var rootNode = xmlDoc.createElement (rootName);
            xmlDoc.appendChild (rootNode);
        }
    }
    else {
        if (document.implementation.createDocument) {
            xmlDoc = document.implementation.createDocument ("", rootName, null);
        }
    }
    
    return xmlDoc;
}

function ParseHTTPResponse (httpRequest) {
    var xmlDoc = httpRequest.responseXML;

            // if responseXML is not valid, try to create the XML document from the responseText property
    if (!xmlDoc || !xmlDoc.documentElement) {
        if (window.DOMParser) {
            var parser = new DOMParser();
            try {
                xmlDoc = parser.parseFromString (httpRequest.responseText, "text/xml");
            } catch (e) {
                alert ("XML parsing error");
                return null;
            };
        }
        else {
            xmlDoc = CreateMSXMLDocumentObject ();
            if (!xmlDoc) {
                return null;
            }
            xmlDoc.loadXML (httpRequest.responseText);

        }
    }

            // if there was an error while parsing the XML document
    var errorMsg = null;
    if (xmlDoc.parseError && xmlDoc.parseError.errorCode != 0) {
        errorMsg = "XML Parsing Error: " + xmlDoc.parseError.reason
                  + " at line " + xmlDoc.parseError.line
                  + " at position " + xmlDoc.parseError.linepos;
    }
    else {
        if (xmlDoc.documentElement) {
            if (xmlDoc.documentElement.nodeName == "parsererror") {
                errorMsg = xmlDoc.documentElement.childNodes[0].nodeValue;
            }
        }
    }
    if (errorMsg) {
        alert (errorMsg);
        return null;
    }

        // ok, the XML document is valid
    return xmlDoc;
}

    // returns whether the HTTP request was successful
function IsRequestSuccessful (httpRequest) {
        // IE: sometimes 1223 instead of 204
    var success = (httpRequest.status == 0 || 
        (httpRequest.status >= 200 && httpRequest.status < 300) || 
        httpRequest.status == 304 || httpRequest.status == 1223);
    
    return success;
}

<?xml version="1.0" encoding="utf-8"?>
<news>
    <channel>
        <item>
            <title>Paula Abdul leaves American Idol</title>
            <description>Paula Abdul has officially confirmed that she won’t be returning to American Idol this season. "With sadness in my heart, I’ve decided not to return to Idol," she wrote on her Twitter page.</description>
            <pubDate>Wed, August 5, 2009 19:52:31 +0200</pubDate>
            <link>http://www.tribute.ca/news/index.php/its-official-paula-abdul-leaves-american-idol/2009/08/05/</link>
        </item>

        <item>
            <title>Criminal Minds star Moore hit by car</title>
            <description>Shemar Moore, 39, who plays FBI Agent Derek Morgan in the CBS drama Criminal Minds, was hit by a car while bicycling in Los Angeles last Saturday.</description>
            <pubDate>Thu, August 4, 2009 13:28:12 +0200</pubDate>
            <link>http://www.tribute.ca/news/index.php/criminal-minds-star-moore-hit-by-car/2009/08/04/</link>
        </item>

        <item>
            <title>Madonna writes love song for ex-husband</title>
            <description>Madonna has sparked speculation that she wants to get back with her ex-husband, Guy Ritchie, after writing a love song for him in which she calls him her "eternal love".</description>
            <pubDate>Fri, July 31, 2009 04:01:50 +0200</pubDate>
            <link>http://www.tribute.ca/news/index.php/madonna-writes-love-song-for-ex-husband/2009/07/31/</link>
        </item>
    </channel>
</news>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

Example HTML code 2:

This example is similar to the previous one, but it uses asynchronous loading:

Code

ajax.js

news.xml

<head>
    <script type="text/javascript" src="ajax.js"></script>
    
    <script type="text/javascript">
        var xmlDoc = null;

        function LoadXML () {
            xmlDoc = CreateXMLDocumentObject ();    // defined in ajax.js
            if (!xmlDoc) {
                return;
            }

            if (typeof (xmlDoc.load) === "undefined") { // Google Chrome and Safari
                alert ("Your browser does not support the load method for XML documents!");
                return;
            }

            var url = "news.xml";
            xmlDoc.async = true;
            if (xmlDoc.addEventListener) {  // all browsers except IE
                xmlDoc.addEventListener("load", OnLoadXML, false);
            }
            else {  // IE
                xmlDoc.onreadystatechange = OnStateChange;
            }
            xmlDoc.load (url);
        }

        function OnLoadXML () {
            FillTable ();
        }

        function OnStateChange () {
            if (xmlDoc.readyState == 0 || xmlDoc.readyState == 4) {
                FillTable ();
            }
        }

        function FillTable () {
            var errorMsg = null;
            if (xmlDoc.parseError && xmlDoc.parseError.errorCode != 0) {
                errorMsg = "XML Parsing Error: " + xmlDoc.parseError.reason
                          + " at line " + xmlDoc.parseError.line
                          + " at position " + xmlDoc.parseError.linepos;
            }
            else {
                if (xmlDoc.documentElement) {
                    if (xmlDoc.documentElement.nodeName == "parsererror") {
                        errorMsg = xmlDoc.documentElement.childNodes[0].nodeValue;
                    }
                }
            }
            if (errorMsg) {
                alert (errorMsg);
                return null;
            }

            var resTable = document.getElementById ("resTable");
            var xmlNodes = ["title", "description", "pubDate", "link"];

            var itemTags = xmlDoc.getElementsByTagName ("item");
            for (i = 0; i < itemTags.length; i++) {
                resTable.insertRow (i);
                for (j = 0; j < xmlNodes.length; j++) {
                    var recordNode = itemTags[i].getElementsByTagName (xmlNodes[j])[0];
                    resTable.rows[i].insertCell (j);
                    if ('textContent' in recordNode)
                        resTable.rows[i].cells[j].innerHTML = recordNode.textContent;
                    else
                        resTable.rows[i].cells[j].innerHTML = recordNode.text;
                }
            }
        }
    </script>
</head>
<body onload="LoadXML ()">
    <table border="1px">
        <thead style="font-weight: bold;">
            <tr>
                <td>Title</td>
                <td>Description</td>
                <td>PubDate</td>
                <td>Link</td>
            </tr>
        </thead>
        <tbody id="resTable">
        </tbody>
    </table>
</body>


function CreateHTTPRequestObject () {
        // although IE supports the XMLHttpRequest object, but it does not work on local files.
    var forceActiveX = (window.ActiveXObject && location.protocol === "file:");
    if (window.XMLHttpRequest && !forceActiveX) {
        return new XMLHttpRequest();
    }
    else {
        try {
            return new ActiveXObject("Microsoft.XMLHTTP");
        } catch(e) {}
    }
    alert ("Your browser doesn't support XML handling!");
    return null;
}

function CreateMSXMLDocumentObject () {
    if (typeof (ActiveXObject) != "undefined") {
        var progIDs = [
                        "Msxml2.DOMDocument.6.0", 
                        "Msxml2.DOMDocument.5.0", 
                        "Msxml2.DOMDocument.4.0", 
                        "Msxml2.DOMDocument.3.0", 
                        "MSXML2.DOMDocument", 
                        "MSXML.DOMDocument"
                      ];
        for (var i = 0; i < progIDs.length; i++) {
            try { 
                return new ActiveXObject(progIDs[i]); 
            } catch(e) {};
        }
    }
    return null;
}

function CreateXMLDocumentObject (rootName) {
    if (!rootName) {
        rootName = "";
    }
    var xmlDoc = CreateMSXMLDocumentObject ();
    if (xmlDoc) {
        if (rootName) {
            var rootNode = xmlDoc.createElement (rootName);
            xmlDoc.appendChild (rootNode);
        }
    }
    else {
        if (document.implementation.createDocument) {
            xmlDoc = document.implementation.createDocument ("", rootName, null);
        }
    }
    
    return xmlDoc;
}

function ParseHTTPResponse (httpRequest) {
    var xmlDoc = httpRequest.responseXML;

            // if responseXML is not valid, try to create the XML document from the responseText property
    if (!xmlDoc || !xmlDoc.documentElement) {
        if (window.DOMParser) {
            var parser = new DOMParser();
            try {
                xmlDoc = parser.parseFromString (httpRequest.responseText, "text/xml");
            } catch (e) {
                alert ("XML parsing error");
                return null;
            };
        }
        else {
            xmlDoc = CreateMSXMLDocumentObject ();
            if (!xmlDoc) {
                return null;
            }
            xmlDoc.loadXML (httpRequest.responseText);

        }
    }

            // if there was an error while parsing the XML document
    var errorMsg = null;
    if (xmlDoc.parseError && xmlDoc.parseError.errorCode != 0) {
        errorMsg = "XML Parsing Error: " + xmlDoc.parseError.reason
                  + " at line " + xmlDoc.parseError.line
                  + " at position " + xmlDoc.parseError.linepos;
    }
    else {
        if (xmlDoc.documentElement) {
            if (xmlDoc.documentElement.nodeName == "parsererror") {
                errorMsg = xmlDoc.documentElement.childNodes[0].nodeValue;
            }
        }
    }
    if (errorMsg) {
        alert (errorMsg);
        return null;
    }

        // ok, the XML document is valid
    return xmlDoc;
}

    // returns whether the HTTP request was successful
function IsRequestSuccessful (httpRequest) {
        // IE: sometimes 1223 instead of 204
    var success = (httpRequest.status == 0 || 
        (httpRequest.status >= 200 && httpRequest.status < 300) || 
        httpRequest.status == 304 || httpRequest.status == 1223);
    
    return success;
}

<?xml version="1.0" encoding="utf-8"?>
<news>
    <channel>
        <item>
            <title>Paula Abdul leaves American Idol</title>
            <description>Paula Abdul has officially confirmed that she won’t be returning to American Idol this season. "With sadness in my heart, I’ve decided not to return to Idol," she wrote on her Twitter page.</description>
            <pubDate>Wed, August 5, 2009 19:52:31 +0200</pubDate>
            <link>http://www.tribute.ca/news/index.php/its-official-paula-abdul-leaves-american-idol/2009/08/05/</link>
        </item>

        <item>
            <title>Criminal Minds star Moore hit by car</title>
            <description>Shemar Moore, 39, who plays FBI Agent Derek Morgan in the CBS drama Criminal Minds, was hit by a car while bicycling in Los Angeles last Saturday.</description>
            <pubDate>Thu, August 4, 2009 13:28:12 +0200</pubDate>
            <link>http://www.tribute.ca/news/index.php/criminal-minds-star-moore-hit-by-car/2009/08/04/</link>
        </item>

        <item>
            <title>Madonna writes love song for ex-husband</title>
            <description>Madonna has sparked speculation that she wants to get back with her ex-husband, Guy Ritchie, after writing a love song for him in which she calls him her "eternal love".</description>
            <pubDate>Fri, July 31, 2009 04:01:50 +0200</pubDate>
            <link>http://www.tribute.ca/news/index.php/madonna-writes-love-song-for-ex-husband/2009/07/31/</link>
        </item>
    </channel>
</news>