Book of Vaadin - vaadin.com

Chapter 10. Developing Custom Components
Prev		Next

Chapter 10. Developing Custom Components

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.20, “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 10.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.

10.1. Overview

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 Paintable interface 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 10.1, “Color Picker Package” illustrates the folder hierarchy of the Color Picker example used in this chapter. The example is available in the demo application of Vaadin with URL /colorpicker/. You can find the full source code of the application in the source folder of the demos in the installation package.