AjaxRequest

Purpose

Not Within Scope Of This Library

Simple Request
Retrieve the current URL and show its source. This uses a simple 'onSuccess' handler function to populate the source box.
By default, AjaxRequest always uses the current URL as retrieved from window.location.href unless a URL is given to it.

AjaxRequest.get(
  {
    'onSuccess':function(req){ document.forms[0].pageSource.value = req.responseText; }
  }
);



Error Handling
This will request a page that doesn't exist, and trap the error using the onError handler. The string describing the error is found in the statusText property of the AjaxRequest object passed to the onError handler. 

AjaxRequest.get(
  {
    'url':'junk.html'
    ,'onSuccess':function(req){ alert('Success!'); }
    ,'onError':function(req){ alert('Error!\nStatusText='+req.statusText);}
  }
);


Timeout
There is no built-in support for a request timeout in the XMLHttpRequest object, but the AjaxRequest object provides this functionality.
If a timeout (in ms) is specified and the request doesn't complete before this time, the onTimeout handler will be called.
This example will request a page that takes 5 seconds to load, and set a timeout of 2 seconds. The timeout will fire before the success, and be handled instead of the success.
If the timeout occurs, abort() will be called on the XMLHttpRequest. The results of this on your server-side process may vary

AjaxRequest.get(
  {
    'url':'sleep.pl'
    ,'onSuccess':function(){ alert('Success!'); }
    ,'timeout':2000
    ,'onTimeout':function(req){ alert('Timed Out!'); }
  }
);


Simultaneous Requests
The demo below illustrates simultaneous requests which do not collide with each other. Each button requests a script from the server which waits for 5 seconds, then returns "Done!". Click the buttons in any order, at any speed, and the corresponding checkboxes will be filled in accordingly. 

function getResponse(target) {
  AjaxRequest.get(
    {
      'url':'sleep.pl'
      ,'onSuccess':function(req){ target.value=req.responseText; }
    }
  );
}







Activity Monitoring
It is often important in AJAX applications to give the user some visual confirmation that something is happening in the background. To do this, you can use 'hooks' into the background processes which are running to take action when requests begin or end.

The example below shows the two ways you can monitor activity - either globally across all requests, or by group. You can 'group' calls together so if you have two forms, for example, and the user submits one, the form can be disabled until the request returns, while the other form stays active. You'll notice that the global activity monitor is activated by all requests on this example page.

Details can be found in the documentation. 

// Simple functions to update the page
function makeActive(o) { o.innerHTML = "Active"; o.style.backgroundColor = "#00ff00"; }
function makeInactive(o) { o.innerHTML = "Inactive"; o.style.backgroundColor = "#ff0000"; }

// Functions called by global begin/end
function AjaxRequestBegin() { makeActive(document.getElementById('ajaxActivity')); }
function AjaxRequestEnd() { makeInactive(document.getElementById('ajaxActivity')); }

// Functions called by group begin/end
function AjaxRequestGroupBegin(groupName) { makeActive(document.getElementById(groupName+"Activity")); }
function AjaxRequestGroupEnd(groupName) { makeInactive(document.getElementById(groupName+"Activity")); }

function getResponse2(target,groupName) {
  AjaxRequest.get(
    {
      'url':'sleep.pl'
      ,'onSuccess':function(req){ target.value=req.responseText; }
      ,'groupName':groupName                    // Assigns this request to the group passed in
      ,'onGroupBegin':AjaxRequestGroupBegin     // Map to the function called when this group starts
      ,'onGroupEnd':AjaxRequestGroupEnd         // Map to the function called when this group ends
    }
  );
}

Overall Activity Group Activity  
Inactive
Inactive
Inactive
Inactive

Form Submittal
Submitting a form via AjaxRequest is trivial. The result of the submit() call is true if the Ajax submission was successful, or false if it was not. This can then be used in a form's onSubmit handler to fall back to a normal form submit. The form will be submitted as it would in a normal submission, maintaining proper element order, ignoring disabled fields, and handling multiple fields of the same name. Since Javascript cannot access file input contents, file inputs are ignored. 

function submitForm(theform) {
  var status = AjaxRequest.submit(
    theform
    ,{
      'onSuccess':function(req){ document.forms['form2'].submitResults.value = req.responseText; }
    }
  );
  return status;
}

value1:
value2: a b c
value3: yes
value4:
value5:
value6: (hidden input with name=value6, value=test)
value7: (file inputs will not get submitted)
value8:
value9:



Results of form submission:

Event Handlers
Simple event handler functions - if defined - will get fired as the request enters each state change. In most cases, only the onSuccess and possibly the onError handlers will be used. 
AjaxRequest.get(
  {
    'onLoading':function() { alert("Loading"); }
    ,'onLoaded':function() { alert("Loaded"); }
    ,'onInteractive':function() { alert("Interactive"); }
    ,'onComplete':function() { alert("Complete"); }
    ,'onSuccess':function() { alert("Success"); }
  }
);


Request Parameters
Parameters (whether in the URL for GET requests or in the body for POST requests) can be easily added to a request. The "parameters" attribute of the AjaxRequest is an object of name/value pairs to add to the request, and it can be built manually. In addition, any argument given to the get(), post(), or submit() functions which is not an internal attribute will be treated as a parameter.
If the "generateUniqueUrl" parameter is true (default) then a parameter of "AjaxRequestUniqueId" be added with each request so that GET requests are not cached.

AjaxRequest.get(
  {
    'parameters':{ 'a':'1', 'b':'2', 'c':'3' }
    ,'anotherParameter':'true'
    ,'onSuccess':function(req) { document.forms["parameterForm"].exampleUrl.value = req.url; }
  }
);