Using Dojo Toolkit for Building AJAX Applications (Remoting & Event Model & Usage of Widgets)

This hands-on lab takes you through the basics of using Dojo Toolkit for developing responsive and interactive AJAX-based web applications. This document is designed to get you going as quickly as possible. For more detail information on Dojo Toolkit, see the Resources section of Dojo Toolkit. 

The technologies you will get exposed in this hands-on lab include (1) how to use dojo.io.bind() call to do the remoting (2) how to use dojo.event.connect() call for handling various types of events including function calls (3) how to use the widgets that come with the Dojo toolkit (4) how to use JSON data format (5) how to retrieve data from the server.  

Creation of Dojo toolkit widgets will be dealt with in another hands-on lab.

Expected duration: 120 minutes

Exercise 1: Modify "Data Validation with AJAX" (ajax-validation) sample application to use dojo.io.bind()

In this exercise, you are going to modify "ajax-validation" sample program to use dojo.io.bind() call.  You will also use DOM manipulation utilities of Dojo toolkit as well. This sample application that you are going to modify is provided as ready-to-open NetBeans project called ajax-validation as part of the hands-on lab zip file (4260_ajaxdojointro.zip).

(1.1) Open, build, and run "ajax-validation" sample application

0. Start NetBeans IDE. 
1. Open ajax-validation NetBeans project. 

2. Build and run ajax-validation project.

Figure-1.12: Run the project

3.  Observe that the Firefox browser gets displayed. 
4. Type some characters like sa in the User Id: field.
5. Observe that Valid User Id string gets displayed on the right side of the text field. (Figure-1.13 below)  This is an example of AJAX usage case in which input data is being validated by the server through AJAX.

Figure-1.13: Running "Data Validation using AJAX" sample application

                                                                                                                                        return to top of the exercise

(1.2) Create a new project by copying the ajax-validation project you created above

You can modify the ajax-validation project directly.  But just to preserve the original project in its current form, we will create a new project by copying the ajax-validation project into a new project.  You will name the new project as ajax-validation-dojo.io.bind.

1. Right click ajax-validation project node and select Copy Project.  The Copy Project dialog box appears.
2. In the Project Name: field, type in ajax-validation-dojo.io.bind. Click Copy button. (Figure-1.14 below)  The ajax-validation-dojo.io.bind project appears under Projects tab window.

Figure-1.14: Copy Project dialog box

3. Change Context path of the new project. (You have to do this only for NetBeans 5.0. It will be done automatically for NetBeans 5.5.1)

Figure-1.15: Change the context path to reflect the new project's context path

                                                                                                                                        return to top of the exercise

(1.3) Copy Dojo toolkit JavaScript files into the newly created project

1. Select Window from the top-level menu bar and select Favorites (Ctrl+3). (Figure-1.16 below) This will add Favorites tab window.


Figure-1.16: Open Favorites window

2. Select Favorites tab window. (Figure-1.17 below) 
3. Right click in any point inside the Favorites tab window.  Select Add to Favorites. (Figure-1.17 below) 

4. In the Add to Favorite window, select the ajaxdojointro directory which is created when you unzipped the hands-on lab zip file, 4260_ajaxdojointro.zip file. Click Add. (Figure-1.18 below)

Figure-1.18: Add ajaxdojointro directory to the Favorites window

5. Select and right click dojo-0.4.3-ajax node under ajaxdojointro->dojo-json->web and select Copy. (Figure-1.19 below - the figure below shows dojo-0.4.3-ajax, which will be corrected later)  You are copying Dojo Toolkit JavaScript files from the local file system.

Figure-1.19: Copy Dojo toolkit JavaScript files

6. Select Projects tab window.  This will place the Projects tab window on the front (instead of Favorites tab window).
7. Expand ajax-validation-dojo.io.bind project node.
8. Right click Web Pages and select Paste. (Figure-1.20 below).  Observe that Dojo toolkit JavaScript files are copied into the project. 

Note: In production environment, you should pick and choose only the needed JavaScript files from Dojo toolkit in order to reduce the size of the files that need to be downloaded from the server to a client browser.  In this exercise, for the sake of the simplicity, we copied all JavaScript files from Dojo toolkit including demo files.


