8.7. GWT Widget Development

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.

8.7.1. Creating a Widget Project in Eclipse

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.

  1. Create a new project in the Eclipse IDE. (Section 1.6.1)
  2. Import IT Mill Toolkit library JAR into the project. (Section 1.6.2)
  3. Import GWT directory into the project. (Section 8.7.2 below)
  4. Write the source code in a Java module. (Section 8.7.3 below)
  5. Write the web.xml Deployment Descriptor for the web application.

    • Define the custom widget set to use instead of the default widget set. (Section 8.6.2 above)
  6. Compile the widget set to JavaScript runtime with GWT Compiler. (Section 8.7.4 below)
  7. Configure the project in Apache Tomcat (or some other web container) and start the server. (Section 1.6.6 below)
  8. Either:

    1. Open a web browser to use the web application.
    2. Debug the widgets with Hosted Mode Browser. (Section 8.7.6)

The contents of a ready widget development project are described in Section 8.7.5, “Ready to Run”.

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

  1. Right-click on the project folder in Project Explorer and select ImportImport....
  2. From the Import dialog, select GeneralFile System and click Next.
  3. 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.
  4. Select the gwt entry in the list box for importing.
  5. 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.)
  6. 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 PathLibraries.

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

  1. Right-click on the WebContent/WEB-INF folder and select NewFolder.
  2. In the New Folder dialog, enter src as the Folder name and click Finish.
  3. Right-click on the src folder and select Build PathUse 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

In Eclipse, you can insert a folder inside a source package in FileNewFolder.

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.

  1. Right-click on the source folder and select Import.
  2. In the Import dialog, select GeneralFile System and click Next.
  3. Browse to WebContent/WEB-INF/src/com/itmill/toolkit/demo/colorpicker/ and click Ok button in the Import from directory dialog.
  4. In the Into folder field, enter myproject/WebContent/WEB-INF/src/com/itmill/toolkit/demo/colorpicker.
  5. Check the colorpicker entry in the list box.
  6. 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.

8.7.4. Compiling GWT Widget Sets

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

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

8.7.5. Ready to Run

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

Figure 8.5. Annotated Project Contents

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

8.7.6. Hosted Mode Browser

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

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

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

    Figure 8.7. Creating New Launch Configuration

    Creating New Launch Configuration

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

    Naming Launch Configuration

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

    GWTShell Arguments

  5. 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.
  6. Click Apply to save the launch configuration.
  7. 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

Setting a Breakpoint

Select from menu RunDebug... 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

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.

8.7.7. Out of Process Hosted Mode (OOPHM)

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):

  1. Install OOPHM plugin from gwt/plugins in your browser
  2. Compile custom widget sets with the GWT Compiler provided in gwt-dev-oophm.jar instead of the platform-dependent library.
  3. Launch Hosted Mode debugging with the 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.