Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674

5 files changed, 185 insertions, 0 deletions

diff --git a/documentation/clientsidewidgets/chapter-clientsidewidgets.asciidoc b/documentation/clientsidewidgets/chapter-clientsidewidgets.asciidoc
new file mode 100644
index 0000000000..7adfe276e3
--- /dev/null
+++ b/documentation/clientsidewidgets/chapter-clientsidewidgets.asciidoc
@@ -0,0 +1,18 @@
+[[clientsidewidgets]]
+== Client-Side Widgets
+
+This chapter gives basic documentation on the use of the Vaadin client-side
+framework for the purposes of creating client-side applications and writing your
+own widgets.
+
+__We only give a brief introduction to the topic in this chapter. Please refer
+to the GWT documentation for a more complete treatment of the GWT widgets.__
+
+
+include::clientsidewidgets-overview.asciidoc[leveloffset=+2]
+
+include::clientsidewidgets-gwt.asciidoc[leveloffset=+2]
+
+include::clientsidewidgets-vaadin.asciidoc[leveloffset=+2]
+
+include::clientsidewidgets-grid.asciidoc[leveloffset=+2]
diff --git a/documentation/clientsidewidgets/clientsidewidgets-grid.asciidoc b/documentation/clientsidewidgets/clientsidewidgets-grid.asciidoc
new file mode 100644
index 0000000000..40e1e2ff19
--- /dev/null
+++ b/documentation/clientsidewidgets/clientsidewidgets-grid.asciidoc
@@ -0,0 +1,77 @@
+---
+title: Grid
+order: 4
+layout: page
+---
+
+[[clientsidewidgets.grid]]
+= Grid
+
+The [classname]#Grid# widget is the client-side counterpart for the server-side
+[classname]#Grid# component described in
+<<dummy/../../../framework/components/components-grid#components.grid,"Grid">>.
+
+The client-side API is almost identical to the server-side API, so its
+documentation is currently omitted here and we refer you to the API
+documentation. In the following, we go through some customization features of
+[classname]#Grid#.
+
+[[clientsidewidgets.grid.renderers]]
+== Renderers
+
+As described in
+<<dummy/../../../framework/components/components-grid#components.grid.renderer,"Column
+Renderers">>, renderers draw the visual representation of data values on the
+client-side. They implement [interfacename]#Renderer# interface and its
+[methodname]#render()# method. The method gets a reference to the element of the
+grid cell, as well as the data value to be rendered. An implementation needs to
+modify the element as needed.
+
+For example, [classname]#TextRenderer# is implemented simply as follows:
+
+
+----
+public class TextRenderer implements Renderer<String> {
+    @Override
+    public void render(RendererCellReference cell,
+                       String text) {
+        cell.getElement().setInnerText(text);
+    }
+}
+----
+
+The server-side renderer API should extend [classname]#AbstractRenderer# or
+[classname]#ClickableRenderer# with the data type accepted by the renderer. The
+data type also must be given for the superclass constructor.
+
+
+----
+public class TextRenderer extends AbstractRenderer<String> {
+    public TextRenderer() {
+        super(String.class);
+    }
+}
+----
+
+The client-side and server-side renderer need to be connected with a connector
+extending from [classname]#AbstractRendererConnector#.
+
+
+----
+@Connect(com.vaadin.ui.renderer.TextRenderer.class)
+public class TextRendererConnector
+       extends AbstractRendererConnector<String> {
+    @Override
+    public TextRenderer getRenderer() {
+        return (TextRenderer) super.getRenderer();
+    }
+}
+----
+
+Renderers can have parameters, for which normal client-side communication of
+extension parameters can be used. Please see the implementations of different
+renderers for examples.
+
+
+
+
diff --git a/documentation/clientsidewidgets/clientsidewidgets-gwt.asciidoc b/documentation/clientsidewidgets/clientsidewidgets-gwt.asciidoc
new file mode 100644
index 0000000000..c4605e7ef0
--- /dev/null
+++ b/documentation/clientsidewidgets/clientsidewidgets-gwt.asciidoc
@@ -0,0 +1,20 @@
+---
+title: GWT Widgets
+order: 2
+layout: page
+---
+
+[[clientsidewidgets.gwt]]
+= GWT Widgets
+
+GWT widgets are user interface elements that are rendered as HTML. Rendering is
+done either by manipulating the HTML Document Object Model (DOM) through the
+lower-level DOM API, or simply by injecting the HTML with
+[methodname]#setInnerHTML()#. The layout of the user interface is managed using
+special panel widgets.
+
+For information about the basic GWT widgets, please refer to the GWT Developer's
+Guide at https://developers.google.com/web-toolkit/doc/latest/DevGuideUi.
+
+
+
diff --git a/documentation/clientsidewidgets/clientsidewidgets-overview.asciidoc b/documentation/clientsidewidgets/clientsidewidgets-overview.asciidoc
new file mode 100644
index 0000000000..75206944ed
--- /dev/null
+++ b/documentation/clientsidewidgets/clientsidewidgets-overview.asciidoc
@@ -0,0 +1,33 @@
+---
+title: Overview
+order: 1
+layout: page
+---
+
+[[clientsidewidgets.overview]]
+= Overview
+
+The Vaadin client-side API is based on the Google Web Toolkit. It involves
+__widgets__ for representing the user interface as Java objects, which are
+rendered as a HTML DOM in the browser. Events caused by user interaction with
+the page are delegated to event handlers, where you can implement your UI logic.
+
+In general, the client-side widgets come in two categories - basic GWT widgets
+and Vaadin-specific widgets. The library includes __connectors__ for integrating
+the Vaadin-specific widgets with the server-side components, thereby enabling
+the server-side development model of Vaadin. The integration is described in
+<<dummy/../../../framework/gwt/gwt-overview.asciidoc#gwt.overview,"Integrating
+with the Server-Side">>.
+
+The layout of the client-side UI is managed with __panel__ widgets, which
+correspond in their function with layout components in the Vaadin server-side
+API.
+
+In addition to the rendering API, the client-side API includes facilities for
+making HTTP requests, logging, accessibility, internationalization, and testing.
+
+For information about the basic GWT framework, please refer to
+https://developers.google.com/web-toolkit/overview.
+
+
+
diff --git a/documentation/clientsidewidgets/clientsidewidgets-vaadin.asciidoc b/documentation/clientsidewidgets/clientsidewidgets-vaadin.asciidoc
new file mode 100644
index 0000000000..21dc4d9e27
--- /dev/null
+++ b/documentation/clientsidewidgets/clientsidewidgets-vaadin.asciidoc
@@ -0,0 +1,37 @@
+---
+title: Vaadin Widgets
+order: 3
+layout: page
+---
+
+[[clientsidewidgets.vaadin]]
+= Vaadin Widgets
+
+Vaadin comes with a number of Vaadin-specific widgets in addition to the GWT
+widgets, some of which you can use in pure client-side applications. The Vaadin
+widgets have somewhat different feature set from the GWT widgets and are
+foremost intended for integration with the server-side components, but some may
+prove useful for client-side applications as well.
+
+
+----
+public class MyEntryPoint implements EntryPoint {
+    @Override
+    public void onModuleLoad() {
+        // Add a Vaadin button
+        VButton button = new VButton();
+        button.setText("Click me!");
+        button.addClickHandler(new ClickHandler() {
+            @Override
+            public void onClick(ClickEvent event) {
+                mywidget.setText("Clicked!");
+            }
+        });
+        
+        RootPanel.get().add(button);
+    }
+}
+----
+
+
+