Figure-1.20: Paste the Dojo toolkit JavaScript files into the NetBeans project

                                                                                                                                        return to top of the exercise

(1.4) Modify index.jsp file to use dojo.io.bind()

In this step, you are going to modify index.jsp file to use dojo.io.bind() instead of directly creating XMlHttpRequest JavaScript object and using it to perform asynchronous communication with the server.

1. Double-click index.jsp of the ajax-validation-dojo.io.bind project to open it in the source editor window. (Figure-1.40 below) 

Figure-1.40: Open index.jsp in the source editor

2. Modify the index.jsp file as following.  The new code fragments that need to be added are highlighted in bold and blue colored font while the old code fragments that need to be removed are highlighted in bold and red colored font.  The code fragments that remain the same are in regular font.  Please pay attention to the comments that explain why some code fragments are removed and why some are added.  (This is the complete code of the index.jsp file.  So you can copy and paste the complete code.)

3. Right-click ajax-validation-dojo.bo.bind project and select Run Project.  The new project should behave in the same way ajax-validation project behaved as you've seen above. 

Trouble-shooting:  If you are experiencing a problem, for example, typing a string in the User Id: field does not generate Valid User Id message (Figure-1.42 below), open JavaScript Console and see the debugging messages displayed (Figure-1.43 below).

Figure-1.42: Open JavaScript Console for debugging

Figure-1.43: JavaScript Console displays errors discovered in the JavaScript.  The above indicates that you have not copied dojo.js file into your project yet or copied it into a directory that is not specified correctly in the index.jsp page.

                                                                                                                                        return to top of the exercise

(1.5) Use DOM manipulation methods of Dojo toolkit

(1.6) Error handling

In this step, you are going to simulate a HTTP error condition and see if the error handler in the dojo.io.bind() gets called.

1. Modify validateUserId() function of the index.jsp as shown in Code-1.60 below.  The new code fragments that need to be added are highlighted in bold and blue colored font while the old code fragments that need to be removed are highlighted in bold and red colored font.  This is to generate a HTTP error condition by passing an invalid path.

// This is the modified validateUserId() function function validateUserId() {     //if (!target) target = document.getElementById("userid");     if (!target) target = dojo.byId("userid");     //var sampleFormNode = document.getElementById("submit_btn");     var sampleFormNode = dojo.byId("submit_btn");         // Use dojo.io.bind() for remoting     dojo.io.bind({           // URL -  location of the data you want to get           //url: "validate?id=" + escape(target.value),           url: "validateInvalidURL?id=" + escape(target.value),                     // Callback function that you'd like to have called           // when you actually do get the data           load: function(type, data, evt){ processRequest(data);},                     // Error handling           error: function(type, error){ alert("error"); },                     // Backward and forward button handling           backButton: function() { alert("back button pressed"); },           forwardButton: function() { alert("forward button pressed");},                     // Type of data that is returned           mimetype: "text/xml"              });  }

Code-1.60: Simulate an error condition by passing invalid URL

2. Right-click ajax-validation-dojo.bo.bind project and select Run Project.  Firefox browser gets displayed.
3. Type in a character into the User Id field in the browser.
4. You should see an alert message. (Figure-1.61 below)


Figure-1.61: Error handler displays an alert message

5.  Remove the error condition by removing the change you made in validateUserId() function of the index.jsp in Code-1.60 above.

                                                                                                                                        return to top of the exercise

(1.7) Experiment with "mimetype"

Please note that you were using "text/xml" as a value of "mimetype".  What it does is when the data is received from the server, it is parsed as an XML document.  That is the reason you could extract the data as an DOM object inside the proceRequest(data) function as shown below. Since it is a DOM object you could use getElementByTagName(..) or dojo.dom.textContent..) DOM methods.

