Chapter 8. Developing Custom Components

This chapter gives details on how to create custom client-side components as Google Web Toolkit (GWT) widgets and how to integrate them with IT Mill Toolkit. The client-side implementations of all standard user interface components in IT Mill Toolkit use the same client-side interfaces and patterns.

Google Web Toolkit is intended for developing browser-based user interfaces using the Java language, which is compiled into JavaScript. Knowledge of such client-side technologies is usually not needed with IT Mill Toolkit, as its repertoire of user interface components should be sufficient for most applications. The easiest way to create custom components in IT Mill Toolkit is to make composite components with the CustomComponent class. See Section 4.17, “Custom Composite Components” for more details on the composite components. In some cases, however, you may need to either make modifications to existing components or create new or integrate existing GWT widgets with your application.

If you need more background on the architecture, Section 2.3, “Client-Side Engine” gives an introduction to the architecture of the IT Mill Toolkit Client-Side Engine. If you are new to Google Web Toolkit, Section 2.2.2, “Google Web Toolkit” gives an introduction to GWT and its role in the architecture of IT Mill Toolkit.

On Terminology

Google Web Toolkit uses the term widget for user interface components. In this book, we use the term widget to refer to client-side components made with Google Web Toolkit, while using the term component in a general sense and also in the special sense for server-side components.

8.1. Overview

Google Web Toolkit (GWT) is an integral part of IT Mill Toolkit since Release 5. All rendering of user interface components in a web browser is programmed with GWT. Using custom GWT widgets is easy in IT Mill Toolkit. This chapter gives an introduction to GWT widgets and details on how to integrate them with IT Mill Toolkit.

On the client side, in the web browser, you have the IT Mill Toolkit Client-Side Engine. It uses the GWT framework, and both are compiled into a JavaScript runtime component. The client-side engine is contained in the com.itmill.toolkit.terminal.gwt.client package and the client-side implementations of various user interface components are in the com.itmill.toolkit.terminal.gwt.client.ui package. You can find the source code for these packages in the IT Mill Toolkit installation package. You make custom components by inheriting GWT widget classes. To integrate them with IT Mill Toolkit, you have to implement the Paintable interface of the Client-Side Engine that provides the AJAX communications with the server-side application. To enable the custom widgets, you also need to implement a widget set. A widget set is a factory class that can instantiate your widgets. It needs to inherit the DefaultWidgetSet that acts as the factory for the standard widgets. You can also define stylesheets for custom widgets. A client-side module is defined in a GWT Module Descriptor.

To summarize, to implement a client-side widget that is integrated with IT Mill Toolkit, you need the following:

  • A GWT widget that implements the Paintable interface of the IT Mill Toolkit Client-Side Engine
  • A widget factory (a "widget set") that can create the custom widget or widgets
  • Default CSS style sheet for the widget set (optional)
  • A GWT Module Descriptor (.gwt.xml) that describes the entry point and style sheet

On the server side, you need to implement a server-side component that manages serialialization and deserialization of its attributes with the client-side widget. A server-side component usually inherits the AbstractComponent or AbstractField class and implements either the paintContent() or the more generic paint() method to serialize its data to the client. These methods "paint" the component by generating a UIDL element that is sent to the client. The UIDL element contains all the relevant information about the component, and you can easily add your own attributes to it.

Figure 8.1, “Color Picker Module” below illustrates the folder hierarchy of the Color Picker example used in this chapter. The example is available in the demo application of IT Mill Toolkit with URL /colorpicker/. You can find the full source code of the application in the source module for the demos in the installation package.

Figure 8.1. Color Picker Module

Color Picker Module

The ColorPickerApplication.java application provides an example of using the ColorPicker custom component. To allow accessing the application, it must be defined in the deployment descriptor web.xml. See Section 3.7.3, “Deployment Descriptor web.xml for details. The source code for the server-side component is located in the same folder.

A client-side widget set must be developed within a single source module tree. This is because GWT Compiler takes as its argument the root folder of the source code, in the Color Picker example the colorpicker.gwt.client module, and compiles all the contained Java source files into JavaScript. The path to the source files, the entry point class, and the style sheet are specified in the WidgetSet.gwt.xml descriptor for the GWT Compiler. The WidgetSet.java provides source code for the entry point, which is a factory class for creating the custom widget objects. The actual custom widget is split into two classes: GwtColorPicker, a pure GWT widget, and IColorPicker that provides the integration with IT Mill Toolkit. The default style sheet for the widget set is provided in gwt/public/colorpicker/styles.css.