Elementals.js

Latest Version: 3.7 Final 20 December 2018

Method _.ajax

Summary:

Creates an An XMLHttpRequest object or the appropriate activeX equivalent with a simple callback assignment for status code 200, or a complex object containing methods for handling multiple states. Can optionally be used to .open(), .send() and set HTTP headers and mime-type.

Calling Convention:
_.ajax([callback || dataObject])
Parameters: Must contain at least one of:
callback optional
A function to be called when readystate is 4 and status is 200.
dataObject optional
An object containing:
  • state optional -- an object of methods for handling XMLHTTP readystates. If readystate 4 is not included, a default handler is used that will call the appropriate dataObject.status or log the result.
  • status -- an object of methods for handling different status codes. You will at least want to include dataObject.status[200] for handling a valid return value when using the dataObject approach to calling _.ajax. Any other status can be custom handled as desired, and if a specific match for a status code isn't found, dataObject.status[catchAll] will be checked and called if found.
  • progress optional -- a function to be called when onprogress fires.
  • request optional -- an array that if present will do an:

    XMLHttp.open([dataObject].request[0], [dataObject].request[1]);
    // if mimeType or headers are set, they'll be sent here
    XMLHttp.send([dataObject].request[2]);
    • array index 0 = method such as 'GET' or 'POST'
    • array index 1 = URI to be retrieved
    • array index 2 [optional] = Post String sent()
  • mimeType optional -- a mime-type override string. Will only be sent/set if request is in use and before XMLHttp.send() is performed. When manually doing .send() use XMLHttp.overrideMimeType as normal.
  • headers optional -- an array of name and value pairs to be sent as HTTP headers in the request. Will only be sent/set if request is in use and before XMLHttp.send() is performed.
  • onReadyLog optional -- the type of logging to perform should a [XMLHttp].onreadystatechange go unhandled, with 'silent' being the default. (aka no action taken)
    see _.log for more information.
  • onStatusLog optional -- the type of logging to perform when [XMLHttp].onreadystatechange == 4 and the [XMLHttp].status code goes unhandled, with 'silent' being the default. (aka no action taken)
    see _.log for more information.
Returns:
An XMLHttpRequest object or the appropriate activeX equivalent, extended by elementals functionality.
Extensions to XMLHttpRequest
.getJSON()
Returns a JSON.parse of [XMLHttp].responseText
.getXMLValueById(id)
Returns the _.Node.text of [XMLHttp].responseXML.getElementById(id)
.getXMLValuesByTagName(tagName, limit)

Returns an array of _.Node.text values of all elements retrieved by [XMLHttp].responseXML.getElementsByTagName(tagName). If limit is unset, all results are retrieved, otherwise the number of results returned will not exceed limit.

If limit is set to one, the actual value of the first found match is returned, NOT an array!

Example #1

Using the callback function method.

JavaScript

var x = ajax(function(x) {
	alert('retrieved file successfully');
});
x.open('GET', 'test.html');
x.send();

Example #2

Using the dataObject method.

JavaScript

var x = ajax({
	status : {
		'200' : function(x) {
			alert('AJAX Success');
		},
		'404' : function(x) {
			alert('File Not Found');
		},
		'catchAll' : function(x) {
			alert('Unhandled status code: ' + x.status);
		}
	},
	progress : function(e) {
		console.log('AJAX PROGRESS: ' + e.loaded + '/' + e.total);
	},
	request : [ 'POST', 'search.php' , 'q=test&user=jimbo' ]
});

Live Demo's are available here:

  1. Simple AJAX Demo.
  2. AJAX and the "onprogress" event.