How to Create an AJAX-enabled Phobos Application

Before getting started with this tutorial, you should satisfy the following requirements:

• Be familiar with the basic structure of a Phobos application. You can get this information from the tutorial, Your First Phobos Application, or the Phobos Overview document.
• Understand the basics of AJAX.

Introducing the List Example

Running the Example

1. Make sure you have the NetBeans 5.5 IDE installed and running on your system.
2. Install the Ajax update center and all the Phobos modules in the IDE following all the instructions on the Phobos download page.
3. Create a new project selecting "Scripting / Samples" as the category and "Ajax List" as the project:

http://localhost:8888/

How the Application Works

• A startup script that directs the request to the controller so that the view can be rendered.  In the AJAXlist example, this file is called index.js, and is located in the application/script directory of the project.
• An embedded JavaScript file that represents the view. This file contains the code to initialize and send the XMLHttpRequest, the HTML that defines the form components that appear on the page, and any style information.  In the AJAXlist example, this file is called list.ejs, and is located in the application/view directory of the project.
  
• A controller that handles the incoming XMLHttpRequest and renders the view.  In the AJAXlist example, this file is called list.js, and is located in the application/controller directory of the project.

1. The index.js file handles the initial request by redirecting it to the /list/show URL. The list part of the URL is a controller, and show is one of its functions. The show function is defined in list.js.
2. The Phobos runtime creates the List controller and invokes the show function.
3. The show function creates the list, saves it into the session, and renders the list.ejs view.
4. The user enters an item to add to the list and clicks the Add to List button.
5. When the user clicks Add to List, the XMLHttpRequest object is created, and the client sends a POST HTTP request to the /list/compute URL with the request paramenters representing the value that the user entered and the command "add", thereby calling the compute function of List controller with these parameters.
   
6. The compute function does the following:
   1. Gets the value the user entered and the value of the command.
   2. Adds the value to the list and saves it into the session.
   3. Sends the list as part of the response back to the client.
7. When the user clicks an item in the list that is rendered to the page, another XMLHttpRequest object is created and the compute function is called again, this time passing the index of the item to be deleted and the command "remove" as the request parameters.
8. The compute function does the following:
   1. Gets the value of the index and the command from the request parameters.
   2. Removes the item at the selected index from the list and saves the list into session.
   3. Sends the new list as part of the response back to the client.

• Handling the Initial Request
• Rendering the View
• Creating the Form Template
• Creating and Sending an XMLHttpRequest
• Processing the XMLHttpRequest

Handling the Initial Request

library.httpserver.sendRedirect(library.httpserver.makeURL("/list/show"));

Rendering the View

 var list = invocation.session.list;
 if (list == undefined) {
   var list = new Array();
   invocation.session.list = library.json.serialize(list);
 }

library.view.render("list.ejs");

• A set of CSS styles
• The script that initializes the XMLHttpRequest object and sends it to the controller
• The HTML tags that represent the form elements on the page

Creating the Form Template

  <div id="listForm" class="listContainer">
  <form name="autofillform" onSubmit="submitData(); return false;">
   <input id="entryField" type="text" size="20" value="Enter New Value">
   <input type="button" onclick="submitData(); return false;" value="Add to List">
  </form>
 <div id="list" class="listDiv"></div>
</div>

Notice that there are two div tags, one inside the other. A JavaScript function looks for a tag in a page using the unique IDs of div tags. The outer div tag wraps the form component, which includes the field in which the user enters an item, and the button to add the item to the list, as well as the inner div tag. The inner div tag identifies the component that displays the list on the page.

When the user clicks the button, Phobos gets the ID of the entire list and invokes the submitData method, which the next section discusses.  The response that the server returns includes the updated list, which includes the item the user added.  This response replaces the inner div tag.  The following code is an example of a response that shows a 2-item list:

<ol>
<li><div class=\"plain\" onmouseover=\"this.className ='over';\" 
	onmouseout=\"this.className ='plain';\" 
	onclick=\"removeItem('"0"')\">" + list[0] + "</div></li>