// This is the modified processRequest() function function processRequest(data) {             // var message = data.getElementsByTagName("valid")[0].childNodes[0].nodeValue;             var message = dojo.dom.textContent(data.getElementsByTagName("valid")[0]);             setMessageUsingDOM(message);             //var submitBtn = document.getElementById("submit_btn");             var submitBtn = dojo.byId("submit_btn");             if (message == "false") {               submitBtn.disabled = true;             } else {               submitBtn.disabled = false;             } }

Figure-1.70: Received the data as DOM object

Now let's change the mimetype to "text/plain" and see what happens.

1. Modify validateUserId() function of the index.jsp as shown in Code-1.60 below.  The new code fragments that need to be added are highlighted in bold and blue colored font while the old code fragments that need to be removed are highlighted in bold and red colored font. 

// This is the modified validateUserId() function function validateUserId() {     //if (!target) target = document.getElementById("userid");     if (!target) target = dojo.byId("userid");     //var sampleFormNode = document.getElementById("submit_btn");     var sampleFormNode = dojo.byId("submit_btn");         // Use dojo.io.bind() for remoting     dojo.io.bind({           // URL -  location of the data you want to get           url: "validate?id=" + escape(target.value),                     // Callback function that you'd like to have called           // when you actually do get the data           load: function(type, data, evt){ processRequest(data);},                     // Error handling           error: function(type, error){ alert("error"); },                     // Backward and forward button handling           backButton: function() { alert("back button pressed"); },           forwardButton: function() { alert("forward button pressed");},                     // Format of the data to which the received data will be interpreted           //mimetype: "text/xml"             mimetype: "text/plain"           });  }

Code-1.71: Simulate an error condition by passing invalid URL

2. Right-click ajax-validation-dojo.bo.bind project and select Run Project.  Firefox browser gets displayed.
3. Press F12 key to see the FireBug debugger.
5. Type in characters into the User Id field in the browser.
6. Observe the error condition reported by the FireBug debugger. (Figure-1.72 below)  The error indicates that the data that is received from the server is not parsed as an XML document anymore since you indicated your intention of receiving the data in plain text form. 


Figure-1.72: The data is not interpreted as XML

7. Change it the mimetype to "text/xml"   to make things work again.

                                                                                                                                        return to top of the exercise

(1.8) Use "formNode" parameter of dojo.io.bind()

In this step, you are going to use "formNode" to send the entire form (collection of input form fields) to the server.

1. Modify validateUserId() function of the index.jsp as shown in Code-1.80 below.  The new code fragments that need to be added are highlighted in bold and blue colored font while the old code fragments that need to be removed are highlighted in bold and red colored font. 

// This is the modified validateUserId() function function validateUserId() {     //if (!target) target = document.getElementById("userid");     if (!target) target = dojo.byId("userid");     //var sampleFormNode = document.getElementById("submit_btn");     var sampleFormNode = dojo.byId("submit_btn");         // Use dojo.io.bind() for remoting     dojo.io.bind({           // URL -  location of the data you want to get           //url: "validate?id=" + escape(target.value),           // Since the form data is passed to the server via formNode           // parameter below, no need to pass target.value here.           url: "validate",              // The server code in this ajax-validation           // sample application expects "GET".  It           // uses "POST" for account creation. Probably           // not a good practice but that is the way           // the server side code is written for now.           method: "GET",            // Send form data. "myform" is the id of the input form.            formNode: dojo.byId("myform"),                         // Callback function that you'd like to have called           // when you actually do get the data           load: function(type, data, evt){ processRequest(data);},                     // Error handling           error: function(type, error){ alert("error"); },                     // Backward and forward button handling           backButton: function() { alert("back button pressed"); },           forwardButton: function() { alert("forward button pressed");},                     // Type of data you want to receive           mimetype: "text/xml"              });  }

Code-1.80: Use formNode

2. Modify the <form ..> element to give it an id attribute as shown in Code-1.81 below.  Note that  id="myform" is added as an attribute.

<form id="myform" name="updateAccount" action="validate" method="post">    <input type="hidden" name="action" value="create"/>    <table border="0" cellpadding="5" cellspacing="0">     <tr>      <td><b>User Id:</b></td>      <td>       <input    type="text"                 size="20"                  id="userid"         name="id"              onkeyup="validateUserId()">      </td>      <td>       <div id="userIdMessage"></div>      </td>     </tr>     <tr>      <td align="right" colspan="2">       <input id="submit_btn" type="Submit" value="Create Account">      </td>      <td></td>     </tr>    </table>   </form>

