Integrating with the Server-Side

The communication between a client-side widget and a server-side component is managed with a connector that handles syncronizing the widget state and events to and from the server-side.

When painting the user interface, a client-side widget is created for each server-side component. This mapping is defined in the connector class with a @Connect annotation.

The state of a server-side component is synchronized automatically to the client-side widget using a shared state object. A shared state object implements the ComponentState interface and it is used both in the server-side and the client-side component. On the client-side, a connector always has access to its state instance, as well to the state of its parent component state and the states of its children.

The state sharing assumes that state is defined with standard Java types, such as primitive and boxed primitive types, String, arrays, and certain collections (List, Set, and Map) of the supported types. Also the Vaadin Connector and some special internal types can be shared.

In addition to state, both serverand client-side can make remote procedure calls (RPC) to the other side. RPC is used foremost for event notifications. For example, when a client-side connector of a button receives a click, it sends the event to the server-side using RPC.

Integrating JavaScript Components

In addition to the GWT widget integration, Vaadin offers a simplified way to integrate pure JavaScript components. The JavaScript connector code is published from the server-side. As the JavaScript integration does not involve GWT programming, no widget set compilation is needed.

16.2. Starting It Simple With Eclipse

Let us first take the easy way and create a simple component with Eclipse.While you can develop new widgets with any IDE or even without, you may find Eclipse and the Vaadin Plugin for it useful, as it automates all the basic routines of widget development, most importantly the creation of new widgets.

16.2.1. Creating a Widget

1.	Right-click the project in the Project Explorer and select New Other....
2.	In the wizard selection, select Vaadin Vaadin Widget and click Next.

Integrating JavaScript Components

361

Integrating with the Server-Side

3. In the New Component Wizard, make the following settings.

Source folder

The root folder of the entire source tree. The default value is the default source tree of your project, and you should normally leave it unchanged unless you have a different project structure.

Package

The parent package under which the new server-side component should be created. If the project does not already have a widget set, one is created under this package in the widgetset subpackage.The subpackage will contain the .gwt.xml descriptor that defines the widget set and the new widget stub under the widgetset.client subpackage.

362	Creating a Widget

Integrating with the Server-Side

Name

The class name of the new server-side component. The name of the client-side widget stub will be the same but with "-Widget" suffix, for example, MyComponentWidget. You can rename the classes afterwards.

Superclass

The superclass of the server-side component. It is AbstractComponent by default, but com.vaadin.ui.AbstractField or com.vaadin.ui.AbstractSelect are other commonly used superclasses. If you are extending an existing component, you should select it as the superclass. You can easily change the superclass later.

Template

Select which template to use. The default is Full fledged, which creates the serverside component, the client-side widget, the connector, a shared state object, and an RPC object. The Connector only leaves the shared state and RPC objects out.

Finally, click Finish to create the new component.

The wizard will:

•Create a server-side component stub in the base package

•If the project does not already have a widget set, the wizard creates a GWT module descriptor file (.gwt.xml) in the base package and modifies the web.xml deployment descriptor to specify the widget set class name parameter for the application

•Create a client-side widget stub (along with the connector and shared state and RPC stubs) in the client.componentname package under the base package

The structure of the server-side component and the client-side widget, and the serialization of component state between them, is explained in the subsequent sections of this chapter.

To compile the widget set, click the Compile widget set button in the Eclipse toolbar. See Section 16.2.2, “Compiling the Widget Set” for details. After the compilation finishes, you should be able to run your application as before, but using the new widget set. The compilation result is written under the WebContent/VAADIN/widgetsets folder. When you need to recompile the widget set in Eclipse, see Section 16.2.2, “Compiling the Widget Set”. For detailed information on compiling widget sets, see Section 13.4, “Compiling a Client-Side Module”.

The following setting is inserted in the web.xml deployment descriptor to enable the widget set:

<init-param>

<description>Application widgetset</description> <param-name>widgetset</param-name>

<param-value>com.example.myproject.widgetset.MyprojectApplicationWidgetset</param-value> </init-param>

You can refactor the package structure if you find need for it, but GWT compiler requires that the client-side code must always be stored under a package named "client" or a package defined with a source element in the widget set descriptor.

16.2.2. Compiling the Widget Set

After you edit a widget, you need to compile the widget set. The Vaadin Plugin for Eclipse automatically suggests to compile the widget set in various situations, such as when you save a client-

Compiling the Widget Set

363