Creating an AJAX-Enabled Application, a Toolkit Approach

 
 
By Rick Palkovic and Mark Basler, September 2006  

Articles Index

This is the second in a series of articles that describe ways to introduce Ajax functionality into an existing web application developed with the NetBeans IDE. Readers are encouraged to read the first article in the series, Creating an Ajax-Enabled Application, a Do-It-Yourself Approach, before reading this one. At a minimum, install the example project, the NetBeans 5.5 IDE, and the GlassFish server, as described in Downloading and Installing the Tools.

Learn About Ajax

For background information about Ajax and strategies for implementation, see Ajax Design Strategies by Ed Ort and Mark Basler.
 

Your first approach to introducing Ajax functionality into the Duke's Bookstore application was do-it-yourself: you hand-coded JavaScript and CSS files on the client side and wrote a servlet to service the Ajax XMLHttpRequest on the server.

The do-it-yourself approach works well enough for simple projects, but as your project grows you want to find an approach that requires less client-side coding. For your second attempt to implement pop-up balloons in your application, you use one of the available JavaScript libraries to minimize the amount of JavaScript code you need to write.

In this article, you use the JavaScript libraries available with the Dojo Toolkit. The Dojo Toolkit provides a comprehensive set of JavaScript libraries and is receiving industry support from companies such as Sun Microsystems, AOL, and IBM. The Dojo Tookit is the logical choice for your project. Note that adopting Dojo libraries doesn't preclude other solutions. If at some point the Dojo libraries don't provide required functionality, they can be combined with libraries from other sources.

One advantage of using Dojo libraries is that they are designed to work with various browsers when desired functionality is missing. As a minimum, JavaScript must be enabled on the client browser in order for Ajax techniques to work. However, if JavaScript has been disabled entirely on the browser, the Dojo libraries do not prevent the page from loading. In the case of your bookstore application, there is no real penalty to the user if a missing browser technology prevents the pop-up balloons from appearing, so the degraded case is easy to handle. For more feature-packed Ajax pages, degradable code is more important.

 
Contents
 
-  Downloading the Dojo Toolkit Library
-  Adding Dojo Libraries to an Application
-  Incorporating the Dojo Library Into Your Project
-  Opening the Bookstore Project in the NetBeans IDE
-  Replacing the bookcatalog.jsp File
-  Running the Bookstore Project
-  Examining the Dojo Files
-  Summary
-  Next Steps
-  References
 
Downloading the Dojo Toolkit Library

To download and install the Dojo Toolkit library:

  1. Download the compressed Dojo Toolkit file from the Dojo web site.

  2. Expand the downloaded file and read the accompanying documentation, especially the README file.

You are now ready to see how to use the Dojo library in a web application.

Adding Dojo Libraries to an Application

To use the Dojo libraries with a web application, two sections of code are required:

  1. Include the Dojo bootstrap file: 

                           
<script type="text/javascript" src="
                      
pathname
                      
/dojo.js"/>



    where pathname is the location where the dojo.js file is stored. The dojo.js file includes a section that bootstraps the Dojo Toolkit. Depending on the release build of Dojo you are using, the file also includes code for some of the Dojo library modules.

  2. Specify the packages you are using, such as dojo.io: 

                           
<script type="text/javascript"> dojo.require("dojo.io.*"); </script>



    Note the similarity to the Java import statement.

The next section describes how to use these statements in your project.

Incorporating the Dojo Library Into Your Project

To incorporate the Dojo libraries into the project you developed in Creating an Ajax-Enabled Application, a Do-It-Yourself Approach, you need to edit or replace the following two files:

  • project /examples/web/bookstore2/web/popup.js

  • project /examples/web/bookstore2/web/books/bookcatalog.jsp

where project is the root location of your project directory.

Pre-edited versions of the files have already been placed in the project for you, to be incorporated as described in the next section.

You also need to insert the dojo.js bootstrap file from the Dojo distribution into your project and include the supporting libraries.

The dojo.js File


The dojo.js file enables the entire Dojo library suite. The file includes some common functionality, such as dojo.io.bind. Depending on the Dojo edition, the file also provides a profile that makes certain Dojo features available. To make sure all Dojo features are available regardless of the Dojo edition, all editions provide access to the entire Dojo library in the dojo/src directory. Any features that aren't built into the dojo.js file can be dynamically loaded at runtime through the dojo.require() statement.

