IT Mill - Embedding Applications in Web Pages

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, 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.

Embedding Inside a `<div>` Element

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 view the initial page easily by opening an application in a web browser and viewing its source code. The easiest way to embed an application is simply to copy and paste the embedding code from the initial page.

Embedding requires four elements inside the HTML document:

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 contains parameters for the engine. The two required parameters are the application URI, appUri, and path info, pathInfo. They are defined simply as follows:
```
    <script type="text/javascript">
        var itmill = {appUri:'Calc', pathInfo: '/'};
    </script>
```
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/widgets
ets/com.itmill.toolkit.terminal.gwt.DefaultWidgetSet/com.itmill.toolkit.te
rminal.gwt.DefaultWidgetSet.nocache.js'></script>
```
The engine URI consists of the context of the web application, itmill-toolkit-examples above, followed by 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.
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>
```
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.6. 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.

Embedding Inside an `<iframe>` Element

Embedding an IT Mill Toolkit application inside an <iframe> element is even more trivial than the method described above, as it does not require definition of any IT Mill Toolkit specific definitions. 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.7, “IT Mill Toolkit Applications Embedded Inside IFrames” below.

Figure 3.7. IT Mill Toolkit Applications Embedded Inside IFrames