vaadin-framework/documentation/gwt/gwt-overview.asciidoc

---
title: Overview
order: 1
layout: page
---

[[gwt.overview]]
= Overview

Vaadin components consist of two parts: a server-side and a client-side
component. The latter are also called __widgets__ in Google Web Toolkit (GWT)
parlance. A Vaadin application uses the API of the server-side component, which
is rendered as a client-side widget in the browser. As on the server-side, the
client-side widgets form a hierarchy of layout widgets and regular widgets as
the leaves.

[[figure.gwt.overview.widget-integration]]
.Integration of Client-Side Widgets
image::img/widget-integration-hi.png[]

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.
((("connector")))

When rendering the user interface, a client-side connector and a widget are
created for each server-side component. The mapping from a component to a
connector is defined in the connector class with a [literal]#++@Connect++#
annotation, and the widget is created by the connector class.
((("@Connect")))

The state of a server-side component is synchronized automatically to the
client-side widget using a __shared state__ object. A shared state object
extends [classname]#AbstractComponentState# 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. ((("state
object")))
((("[classname]#AbstractComponentState#")))

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

In addition to state, both server- and 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.

[[gwt.overview.project]]
== Project Structure

Widget set compilation, as described in
<<../clientside/clientside-module#clientside.module,"Client-Side
Module Descriptor">>, requires using a special project structure, where the
client-side classes are located under a [filename]#client# package under the
package of the module descriptor. Any static resources, such as stylesheets and
images, should be located under a [filename]#public# folder (not Java package).
The source for the server-side component may be located anywhere, except not in
the client-side package.

The basic project structure is illustrated in <<figure.gwt.overview.project>>.

[[figure.gwt.overview.project]]
.Basic Widget Integration Project Structure
image::img/gwt-widget-files-hi.png[]

The Eclipse wizard, described in
<<gwt-eclipse#gwt.eclipse,"Starting It Simple With
Eclipse">>, creates a widget integration skeleton with the above structure.


[[gwt.overview.javascript]]
== 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.
((("JavaScript")))