taconite-client.js

Summary

This JavaScript file represents the core browser-side functionality supplied by Taconite. In general, the tools in this file wrap an instance of XMLHttpRequest object and provide utility methods for gather data from form elements to be sent to the server as par of an Ajax request.


Class Summary
AjaxRequest The AjaxRequest object wraps an instance of XMLHttpRequest and provides facilities for setting functions that are called before a request is made and after a request returns.

/**
 @fileoverview
 
 This JavaScript file represents the core browser-side functionality
 supplied by Taconite. In general, the tools in this file wrap an instance
 of XMLHttpRequest object and provide utility methods for gather data from
 form elements to be sent to the server as par of an Ajax request.
 */

var taconite_client_version="3.0";

/**
 Constructor for the AjaxRequest class. 
 
 <br><br>
 Example:
 
 <br><br>
 var ajaxRequest = new AjaxRequest("YOUR_URL");
 
 @class The AjaxRequest object wraps an instance of XMLHttpRequest and provides 
 facilities for setting functions that are called before a request is made
 and after a request returns. By default, AjaxRequest handles the server
 response by simply calling eval(), passing to it the responseText from 
 the XMLHttpRequestObject, of course assuming that the response was 
 generated by Taconite on the server side and that running eval() will 
 update the web page.<br><br>Example Usage:<br><br>var ajaxRequest = new AjaxRequest("YOUR_URL");
 <br>ajaxRequest.addFormElements("form_element_id_attribute_value-or-form_dom_element");
 <br>ajaxRequest.sendRequest();
 
 @constructor
 @param {String} a String repesenting the URL to which the Ajax request
 will be sent.
 */