Code-1.81: Add an id attribute to the <form ..> element

3. Right-click ajax-validation-dojo.bo.bind project and select Run Project.  Firefox browser gets displayed.
4. Press F12 key to see the FireBug debugger.
5. Type in characters into the User Id field in the browser.
6. Observe the HTTP traffic between the browser and server. (Figure-1.82 below)


Figure-1.82: Usage of formNode

(1.9) Play around with "Forward"/"Backward" and bookmarking

1. Modify the index.jsp as shown in Code-1.90 below.  The new code fragments that need to be added are highlighted in bold and blue colored font.

<!-- Dojo configuration --> <script language="JavaScript" type="text/javascript">        djConfig = { preventBackButtonFix: false }; </script> <!-- Include Dojo toolkit library file dojo.js, make sure the directory path is set correctly --> <script language="JavaScript"             type="text/javascript"             src="dojo-0.4.3-ajax/dojo.js">                </script>    <script type="text/javascript"> dojo.require("dojo.undo.browser"); var target;

Code-1.90: Add Dojo configuration

2. Copy the iframe_history.html from the dojo-0.4.3-ajax/ directory to its parent directory.
3. Right-click ajax-validation-dojo.bo.bind project and select Run Project.  Firefox browser gets displayed.
4. Press F12 key to see the FireBug debugger.
5. Type in characters into the User Id field in the browser.
6. Press backward button.  (Figure-1.91 below)
7. Observe the alert message. (Figure-1.91 below) Click OK button to close the alert message.


Figure-1.91: Backward button function gets called

9. Press forward button. (Figure-1.92 below)
10. Observe the alert message. (Figure-1.92 below)


Figure-1.92: Forward button function gets called

Now let's suppose that we want the behavior of the backward button to be something like "starting new". 

11.  Modify validateUserId() function of the index.jsp as shown in Code-1.93 below.  The new code fragments that need to be added are highlighted in bold and blue colored font while the old code fragments that need to be removed are highlighted in bold and red colored font.

// This is the modified validateUserId() function function validateUserId() {     //if (!target) target = document.getElementById("userid");     if (!target) target = dojo.byId("userid");     //var sampleFormNode = document.getElementById("submit_btn");     var sampleFormNode = dojo.byId("submit_btn");         // Use dojo.io.bind() for remoting     dojo.io.bind({           // URL -  location of the data you want to get           //url: "validate?id=" + escape(target.value),           // Since the form data is passed to the server via formNode           // parameter below, no need to pass target.value here.           url: "validate",              // The server code in this ajax-validation           // sample application expects "GET".  It           // uses "POST" for account creation. Probably           // not a good practice but that is the way           // the server side code is written for now.           method: "GET",            // Send form data. "myform" is the id of the input form.            formNode: dojo.byId("myform"),                         // Callback function that you'd like to have called           // when you actually do get the data           load: function(type, data, evt){ processRequest(data);},                     // Error handling           error: function(type, error){ alert("error"); },                     // Backward and forward button handling           // backButton: function() { alert("back button pressed"); },           // New backward button behavior           backButton: function() {                  // Blank out the User Id field value                  target.value="";                  // Display a message indicating Backward button is pressed                  var userMessageElement = dojo.byId("userIdMessage");                  userMessageElement.innerHTML = "Backward button pressed. Start again!";                  // Disable the submit button                  var submitBtn = dojo.byId("submit_btn");                  submitBtn.disabled = true;           },           forwardButton: function() { alert("forward button pressed");},                     // Type of data you want to receive           mimetype: "text/xml"              });  }

Code-1.93: Modified behavior of the backward button

12. Right-click ajax-validation-dojo.bo.bind project and select Run Project.  Firefox browser gets displayed.
13. Type in characters into the User Id field in the browser.
14. Press backward button.  (Figure-1.91 below)
15. Observe that User Id field is blanked out while "Backward button pressed, Start again!" message gets displayed and the Created Account button is disabled.