You can sometimes speed up your application's response time by customizing the dojo.js file to make it as small as possible (see the Dojo web site for more information). In your project you will use the default version of the file for the sake of simplicity.

The dojo.js file has already been placed in your NetBeans project, in the following location:

project /examples/web/bookstore2/web/dojo.js

where project is the root location of your project directory.

The popup_dojo.js File


To use the Dojo library in your project, you need to edit the existing popup.jsp file or replace it with a different file. A pre-edited version of the file, called popup_dojo.js, has been provided to speed the process. You will include popup_dojo.js in the project build and exclude popup.jsp by changing a line in the bookcatalog.jsp file.

Opening the Bookstore Project in the NetBeans IDE
  1. Start the NetBeans IDE if it is not already running.

  2. From the NetBeans toolbar, choose File > Open. The Open Project window opens.

  3. Navigate to project /examples/web/bookstore2. Select the bookstore2 project folder and click Open Project Folder. The IDE opens the project folder and selects bookstore2 as the main project. The bookstore project is also opened because bookstore2 depends on many of the files in bookstore.

  4. If the IDE flags the bookstore project and alerts you that references need to be resolved:

    1. Right-click the project and choose Resolve Reference Problems from the pop-up menu.

    2. In the resulting window, click Resolve and navigate to the server /glassfish/lib directory, where server is the root of your GlassFish server installation.

    3. Select the javaee.jar file and open it. Click Close to resolve the reference and close the window.

  5. If the bookstore2 project also produces an alert:

    1. Right-click on the project name and choose Resolve Missing Server Problem from the pop-up menu.

    2. In the resulting window, select the GlassFish server that you registered in Creating an Ajax-Enabled Application, a Do-It-Yourself Approach. Click OK to resolve the reference.

Replacing the bookcatalog.jsp File

You need to edit the bookcatalog.jsp file to reference the dojo.js and popup_dojo.js files you are using. Instead of editing the bookcatalog.jsp file, replace it with the bookcatalog_popup_dojo.jsp file already in the project directory.

  1. In the NetBeans IDE, click the Files tab to open the Files view of your project.

  2. Expand the bookstore2 > web > books node and select the bookcatalog.jsp file.

  3. Right-click and choose Rename from the pop-up menu. Rename the file to bookcatalog_popup.jsp to remove it from the build.

    Figure 1:Renaming the bookcatalog.jsp file
    Figure 1: Renaming the bookcatalog.jsp file
     
  4. Similarly, rename the bookcatalog_popup_dojo.jsp file to bookcatalog.jsp, making the new file part of the project build.
Running the Bookstore Project

You can now build and deploy the bookstore2 project.

In the NetBeans Projects window, the bookstore2 project should be shown in bold type to indicate that it is the main project. If it is not, set it as the main project by choosing Files > Set Main Project > bookstore2.

  • Build and deploy the bookstore2 project by choosing Run > Run Main Project.

The status of the build is shown in the NetBeans Output window. When the build finishes successfully, your browser opens to show the Duke's Bookstore application. The application behaves just as it did when you implemented pop-up balloons in the do-it-yourself approach.

Examining the Dojo Files

You now examine the files that make the pop-up balloons work with the Dojo library.

The bookcatalog.jsp File


To examine the bookcatalog.jsp (formerly the bookcatalog_popup_dojo.jsp file):

  1. In the NetBeans IDE, click the Files tab to show the Files view of the project.

  2. Expand the bookstore > web > books node and double-click bookcatalog.jsp. The file opens in the NetBeans Editor, as shown in the following figure.

    Reliable Messaging Screenshot
    Figure 2: The bookcatalog.jsp file in the NetBeans IDE
    Click here for a larger image.


The code of interest in bookcatalog.jsp lies between lines 28 and 58, bounded by the following comments: 

                   
<!-- BEGIN: popup -->



and

                   
<!-- END: popup -->



Lines 29–30, shown below, import two scripts: dojo.js, the base Dojo script, and popup_dojo.js, a modification of the original popup.js script. 

<script type="text/javascript" src="../dojo.js></script>
<script type="text/javascript" src="../popup_dojo.js"></script>



The remainder of the file is identical to the bookcatalog_popup.jsp file that you introduced in the do-it-yourself implementation described in Creating anAjax-Enabled Application, a Do-It-Yourself Approach.

The popup_dojo.js File


