Returning multiple values with GlideAjax

[john_roberts]

I've heard a number of questions on how to use GlideAJAX to return multiple values. It wasn't clear in the wiki (until now) how to do this so most people were sending a string array of values to be parsed on the client. This works but there's much more you can do since the response is an XML document.


Let's start with the requirement.
I want an AJAX service to get a favorite value for a particular item.
I also want the ability to return all favorite values if I don't provide an item.


First we need an AJAX Processor. These are specified in script include records. The script include must have "client callable" field enabled and the script class must extend AbstractAjaxProcessor.


AJAX Processor Script Include

/*
 * MyFavoritesAjax script include Description - sample AJAX processor returning multiple value pairs
 */
var MyFavoritesAjax = Class.create();

MyFavoritesAjax.prototype = Object.extendsObject(AbstractAjaxProcessor, {

/*
 * method available to client scripts call using:
 * var gajax = new GlideAjax("MyFavoritesAjax");
 * gajax.addParam("sysparm_name", "getFavorites");
 */
ajaxFunction_getFavorites : function() {
// build new response xml element for result
var result = this.newItem("result");

// get parameter from client request, force to string so switch is happy
var item = this.getParameter("sysparm_item") + "";

// add requested item to response for debugging
result.setAttribute("requested_item", item);

// get item favorite or return all
switch (item) {
case "color":
this._addFavorite("color", "blue");
break;
case "beer":
this._addFavorite("beer", "lager");
break;
case "pet":
this._addFavorite("pet", "dog");
break;
default:
// add message to return
result.setAttribute("message", "no item or invalid item specified, returning all available items");

// no item specified, return all favorites
this._addFavorite("color", "blue");
this._addFavorite("beer", "lager");
this._addFavorite("pet", "dog");
}

// elements are returned to the client through the inherited methods of AbstractAjaxProcessor
},

_addFavorite : function(name, value) {
//create new favorite node with attributes
var favs = this.newItem("favorite");
favs.setAttribute("name", name);
favs.setAttribute("value", value);
},

type : "MyFavoritesAjax"
});

Now we need a client side script to build and submit the AJAX request, plus a callback function to process the results from the server. In this example lets assume we only want the favorite value for "beer". We'll specify this in the "sysparm_item" parameter of the request.

Client Script with Specified Favorite Item Parameter

// new GlideAjax object referencing name of AJAX script include
var gajax = new GlideAjax("MyFavoritesAjax");
// add name parameter to define which function we want to call
// method name in script include will be ajaxFunction_getFavorites
gajax.addParam("sysparm_name", "getFavorites");

// add optional item to get favorite
gajax.addParam("sysparm_item", "beer");

// submit request to server, call ajaxResponse function with server response
gajax.getXML(ajaxResponse);

function ajaxResponse(serverResponse) {
// get result element and attributes
var result = serverResponse.responseXML.getElementsByTagName("result");
var message = result[0].getAttribute("message");
var reqItem = result[0].getAttribute("requested_item");

// check for message attribute and alert user
if (message)
alert(message);

// build output to display on client for testing
var output = "";

// get favorite elements
var favorites = serverResponse.responseXML.getElementsByTagName("favorite");
for ( var i = 0; i < favorites.length; i++) {
var name = favorites<i>.getAttribute("name");
var value = favorites<i>.getAttribute("value");
output += name + " = " + value + "\n";
}
alert(output);
}

XML Response

<xml sysparm_max="15" sysparm_name="getFavorites" sysparm_processor="MyFavoritesAjax">
   <result requested_item="beer"></result>
   <favorite name="beer" value="lager"></favorite>
</xml>

This time we don't have a specific favorite item so we'll get multiple favorite nodes.


Client Script Without Specific Item, Returns All Favorites

// new GlideAjax object referencing name of AJAX script include
var gajax = new GlideAjax("MyFavoritesAjax");
// add name parameter to define which function we want to call
// method name in script include will be ajaxFunction_getFavorites
gajax.addParam("sysparm_name", "getFavorites");

// submit request to server, call ajaxResponse function with server response
gajax.getXML(ajaxResponse);

function ajaxResponse(serverResponse) {
// get result element and attributes
var result = serverResponse.responseXML.getElementsByTagName("result");
var message = result[0].getAttribute("message");
var reqItem = result[0].getAttribute("requested_item");

// check for message attribute and alert user
if (message)
alert(message);

// build output to display on client for testing
var output = "";

// get favorite elements
var favorites = serverResponse.responseXML.getElementsByTagName("favorite");
for ( var i = 0; i < favorites.length; i++) {
var name = favorites<i>.getAttribute("name");
var value = favorites<i>.getAttribute("value");
output += name + " = " + value + "\n";
}
alert(output);
}

XML Response

<xml sysparm_max="15" sysparm_name="getFavorites" sysparm_processor="MyFavoritesAjax">
   <result message="no item or invalid item specified, returning all available items" requested_item="null"></result>
   <favorite name="color" value="blue"></favorite>
   <favorite name="beer" value="lager"></favorite>
   <favorite name="pet" value="dog"></favorite>
</xml>