3.8. Embedding Applications in Web Pages

Many web applications and especially web sites are not all AJAX, but AJAX is used only for specific functionalities. In practice, many web applications are a mixture of dynamic web pages and AJAX applications embedded to such pages.

Embedding IT Mill Toolkit applications is easy. There are two basic ways to embed them. One is to have a <div> placeholder for the web application and load the IT Mill Toolkit Client-Side Engine with a simple JavaScript code. The second method is even easier, which is to simply use the <iframe> element. Both of these methods have advantages and disadvantages. The <div> method can only embed one application in a page, while the <iframe> method can embed as many as needed. One disadvantage of the <iframe> method is that the size of the <iframe> element is not flexible according to the content while the <div> method allows such flexibility. The following sections look closer into these two embedding methods.

3.8.1. Embedding Inside a <div> Element

The loading code for the Client-Side Engine has changed in IT Mill Toolkit version 5.1.2 and the explanation below is no longer compatible with 5.1.2 and later versions. Please view the source code of the initial page of your application in your browser or see the WebContent/multiapp.html for an example.

You can embed an IT Mill Toolkit application inside a web page with a method that is equivalent to loading the initial page content from the application servlet in a non-embedded application. Normally, the ApplicationServlet servlet generates an initial page that contains the correct parameters for the specific application. You can easily configure it to load multiple IT Mill Toolkit applications on the same page, assuming that they use the same widget set.

You can view the initial page for your application easily simply by opening the application in a web browser and viewing the HTML source code. You could just copy and paste the embedding code from the default initial page. It has, however, some extra functionality that is not normally needed: it generates some of the script content with document.write() calls, which is useful only when you are running the application as a portlet in a portal. The method outlined below is much simpler.

The WebContent/multiapp.html file included in the IT Mill Toolkit installation package provides an example of embedding (multiple) IT Mill Toolkit applications in a page. After launching the demo application, you can view the example at URL http://localhost:8888/multiapp.html. Notice that the example assumes the use of root context for the applications (/).

Embedding requires four elements inside the HTML document:

  1. In the <head> element, you need to define the application URI and parameters and load the IT Mill Toolkit Client-Side Engine. The itmill variable is an associative map that can contain various runtime data used by the Client-Side Engine of IT Mill Toolkit. The toolkitConfigurations item is itself an associate map that contains parameters for each of the applications embedded in the page. The map must contain the following items:

    Table 3.2. toolkitConfigurations parameters

    appUriThe application URI consists of the context and the application path. If the context is /mycontext and the application path is myapp, the appUri would be /mycontext/myapp. The multiapp.html example assumes the use of root context, which is used in the demo application.
    pathInfoThe PATHINFO parameter for the Servlet.
    themeUriURI of the application theme. The URI must include application context and the path to the theme directory. Themes are, by default, stored under the /ITMILL/themes/ path.
    versionInfoThis item is itself an associative map that contains two parameters: toolkitVersion contains the version number of the IT Mill Toolkit version used by the application. The applicationVersion parameter contains the version of the particular application.

    The following example defines two applications to run in the same window: the Calculator and Hello World examples. In the example, the application context is /tk5.

    <script type="text/javascript">
        var itmill = {
            toolkitConfigurations: {
                'calc': {
                    appUri:'/tk5/Calc',
                    pathInfo: '/',
                    themeUri: '/tk5/ITMILL/themes/example',
                    versionInfo : {
                        toolkitVersion:"5.9.9-INTERNAL-NONVERSIONED-DEBUG-BUILD",
                        applicationVersion:"NONVERSIONED"
                    }
                },
                'hello': {
                    appUri:'/tk5/HelloWorld',
                    pathInfo: '/',
                    themeUri: '/tk5/ITMILL/themes/example',
                    versionInfo : {
                        toolkitVersion:"5.9.9-INTERNAL-NONVERSIONED-DEBUG-BUILD",
                        applicationVersion:"NONVERSIONED"
                    }
                }
            }};
    </script>
  2. Loading the IT Mill Toolkit Client-Side Engine is done with the following kind of line in the <head> element:

    <script language='javascript'
        src='/itmill-toolkit-examples/ITMILL/widgetsets/com.itmill.toolk
    it.terminal.gwt.DefaultWidgetSet/com.itmill.toolkit.terminal.gwt.DefaultWi
    dgetSet.nocache.js'></script>

    The engine URI consists of the context of the web application, itmill-toolkit-examples above, followed by the path to the JavaScript (.js) file of the widget set, relative to the WebContent directory. The file contains the Client-Side Engine compiled for the particular widget set. The line above assumes the use of the default widget set of IT Mill Toolkit. If you have made custom widgets that are defined in a custom widget set, you need to use the path to the compiled widget set file. Widget sets must be compiled under the WebContent/ITMILL/widgetsets directory.

  3. In the <html> element, you need to do a routine inclusion of GWT history iframe element as follows:

    <iframe id="__gwt_historyFrame" style="width:0;height:0;border:0"></iframe>
  4. The location of the IT Mill Toolkit application is defined with a div placeholder element having id="itmill-ajax-window" as follows:

    <div id="itmill-ajax-window"/>

