/*
============================================================
Project: Shop template application development

Purpose: This is an template to be used when building a
one page ajax based web shop.

Last modified: 06 Feb 2008.

This JavaScript file provides specific functions related to
XHR (XML HTTP Request). The logic explained here is a
generic one which is being used hundreds of other 
Web applications. This logic can be found in any
Ajax related book or article that describes the inner
workings of XHR. 
============================================================
*/

/*
============================================================
Function: createRequest

Last Modified: 12 May 2007

This function creates an XHR object that is browser
agnostic. As of this writing, XHR is somewhat browser
dependent. We can divide XHR support in two major classes
of browsers i.e. Internet Explorer and non-IE browsers.
Then, within IE, there are different implementations of
XHR in pre-IE6 and the rest. In summary, Microsoft
supports XHR through its ActiveX. After listening to
complaints from the Web developer community, Micrsoft
realized the need to expose XHR as a native browser
object as done in other browsers. The rumor is that
we will soon see XHR support in IE browsers via
XMLHttpRequest object. Until then, we have to take care of
browser dependency as shown in this function.
============================================================
*/
function createRequest() {
   // Define a local variable and set it to null.
   var request = null;

   // Try different things to see which browser is being used.   
   try {
      // Non Microsoft browsers (Firefox, Safari etc.)
      request = new XMLHttpRequest();
   } catch(trymicrosoft) {
      try {
         // IE6 and above.
         request = new ActiveXObject("Msxml2.XMLHTTP");
      } catch(othermicrosoft) {
         try {
            // Older versions of IE i.e. pre-IE6.
            request = new ActiveXObject("Microsoft.XMLHTTP");
         } catch(failed) {
            // No support for XHR
            request = null;
         } // End of catch(failed)
      } // End of catch(othermicrosoft)
   } // End of catch(trymicrosoft)
   
   // Check if we have a valid XHR object. 
   if (request == null) {
      alert("Error creating the XMLHttpRequest object!");
   } else {
      // Return the valid XHR object that was created.
      return(request);
   } // End of if (request == null)
} // End of function createRequest.

/*
============================================================
Function: sendHttpRequest

Last Modified: 12 May 2007

This function transmits any arbitrary data to a server URL.
It takes four arguments:
1) XHR object
2) Callback function (if any) to receive the server response
3) URL to which the content is to be sent.
4) Data to be sent.

The depending on the input parameters, it will either
communicate with the server asynchronously or 
synchronously to do the data interchange. It uses the POST
verb of HTTP to do the REST-style call.
============================================================
*/
function sendHttpRequest(request, callbackFunction, url, postData) {
   // Initialize a local variable to false.
   // This variable indicates if we need to communicate with the
   // server in an asynchronous mode.
   var async_request = false;
   
   // Did the caller give us a Callback function? 
   if (callbackFunction != null) {
      // We have a callback function.
      // Set that function to to XHR object's onreadystatechange property.
      request.onreadystatechange = callbackFunction;
      // Set the local variable to indicate that 
      // we need to send and receive the response in a non-blocking mode
      // i.e. Async. 
      async_request = true;
   }
   
   //  Open a HTTP connection to the provided URL.
   request.open("POST", url, async_request);
   // Set a HTTP request header.
   request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   // Send it now.
   // If async mode was not true, then this call will block until a
   // HTTP response is received from the server.
   // Otherwise, this statement will just send and return without waiting for a
   // server response.      
   var response = request.send(postData);   
   
   if (async_request == false) {
      // We sent the request synchronously. 
      // Hence, return the response received from the server.
      return(response);
   } else {
      // If the request was made asynchronously, we need not bother to return 
      // anything meaningful. The response will be sent directly to the 
      // callback function that was provided by the caller.
      return(true);
   }   
} // End of function sendHttpRequest.