Chapter 11. Developing New Components
Table of Contents
This chapter describes how you can create custom client-side components as Google Web Toolkit (GWT) widgets and how you integrate them with Vaadin. The client-side implementations of all standard user interface components in Vaadin 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 that is executed in the
browser. Knowledge of such client-side technologies is usually not needed with
Vaadin, as its built-in repertoire of user interface components should be
sufficient for most applications. The easiest way to create custom components in
Vaadin is to make composite components with the
CustomComponent class, as described in Section 5.23, “Component Composition with CustomComponent”. In some cases, however, you may need to
make modifications to existing components, integrate existing GWT widgets with
your application, or create entirely new ones.
Creation of new widgets involves a number of rather intricate tasks. The Vaadin Plugin for Eclipse makes many of the tasks much easier, so if you are using Eclipse and the plugin, you should find Section 11.2, “Doing It the Simple Way in Eclipse” helpful.
If you need more background on the architecture, Section 3.4, “Client-Side Engine” gives an introduction to the architecture of the Vaadin Client-Side Engine. If you are new to Google Web Toolkit, Section 3.2.2, “Google Web Toolkit” gives an introduction to GWT and its role in the architecture of Vaadin.
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.
The Client-Side Engine of Vaadin runs in the web browser as a JavaScript program and renders the user interface components according to state data received from the server. For each server-side component, there is a client-side widget, which renders the content of the particular component type. The client-side engine and all the built-in client-side widgets of Vaadin have been programmed in Java with GWT, and compiled into JavaScript with the GWT Compiler. Developing custom Vaadin components and integrating existing GWT widgets is easy, requiring only Java programming.
You can start with any existing GWT widget or design a new one. To integrate
it with Vaadin, you have to implement the Paintable
interface of the client-side engine that provides the AJAX communications with
the server-side application. You can find the interface in the
com.vaadin.terminal.gwt.client package. You can also choose
to extend an existing Vaadin client-side widget in the
com.vaadin.terminal.gwt.client.ui package. You can find the
source code for the built-in widgets in the Vaadin JAR.
To use custom widgets, you need to define a widget set
that inherits the DefaultWidgetSet, which contains the
standard widgets, or some other widget set. You can also define stylesheets
for custom widgets. A widget set is defined in a GWT Module Descriptor.
For the server-side API, you need a server-side component that can serialize
and deserialize its attributes to and from the client-side counterpart.
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 in the browser 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. Upon reception of UIDL messages, the client-side engine creates or updates
user interface widgets as needed.
To summarize, you need to do the following:
- Implement the
Paintableinterface of Vaadin in a GWT widget - Define a widget set that extends an existing widget set with the new widget
- Create a default CSS style sheet for the widget set (optional)
- Create a GWT Module Descriptor (
.gwt.xml) that defines the widget set and the optional style sheet - Create a server-side counterpart for the client-side widget
Figure 11.1, “Color Picker Package” illustrates the folder hierarchy of the Color Picker example used in this chapter.
The ColorPickerApplication.java application provides an
example of using the custom ColorPicker component. The
source code for the server-side implementation of the component is located in
the same folder.
The GWT Compiler takes the root folder of the client-side source code as its
argument and compiles all the Java source files into JavaScript. A client-side
widget set must therefore be contained within a single package, which in the
Color Picker example is the
com.vaadin.demo.colorpicker.gwt.client package. The
inherited widget set and an optional style sheet are specified in a
.gwt.xml descriptor for the GWT Compiler. In the example,
the client-side widget is split in two classes:
GwtColorPicker, a pure GWT widget, and
VColorPicker that provides the integration with
Vaadin. The default style sheet for the widget set is defined in the
descriptor and located in the
gwt/public/colorpicker/styles.css subfolder.