Below is a complete example of embedding an application. It works out-of-the-box with the Calculator demo application.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
  <head>
    <title>Embedding Example</title>

    <!-- Set parameters for the IT Mill Toolkit Client-Side Engine. -->
    <script type="text/javascript">
	    var itmill = {appUri:'Calc', pathInfo: '/'};
    </script>
    
    <!-- Load the IT Mill Toolkit Client-Side Engine. -->
    <script language='javascript' src='/itmill-toolkit-examples/ITMILL/widgetse
ts/com.itmill.toolkit.terminal.gwt.DefaultWidgetSet/com.itmill.toolkit.terminal
.gwt.DefaultWidgetSet.nocache.js'></script>

    <!-- We can stylize the web application. -->
    <style>
        #itmill-ajax-window {background: #c0c0ff;}
        .i-button {background: pink;}
    </style>
  </head>

  <body>
    <!-- This <iframe> element is required by GWT. -->
    <iframe id="__gwt_historyFrame" style="width:0;height:0;border:0"></iframe>
    
    <h1>This is a HTML page</h1>
	<p>Below is the IT Toolkit Application inside a table:</p>
	<table align="center" border="3" style="background: yellow;">
	  <tr><th>The Calculator</th></tr>
	  <tr>
	    <td>
          <!-- Placeholder <div> for the IT Mill Toolkit application -->
          <div id="itmill-ajax-window"/>
        </td>
      </tr>
    </table>	
  </body>
</html>

The page will look as follows:

Figure 3.12. Embedded Application

Embedded Application

You can style the web application with themes as described in Chapter 6, Themes. The Client-Side Engine loads the style sheets required by the application. In addition, you can do styling in the embedding page, as was done in the example above.

The Reservation Demo and Windowed Demos provide similar examples of embedding an application in a web page. The embedding web pages are WebContent/reservr.html and WebContent/windoweddemos.html, respectively.

The disadvantage of this embedding method is that there can only be one web application embedded in a page. One is usually enough, but if it is not, you need to use the <iframe> method below.

3.8.2. Embedding Inside an <iframe> Element

Embedding an IT Mill Toolkit application inside an <iframe> element is even easier than the method described above, as it does not require definition of any IT Mill Toolkit specific definitions. The use of <iframe> makes it possible to embed multiple web applications or two different views to the same application on the same page.

You can embed an application with an element such as the following:

<iframe src="/itmill-toolkit-examples/Calc"></iframe>

The problem with <iframe> elements is that their size of is not flexible depending on the content of the frame, but the content must be flexible to accommodate in the frame. You can set the size of an <iframe> element with height and width attributes.

Below is a complete example of using the <iframe> to embed two applications in a web page.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
  <head>
    <title>Embedding in IFrame</title>
  </head>

  <body style="background: #d0ffd0;">
    <h1>This is a HTML page</h1>
    <p>Below are two IT Mill Toolkit applications embedded inside a table:</p>

    <table align="center" border="3">
      <tr>
        <th>The Calculator</th>
        <th>The Color Picker</th>
      </tr>
      <tr valign="top">
        <td>
          <iframe src="/itmill-toolkit-examples/Calc" height="200"
                  width="150" frameborder="0"></iframe>
        </td>
        <td>
          <iframe src="/itmill-toolkit-examples/colorpicker" height="330" width="400"
                  frameborder="0"></iframe>
        </td>
      </tr>
    </table>
  </body>
</html>

The page will look as shown in Figure 3.13, “IT Mill Toolkit Applications Embedded Inside IFrames” below.

Figure 3.13. IT Mill Toolkit Applications Embedded Inside IFrames

IT Mill Toolkit Applications Embedded Inside IFrames