AJAX MVC Documentation Home

Available at:

Introduction

Definition: AJAX (Asynchronous JavaScript and XML) MVC (Model-View-Controller)

If you believe that AJAX is great, but that it's too unstructured for building a complex web application, then this is the tool for you. The AJAX MVC separates view management from data services in web applications cleanly and configurably. The AJAX MVC enables you to build lightweight, rich web interfaces that plug into Service Oriented Architectures (SOA) the same way you would use Macromedia/Adobe Flex, but without the overhead of the Flash Player. The AJAX MVC manages data/view integration entirely on the client-side, so it needs nothing more than a simple web server to work.

The purpose of an MVC framework is to separate the presentation of data from the data itself. In today's service oriented architectures, data manipulation and retrieval has been relegated to web services, giving middle-tier software engineers much greater control over data access and integrity. Similarly, rich web interfaces have been gaining in popularity, and products such as Macromedia (err, I mean Adobe) Flex have already started providing tools that integrate these user interfaces with SOA-style data services. But what about tools to integrate plain old HTML/JavaScript (a.k.a. AJAX) with these data services that are coming online? AJAX applications are notorious for their difficulty to debug and maintain, and I think this largely comes from the extra burden of data service integration being placed on the user interface developer.

The AJAX MVC strives to eliminate ad-hoc data service integration from AJAX applications. Hopefully, it will help to provide some standardization in the burgeoning world of AJAX applications, and let UI developers focus on the more enjoyable aspects of front end development!

History

My background is in middle-tier J2EE development, but I've had plenty of experience with Struts/Tiles, so when I started playing with AJAX, my natural instinct was to look for some Struts-like MVC for it. I was surprised to find that there was none. I found some JSP tag libraries that could generate AJAX-looking UI widgets, but this is not what AJAX is all about. An AJAX application should be able to stand on its own, making web service requests for data (ideally SOAP requests) only when data is needed. Without the data service, the AJAX application should be able to continue running on its own; no fresh data, perhaps, but not hitting the user with a server error or worse yet, the old "The page cannot be displayed."

I was also looking for simplicity at the integration point between the UI and data services. Struts exposes one method - execute() - to the front-end developer. Within that method, all data retrieval and transformation must take place before being passed to the view (usually a JSP page). Since data services provide data as XML, and, in the case of an AJAX application, the view is just an HTML page, shouldn't there be a simple way to map data to a view component?

Not finding any frameworks that met my needs, I decided to build my own, which I am now making available to whoever wants to use it.

Getting Started with the AJAX MVC

Pending the writing of more detailed documentation, the best way to start learning the AJAX MVC is to deploy the sample application provided with the distribution. Following the instructions in the samples/README file, deploy the simple AJAX application to your web server.

Read the comments in the mvc-config.xml file, too. There you will see that the sample application has been configured to alert all incoming and outgoing XML messages in popup windows. This is useful for debugging, but you can turn it off if you like.

The general principals of the AJAX MVC are as follows:

All events to be handled by the AJAX MVC should trigger the execute(actionName) JavaScript function

All actionName's are registered in the mvc-config.xml file with <action> tags

Whenever an action is invoked via the execute(actionName) function, the following sequence of events takes place:

The actionName is looked up in the mvc-config.xml file (actually the file contents are cached as a JavaScript Array, so the file is only downloaded once)

If there is a callBefore function specified, it is invoked. This could be anything, but I've used it to change the cursor appearance, hide changing components, and move form data around

If there is a view, it is retrieved and inserted into the named component. You don't have to have a view; for example, if you call a web service method that does not return data.

If a form is specified, data is retrieved from it and translated into a document/literal style SOAP message (see "Mapping Data").

If there was a model (the action might just load some static HTML), retrieve it. If an operation is specified, the model is treated as a web service endpoint location, and the form SOAP message (if any) is sent as a SOAP request to the operation. If there is no operation, the model is treated as a static XML file.

The returning SOAP response (which must also be document/literal style) is loaded into the view. (See "Mapping Data")

If there is a callAfter function specified, this is now called. Again, this could be anything, but I've used this to change the cursor appearance back to normal or to invoke a transition effect that shows the now populated page component.

Mapping Data

Incoming Data:

Incoming XML data must be document/literal style (i.e. not RPC encoded). If you don't know the difference between document/literal style and RPC encoded SOAP messages, here's an easy way to tell the difference: If the XML is legible, it's document/literal style. If you've ever hand-coded an XML file, you were (if you're not insane) writing it in document/literal style.

The name of the root node of the incoming XML is ignored. Its only purpose is to wrap the rest of the XML message. Within the root node, there are elements that contain more elements, and elements that contain text. Elements that contain more elements must map to HTML elements with an id attribute set to the tag name of the XML element, like this:

<Test>
   <name>Fred</name>
   <age>30</age>
</Test>

Maps to:

<tr id="Test"> ... </tr>

Elements that contain text must map to an HTML <div> tag that has a name attribute set to the tag name of the XML element, like this:

<name>Fred</name>

Maps to:

<div name="name"></div>

Elements should never contain both child elements and text.

XML data is mapped hierarchically. In the first example above, the name "Fred" would only be applied inside an HTML element with the id value "Test." If the <name> tag were not wrapped in a <Test> tag, then all the instances of

<div
name="name"></div>

would be filled with the value "Fred."

If there were more than one instance of the <Test> element in the first example, the AJAX MVC would duplicate the HTML element with the id value "Test" for each incoming <Test> element. This duplication can be nested to any arbitrary depth, and is illustrated in the sample application.

Outgoing Data:

Given the id of an HTML element that will be used as the "form" (the form attribute in the mvc-config.xml file), the same process used for incoming data is applied in reverse to produce a document/literal SOAP request message. Notice that any HTML element can be the "form" as long as its id is unique in the HTML document. Of course, you can use a true HTML <form> as your form, and the process works the same way. The only difference is that <input> tags get their values from their value attributes rather than their contents.

License

The AJAX MVC is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

The AJAX MVC is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

The AJAX MVC library includes a copy of the GNU Lesser General Public License (the LICENSE file). If you did not receive a copy of the license, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Acknowlegements

The AJAX MVC uses XML for <SCRIPT>, available at http://xmljs.sourceforge.net for XML parsing. Thanks to Jon van Noort, David Joham and Scott Severtson

The AJAX MVC deployment version is packed using Dean Edwards' "Packer," available at http://dean.edwards.name/packer/

Known Bugs

These are all expected to be fixed very soon!

Checkboxes/Radio buttons don't work

Packed version with inline XML SAX and XML W3C DOM doesn't load