function AjaxRequest(url) {
    /** @private */
    var self = this;
    
    /** @private */
    var xmlHttp = createXMLHttpRequest();
    
    /** @private */
    var queryString = "";
    
    /** @private */
    var requestURL = url;
    
    /** @private */
    var method = "GET";
    
    /** @private */
    var preRequest = null;
    
    /** @private */
    var postRequest = null;
    
    /** @private */
    var debugResponse = false;
    
    /** @private */
    var async = true;
    
    /** @private */
    var parser = new TaconiteParser();
    
    /** @private errorHandler*/ 
    var errorHandler = null;
    
    
    /**
     Return the instance of the XMLHttpRequest object wrapped by this object.
     @return XMLHttpRequest
     */
    this.getXMLHttpRequestObject = function() {
        return xmlHttp;
    }

    /**
     Return the parser that wil be used to parse the reponse to this request.
    */
    this.getParser = function() {
        return parser;
    }
    
    /** 
     @param {Parser} Set the parser that's used to parse the server's XML response,
     Deaults to the standard TaconiteParser class.
     */	
    this.setParser = function(newParser) {
        parser = newParser;
    }
    
    /**
     Set the pre-request function. This function will be called prior to 
     sending the Ajax request. The pre-request function is passed a reference
     to this AjaxRequest object.
     @param {Function} The function to be called prior to sending the Ajax
     request. The function has passed to it this AjaxRequest object.
     */
    this.setPreRequest = function(func) {
        preRequest = func;
    }
    
    /**
     Add a function to the list of pre request functions that will be called 
     before the request is sent to the server.  The pre request function has passed
     to it this AjaxRequest object.  This method is similar to setPreRequest, 
     except that method overwrites the previously existing pre request method,
     while this one adds a function to the list of functions.  Pre request functions
     are called in the order in which they were added.
     @param {Function} A function to be called prior to sending the Ajax
     request. The function has passed to it this AjaxRequest object.
    */
    this.addPreRequest = function(func) {
        var previous = preRequest;
        preRequest = function() {
            if(previous != null) {
                previous();
            }
            func();
        };
    }

    /**
     Set the post-request function. This function will be called after the
     response has been received and after the response XML has been parsed. 
     The post request function is passed a reference to this AjaxRequest object. 
     @param {Function} The function to be called after receiving the Ajax
     response. The function is passed a reference of this AjaxRequest object.
     */
    this.setPostRequest = function(func) {
        postRequest = func;
    }
    
    /**
     Add a function to the list of post request functions.  The post request
     functions are called in the order in which they were added.  This method is
     similar to setPostRequest, except that method overwrites any previous post
     request method.  This one adds to the list of functions that are called after
     the response has been received.
     @param {Function} A function to be called after receiving the Ajax
     response. The function is passed a reference of this AjaxRequest object.
    */
    this.addPostRequest = function(func) {
        var previous = postRequest;
        postRequest = function() {
            if(previous != null) {
                previous();
            }
            func();
        };
    }
    
    /**
     Return the post request function.
     */
    this.getPostRequest = function() {
        return postRequest;
    }
    
    /**
     Send the Ajax request using the POST method. Use with caution -- some
     browsers do not support the POST method with the XMLHttpRequest object.
     */
    this.setUsePOST = function() {
        method = "POST";
    }
    
    /**
     Send the Ajax request using the GET method, where parameters are sent
     as a query string appended to the URL. This is the default behavior.
     */
    this.setUseGET = function() {
        method = "GET";
    }
    
    /**
     Enable client-side debugging.  The server's response will be written
     to a text area appended to the bottom of the page.  If parsing is
     performed on the client side, then the results of the parsing operations
     are shown in their own text areas.
     */
    this.setEchoDebugInfo = function() {
        debugResponse = true;
    }
    
    /**
     Indicate if debugging is enabled.
     @return boolean
     */
    this.isEchoDebugInfo = function() {
        return debugResponse;
    }
    
    /**
     Set the query string that will be sent to the server. For GET
     requests, the query string is appended to the URL. For POST
     requests, the query string is sent in the request body. This 
     method is useful, for example, if you want to send an XML string
     or JSON string to the server.
     @param {String} qa, the new query string value.
     */
    this.setQueryString = function(qs) {
        queryString = qs;
    }
    
    /**
     Return the query string.
     @return The query string.
     */
    this.getQueryString = function() {
        return queryString;
    }
    
    /** 
     @param {Boolean} asyncBoolean, set to true if asynchronous request, false synchronous request. 
     */
    this.setAsync = function(asyncBoolean){
        async = asyncBoolean;
    }
    
    /** 
     @param {Function} Set the error handler function that is called if the 
     server's HTTP response code is something other than 200.
     */	
    this.setErrorHandler = function(func){
        errorHandler = func;
    }
    
    /**
     Add all of the form elements under the specified form to the query
     string to be sent to the server as part of the Ajax request. 
     The values are automatically encoded.
     @param form, A form DOM element, or the id attribute of the form element from
     which you wish to accumulate the form values.
     */
    this.addFormElements = function(form) {
        var formElements = new Array();
        if (form != null) {
            if (typeof form == "string") {
                var el = document.getElementById(form);
                if (el != null) {
                    formElements = el.elements;
                }
            } else {
                formElements = form.elements;
            }
        }
        var values = toQueryString(formElements);
        accumulateQueryString(values);
    }
    
    /**
     Add the name/value pair to the query string.
     @param {String} name
     @param {String} value
     */
    this.addNameValuePair = function(name, value) {
        var nameValuePair = name + "=" + encodeURIComponent(value);
        accumulateQueryString(nameValuePair);
    }
    
    /**
     Same as addNamedFormElements, except it will filter form elements by form's id.
     For example, these are all valid uses:<br>
     <br>ajaxRequest.addNamedFormElements("form-id""element-name-1");
     <br>ajaxRequest.addNamedFormElements("form-id","element-name-1",
     "element-name-2", "element-name-3");
     */
    this.addNamedFormElementsByFormID = function() {
        var elementName = "";
        var namedElements = null;
        
        for(var i = 1; i < arguments.length; i++) {
            elementName = arguments[i];
            namedElements = document.getElementsByName(elementName);
            var arNamedElements = new Array();
            for(j = 0; j < namedElements.length; j++) {
                if(namedElements[j].form  && namedElements[j].form.getAttribute("id") == arguments[0]){
                    arNamedElements.push(namedElements[j]);				
                }
            }
            if(arNamedElements.length > 0){
                elementValues = toQueryString(arNamedElements);
                accumulateQueryString(elementValues);
            }
        }
    }
    
    /**
     Add the values of the named form elements to the query string to be
     sent to the server as part of the Ajax request. This method takes any 
     number of Strings representing the form elements for wish you wish to 
     accumulate the values. The Strings must be the value of the element's 
     name attribute.<br><br>For example, these are all valid uses:<br>
     <br>ajaxRequest.addNamedFormElements("element-name-1");
     <br>ajaxRequest.addNamedFormElements("element-name-1", "element-name-2", "element-name-3");
     */
    this.addNamedFormElements = function() {
        var elementName = "";
        var namedElements = null;
        
        for(var i = 0; i < arguments.length; i++) {
            elementName = arguments[i];
            namedElements = document.getElementsByName(elementName);
            
            elementValues = toQueryString(namedElements);
            
            accumulateQueryString(elementValues);
        }
        
    }
    
    /**
     Add the values of the id'd form elements to the query string to be
     sent to the server as part of the Ajax request. This method takes any 
     number of Strings representing the ids of the form elements for wish you wish to 
     accumulate the values. The Strings must be the value of the element's 
     name attribute.<br><br>For example, these are all valid uses:<br>
     <br>ajaxRequest.addFormElementsById("element-id-1");
     <br>ajaxRequest.addFormElementsById("element-id-1", "element-id-2", "element-id-3");
     */
    this.addFormElementsById = function() {
        var id = "";
        var element = null;
        var elements = new Array();
        
        for(var h = 0; h < arguments.length; h++) {
            element = document.getElementById(arguments[h]);
            if(element != null) {
                elements[h] = element;
            }
        }
        
        elementValues = toQueryString(elements);
        accumulateQueryString(elementValues);
    }
    
    /**
     Send the Ajax request.
     */
    this.sendRequest = function() {
        if(preRequest) {
            preRequest(self);
        }
        
        var obj = this;
        if(async)
            xmlHttp.onreadystatechange = function () { handleStateChange(self) };
            
            if(requestURL.indexOf("?") > 0) {
                requestURL = requestURL + "&ts=" + new Date().getTime();
            }
            else {
                requestURL = requestURL + "?ts=" + new Date().getTime();
            }
            
            
            try {
                if(method == "GET") {
                    if(queryString.length > 0) {
                        requestURL = requestURL + "&" + queryString;
                    }
                    xmlHttp.open(method, requestURL, async);
                    xmlHttp.send(null);
                }
                else {
                    xmlHttp.open(method, requestURL, async);
                    //Fix a bug in Firefox when posting
                    try {
                        if (xmlHttp.overrideMimeType) {
                            xmlHttp.setRequestHeader("Connection", "close");//set header after open
                        }			
                    }
                    catch(e) {
                        // Do nothing
                    }
                    xmlHttp.setRequestHeader("Content-Type", "application/x-www-form-urlencoded"); 
                    xmlHttp.send(queryString);
                }
            }
            catch(exception) {
                if(errorHandler) {
                    errorHandler(self, exception);
                }
                else {
                    throw exception;
                }
            }
            
            if(!async) {  //synchronous request, handle the state change
                handleStateChange(self);
            }
            
            if(self.isEchoDebugInfo()) {
                echoRequestParams();
            }
    }
    
    
    /** @private */
    handleStateChange = function(ajaxRequest) {
        if(ajaxRequest.getXMLHttpRequestObject().readyState != 4) {
            return;
        }
        if(ajaxRequest.getXMLHttpRequestObject().status != 200) {
            errorHandler(self);
            return;
        }
        try {
            var debug = ajaxRequest.isEchoDebugInfo();
            if(debug) {
                echoResponse(ajaxRequest);
            }
            
            ajaxRequest.getParser().parse(ajaxRequest.getXMLHttpRequestObject().responseXML);
        }
        catch(exception) {
            if(errorHandler) {
                errorHandler(self, exception);
            }
            else {
                throw exception;
            }
        }
        finally {
            try {
                if(ajaxRequest.getPostRequest()) {
                    var f = ajaxRequest.getPostRequest();
                    f(ajaxRequest);
                }
            }
            catch(exception) {
                if(errorHandler) {
                    errorHandler(self, exception);
                }
            }
        }
    }
    
    
    /**
     Create an instance of the XMLHttpRequest object, using the appropriate
     method for the type of browser in which this script is running. For Internet
     Explorer, it's an ActiveX object, for all others it's a native JavaScript
     object.
     @return an instance of the XMLHttpRequest object.
     @private
     */
    function createXMLHttpRequest() {
        var req = false;
        if (window.XMLHttpRequest) {
            req = new XMLHttpRequest();
        }
        else if (window.ActiveXObject) {
            try {
                req = new ActiveXObject("Msxml2.XMLHTTP");
            }
            catch(e) {
                try {
                    req = new ActiveXObject("Microsoft.XMLHTTP");
                }
                catch(e) {
                    req = false;
                }
            }
        }
        return req;
    }
    
    /** @private */
    function accumulateQueryString(newValues) {
        if(queryString == "") {
            queryString = newValues; 
        }
        else {
            queryString = queryString + "&" +  newValues;
        }
    }
    
    /** @private */
    function toQueryString(elements) {
        var node = null;
        var qs = "";
        var name = "";
        
        var tempString = "";
        for(var i = 0; i < elements.length; i++) {
            tempString = "";
            node = elements[i];
            
            name = node.getAttribute("name");
            //use id if name is null
            if (!name) {
                name = node.getAttribute("id");
            }
            name = encodeURIComponent(name);
            
            if(node.tagName.toLowerCase() == "input") {
                if(node.type.toLowerCase() == "radio" || node.type.toLowerCase() == "checkbox") {
                    if(node.checked) {
                        tempString = name + "=" + encodeURIComponent(node.value);
                    }
                }
                
                if(node.type.toLowerCase() == "text" || node.type.toLowerCase() == "hidden" || node.type.toLowerCase() == "password") {
                    tempString = name + "=" + encodeURIComponent(node.value);
                }
            }
            else if(node.tagName.toLowerCase() == "select") {
                tempString = getSelectedOptions(node);
            }
            
            else if(node.tagName.toLowerCase() == "textarea") {
                tempString = name + "=" + encodeURIComponent(node.value);
            }
            
            if(tempString != "") {
                if(qs == "") {
                    qs = tempString;
                }
                else {
                    qs = qs + "&" + tempString;
                }
            }
            
        }
        
        return qs;
    }
    
    /** @private */
    function getSelectedOptions(select) {
        var options = select.options;
        var option = null;
        var qs = "";
        var tempString = "";
        
        for(var x = 0; x < options.length; x++) {
            tempString = "";
            option = options[x];
            
            if(option.selected) {
                tempString = encodeURIComponent(select.name) + "=" + encodeURIComponent(option.value);
            }
            
            if(tempString != "") {
                if(qs == "") {
                    qs = tempString;
                }
                else {
                    qs = qs + "&" + tempString;
                }
            }
        }
        
        return qs;
    }
    
    /** @private */
    function echoResponse(ajaxRequest) {
        var echoTextArea = document.getElementById("debugResponse");
        if(echoTextArea == null) {
            echoTextArea = createDebugTextArea("Server Response:", "debugResponse");
        }
        var debugText = ajaxRequest.getXMLHttpRequestObject().status 
        + " " + ajaxRequest.getXMLHttpRequestObject().statusText + "\n\n\n";
        echoTextArea.value = debugText + ajaxRequest.getXMLHttpRequestObject().responseText;
    }
    
    /** @private */
    function echoParsedJavaScript(js) {
        var echoTextArea = document.getElementById("debugParsedJavaScript");
        if(echoTextArea == null) {
            var echoTextArea = createDebugTextArea("Parsed JavaScript (by JavaScript Parser):", "debugParsedJavaScript");
        }
        echoTextArea.value = js;
    }
    
    /** @private */
    function createDebugTextArea(label, id) {
        echoTextArea = document.createElement("textarea");
        echoTextArea.setAttribute("id", id);
        echoTextArea.setAttribute("rows", "15");
        echoTextArea.setAttribute("style", "width:100%");
        echoTextArea.style.cssText = "width:100%";
        
        document.getElementsByTagName("body")[0].appendChild(document.createTextNode(label));
        document.getElementsByTagName("body")[0].appendChild(echoTextArea);
        return echoTextArea;
    }
    
    
    /** @private */
    function echoRequestParams() {
        var qsTextBox = document.getElementById("qsTextBox");
        if(qsTextBox == null) {
            qsTextBox = createDebugTextBox("Query String:", "qsTextBox");
        }
        qsTextBox.value = queryString;
        
        var urlTextBox = document.getElementById("urlTextBox");
        if(urlTextBox == null) {
            urlTextBox = createDebugTextBox("URL (Includes query string if GET request):", "urlTextBox");
        }
        urlTextBox.value = requestURL;
    }
    
    /** @private */
    function createDebugTextBox(label, id) {
        textBox = document.createElement("input");
        textBox.setAttribute("type", "text");
        textBox.setAttribute("id", id);
        textBox.setAttribute("style", "width:100%");
        textBox.style.cssText = "width:100%";
        
        document.getElementsByTagName("body")[0].appendChild(document.createTextNode(label));
        document.getElementsByTagName("body")[0].appendChild(textBox);
        return textBox;
    }
};


Documentation generated by JSDoc on Thu Apr 15 22:04:54 2010