pui.AjaxRequest object

pui.AjaxRequest serves as a cross-browser compatible wrapper for the browser’s "XMLHttpRequest" object used to initiate HTTP requests for server-side resources from client-side scripts -- i.e. JavaScript code.

Usage

To make Ajax requests, a pui.AjaxRequest object is first created using the new keyword and one of the 2 available constructors.

After the object is created, options may be specified by setting properties on the object. Once all desired options are set, the request can be transmitted using the send() method on the object. Responses are processed by providing handler functions using the object’s onfail, onsuccess, and onready properties.

Constructors

pui.AjaxRequest(string url)

This form of the constructor creates the pui.AjaxRequest object and sets the url property of the object to the given url parameter. Any other desired options can be specified before sending the request by setting any of the available properties (as listed below) on the object.

pui.AjaxRequest(object options)

This form of the constructor accepts an options object as a parameter. Any of the available properties on the pui.AjaxRequest object can be set during object creation using this constructor by including the appropriate property name/value pairs in the options parameter.

Properties

async - Boolean value that determines if the request will be sent synchronously or asynchronously. In an asynchronous request, processing of the script does not wait for the completion of the HTTP request. Synchronous requests cause the script to stop executing when the request is sent, and then to restart when the response is received. Valid values are Boolean true or false. The default value if not specified is true.

cacheBuster - Boolean value that controls whether or not to apply a "cache buster" query string to the URL for "GET" requests, to force the browser to retrieve a new copy of a resource from the server. The default value if not specified is true. (Requires Profound UI 6.4.2 or newer.)

headers - Object containing name/value pairs to be sent as HTTP headers on the request.

method - String containing the HTTP request method to use. Valid values are "GET", "POST", and "PUT". The property is not case-sensitive. The default value if not specified is "GET".

params - Object containing name/value pairs to be sent along as parameters on the request. The name/value pairs will be URI encoded automatically when sent, so there is no need to encode them manually when using this property.

password - String containing the password to send to the server. Used when the HTTP server requires user authentication.

postData - String containing the POST data to send to the HTTP server with the request. Used only with POST requests. The POST data should be in the form of standard URL encoded name/value pairs.

reqData - (Requires AjaxLibrary 1.59 or Profound UI 6.3.0 or newer) String containing data to send to the HTTP server with PUT or POST requests. The data should be in the same format as you specify in the content-type option of the headers parameter. If no content-type is provided, URL encoded name/value pairs are assumed.

suppressAlert - Boolean value that controls whether or not to display HTTP error messages. By default, the pui.AjaxRequest object will automatically report any HTTP failure states with an alert box. This property can be set to false if you do not want these alerts to display. Other alert messages that result from improper use of the pui.AjaxRequest object (such as giving an invalid HTTP request method) will result in alert box messages that cannot be suppressed.

url - String containing the URL of the Web page or service to request. This can be either an absolute or relative URL. Any query string parameters can be appended to the URL in the standard fashion. All data items on the URL should be properly encoded. Keep in mind that Web browsers do not support cross-domain Ajax requests. The URL can also be given in the pui.AjaxRequest(url) constructor.

user - String containing the user name to send to the server. Used when the HTTP server requires user authentication.

Events

onfail - This event fires when the pui.AjaxRequest object has received a failed response from the HTTP server. Either a named or anonymous function can be specified for this event.

onready - This event fires when the pui.AjaxRequest object has received a response of any kind from the HTTP server, successful or failed. Either a named or anonymous function can be specified for this event.

onsuccess - This event fires when the pui.AjaxRequest object has received a successful response from the HTTP server. Either a named or anonymous function can be specified for this event.

Methods

abort() - Aborts a request that is in process. This method is valid only when using an asynchronous request.

getAllResponseHeaders() - Returns a string containing all HTTP headers sent with the server response.

getResponseHeader(string headerLabel) - Returns the value of a specified HTTP header sent back with the server response. headerLabel is a string containing the name of the desired header to check (i.e. content-type).

getResponseText() - Returns a string containing the response from the Web page or service.

getResponseXML() – This method is valid only when the content type of the requested Web service is 'text/xml'. An XML document object is returned. This can then be processed using the browser’s built in XML parser.

getStatus() - Returns the HTTP status code of a completed request.

getStatusMessage() - Returns a formatted status message that contains both the HTTP status code and text (i.e. 401 - Page Not Found).

getStatusText() - Returns the HTTP status text of a completed request.

ok() - Returns a Boolean true or false value that indicates whether the last request was successful or not.

pui.AjaxRequest(url) - Constructor that creates an instance of the pui.AjaxRequest object. url is an optional parameter that sets the url property of the object upon creation. See url property for valid usage.

send() - Calling this method sends the Ajax request to the server. pui.AjaxRequest events will fire when the server responds.

setRequestHeader(headerLabel, headerValue) - Sets HTTP headers to be sent with the request. headerLabel is a string containing the name of the desired HTTP header to set, such as 'content-type'. headerValue is a string that contains the corresponding value, such as 'text/xml'.

pui.AjaxRequest Examples

Sending an asynchronous GET request:

In this example parameters are sent on the URL. They do not need to be encoded because they contain numeric digits only.

No failure processing is done in this case - the pui.AjaxRequest object’s built-in HTTP error reporting mechanism is used.

var ajaxRequest = new
pui.AjaxRequest("getInfo.pgm?referenceNumber=123&customerNumber=456");
ajaxRequest.onsuccess = function(ajaxRequest) {
  alert(ajaxRequest.getResponseText());
}
ajaxRequest.send();

Sending a synchronous POST request:

In this example parameters are sent in the POST data. They are URL encoded because they contain character data.

The built-in error reporting mechanism is disabled, and a programmer-defined error handling routine is registered.

var ajaxRequest = new pui.AjaxRequest("getInfo.pgm");
ajaxRequest.method = "post";
ajaxRequest.async = false;
ajaxRequest.suppressAlert = true;
ajaxRequest.postData = "customerName=" + encodeURIComponent("David Russo") + "&customerNumber=" + encodeURIComponent("H52N-100");
ajaxRequest.onsuccess = infoHandler;
ajaxRequest.onfail = failHandler;
ajaxRequest.send();
function infoHandler(ajaxRequest) {
  alert(ajaxRequest.getResponseText());
}
function failHandler(ajaxRequest) {
  alert(ajaxRequest.getStatusMessage());
}

Sending an asynchronous POST request using alternate constructor:

In this example, all options on the request are set at object creation-time using the alternate constructor.

The built-in error reporting mechanism is disabled, and a programmer-defined error handling routine is registered.

var ajaxRequest = new pui.AjaxRequest({
  url: "getInfo.pgm",
  method: "post",
  async: true,
  suppressAlert: true,
  params: {
    customerName: "David Russo",
    customerNumber: "H52N-100"
  },
  onsuccess: infoHandler,
  onfail: failHandler
});
ajaxRequest.send();

function infoHandler(ajaxRequest) {
  alert(ajaxRequest.getResponseText());
}

function failHandler(ajaxRequest) {
  alert(ajaxRequest.getStatusMessage());
}