Rico Ajax Engine
Rico Ajax Engine
Rico Ajax Engine
The Rico JavaScript library provides a single JavaScript object, AjaxEngine, for adding Ajax to any HTML page. What is Ajax? Widkipedia has the following definition for Ajax: Traditional web applications allow users to fill out forms, and when these forms are submitted, a request is sent to a web server. The web server acts upon whatever was sent by the form, and then responds back by sending a new web page. A lot of bandwidth is wasted since much of the HTML from the first page is present in the second page. Because a request to the web server has to be transmitted on every interaction with the application, the application's response time is dependant on the response time of the web server. This leads to user interfaces that are much slower than their native counterparts. AJAX applications, on the other hand, can send requests to the web server to retrieve only the data that is needed, usually using SOAP or some other XML-based web services dialect, and using JavaScript in the client to process the web server response. The result is more responsive applications, since the amount of data interchanged between the web browser and web server is vastly reduced. Web server processing time is also saved, since a lot of this is done on the computer from which the request came. Comparing Ajax to Normal HTTP Mechanism As stated above, the traditional way users interact with a page is to click a link (usually translates to an HTTP GET request) or click a submit button on a form (usually translates to an HTTP POST request request). In the first case, a new page Web Page Web is requested and the browser Server Web Page refreshes with new content. In the second case, either a new page or response the same page with modified values is returned. In Ajax the request is made using the JavaScript function XmlHttpRequest. The request asks for a block of XML data (rather than a whole page to refresh) that the JavaScript code can handle in whatever way it sees fit. For example, here are some ways the XML data could be interpreted:
XML data that the JavaScript code parses to extract data. This data in turn is used to fill in field values or tables in a display.
Rico AjaxEngine
Rico provides a JavaScript object named AjaxEngine that simplifies using Ajax to update the contents within a page. The engine provides the following features: A standard XML definition for the basic Ajax response A way to specify that a response is targeted for a specific HTML element Automatic update of the targeted HTML elements innerHTML with the contents of the response A way to specify that a response is targeted for a specific JavaScript Ajax response handler Standard mechanism for an Ajax response handler to receive response messages Support for multiple Ajax responses as the result of one Ajax request (multiple updates to elements and/or JavaScript objects). Simple API for registering the Ajax Request Handler and the Ajax Response Handler Overview of AjaxEngine Using the AjaxEngine to create dynamic content is very straightforward. There are three steps. 1. Register the Ajax request handler. This tells the AjaxEngine that a specific web service or server call is mapped to a request handler name. 2. Register the Ajax response handler. This is either specifies an HTML element as the target of the data being returned (in which case the contents of the response is HTML code) or it specifies a specific JavaScript object that will manage the response 3. Invoke the Ajax request when the appropriate event occurs in the interface. 2
Rolodex Demo Lets use the Rolodex demo from the openrico web site (http://openrico.org/demos.page?demo=ricoAjaxInnerHTML.html). Recall that by selecting persons from the list on the left, a rolodex card is displayed on the right hand side.
For this demo we built a server-side process to handle requests for information about a person. When the person is selected in the list we use Ricos AjaxEngine to call this request handler and then we process the response containing personal information and display it as a rolodex card.
Notice the Ajax Engine is refereced with the identifier ajaxEngine. The included rico.js file creates an instance of the Ajax Engine with this name making it available to your page scripts to reference. 3
Jakarta Struts is an open source framework that provides mechanisms for handling requests, responses, page forwarding and other mechanisms that are required by web applications. The .do is simple a convention that means this is an Action (an event handler.)
This is a typical Rico ajax-response. It contains a block of well-formed XML code. Understanding the ajax-response in Rico Notice several important items about the Ajax response First the response is wrapped in the tags <ajax-response></ajax-response>. Every Rico Ajax response must have this element as the root of the XML returned. 4
And last, notice that contained in the XML is a set of well-formed XHTML code. The code in this example is the necessary HTML to create a rolodex card (and coupled with the correct CSS style class) looks like this:
The div that is in bold is the response handler. Two things are required for Rico to recognize this element as the response handler: 1. Give the element an id that matches the id of the response in the ajaxresponse 2. Register the element id with Rico ajaxEngine.registerAjaxElement(personInfo); When the response returns the AjaxEngine will copy the response HTML into the innerHTML of the DIV (personInfo). The result in this case would be equivalent to the following HTML code:
<div style="display:inline" id="personInfo"> <div class="person"><span class="personName">Mr. Pat Barnes</span><span class="personAddress">1743 1st Avenue Boston, Boston 71204-2345</span><span class="personOccupation">Executive Vice President</span><span class="personPhoneNumber">Phone #: (972) 555-0293</span><span class="personMobile">Mobile #: (972) 555-0295</span><span class="personNotes">Notes: Spouse playes tennis at the country club with John.</span></div> </div>
The getPerson function makes the Ajax request. Here is the method:
function getPersonInfo(selectBox) { var nameToLookup = selectBox.value.split(","); var firstName = nameToLookup[1].substring(1); var lastName = nameToLookup[0]; ajaxEngine.sendRequest( 'getPersonInfo', "firstName=" + firstName, "lastName=" + lastName ); }
This functions main responsibility is to call the sendRequest method on the Ajax Engine passing the request parameters expected by our request handler (remember our Struts Action, getPersonInfo.do?) Notice that it uses the name for the request handler not the actual URL. Thats it!! Lets review how to get Ajax running in your page. 1. Register your Ajax request handler 2. Register your Ajax response handler 3. Invoke sendRequest in the appropriate event. Lets look at the second type of response typeobject. The Form Letter Updater demo (http://openrico.org/demos.page?demo=ricoAjaxComplex.html.) In this demo, selecting a person on the left causes the personal information to be substituted into the form letter (a mail merge.)
Notice in our case the content of the response is XML code describing a single person. Obviously the content is completely application specific. We are retrieving fields of information about a person as XML attributes.
When a request is made, the XML is processed by the JavaScript object and the appropriate person data is inserted into the form letter. Here is what the FormLetterUpdater object does with the ajax response:
ajaxUpdate: function(ajaxResponse) { this.setPerson(ajaxResponse.childNodes[0]); }, setPerson: function(aPerson) { this.lastPersonSelected = aPerson; for ( var i = 0 ;i < FormLetterUpdater.attributes.length ;i++ ) { var attr = FormLetterUpdater.attributes[i]; this.substitute( "span", attr, this.emphasizedHTML( aPerson.getAttribute(attr) ) ); } }, substitute: function( tagName, tagClass, value ) { var elements = document.getElementsByTagAndClassName( tagName, tagClass); for ( var i = 0 ; i < elements.length ; i++ ) elements[i].innerHTML = value; },
Notice the ajaxUpdate expects one child as its nodea person. This is passed to the setPerson method. The FormLetterUpdater:setPerson method iterates over the attributes found on the person object and locates spans with the same id and substitutes the attribute values into the innerHTML of each span. Since you can define your response any way you want (as long as the response is valid XML markup) you can process the response data anyway you see fit.
Registering the Ajax Object Just like we registered an element (AjaxEngine.registerElement) if you are going to have a request handler that is a JavaScript object you will need to register the object with the Ajax Engine.
ajaxEngine.registerAjaxObject(formLetterUpdater, new FormLetterUpdater());
Differences So what is the difference between the two types of responses? The response type element is for simple updating of an HTML elements content with some HTML. The response type object allows for custom or more advanced manipulation of the response data to update the page content.
Multiple Responses
Dont forget that you can also embed multiple responses in the same ajax-response. You can also mix element and object responses in the same ajax-response.
Summary
In summary, the Rico AjaxEngine simplifies updating page content with Ajax. It provides a very straightforward way to change the HTML content of any HTML element. But it also provides an open ended way to respond to more complex data sets returned via a JavaScript object.
10