/* - - - - - - - - - - - - - - - - - - - - - - -
 Abraham
 02 September 2008
 - Javascript file to include for AJAX
 - - - - - - - - - - - - - - - - - - - - - - -

    USE:  AJAX functions
    WHO:  Abraham
    HOW:  See seperate functions for details
    NOTE: Important divisions to consider:
          <div id="ajax_image"> that contains an image to display while processing AJAX request
          - remember to reset the image in your ajax_return_function, with: clear_wait();
          <div id="message_div"> that will contain server messages, or ajax_taking_too_long message

 - - - - - - - - - - - - - - - - - - - - - - - */

    var timer;
    var req;

    /*
          ajax( url, callback, postData );

          url = location of server-side file
                eg. ajax/file.php?id=2 - with parameters to pass, automatic use of GET method,
                eg. ajax/file.php - without parameters, automatic use of POST method, uses postData as parameters
          callback = function to call on completion. function is sent the XMLHttp request as parameter
          postData = eg. id=2&valid=yes - if not empty, ajax function uses POST method with this data as parameter

          example call:
          GET:  ajax('phpfile.php?id=3&name=abc', 'return_function');
          POST: ajax('phpfile.php', 'return_function', 'id=3&name=abc');

    */

    function ajax(url, callback, postData) {
        var tosend;
        abort_request();
        req = createXMLHTTPObject();
        if (!req) return true;

        start_wait();

        var method = (postData) ? "POST" : "GET";
        req.open(method, url, true);
        req.setRequestHeader('User-Agent','XMLHTTP/1.0');
        if (postData) {
            req.setRequestHeader('Content-type','application/x-www-form-urlencoded');
        }
        req.onreadystatechange = function () {
            // do nothing until the ajax call is complete
            if (req.readyState == 4) { // readyState 4 = "complete"
                if (req.status == 200) { // OK
                    if (!(response = req.responseText)) {
                        // Earlier versions of IE make it this far before choking,
                        // so we provide a graceful exit to the process.
                        return true;
                    }
                    if (callback) { // call the callback if there is one
                        tocall = callback+"(req)";
                        eval(tocall);
                    }
                }
                else if (req.status == 0) {
                  // user abort; do nothing
                }
                else {
                    alert(req.status + ": A problem was encountered retrieving the AJAX data: \n" + req.statusText);
                }

            }
        }
        if ( (req.readyState == 4) || (req.readyState=="complete") ) return false;
        req.send(postData);
    }


    /*
        helper function to set up the XMLHttpRequest object
    */
    var XMLHttpFactories = [
        function () {return new XMLHttpRequest()},
        function () {return new ActiveXObject("Msxml2.XMLHTTP")},
        function () {return new ActiveXObject("Msxml3.XMLHTTP")},
        function () {return new ActiveXObject("Microsoft.XMLHTTP")}
    ];


    /*
        helper function to set up the XMLHttpRequest object
    */
    function createXMLHTTPObject() {
        var xmlhttp = false;
        for (var i=0;i<XMLHttpFactories.length;i++) {
            try {
                xmlhttp = XMLHttpFactories[i]();
            }
            catch (e) {
                continue;
            }
            break;
        }
        return xmlhttp;
    }


    /*
        abort AJAX request
    */
    function abort_request() {
        try {
            window.clearTimeout(timer);
            if ( (req) && (req.abort) ) {
                req.abort();
            }
        }
        catch(e) {}
    }


    /*
        parse returned JSON
    */
    function parse_JSON() {
        return eval( "(" + req.responseText + ")" );
    }


    /*
        start waiting for AJAX request return
    */
    function start_wait(req) {
        var content = "Please wait while your message is being sent.";
        message('message_div', content, 'warning');
        set_display('ajax_image', 1);
    }


    /*
        stop waiting for AJAX request return
    */
    function clear_wait() {
        set_display('ajax_image', 0);
        set_display('message_div', 0);
    }