Figure-1.94: New Backward button behavior


                                                                                                                                        return to top of the exercise

(1.10) Move JavaScript code into a separate file

In this step, you are going to move the JavaScript code into another file called, myjavascript.js.  This is an optional step.

1.  (Assuming you have installed NetBeans JavaScript editor plug-in), right click Web Pages under ajax-validation-dojo.io.bind project node and select New->JSTemplate.js.
2. Observe New JSTemplate.js dialog box appears.
3. For the File Name field, type in myjavascript. Click Finish. (Figure-1.100 below)

Figure-1.100: Create myjavascript.js file

Note: If you have not installed NetBeans JavaScript editor plug-in, just create a new file called myjavacript.js under Web Pages directory.

12. Right-click ajax-validation-dojo.bo.bind project and select Run Project.

                                                                                                                                        return to top of the exercise

Solution to Exercise 1

Summary

In this exercise, you have modified sample applications that use XMLHttpRequest  to use dojo.io.bind() from Dojo toolkit instead. 

                                                                                                                                                return to the top

Exercise 2: Dojo Event Model

In this exercise, you will exercise the various event programming models of the Dojo toolkit.

1. Create a new project called "dojo-event1" by copying the "ajax-validation-dojo.io.bind" project you created above
   
2. Use dojo.event.connect() call for a user initiated event
   
3. Use dojo.event.connect() call for window loading event
   
4. Attach a function of an object to a DOM node's event handler
5. Attach multiple event handlers
6. Attach "before advice" event handler
7. Attach "around" event handler wrapper
8. Publish and subscribe event model (will be added in the future)
9. Disconnect (will be added in the future)
   

(2.1) Create a new project called "dojo-event1" by copying the "ajax-validation-dojo.io.bind" project you created above

You can create a new NetBeans project from scratch but you can also create one that contains Dojo toolkit library file by copying the ajax-validation-dojo.io.bind project.  We will name it as dojo-event1 project.

1. Right click ajax-validation-dojo.io.bind project and select Copy Project.  The Copy Project dialog box appears.
2. In the Project Name: field, type in dojo-event1. (Figure-2.10 below) The copying project might take a couple of minutes. The dojo-event1 project appears under Projects tab window.

Figure-2.10: Create dojo-event1 project by copying

3. Change Context Path of the new project. (You have to do this only for NetBeans 5.0.  It is taken care of automatically for NetBeans 5.5)

• Right-click dojo-event1 project and select Properties.  The Project Properties dialog box appears.
• Select Run and change the Context Path: field to /dojo-event1. (Figure-2.11 below)
  

Figure-2.11: Change the Context Path to /dojo-event1

                                                                                                                                        return to top of the exercise

(2.2) Use dojo.event.connect() call for a user initiated event

We are now going to modify the index.jsp in which we are going to use dojo.event.connect().  

Note: If you want to leave the original code intact, you can always create a new project by copying the current project.  Please make sure you change the Context Path: to reflect the new project name if you decided to do so.

1. Double-click the index.jsp file of the dojo-event1 project to open it in the  source editor.  Please make sure you do not change the index.jsp file of the ajax-validation-dojo.io.bind project unless that is what you want to.

2. Replace the complete content of the index.jsp file with the following code (Code-2.20 below).  Please study how dojo.event.connect() call is used to register myHandler event handler to the onclick property of the mylink node.

3. Right click dojo-event1 project and select Run Project.  You should see the following page. (Figure-2.21 below)

Figure-2.21: Simple Dojo Event Handler front page

4. Click Click Me link.  You should see an alert message that gets invoked inside the event handler. (Figure-2.22 below) Click OK to close the alert.


Figure-2.22: Alert message from the event handler

(2.3) Use dojo.event.connect() call for window loading event

1. Modify the index.jsp to use dojo.event.connect() call for window loading event.  (Code-2.30 below).  The new code fragments that need to be added are highlighted in bold and blue-colored font while the old code fragments that need to be removed are highlighted in bold and red colored font.  The code fragments that remain the same are in regular font.