Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 86 insertions, 0 deletions

diff --git a/documentation/gwt/gwt-overview.asciidoc b/documentation/gwt/gwt-overview.asciidoc
new file mode 100644
index 0000000000..16841ab791
--- /dev/null
+++ b/documentation/gwt/gwt-overview.asciidoc
@@ -0,0 +1,86 @@
+---
+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
+<<dummy/../../../framework/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
+<<dummy/../../../framework/gwt/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")))
+
+
+
+