The dojo.js file you are using in your project requires no coding on your part. However, you do need to code the popup_dojo.js file, just as you do for the do-it-yourself approach.

The first line in the file makes sure that the dojo.io library package is available: 

                   
dojo.require("dojo.io.*");



This package is, in fact, the only one used in the project.

One advantage in the Dojo version of the pop-up JSP file is that the Dojo libraries provide the necessary initilization request for the Ajax XMLHttpRequest object. In the popup_dojo.js file, this request is provided by the showPopupInternal() function (lines 35–50). The request results from the object literal format (lines 38–45) where the objects are set up. Line 48 dispatches the request.

As discussed in the Creating an Ajax-Enabled Application, a Do-It-Yourself Approach, this function can be easily changed to direct the request to either a servlet or a JSP page on the server side by changing the value of the url argument.

The following table compares the bpui.alone.showPopupInternal() function in each file, stripped of most comments for brevity. In terms of the amount of code you have to write for this function, there is very little difference between the Dojo and the do-it-yourself approaches.

From popup_dojo.js File From popup.js File 
bpui.alone.showPopupInternal=
                    


function(popupx,  bookId) {
                    


  // retrieve data through dojo call
                    


  var bindArgs =  {
                    


    url: "../PopupServlet?bookId="
                    


      + escape (bookId),
                    


    mimetype: "text/xml",
                    


    handle:  bpui.alone.ajaxReturnFunction};
                    


  bpui.alone.req=dojo.io.bind (bindArgs);
                    


}
                    


                  
bpui.alone.showPopupInternal=
                    


function(popupx,  bookId) {
                    


  // set up request
                    


   bpui.alone.req=bpui.alone.initRequest();
                    


  url="../PopupServlet? bookId="
                    


      + escape(bookId);
                    


   bpui.alone.req.onreadystatechange =
                    


       bpui.alone.ajaxReturnFunction;
                    


  bpui.alone.req.open("GET", url,  true);
                    


  bpui.alone.req.send(null);
                    


}

The code illustrates one advantage of the Dojo libraries: they handle most browser differences for you, in this case eliminating the need for an initRequest() call.

The Ajax callback function, bpui.alone.ajaxReturnFunction(), also differs between the two files. View the function in lines 52–70 of the popup_dojo.js file.

In line 53, the function signature defines the type, data, and event arguments:

                   
bpui.alone.ajaxReturnFunction=function(type, data, evt)



whereas, in the popup.js file, the function signature does not define these arguments: 

                   
bpui.alone.ajaxReturnFunction=function()



The function in the popup_dojo.js file checks status of the returned XMLHttpRequest object using the evt (event) argument (lines 57–58): 

if (evt.readyState == 4) {
                  


    if (evt.status == 200) {
                  


       ...



In contrast, in the popup.js file, the same function checks the status of the XMLHttpRequest object directly with the following lines: 

if (bpui.alone.req.readyState == 4) {
                  


    if (bpui.alone.req.status == 200) {
                  


       ...



Overall, the popup_dojo.js and popup.js files represent about the same level of coding effort.

Summary

For the very simple Ajax functionality you are implementing in this example project, the benefits of a robust library aren't readily apparent, especially if the amount of hand coding required is the primary consideration.

As you expand your application's functionality, however, you can take advantage of additional library modules. In that case, there can be a clear advantage to using JavaScript libraries such as those provided by the Dojo Toolkit. For example, if you want to send form data through an Ajax call, the amount of hand coding can be very large in the do-it-yourself approach. In contrast, to introduce a form with Dojo, you need only create a form node in your bind argument. One line of code can provide the necessary functionality.

Even in the simplest of applications, a JavaScript library such as one provided by the Dojo Toolkit can provide some advantages. Notably,

  • It handles events for you.

  • It adjusts well to browser differences.

  • It provides support for history and bookmark browser features that can be troublesome in Ajax.

  • It handles cases in which JavaScript capability in the client browser is disabled or nonexistent.

  • It provides a wide range of useful widgets such as date picker, rich text editor, time picker, and many more.
 
Next Steps

In your next implementation, you create a custom JSF component to generate the Javascript that executes the Ajax interactions on the client side. The JSF component is packaged with the application bundle and accessed directly. A Java Servlet on the server side responds to the Ajax request.

References
 
Developer Services and Training
 
Rate and Review
Tell us what you think of the content of this page.
Excellent   Good   Fair   Poor  
Comments: