Simple IT Mill Toolkit JSP Integration

Introduction

Integrating an IT Mill Toolkit application with an existing JSP application is a very common problem. The purpose of this article is to give you a step-by-step tutorial on how to embed an IT Mill Toolkit application into a JSP page and how to do some Ajax communication between JSP and the Toolkit application. The techniques used in this article are not limited to JSP pages but work also in any HTML page. This article is therefore also applicable to integrating PHP, Perl, Python or web applications written in any other language with IT Mill Toolkit. Of course you can also embed the Toolkit application into a static HTML page.

In this example we are using a simple IT Mill Toolkit application with a Table component containing 1000 random names in it. In the JSP page we have a single HTML input component and a submit button that will submit the contents of the input component to the Toolkit application and it is used as a filter to filter the rows of the Table component. As a response from the Toolkit application we get the number of rows matching the filtering text and we display it to the user.

Files

The example consists of four files:

If you want to quickly see what this is all about you can also download JspToolkitIntegration.war archive and try it out.

IT Mill Toolkit Application

Let's start by creating a simple application with IT Mill Toolkit. In this example we use a simple application with a Table component containing 1000 random names in it. I will not go much into the details here since the IT Mill Toolkit manual contains a good tutorial on how to get started with Toolkit applications and you can also see the source code from the attached TableApplication.java file.

To get some communication happening between the application and the external JSP page, we need to implement the com.itmill.toolkit.terminal.URIHandler interface. The URIHandler interface consists of a single method called handleURI we now need to implement. Later we'll be using a REST-like URI (for example refresh/mich) to send the filtering string to the Toolkit application. Now all we need to do is parse the filtering string in the handleURI method from the given relativeUri parameter and refresh the Table accordingly. We also want to send back the number of rows matching the filtering string, so we return a DownloadStream instance with a ByteArrayInputStream for bytes of the string we want to send as a response. 

// from URIHandler interface
@Override
public DownloadStream handleURI(URL context, String relativeUri) {
    if (relativeUri.startsWith("refresh/")) {
        refreshTable(relativeUri.substring("refresh/".length()));
        return new DownloadStream(new ByteArrayInputStream(Integer.toString(table.size())
            .getBytes()), "text/plain", null);
    }        

    return super.handleURI(context, relativeUri);
}

The Deployment Descriptor

Now we need to create a web.xml deployment descriptor for the application (or to add the application into an existing one). We map the TableApplication into an url-pattern /TableApplication/*. An important step is also to map /ITMILL/* url-pattern to the application or otherwise the default widgetset needed by the application would not be loaded. See also the IT Mill Toolkit manual for more details. 

<servlet-mapping>
        <servlet-name>TableApplication</servlet-name>
        <url-pattern>/TableApplication/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
        <servlet-name>TableApplication</servlet-name>
        <url-pattern>/ITMILL/*</url-pattern>
</servlet-mapping>

JSP page

Next we should create the JSP page to embed the IT Mill Toolkit application into. We must include the toolkitIntegration.jsp file which contains the basic settings needed to initialize the IT Mill Toolkit application and to tell in which div to embed it into. So now we add the following lines to the head section of the JSP page. 

<% 

// URI of the Toolkit application (defined in web.xml)
String appUri = "TableApplication";

// id of the div element to embed the Toolkit application into          
String appDiv = "itmApplication";

// context path of the application
String contextPath = "/JspToolkitIntegration";

%>                
<jsp:include page="toolkitIntegration.jsp">
    <jsp:param name="appUri" value="<%=appUri %>"/>
    <jsp:param name="appDiv" value="<%=appDiv %>"/>
    <jsp:param name="contextPath" value="<%=contextPath %>"/>                   
</jsp:include>

In addition to the included JSP template we need to define a JavaScript function to send the previously mentioned REST-like URI request to the server. For this purpose we write a function called submitData. This function constructs the request URI and passes it to itmSubmitData function defined in the included JSP template. The itmSubmitData function sends an Ajax request to the server to the given URI and calls the given callback function with responseText parameter when the response is ready. The given callback function invokes itmill.forceSync() function to force the client-side to synchronize its state with the server. 

/**
 * Submits the value of input#filterString element to the server
 * and puts the returned result count into p#resultsFound element.
 */ 
function submitData() {                                                                 
    var filterString = document.getElementById("filterString");
    if (filterString) {                         
        itmSubmitData("refresh/" + filterString.value, function(response) {
                document.getElementById("resultsFound").innerHTML = "Results found " + response;
                itmill.forceSync();
        });
    }                   
    return false;                                                                               
}

Now we can write the body section of the page. Notice how we use the same appDiv variable as the id of the div as we passed to the toolkitIntegration.jsp file. This is where the application will be embeded into. The form on the page is actually never submitted traditionally since we call the submitData function when user submits the form. 

<form action="post" onsubmit="return submitData()">             
    <label for="filterString">Filter by first name</label>
    <input type="text" name="filterString" id="filterString" />
    <input type="submit" value="Filter" />                      
</form>
<p id="resultsFound"></p>
                
<div id="<%=appDiv %>" style="height: 500px; margin: 10px"></div>

Final Words

There it is. A JSP page with an IT Mill Toolkit application embeded inside a single div element.

Attachments