<li><div class=\"plain\" onmouseover=\"this.className ='over';\" 
	onmouseout=\"this.className ='plain';\" 
	onclick=\"removeItem('"1"')\">" + list[1] + "</div></li>
</ol>

Note that the removeItem function is invoked with the index of the item on which the user clicked.  You'll see in the next section how submitData and removeItem construct URLs with the appropriate request parameters so that the controller appropriately adds an item to or removes an item from the list.

Creating and Sending the XMLHttpRequest to the Controller

function submitData() {
    entryField = document.getElementById("entryField");
    var url = <%= library.view.quoteUrl("/list/compute") %>; 
	+ "?command=add&entryField=" + entryField.value;
    initRequest(url);
}

The add command and the value of entryField are added to the URL as request parameters.  The compute function of the List controller uses the command to determine if it needs to add an item to or remove an item from the list.

Similarly to submitData, the removeItem function creates a URL, which it passes to the initRequest function.

function removeItem(index) {
    var url = <%= library.view.quoteUrl("/list/compute") %> + "?command=remove&index=" + index;
    initRequest(url);   
}

Note that removeItem takes the index of the item to remove and adds it as well as the remove command to the URL as request parameters.

The initRequest function creates the XMLHttpRequest object and sends it to the URL passed to it by the submitData or removeItem functions. As shown in the following code, the initRequest function is exactly the same as it would be if you were implementing this example with any other web application framework.

function initRequest(url) {
    var list = document.getElementById("list");
    if (window.XMLHttpRequest) {
        req = new XMLHttpRequest();
    } else if (window.ActiveXObject) {
        isIE = true;
        req = new ActiveXObject("Microsoft.XMLHTTP");
    }
    req.onreadystatechange = processRequest;
    req.open("POST", url, true);
    req.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
    req.send(null);
    
    function processRequest () {
      if (req.readyState == 4) {
        if (req.status == 200) {
          list.innerHTML = req.responseText;
        }
      }
    }

}

• Creates the XMLHttpRequest object, first checking if the user's browser is Internet Explorer or not and creating the object accordingly.
• Sets the object's onreadystatechange property to the callback function, processRequest. This means that whenever the readyState of the object changes, this function is invoked.
• The processRequest function checks if the readyState is 4, which means that the request is completed, and then it checks if the status of the request is 200, which means that it was successful. In that case, the processRequest function replaces the list div element with the response from the controller.
• The initRequest function then calls the object's open function, passing in the HTTP method, the URL to send the request, and a boolean indicating whether or not to make the request asynchronous.
  
• Finally, it sends the request to the URL specified, which means that the compute function of the List controller will be invoked.

Processing the XMLHttpRequest

The compute function uses the onMethod function of the Phobos httpserver library to restrict parts of its implementation to only be invoked during certain HTTP methods. In the case of the code that adds items to or removes items from the list and returns the response, the compute function ensures that this code is only executed during a POST:

this.compute = function() {
	library.httpserver.onMethod({
		POST: function() {
			//code to add items from the list and remove items from the list
		},

	var list = library.json.deserialize(invocation.session.list);

      if (command == "add") {
	   var index = list.length;
	   list[index] = entryField;
	}
	if (command == "remove") {
	   var index = Number(request.getParameter("index"));
	   var length = list.length;
	   if (index != null) {
		while (index < length - 1){
			list[index] = list[index+1];
			index = index + 1;
		}
		list.length = index;
	   }

After it updates the list, the compute function sends the response back to the client:

	response.setStatus(200);
	response.setContentType("text/html");
	writer = response.getWriter();
	writer.println("<ol>");	
        for (var index = 0; index < list.length; ++index){
           writer.println("<li><div class=\"plain\" onmouseover=\"this.className ='over';\" 
	      onmouseout=\"this.className ='plain';\" 
	      onclick=\"removeItem('" + index + "')\">" + list[index] + "</div></li>");
        }
        writer.println("</ol>");
        writer.flush(); 

Deploying the Application

What's Next