IT Mill - IT Mill Toolkit Reference Manual GWT Widget Development

Creating a Widget Project in Eclipse

Creation of an IT Mill Toolkit project that uses the default widget set was covered in the section called “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.

Create a new project in the Eclise IDE. (Section )
Import IT Mill Toolkit library JAR into the project. (Section )
Import GWT directory into the project. (Section below)
Write the source code in a Java module. (Section below)
Write the web.xml Deployment Descriptor for the web application.
- Define the custom widget set to use instead of the default widget set. (Section above)
Compile the widget set to JavaScript runtime with GWT Compiler. (Section below)
Configure the project in Apache Tomcat (or some other web container) and start the server. (Section below)
Either:
1. Open a web browser to use the web application.
2. Debug the widgets with Hosted Mode Browser. (Section )

The contents of a ready widget development project are described in the section called “Ready to Run”.

Importing GWT Installation Package

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.

Right-click on the project folder in Project Explorer and select Import → Import....
From the Import dialog, select General → File System and click Next.
Click Browse button of the "From directory" field and browse to the gwt directory under the IT Mill Toolkit installation directory. Click Ok in the file selection dialog.
Select the gwt entry in the list box for importing.
In the "Into folder" field, enter 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.)
Click Finish.

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 Properties. Select Java Build Path → Libraries.

Creating a GWT Module

This section gives details on writing an application module that includes custom widgets.

Creating the Source Folder

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 the section called “Compiling a Custom Widget Set” 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.

Right-click on the WebContent/WEB-INF folder and select New → Folder.
In the New Folder dialog, enter src as the Folder name and click Finish.
Right-click on the src folder and select Build Path → Use as Source Folder.

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.

Creating Source Files

-- This section is unfinished --

In Eclipse, you can insert a folder inside a source package in File → New → Folder.

Importing the ColorPicker Demo

If you want to use the Color Picker application as an application skeleton, you need to import it under the source folder.

Right-click on the source folder and select Import.
In the Import dialog, select General → File System and click Next.
Browse to WebContent/WEB-INF/src/com/itmill/toolkit/demo/colorpicker/ and click Ok button in the Import from directory dialog.
In the Into folder field, enter myproject/WebContent/WEB-INF/src/com/itmill/toolkit/demo/colorpicker.
Check the colorpicker entry in the list box.
Click Finish.

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.

Compiling GWT Widget Sets

When running an application in a regular browser, you need to compile the IT Mill Toolkit Client-Side Engine and any custom widget sets to JavaScript. This is done with the GWT Compiler. IT Mill Toolkit installation package includes an Ant build script build-widgetsets.xml in the root directory. To compile all widget sets, just change to the directory and enter:

$ ant -f build-widgetsets.xml

This will compile all widget sets configured in the build script. Building all widget sets can take several minutes. If you wish to build only a specific widget set, give its target name as a parameter for Ant as follows:

$ ant -f build-widgetsets.xml compile-colorpicker_demo-widgetset

Alternatively, you can launch the build script from Eclipse, by right-clicking the script in Package Explorer and selecting Run As → Ant Build. Progress of the compilation is shown in the Console window.

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 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 the section called “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.

Warning

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.

Compiling a Custom Widget Set

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: use this template to compile your own widgetset -->
<target name="compile-my-widgetset" depends="init">
    <fail message="Please open build-widgetset.xml and update your widgetset's
                      package name to enable this target" />
    <!-- remove upper fail message -->
    <java classname="com.google.gwt.dev.GWTCompiler" failonerror="yes"
             fork="yes" maxmemory="128m">
        <arg value="-out" />
        <arg value="${client-side-destination}" />
        <!-- NOTE: Update line below and tell package name to your own widgetset -->
        <arg value="com.myexample.gwt.MyWidgetSet" />
        <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. You can now compile the widget set with the following command:

$ ant -f build-widgetsets.xml com.myexample.gwt.MyWidgetSet

If you wish to compile the target when running the build script with the default target, you have to make the default target depend on your target. Edit the default target at the end of the file:

<target name="compile-all-widgetsets"
        depends="compile-default-widgetset,
                 compile-colorpicker_demo-widgetset,
                 compile-reservation_demo-widgetset,
                 compile-my-widgetset" />

Ready to Run

Figure 8.5, “Annotated Project Contents” shows the contents of a ready project.

Figure 8.5. Annotated Project Contents

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 , or debug it with the GWT Hosted Mode Browser, as detailed in the next section.

Hosted Mode Browser

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

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 Hosted Browser.

The browser window has a Compile/Browse 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 in the section called “Compiling GWT Widget Sets”.

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

Configuring Hosted Mode Launching in Eclipse

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 the section called “QuickStart with Eclipse” as an example project. The project includes source code for the Color Picker demo application.

Select from menu Run → Debug... and the 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.
Select the Java Application folder and click on the New button to create a new launch configuration.

Figure 8.7. Creating New Launch Configuration
Click on the created launch configuration to open it on the right-side panel. In the Main tab, give the launch configuration a name. Define the Main class as com.google.gwt.dev.GWTShell.
Figure 8.8. Naming Launch Configuration
Switch to the Arguments tab and enter arguments for the Hosted Mode Browsed Java application.
1. 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:
  
  -noserver
  
  Prevents an embedded web server from starting, thereby allowing to use an already running server.
  
  -whitelist
  
  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.
  
  -out
  
  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.
  
  URL
  
  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.
2. 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.
Figure 8.9. GWTShell Arguments
In the Classpath tab, you will by default have 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.
Click Apply to save the launch configuration.
Click Debug to launch the Hosted Mode Browser using the launch configuration.

See the following section for details on debugging with the Hosted Mode Browser.

Debugging with 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:

GWT is installed under the project folder.
GWT libraries are included in the project classpath.
Widget sets have been compiled with GWT Compiler.
web.xml descriptor is configured.
Web server is running and listening to the correct port.
Hosted Mode Browser launcher 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 Toggle Breakpoint from the popup menu. A small magnifying glass will appear in the bar to indicate the breakpoint.

Figure 8.10. Setting a Breakpoint

Select from menu Run → Debug... and the 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.

Figure 8.11. Debugging with Hosted Mode Browser

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

GWT Widget Development