Development of new GWT widgets includes management of the source code tree, running and debugging the application with the GWT Hosted Mode Browser, and compiling the widgets and the IT Mill Toolkit Client-Side Engine to JavaScript with the GWT Compiler.
You can use any IDE for developing GWT components for IT Mill Toolkit. The examples given in this book are for the Eclipse IDE. It allows easy launching of the GWT Hosted Mode Browser, debugging, and running an external compiler for GWT widget sets.
Creation of an IT Mill Toolkit project that uses the default widget set was covered in Section 1.6, “Your First Project with IT Mill Toolkit”. Developing custom widgets creates a number of additional requirements for a project. Let us review the steps required for creating a project. Details for each step are given in the subsequent sections.
Write the web.xml
Deployment Descriptor for the web application.
Either:
The contents of a ready widget development project are described in Section 8.7.5, “Ready to Run”.
You will need to include the Google Web Toolkit in your project to develop
custom widgets. The installation directory of IT Mill Toolkit includes
full GWT installation in the gwt
subdirectory. The
package includes precompiled libraries and applications for the specific
platform of the installation. To use the libraries, you need to configure
them in the classpath of your project as described below.
You need to copy the gwt
directory to your
project. You can either copy it with system tools or, if you are using
Eclipse, import the directory. Importing the directory is done as follows.
gwt
directory under the IT Mill Toolkit installation directory. Click
in the file selection dialog.
gwt
entry in the list box for importing.
myproject/gwt
. (If you do not set this, all the
contents of the gwt
directory will be imported
directly below the root directory of the project which is undesirable.)
If you copied the directory with system tools, remember to select your project and press F5 to refresh the project.
GWT libraries must be included in the classpath of the project. Right-click on the project folder in the Project Explorer in Eclipse and select . Select → .
This section gives details on writing an application module that includes custom widgets.
While the source files can be placed in any directory in ordinary
projects, usually in the src
directory directly
under the project root, the widget build script described below in
Section 8.7.4, “Compiling GWT Widget Sets” as well as the GWT
Hosted Mode Browser assume that source files are located under the
WebContent/WEB-INF/src
folder. The source folder
has to be created and designated as a source folder for the project.
WebContent/WEB-INF
folder
and select
→ .
src
as the Folder name
and click .
src
folder and select
→ .
The folders designated as source folders are moved under the Java Resources folder in the Project Explorer of Eclipse. This is only a display feature; the source directory remains in its original location in the filesystem.
If you want to use the Color Picker application as an application skeleton, you need to import it under the source folder.
WebContent/WEB-INF/src/com/itmill/toolkit/demo/colorpicker/
and click button in the Import
from directory dialog.
myproject/WebContent/WEB-INF/src/com/itmill/toolkit/demo/colorpicker
.
colorpicker
entry in the list box.
This will import the directory as
com.itmill.toolkit.demo.colorpicker package. If you
want to use it as a skeleton for your own project, you should refactor
it to some other name. Notice that you will need to refactor the
package and application name manually in the
web.xml
and .gwt.xml
descriptor files.
When running an application in a regular web browser, you need to compile
the IT Mill Toolkit Client-Side Engine and your custom widget set to
JavaScript. This is done with the GWT Compiler. IT Mill Toolkit
installation package includes an Ant build script
build-widgetset.xml
in the
WebContent/doc/example-source/
directory. To compile
the Color Picker widget set example, just change to the directory and
enter:
$
ant -f build-widgetset.xml
We advice that you copy the build script to your project and use it as a template. Just set the paths in the "configure" target and the widget set class name in the "compile-widgetset" target to suit your project.
Alternatively, you can launch the build script from Eclipse, by right-clicking the script in Package Explorer and selecting Console window.
→ . Progress of the compilation is shown in the
After compilation, refresh the project by selecting it and
pressing F5. This makes Eclipse scan new
content and become aware of the output of the compilation in the
WebContent/ITMILL/widgetsets/
directory. If the
project is not refreshed, the JavaScript runtime is not included in the
web application and running the application will result in an error
message such as the following:
Requested resource [ITMILL/widgetsets/com.itmill.toolkit.demo.colorpicker.gwt.ColorPickerWidgetSet/ com.itmill.toolkit.demo.colorpicker.gwt.ColorPickerWidgetSet.nocache.js] not found from filesystem or through class loader. Add widgetset and/or theme JAR to your classpath or add files to WebContent/ITMILL folder.
Compilation with GWT is required also initially when using the Hosted Mode Browser described in Section 8.7.6, “Hosted Mode Browser”. The compilation with the GWT Compiler must be done at least once, as it provides files that are used also by the Hosted Mode Browser, even though the browser runs the GWT application in Java Virtual Machine instead of JavaScript.
Because GWT supports a slightly reduced version of Java, GWT compilation can produce errors that do not occur with the Java compiler integrated in the Eclipse IDE.
If you wish to use the build script to compile your own widget sets,
open it in an editor. The build script contains some instructions in
the beginning of the file. You can use the
compile-my-widgetset
target as a template for
your own widget sets.
<!-- NOTE: Modify this example to compile your own widgetset -->
<target name="compile-widgetset" depends="init">
<echo>Compiling com.itmill.toolkit.demo.colorpicker.gwt.ColorPickerWidgetSet.</echo>
<echo>Modify this example ant-script to compile your own widgetsets.</echo>
<java classname="com.google.gwt.dev.GWTCompiler"
failonerror="yes" fork="yes" maxmemory="256m">
<arg value="-out" />
<arg value="${client-side-destination}" />
<!-- Define your GWT widget set class here. -->
<arg value="com.itmill.toolkit.demo.colorpicker.gwt.ColorPickerWidgetSet" />
<jvmarg value="-Xss1024k"/>
<jvmarg value="-Djava.awt.headless=true"/>
<classpath>
<path refid="compile.classpath"/>
</classpath>
</java>
</target>
Replace the target name with your desired target name and the widget
set class name with your own class name. The
-Xss
parameter may be necessary if you
experience stack overflow errors with the default stack size. The
-Djava.awt.headless=true
is relevant in
Linux/UNIX platforms to avoid some X11 warnings.
You can now compile the widget set with the following command:
$
ant -f build-widgetset.xml
Figure 8.5, “Annotated Project Contents” shows the contents of a ready project.
Notice that the Package Explorer does not correspond with the file system contents. Eclipse displays the items marked with asterisk (*) in a logical location, instead of the physical location in the file system.
You can either run the application in web mode, as introduced in Section 1.6.7, or debug it with the GWT Hosted Mode Browser, as detailed in the next section.
The Hosted Mode Browser does not work in Linux since IT Mill Toolkit 5.3.0. The Out of Process Hosted Mode, described in Section 8.7.7, “Out of Process Hosted Mode (OOPHM)”, is an experimental alternative for the Hosted Mode Browser. It is platform-independent and works also on Linux.
The GWT Hosted Mode Browser allows easy debugging of GWT applications. The GWT application is actually not compiled into JavaScript, as is done in the deployment phase, but executed as a Java application. This makes it possible to debug the application with, for example, the Eclipse IDE.
Figure 8.6, “Hosted Mode Browser” shows the hosted mode browser in action. On the left, you have the GWT Development Shell window. It displays compilation information and possible errors that occur during compilation. You can open a new browser window by clicking .
The browser window has a Section 8.7.4, “Compiling GWT Widget Sets”.
button, which runs the GWT Compiler to produce the JavaScript runtime and opens a regular web browser to run the application in Web Mode. Notice that even though it is possible to recompile the program with the button, GWT Compiler must be run before launching the Hosted Mode Browser, as described inBecause GWT supports a slightly reduced version of Java, GWT compilation can produce errors that do not occur with the Java compiler integrated in the Eclipse IDE. Such errors will show up in the GWT Development Shell window.
While the Hosted Mode Browser is a fast and easy way to debug applications, it does not allow inspecting the HTML or DOM tree or network traffic like Firebug does in Mozilla Firefox.
This section gives details on configuring a launcher for the Hosted Mode Browser in the Eclipse IDE. We use the QuickStart installation of IT Mill Toolkit covered in Section 1.5, “QuickStart with Eclipse” as an example project. The project includes source code for the Color Picker demo application.
Select the
folder and click on the button to create a new launch configuration.com.google.gwt.dev.GWTShell
.
Switch to the Arguments tab and enter arguments for the Hosted Mode Browsed Java application.
In the Program arguments field, enter:
-noserver -whitelist "127.0.0.1 ^http[:][/][/]127[.]0[.]0[.]1[:]8080
" -out WebContent/ITMILL/widgetsets http://127.0.0.1:8080
/myproject
The browser application, GWTShell
,
takes as its arguments the following parameters:
Prevents an embedded web server from starting, thereby allowing to use an already running server.
Adds a regular expression to the list of allowed URL patterns for the web browser. Modify the port number from the 8080 given above as necessary.
Output directory for compiling widgets with GWT
Compiler. The directory must be
WebContent/ITMILL/widgetsets
.
You can compile the widgets either from the Hosted
Mode Browser or externally as explained later in this
chapter.
The URL to connect to. This must be the same as the whitelist entry given above. The port number must correspond to the port of the running web server. The Jetty web server included in IT Mill Toolkit will run in port 8888 by default. In contrast, Apache Tomcat installed under Eclipse will run in port 8080 by default.
In the VM arguments field enter, for
example, -Xms256M -Xmx512M
to give the
hosted mode browser more memory than the default amount. On
Mac, add also -XstartOnFirstThread
.
itmill-toolkit-examples
, which
contains the default classpath entries for the project. If the
classpath entries for the project are sufficient, this should be enough.
See the following section for details on debugging with the Hosted Mode Browser.
The purpose of the hosted mode browser is to allow debugging client-side GWT applications, or in our case, GWT widgets. Below is a checklist for important requirements for launching the Hosted Mode Browser:
web.xml
descriptor is configured.
Once everything is ready to start debugging, just open a source file,
for example, the
com.itmill.toolkit.demo.colorpicker.gwt.client.ui.GwtColorPicker
class. Find the onClick()
method. At the line
containing the setColor()
call, right-click
on the leftmost bar in the editor and select
from the popup menu. A small magnifying glass will appear in the bar
to indicate the breakpoint.
Select from menu Debug configuration window will open. Notice that it is not purposeful to run the Hosted Mode Browser in the "Run" mode, because its entire purpose is to allow debugging.
→ and theStarting demo applications under the Hosted Mode Browser can take considerable time! This is especially true for the Reservation and Color Picker applications, which require compilation of custom widget sets. During this time, the Hosted Mode Browser is unresponsive and does not update its window. Compiling widgets can take 5-30 seconds, depending on the hardware.
Please refer to Eclipse IDE documentation for further instructions on using the debugger.
The Out of Process Hosted Mode of GWT is an experimental new way for debugging GWT applications in a regular web browser. This allows using other browser debugging tools, such as Firebug, while debugging in hosted mode.
The Hosted Mode Browser does not work in Linux since IT Mill Toolkit 5.3.0, so the OOPHM is the only way to debug client-side code in Linux.
The OOPHM installation package of IT Mill Toolkit is a platform-independent package available separately from the platform specific packages. Use of OOPHM requires (see more detailed notes further below):
gwt/plugins
in
your browsergwt-dev-oophm.jar
instead of the platform-dependent
library.gwt-dev-oophm.jar
in class path.If you try debugging the demo applications in the IT Mill Toolkit installation package, just install the plugin (Step 1), launch the server in Web Mode, and then launch the Hosted Mode in debug mode (Step 3) with the included launch configuration.
The OOPHM plugin is available for Mozilla Firefox, Internet Explorer, and
WebKit based browsers. You should install the plugin from the browser by
opening the plugin file for your browser in the
gwt/plugins
directory. The Firefox plugin directory
contains two plugins; you should normally use the
oophm-xpcom.xpi
plugin.
The installation package contains the built-in default widget set compiled
with the OOPHM, but if you have your own widget sets (which is usually the
reason why you want to use client-side debugging in the first place), you
need to compile them. If you have compiled them previously with a regular
installation of IT Mill Toolkit, you need to recompile them with the GWT
Compiler provided in the gwt-dev-oophm.jar
library. Compiling GWT widget sets is covered in Section 8.7.4, “Compiling GWT Widget Sets”. The compilation of OOPHM widget sets
uses a large amount of stack memory, so if the JVM default is too small,
you should set it explicitly in compile-widgetset.xml
with the following parameter for the Java process (currently included in
the example build script):
<jvmarg value="-Xss1024k"/>
Launching the debugging is done just as described in Section 8.7.6, “Hosted Mode Browser” for the regular Hosted Mode Browser,
except that you must include the gwt-dev-oophm.jar
library in the class path instead of the platform specific
library. Launching the application with the debug configuration will
contact the plugin in your browser and automatically opens the configured
page.