11.8. GWT Widget Development

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

This will import the directory as com.vaadin.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.

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.

First, you need to make some basic configuration in the configure target:

<target name="configure">
    <!-- Path from this file to the project root -->
    <property name="base"
              value="../../../" />

    <!-- Location of GWT distribution -->
    <property name="gwt-location"
              value="${base}gwt" />

    <!-- Location of Vaadin JAR -->
    <property name="vaadin-jar-location"
            value="${base}WebContent/WEB-INF/lib/vaadin-6.3.3.jar"/>

    <!-- Location of project source code -->
    <property name="src-location"
              value="${base}WebContent/WEB-INF/src" />

    <!-- Target where to compile server-side classes -->
    <property name="server-side-destination"
              value="${base}WebContent/WEB-INF/classes"/>

    <!-- Target where to compile the widget set -->
    <property name="client-side-destination"
              value="${base}WebContent/VAADIN/widgetsets" />
</target>

You also need to define the widget set in the configure-widgetset target:

<!-- NOTE: Modify this example to compile your own widgetset -->
<target name="configure-widgetset">

  <!-- Name of the widget set -->
  <property name="widgetset"
    value="com.vaadin.demo.colorpicker.gwt.ColorPickerWidgetSet"/>

The widget set class name must match the package and the file name of the .gwt.xml descriptor, without the extension.

You can use the compile-widgetset target as it is, or as a template for your own configuration:

<!-- Build the widget set. -->
<target name="compile-widgetset"
        depends="compile-server-side, generate-widgetset">
    <echo>Compiling ${widgetset}...</echo>

    <java classname="com.google.gwt.dev.Compiler"
          failonerror="yes" fork="yes" maxmemory="256m">
        <arg value="-war" />
        <arg value="${client-side-destination}" />
        <arg value="${widgetset}" />
        <jvmarg value="-Xss1024k"/>
        <jvmarg value="-Djava.awt.headless=true"/>
        <classpath>
            <path refid="compile.classpath"/>
        </classpath>
    </java>
</target>

Notice that the server-side must be compiled before the client-side and the compiled server-side classes must be included in the class path for the GWT Compiler. The reason is that the annotations that define the component-to-widget mappings are read from the class files during the GWT compilation.

The -Djava.awt.headless=true parameter is necessary 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

If you use libraries containing other widget sets, you may want to automatically generate the .gwt.xml GWT Module Descriptor that defines the widget set that combines the Vaadin default widget set, widget sets included in any libraries, and any widget sets defined in your project.

If you use the build-widgetset.xml Ant build script as a template, you need to define the settings required for generating a widget set in the configure-widgetset target.

<target name="configure-widgetset">
  <property name="widgetset"
         value="com.vaadin.demo.generated.GeneratedWidgetSet"/>
  <property name="generate.widgetset" value="1"/>
  <property name="widgetset-path" value="com/vaadin/demo/widgetset"/>
</target>

Define the name of the widget set definition file, without the .gwt.xml suffix, in the widgetset property. The generate-widgetset target is executed only if the generate.widgetset property is defined. You also need to give a file path to the widget set directory, relative to the $src-location directory..

The generate-widgetset target is defined as follows:

<target name="generate-widgetset"
        depends="compile-server-side, configure-widgetset"
        if="generate.widgetset">
    
    <!-- Create the directory if it does not already exist. -->
    <mkdir dir="${src-location}/${widgetset-path}"/>
    
    <java classname="com.vaadin.terminal.gwt.widgetsetutils.WidgetSetBuilder"
          failonerror="yes" fork="yes" maxmemory="256m">
        <arg value="${widgetset}"/>
        <jvmarg value="-Xss1024k"/>
        <jvmarg value="-Djava.awt.headless=true"/>
        <classpath>
            <path refid="compile.classpath"/>
        </classpath>
    </java>
</target>

The widget set builder assumes that the root of the source directory is the first item in the class path, here defined with the src-location property. The location must point to the root of the entire source tree, not the path of the widget set under it. Also the location of compiled server-side classes must be included, here defined with the server-side-destination property. In the example script, the class path is defined in the init target as follows:

<path id="compile.classpath">
    <pathelement path="${src-location}" />
	<pathelement path="${server-side-destination}" />
	<pathelement path="${toolkit-jar-location}" />
	<pathelement path="${gwt-location}/gwt-user.jar" />
	<pathelement path="${gwt-location}/gwt-dev-${gwt-platform}.jar" />
    <pathelement path="${gwt-location}/validation-api-1.0.0.GA.jar" />
    <pathelement path="${gwt-location}/validation-api-1.0.0.GA-sources.jar" />
    <fileset dir="${base}WebContent/WEB-INF/lib/">
    	<include name="*.jar"/>
     </fileset>
</path>

This section describes how to create a launch configuration for the GWT Development Mode manually in the Eclipse IDE, without using the Vaadin Plugin for Eclipse.

See the following section for details on debugging with the GWT Development Mode.

The purpose of the GWT Development Mode is to allow debugging client-side GWT applications, or in our case, GWT widgets. Below is a checklist for important requirements for launching the GWT Development Mode:

Once everything is ready to start debugging, just open a source file, for example, the com.vaadin.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.

Select from menu Run → Debug... and the Debug configuration window will open. Notice that it is not purposeful to run the GWT Development Mode in the "Run" mode, because its entire purpose is to allow debugging.

Starting applications under the GWT Development Mode can take considerable time! Compiling widgets can take 10-60 seconds, depending on the hardware. During this time, the web browser is unresponsive, does not update its window, and appears "stuck".

Please refer to Eclipse IDE documentation for further instructions on using the debugger.