Creating a Dynamic User Interface

The idea behind a dynamic user interface is to have a common “framework” for all samples. We will create a new web application and then add new features to the application as we go on. The user interface will look something like the following figure:

The user interface has three main areas: the title/logo that is static, the tabs that are dynamic, and the content area that shows the actual content.

The idea behind this implementation is to use DWR functionality to generate tabs and to get content for the tab pages. The tabbed user interface is created using a CSS template from the Dynamic Drive CSS Library (http://dynamicdrive.com/style/csslibrary/item/css-tabs-menu). Tabs are read from a properties file, so it is possible to dynamically add new tabs to the web page. The following screenshot shows the user interface.

The following sequence diagram shows the application flow from the logical perspective. Because of the built-in DWR features we don’t need to worry very much about how asynchronous AJAX “stuff” works. This is, of course, a Good Thing.

Now we will develop the application using the Eclipse IDE and the Geronimo test environment

Creating a New Web Project

1. 1. First, we will create a new web project. Using the Eclipse IDE we do the following: select the menu File | New | Dynamic Web Project.
   2. This opens the New Dynamic Web Project dialog; enter the project name DWREasyAjax and click Next, and accept the defaults on all the pages till the last page, where Geronimo Deployment Plan is created as shown in the following screenshot:

1. 1. Enter easyajax as Group Id and DWREasyAjax as Artifact Id. On clicking Finish, Eclipse creates a new web project. The following screen shot shows the generated project and the directory hierarchy.

1. Before starting to do anything else, we need to copy DWR to our web application. All DWR functionality is present in the dwr.jar file, and we just copy that to the WEB-INF | lib directory.

A couple of files are noteworthy: web.xml and geronimo-web.xml. The latter is generated for the Geronimo application server, and we can leave it as it is. Eclipse has an editor to show the contents of geronimo-web.xml when we double-click the file.

Configuring the Web Application

The context root is worth noting (visible in the screenshot above). We will need it when we test the application.

The other XML file, web.xml, is very important as we all know. This XML will hold the DWR servlet definition and other possible initialization parameters. The following code shows the full contents of the web.xml file that we will use:

<?xml version="1.0" encoding="UTF-8"?>
<web-app

xsi_schemaLocation=”http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web- app_2_5.xsd”
id=”WebApp_ID” version=”2.5″>
<display-name>DWREasyAjax</display-name>
<servlet>
<display-name>DWR Servlet</display-name>
<servlet-name>dwr-invoker</servlet-name>
<servlet-class>
org.directwebremoting.servlet.DwrServlet
</servlet-class>
<init-param>
<param-name>debug</param-name>
<param-value>true</param-value>
</init-param>
</servlet>

<servlet-mapping>
<servlet-name>dwr-invoker</servlet-name>
<url-pattern>/dwr/*</url-pattern>
</servlet-mapping>

<welcome-file-list>
<welcome-file>index.html</welcome-file>
<welcome-file>index.htm</welcome-file>
<welcome-file>index.jsp</welcome-file>
<welcome-file>default.html</welcome-file>
<welcome-file>default.htm</welcome-file>
<welcome-file>default.jsp</welcome-file>
</welcome-file-list>
</web-app>

DWR cannot function without the dwr.xml configuration file. So we need to create the configuration file. We use Eclipse to create a new XML file in the WEB-INF directory. The following is required for the user interface skeleton. It already includes the allow-element for our DWR based menu.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dwr PUBLIC
    "-//GetAhead Limited//DTD Direct Web Remoting 2.0//EN"
    "http://getahead.org/dwr/dwr20.dtd">
<dwr>
  <allow>
    <create creator="new" javascript="HorizontalMenu">
      <param name="class" value="samples.HorizontalMenu" />
    </create>
  </allow>
</dwr>

In the allow element, there is a creator for the horizontal menu Java class that we are going to implement here. The creator that we use here is the new creator, which means that DWR will use an empty constructor to create Java objects for clients. The parameter named class holds the fully qualified class name.

Developing the Web Application

Since we have already defined the name of the Java class that will be used for creating the menu, the next thing we do is implement it. The idea behind the HorizontalMenu class is that it is used to read a properties file that holds the menus that are going to be on the web page.

We add properties to a file named dwrapplication.properties, and we create it in the same samples-package as the HorizontalMenu-class. The properties file for the menu items is as follows:

menu.1=Tables and lists,TablesAndLists
menu.2=Field completion,FieldCompletion

The syntax for the menu property is that it contains two elements separated by a comma. The first element is the name of the menu item. This is visible to user. The second is the name of HTML template file that will hold the page content of the menu item.

The class contains just one method, which is used from JavaScript and via DWR to retrieve the menu items. The full class implementation is shown here:

package samples;

import java.io.IOException;
import java.io.InputStream;
import java.util.List;
import java.util.Properties;
import java.util.Vector;

public class HorizontalMenu {
public HorizontalMenu() {
}

public List<String> getMenuItems() throws IOException {
List<String> menuItems = new Vector<String>();
InputStream is = this.getClass().getClassLoader().getResourceAsStream(
“samples/dwrapplication.properties”);
Properties appProps = new Properties();
appProps.load(is);
is.close();
for (int menuCount = 1; true; menuCount++) {
String menuItem = appProps.getProperty(“menu.” + menuCount);
if (menuItem == null) {
break;
}
menuItems.add(menuItem);
}
return menuItems;
}
}

The implementation is straightforward. The getMenuItems() method loads properties using the ClassLoader.getResourceAsStream() method, which searches the class path for the specified resource. Then, after loading properties, a for loop is used to loop through menu items and then a List of String-objects is returned to the client. The client is the JavaScript callback function that we will see later. DWR automatically converts the List of String objects to JavaScript arrays, so we don’t have to worry about that.

Testing the Web Application

We haven’t completed any client-side code now, but let’s test the code anyway. Testing uses the Geronimo test environment.

1. 1. The Project context menu has the Run As menu that we use to test the application as shown in the following screenshot:

1. 1. Run on Server opens a wizard to define a new server runtime. The following screenshot shows that the Geronimo test environment has already been set up, and we just click Finish to run the application. If the test environment is not set up, we can manually define a new one in this dialog:

1. 1. After we click Finish, Eclipse starts the Geronimo test environment and our application with it. When the server starts, the Console tab in Eclipse informs us that it’s been started.

The Servers tab shows that the server is started and all the code has been synchronized, that is, the code is the most recent (Synchronization happens whenever we save changes on some deployed file.) The Servers tab also has a list of deployed applications under the server. Just the one application that we are testing here is visible in the Servers tab.

Now comes the interesting part—what are we going to test if we haven’t really implemented anything? If we take a look at the web.xml file, we will find that we have defined one initialization parameter. The Debug parameter is true, which means that DWR generates test pages for our remoted Java classes. We just point the browser (Firefox in our case) to the URL http://127.0.0.1:8080/DWREasyAjax/dwr and the following page opens up:

This page will show a list of all the classes that we allow to be remoted. When we click the class name, a test page opens as in the following screenshot:

This is an interesting page. We see all the allowed methods, in this case, all public class methods since we didn’t specifically include or exclude anything. The most important ones are the script elements, which we need to include in our HTML pages. DWR does not automatically know what we want in our web pages, so we must add the script includes in each page where we are using DWR and a remoted functionality.

Then there is the possibility of testing remoted methods. When we test our own method, getMenuItems(), we see a response in an alert box:

The array in the alert box in the screenshot is the JavaScript array that DWR returns from our method.

Developing Web Pages

The next step is to add the web pages. Note that we can leave the test environment running. Whenever we change the application code, it is automatically published to test the environment, so we don’t need to stop and start the server each time we make some changes and want to test the application.

The CSS style sheet is from the Dynamic Drive CSS Library. The file is named styles.css, and it is in the WebContent directory in Eclipse IDE. The CSS code is as shown:

/*URL: http://www.dynamicdrive.com/style/ */

.basictab{
padding: 3px 0;
margin-left: 0;
font: bold 12px Verdana;
border-bottom: 1px solid gray;
list-style-type: none;
text-align: left; /*set to left, center, or right to align the menu as desired*/
}

.basictab li{
display: inline;
margin: 0;
}

.basictab li a{
text-decoration: none;
padding: 3px 7px;
margin-right: 3px;
border: 1px solid gray;
border-bottom: none;
background-color: #f6ffd5;
color: #2d2b2b;
}

.basictab li a:visited{
color: #2d2b2b;
}

.basictab li a:hover{
background-color: #DBFF6C;
color: black;
}

.basictab li a:active{
color: black;
}

.basictab li.selected a{ /*selected tab effect*/
position: relative;
top: 1px;
padding-top: 4px;
background-color: #DBFF6C;
color: black;
}

This CSS is shown for the sake of completion, and we will not go into details of CSS style sheets. It is sufficient to say that CSS provides an excellent method to create websites with good presentation.

The next step is the actual web page. We create an index.jsp page, in the WebContent directory, which will have the menu and also the JavaScript functions for our samples. It should be noted that although all JavaScript code is added to a single JSP page here in this sample, in “real” projects it would probably be more useful to create a separate file for JavaScript functions and include the JavaScript file in the HTML/JSP page using a code snippet such as this: <script type=”text/javascript” src=”myjavascriptcode/HorizontalMenu.js”/>.

We will add JavaScript functions later for each sample. The following is the JSP code that shows the menu using the remoted HorizontalMenu class.

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
    pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
    "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<link href="styles.css" rel="stylesheet" type="text/css"/>
<script type='text/javascript' src='/DWREasyAjax/dwr/engine.js'></script>
<script type='text/javascript' src='/DWREasyAjax/dwr/util.js'></script>
<script type='text/javascript' src='/DWREasyAjax/dwr/interface/HorizontalMenu.js'></script>
<title>DWR samples</title>
<script type="text/javascript">

function loadMenuItems()
{
HorizontalMenu.getMenuItems(setMenuItems);
}

function getContent(contentId)
{
AppContent.getContent(contentId,setContent);
}

function menuItemFormatter(item)
{
elements=item.split(‘,’);
return ‘<li><a href=”#”
onclick=”getContent(”+elements[1]+”);return false;”>’+elements[0]+'</a></li>’;
}

function setMenuItems(menuItems)
{
menu=dwr.util.byId(“dwrMenu”);
menuItemsHtml=”;
for(var i=0;i<menuItems.length;i++)
{
menuItemsHtml=menuItemsHtml+menuItemFormatter(menuItems[i]);
}
menu.innerHTML=menuItemsHtml;
}

function setContent(htmlArray)
{
var contentFunctions=”;
var scriptToBeEvaled=”;
var contentHtml=”;
for(var i=0;i<htmlArray.length;i++)
{
var html=htmlArray[i];
if(html.toLowerCase().indexOf(‘<script’)>-1)
{
if(html.indexOf(‘TO BE EVALED’)>-1)
{
scriptToBeEvaled=html.substring(html.indexOf(‘>’)+1,html.indexOf(‘</’));
}
else
{
eval(html.substring(html.indexOf(‘>’)+1,html.indexOf(‘</’)));
contentFunctions+=html;
}
}
else
{
contentHtml+=html;
}
}

contentScriptArea=dwr.util.byId(“contentAreaFunctions”);
contentScriptArea.innerHTML=contentFunctions;
contentArea=dwr.util.byId(“contentArea”);
contentArea.innerHTML=contentHtml;
if(scriptToBeEvaled!=”)
{
eval(scriptToBeEvaled);
}
}
</script>
</head>
<body onload=”loadMenuItems()”>
<h1>DWR Easy Java Ajax Applications</h1>
<ul class=”basictab” id=”dwrMenu”>
</ul>
<div id=”contentAreaFunctions”>
</div>
<div id=”contentArea”>
</div>
</body>
</html>

This JSP is our user interface. The HTML is just normal HTML with a head element and a body element. The head includes reference to a style sheet and to DWR JavaScript files, engine.js, util.js, and our own HorizontalMenu.js. The util.js file is optional, but as it contains very useful functions, it could be included in all the web pages where we use the functions in util.js.

The body element has a contentArea place holder for the content pages just below the menu. It also contains the content area for JavaScript functions for a particular content. The body element onload-event executes the loadMenuItems() function when the page is loaded. The loadMenuItems() function calls the remoted method of the HorizontalMenu Java class. The parameter of the HorizontalMenu. getMenuItems() JavaScript function is the callback function that is called by DWR when the Java method has been executed and it returns menu items.

The setMenuItems() function is a callback function for the loadMenuItems() function mentioned in the previous paragraph. While loading menu items, the Horizontal.getMenuItems() remoted method returns menu items as a List of Strings as a parameter to the setMenuItems() function. The menu items are formatted using the menuItemFormatter() helper function.

The menuItemFormatter() function creates li elements of menu texts. Menus are formatted as links, (a href) and they have an onclick event that has a function call to the getContent-function, which in turn calls the AppContent.getContent() function.

The AppContent is a remoted Java class, which we haven’t implemented yet, and its purpose is to read the HTML from a file based on the menu item that the user clicked. Implementation of AppContent and the content pages are described in the next section.

The setContent() function sets the HTML content to the content area and also evaluates JavaScript options that are within the content to be inserted in the content area (this is not used very much, but it is there for those who need it).

Our dynamic user interface looks like this:

Note the Firebug window at the bottom of the browser screen. The Firebug console in the screenshot shows one POST request to our HorizontalMenu.getMenuItems() method. Other Firebug features are extremely useful during development work, and we find it useful that Firebug has been enabled throughout the development work.

Callback Functions

We saw our first callback function as a parameter in the HorizontalMenu.getMenuItems(setMenuItems) function, and since callbacks are an important concept in DWR, it would be good to discuss a little more about them now that we have seen their first usage.

Callbacks are used to operate on the data that was returned from a remoted method. As DWR and AJAX are asynchronous, typical return values in RPCs (Remote Procedure Calls), as in Java calls, do not work. DWR hides the details of calling the callback functions and handles everything internally from the moment we return a value from the remoted Java method to receiving the returned value to the callback function.

Two methods are recommended while using callback functions.

We have already seen the first method in the HorizontalMenu.getMenuItems(setMenuItems) function call. Remember that there are no parameters in the getMenuItems()Java method, but in the JavaScript call, we added the callback function name at the end of the parameter list. If the Java method has parameters, then the JavaScript call is similar to CountryDB.getCountries(selectedLetters,setCountryRows), where selectedLetters is the input parameter for the Java method and setCountryRows is the name of the callback function (we see the implementation later on).

The second method to use callbacks is a meta-data object in the remote JavaScript call. An example (a full implementation is shown later in this article) is shown here:

CountryDB.saveCountryNotes(ccode,newNotes, {
  callback:function(newNotes) 
  { 
    //function body here
  }
});

Here, the function is anonymous and its implementation is included in the JavaScript call to the remoted Java method. One advantage here is that it is easy to read the code, and the code is executed immediately after we get the return value from the Java method. The other advantage is that we can add extra options to the call.

Extra options include timeout and error handler as shown in the following example:

CountryDB.saveCountryNotes(ccode,newNotes, {
  callback:function(newNotes) 
  { 
    //function body here
},
timeout:10000,
errorHandler:function(errorMsg) { alert(errorMsg);}
});

It is also possible to add a callback function to those Java methods that do not return a value. Adding a callback to methods with no return values would be useful in getting a notification when a remote call has been completed.

Afterword

Our first sample is ready, and it is also the basis for the following samples. We also looked at how applications are tested in the Eclipse environment. Using DWR, we can look at JavaScript code on the browser and Java code on the server as one. It may take a while to get used to it, but it will change the way we develop web applications. Logically, there is no longer a client and a server but just a single run time platform that happens to be physically separate. But in practice, of course, applications using DWR, JavaScript on the client and Java in the server, are using the typical client-server interaction. This should be remembered when writing applications in the logically single run-time platform.