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.
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:
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
appUri | The 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. |
pathInfo | The PATHINFO parameter
for the Servlet. |
themeUri | URI 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. |
versionInfo | This 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>
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.
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:
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 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.