Javascript and HTML: Async Communication Prototype

In this article I go over an asynchronous communication prototype I had made in straight Javascript that you use to POST to a server script and pass along the response to a Javascript function specified by the initial call to the prototype. The main benefit here is that you don’t need a full page refresh, which is great for implementing web interfaces that have an application feel to them. It doesn’t use any bulky libraries and should work on all browsers. An ideal use case for this would be websites hosted in an internal network that you wanted to act like an application. Though, with extensive modification you could add security features or just run it through https with proper verification code in the PHP script.

The example code is located on GitHub.

https://www.youtube.com/watch?v=73yU2jtaVBo

In my example I have four files:

  • example.html = the html page that gives the user two buttons that fire off asynchronous calls to a server side script.
  • AsyncManager.js = The prototype (aka. class) that handles communication and response. It also updates a div element with status information.
  • asyncreceiver.php = The server side script written in PHP that handles two example requests from our AsyncManager.js. In this case it sends back a timestamp or random number in a requested range.
  • example.js = The client page script that starts the request and handles the final response from the two example requests.

Here is the AsyncManager.js:


function AsyncManager(htmlStatusElement, onCompleteFunction, serverPostScript, sendDataPairs) {
    this.htmlStatusElement = htmlStatusElement;
    this.onCompleteFunction = onCompleteFunction || function() {};
    var thisInstance = this; // save a reference to this instance for callback
    this.serverPostScript = serverPostScript;
    this.sendDataPairs = sendDataPairs;

    // this handles updating the status element
    this.statusIndicator = function(statusText) {
        // make sure an element reference was returned before trying to set properties
        if (this.htmlStatusElement != null && this.htmlStatusElement != "") {
            document.getElementById(this.htmlStatusElement).innerHTML = statusText;
        }
    };

    // creates an instance of XMLHttpRequest independent of the browser type
    this.returnNewXMLhttpRequestObject = function() {
        var xhrObject = null;
        // see what type of browser is being used
        if (window.XMLHttpRequest) {
            // non MS browsers
            xhrObject = new XMLHttpRequest();
            try {
                xhrObject.overrideMimeType('text/xml');
            } catch (error) {}
        } else if (window.ActiveXObject) {
            try {
                // some versions of IE need special access
                // first attempt to use the newer object
                xhrObject = new ActiveXObject('Msxml2.XMLHTTP');
            } catch (error) {
                // newer version isn't available, try older
                try {
                    // if the newer object doesn't exist, use the older one
                    xhrObject = new ActiveXObject('Microsoft.XMLHTTP');
                } catch (error) {
                    // this IE browser is too old to work, notify the user
                    thisInstance.statusIndicator('Your version of IE is too old.');
                }
            }
        }
        return xhrObject;
    };

    // send data to a server using the attached xml http request object
    this.sendData = function() {
        var constructedPostString = '';
        var sendDataLength = this.sendDataPairs.length;
        thisInstance.httpRequest = this.returnNewXMLhttpRequestObject();
        // make sure an instance was returned before doing anything else
        if (thisInstance.httpRequest != null) {
            // assign the event handler so we can know how return data should be processed
            // if the caller wants to use a custom event handler, let them
            thisInstance.httpRequest.onreadystatechange = function() {
                // the response from the server is complete, continue processing
                if (thisInstance.httpRequest.readyState == 4) {
                    // everything is good, the response is received
                    if (thisInstance.httpRequest.status == 200) {
                        // call the function the instance creater defined and pass the resulting xml
                        thisInstance.onCompleteFunction(thisInstance.httpRequest.responseXML.documentElement);
                        thisInstance.statusIndicator('');
                        // the object is no longer needed, so allow it to be destroyed
                        thisInstance.httpRequest = null;
                    } else {
                        // there was a problem with the request,
                        // for example the response may be a 404 (Not Found)
                        // or 500 (Internal Server Error) response codes
                        thisInstance.statusIndicator('There is an issue connecting to the server...');
                    }
                } else {
                    // still not ready, indicate that to the user
                    thisInstance.statusIndicator('Loading...');
                }
            };
        } else {
            this.statusIndicator('There was an issue connecting to the server...');
        }

        // make sure the connection instance exists before trying to send data
        if (thisInstance.httpRequest != null) {
            // open the connection so we can stream post data to a page
            thisInstance.httpRequest.open('POST', serverPostScript, true);
            thisInstance.httpRequest.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
            // make sure the array holds enough values to process it
            if (sendDataLength > 1) {
                // loop through the array by two (name of post variable + related post data, ...)
                for (var i = 0; i < sendDataLength - 2; i += 2) {
                    constructedPostString += this.sendDataPairs[i]
                        + '=' + escape(this.sendDataPairs[i + 1]) + '&';
                }
                constructedPostString += this.sendDataPairs[sendDataLength - 2]
                    + '=' + escape(this.sendDataPairs[sendDataLength - 1]);
            }
            // send the data to the script page for processing
            thisInstance.httpRequest.send(constructedPostString);
        }
    };

    // now that the instance is initialized, perform the send/receive function
    this.sendData();
}

Here are a pair of functions from example.js that call and receive from AsyncManager:


// a function to test async capability of our AsyncManager prototype
function getAsyncTimestamp() {
    // define our request to the server script
    var postDataArray = [];
    postDataArray.push('action');
    postDataArray.push('get-timestamp');

    // get the needed information
    new AsyncManager('statusdiv',
                     getAsyncTimestamp_callback,
                     'asyncreceiver.php',
                     postDataArray);
}

function getAsyncTimestamp_callback(xmlDataReturned) {
    // called once getAsyncTimestamp() gets a response back from the script
    // extract the expected response tag
    if (xmlDataReturned != null) {
        var returnedValue = xmlDataReturned.getElementsByTagName('responsedata')[0].childNodes[0].nodeValue;
        if (returnedValue != null) {
            document.getElementById('divtimestampresult').innerHTML = returnedValue;
        }
    } else {
        document.getElementById('statusdiv').innerHTML = "There was an issue with the response.";
    }
}