/*
<h1>ajaxlib 1.0</h1>
<p>This library contains a few simple functions for performaing AJAX requests.</p>

<p>keithm 2007-08-29</p>
    
<p>
    NOTE: I strongly recommend using the prototype.js library for AJAX if you 
    possibly can - this one is just for use when you really don't want to send 
    out 100k of Javascript. That one has many, many more options and has had a 
    lot more exhaustive testing with different browser versions.
</p>

<p><a href="http://www.prototypejs.org/">Prototype website</a></p>
*/

// The version of this library:
var ajaxlib_version = 1.0;

// If this is true, you will get popup alerts when exceptions are thrown.
var ajax_debug = false;

/*
<h2>setAjaxDebug(debug)</h2>

<p>Turn on debug information for AJAX requests. You may be better off using firebug
in Firefox, although this debug stuff is useful if you have an IE-specific problem.</p>
*/
function setAjaxDebug(debug)
{
    ajax_debug = debug;
}


/*
<h2>makeAjaxRequest(url, callback, method, async)</h2>
<pre>
    Main method for AJAX request.
    
    Parameters:
    
        url: 
            the URL of the request
        
        callback: 
            a function reference to call back when the request completes. The 
            function will receive the httpRequest object as a parameter.
            
        method:
            e.g. "GET" or "POST". Will default to "GET" if nothing specified.
            
        async
            true/false: whether or not the request should be asynchronous - 
            defaults to true (advisable)
            
    This was adapted from the Mozilla AJAX tutorial here:
    http://developer.mozilla.org/en/docs/AJAX:Getting_Started
     - the contents of which are available under the CC-BY-SA license.
     
    See the updateElement function below for an example of usage.
</pre>
*/
function makeAjaxRequest(url, callback, method, async) 
{
    var httpRequest;
    if(method == null) method = "GET";    
    if(async == null) async = true;


    if (window.XMLHttpRequest)  // Mozilla, Safari, ...
    {
        httpRequest = new XMLHttpRequest();
    } 
    else if (window.ActiveXObject)  // IE
    {
        try 
        {
            httpRequest = new ActiveXObject("Msxml2.XMLHTTP");
        } 
        catch (e) 
        {
            try 
            {
                httpRequest = new ActiveXObject("Microsoft.XMLHTTP");
            } 
            catch (e) 
            {}
        }
    }

    if (!httpRequest) 
    {
        if(ajax_debug) alert('Giving up :( Cannot create an XMLHTTP instance');
        return false;
    }
    
    httpRequest.onreadystatechange = 
        function() { _processResponse(httpRequest, callback); };
    httpRequest.open(method, url, true);
    httpRequest.send('');
    return true;
}

//
// Wrapper for AJAX callback - only calls back on success.
//
function _processResponse(httpRequest, callback) 
{
    try
    {
        if (httpRequest.readyState == 4) 
        {
            if (httpRequest.status == 200) 
            {
            	callback(httpRequest);
            } 
            else 
            {
                if(ajax_debug) alert('There was a problem with the request.');
            }
        }
    }
    catch(e)
    {
        if(ajax_debug) alert("Caught exception: " + e.description);
    }
}


/*
<h2>updateElement(url, element)</h2>
<pre>
 update the content of an HTML element with the response from an AJAX request
  - note this assumes two things:
  1. the content returned is displayable (text or HTML)
  2. the element to be updated is not a table element (doesn't work in IE)
  
  NOTE also: IE is really picky if you return HTML - best to use a DIV for 
  this since it will not work if you try to include e.g. a list item inside 
  a paragraph.
</pre>
*/
function updateElement(url, element)
{
    return makeAjaxRequest(url, function(request)
    {
        element.innerHTML = request.responseText;
    });
}

/*
<h2>updateElementById</h2>
<p>
 See updateElement - this one takes an element ID instead of an element
 object reference
</p>
*/
function updateElementById(url, elementId)
{
    var element = document.getElementById(elementId);
    updateElement(url, element);
}