Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674

7 files changed, 465 insertions, 0 deletions

diff --git a/documentation/clientside/chapter-clientside.asciidoc b/documentation/clientside/chapter-clientside.asciidoc
new file mode 100644
index 0000000000..6effe8475a
--- /dev/null
+++ b/documentation/clientside/chapter-clientside.asciidoc
@@ -0,0 +1,18 @@
+[[clientside]]
+== Client-Side Vaadin Development
+
+This chapter gives an overview of the Vaadin client-side framework, its
+architecture, and development tools.
+
+
+include::clientside-overview.asciidoc[leveloffset=+2]
+
+include::clientside-installing.asciidoc[leveloffset=+2]
+
+include::clientside-module.asciidoc[leveloffset=+2]
+
+include::clientside-compiling.asciidoc[leveloffset=+2]
+
+include::clientside-widget.asciidoc[leveloffset=+2]
+
+include::clientside-debugging.asciidoc[leveloffset=+2]
diff --git a/documentation/clientside/clientside-compiling.asciidoc b/documentation/clientside/clientside-compiling.asciidoc
new file mode 100644
index 0000000000..18afb2c6ac
--- /dev/null
+++ b/documentation/clientside/clientside-compiling.asciidoc
@@ -0,0 +1,81 @@
+---
+title: Compiling a Client-Side Module
+order: 4
+layout: page
+---
+
+[[clientside.compiling]]
+= Compiling a Client-Side Module
+
+A client-side module, either a widget set or a pure client-side module, needs to
+be compiled to JavaScript using the Vaadin Client Compiler. During development,
+the Development Mode makes the compilation automatically when you reload the
+page, provided that the module has been initially compiled once with the
+compiler.
+
+As most Vaadin add-ons include widgets, widget set compilation is usually needed
+when using add-ons. In that case, the widget sets from different add-ons are
+compiled into a __project widget set__, as described in
+<<dummy/../../../framework/addons/addons-overview.asciidoc#addons.overview,"Using
+Vaadin
+Add-ons">>.////
+TODO Provide a link to a proper add-on compilation section when one is
+available.
+////
+
+[[clientside.compiling.overview]]
+== Vaadin Compiler Overview
+
+The Vaadin Client Compiler compiles Java to JavaScript. It is provided as the
+[filename]#vaadin-client-compiler# JAR, which you can execute with the
+[literal]#++-jar++# parameter for the Java runtime. It requires the
+[filename]#vaadin-client# JAR, which contains the Vaadin client-side framework.
+
+The compiler compiles a __client module__, which can be either a pure
+client-side module or a Vaadin widget set, that is, the Vaadin Client-Side
+Engine that includes the widgets used in the application. The client module is
+defined with a module descriptor, which was described in
+<<dummy/../../../framework/clientside/clientside-module#clientside.module,"Client-Side
+Module Descriptor">>.
+
+The compiler writes the compilation result to a target folder that will include
+the compiled JavaScript with any static resources included in the module.
+
+
+[[clientside.compiling.eclipse]]
+== Compiling in Eclipse
+
+When the Vaadin Plugin is installed in Eclipse, you can simply click the
+[guibutton]#Compile Vaadin widgets# button in the toolbar. It will compile the
+widget set it finds from the project. If the project has multiple widget sets,
+such as one for custom widgets and another one for the project, you need to
+select the module descriptor of the widget set to compile before clicking the
+button.
+
+The compilation with Vaadin Plugin for Eclipse currently requires that the
+module descriptor has suffix [filename]#Widgetset.gwt.xml#, although you can use
+it to compile also other client-side modules than widget sets. The result is
+written under [filename]#WebContent/VAADIN/widgetsets# folder.
+
+
+[[clientside.compiling.ant]]
+== Compiling with Ant
+
+You can find a script template for compiling widget sets with Ant and Ivy at the
+link:http://vaadin.com/download/[Vaadin download page]. You can copy the build
+script to your project and, once configured, run it with Ant.
+
+
+[[clientside.compiling.maven]]
+== Compiling with Maven
+
+You can compile the widget set with the [literal]#++vaadin:compile++# goal as
+follows:
+
+[subs="normal"]
+----
+[prompt]#$# [command]#mvn# [parameter]#vaadin:compile#
+----
+
+
+
diff --git a/documentation/clientside/clientside-debugging.asciidoc b/documentation/clientside/clientside-debugging.asciidoc
new file mode 100644
index 0000000000..efbe24a8ec
--- /dev/null
+++ b/documentation/clientside/clientside-debugging.asciidoc
@@ -0,0 +1,125 @@
+---
+title: Debugging Client-Side Code
+order: 6
+layout: page
+---
+
+[[clientside.debugging]]
+= Debugging Client-Side Code
+
+Vaadin currently includes SuperDevMode for debugging client-side code right in
+the browser.
+
+The predecessor of SuperDevMode, the GWT Development Mode, no longer works in
+recent versions of Firefox and Chrome, because of certain API changes in the
+browsers. There exists workarounds on some platforms, but for the sake of
+simplicity, we recommend using the SuperDevMode.
+
+ifdef::web[]
+[[clientside.debugging.devmode]]
+== Launching Development Mode
+
+The Development Mode launches the application in the browser, compiles the
+client-side module (or widget set) when the page is loaded, and allows debugging
+the client-side code in Eclipse. You can launch the Development Mode by running
+the [classname]#com.google.gwt.dev.DevMode# class. It requires some parameters,
+as described later.
+
+The Vaadin Plugin for Eclipse can create a launch configuration for the
+Development Mode. In the Vaadin section of project properties, click the
+[guibutton]#Create development mode launch# button. This creates a new launch
+configuration in the project. You can edit the launch configuration in "Run >
+Run Configurations".
+
+
+----
+-noserver -war WebContent/VAADIN/widgetsets com.example.myproject.widgetset.MyWidgetSet -startupUrl http://localhost:8080/myproject -bindAddress 127.0.0.1
+----
+
+The parameters are as follows:
+
+[parameter]#-noserver#:: Normally, the Development Mode launches its own Jetty server for hosting the content. If you are developing the application under an IDE that deploys it to a server, such as Eclipse, you can disable the Development Mode server with this option.
+[parameter]#-war#:: Specifies path to the location where the JavaScript is to be compiled. When developing a pure client-side module, this could be the [filename]#WebContent# (in Eclipse) or some other folder under it. When compiling widget sets, it must be [filename]#WebContent/VAADIN/widgetsets#.
+[parameter]#-startupUrl#:: Specifies the address of the loader page for the application. For server-side Vaadin applications, this should be the path to the Vaadin application servlet, as defined in the deployment. For pure client-side widgets, it should be the page where the application is included.
+[parameter]#-bindAddress#:: This is the IP address of the host in which the Development Mode runs. For debugging on the development workstation, it can be just [literal]#++127.0.0.1++#. Setting it as the proper IP address of the host enables remote debugging.
+
+
+endif::web[]
+
+[[clientside.debugging.superdevmode]]
+== Launching SuperDevMode
+
+The SuperDevMode is much like the old Development Mode, except that it does not
+require a browser plugin. Compilation from Java to JavaScript is done
+incrementally, reducing the compilation time significantly. It also allows
+debugging JavaScript and even Java right in the browser (currently only
+supported in Chrome).
+
+You can enable SuperDevMode as follows:
+
+. You need to set a redirect property in the [filename]#.gwt.xml# module
+descriptor as follows:
+
+
++
+----
+<set-configuration-property name="devModeRedirectEnabled" value="true" />
+----
++
+In addition, you need the [literal]#++xsiframe++# linker. It is included in the
+[classname]#com.vaadin.DefaultWidgetSet# as well as in the
+[classname]#com.vaadin.Vaadin# module. Otherwise, you need to include it with:
+
+
++
+----
+<add-linker name="xsiframe" />
+----
+. Compile the module (that is, the widget set), for example by clicking the button in Eclipse.
+. If you are using Eclipse, create a launch configuration for the SuperDevMode by
+clicking the [guibutton]#Create SuperDevMode launch# in the [guilabel]#Vaadin#
+section of the project properties.
+
+.. The main class to execute should be [classname]#com.google.gwt.dev.codeserver.CodeServer#.
+.. The application takes the fully-qualified class name of the module (or widget set) as parameter, for example, [classname]#com.example.myproject.widgetset.MyprojectWidgetset#.
+.. Add project sources to the class path of the launch if they are not in the project class path.
+
+
+The above configuration only needs to be done once to enable the SuperDevMode.
+After that, you can launch the mode as follows:
+
+. Run the SuperDevMode Code Server with the launch configuration that you created above. This perfoms the initial compilation of your module or widget set.
+. Launch the servlet container for your application, for example, Tomcat.
+. Open your browser with the application URL and add [literal]#++?superdevmode++# parameter to the URL (see the notice below if you are not extending [classname]#DefaultWidgetSet#). This recompiles the code, after which the page is reloaded with the SuperDevMode. You can also use the [literal]#++?debug++# parameter and then click the [guibutton]#SDev# button in the debug console.
+
+If you make changes to the client-side code and refresh the page in the browser,
+the client-side is recompiled and you see the results immediately.
+
+The Step 3 above assumes that you extend [classname]#DefaultWidgetSet# in your
+module. If that is not the case, you need to add the following at the start of
+the [methodname]#onModuleLoad()# method of the module:
+
+
+----
+if (SuperDevMode.enableBasedOnParameter()) { return; }
+----
+
+Alternatively, you can use the bookmarklets provided by the code server. Go to
+http://localhost:9876/ and drag the bookmarklets " [guilabel]#Dev Mode On#" and
+" [guilabel]#Dev Mode Off#" to the bookmarks bar
+
+
+[[clientside.debugging.chrome]]
+== Debugging Java Code in Chrome
+
+Chrome supports source maps, which allow debugging Java source code from which
+the JavaScript was compiled.
+
+Open the Chrome Inspector by right-clicking and selecting [guilabel]#Inspect
+Element#. Click the settings icon in the lower corner of the window and check
+the "Scripts > Enable source maps" option. Refresh the page with the Inspector
+open, and you will see Java code instead of JavaScript in the scripts tab.
+
+
+
+
diff --git a/documentation/clientside/clientside-installing.asciidoc b/documentation/clientside/clientside-installing.asciidoc
new file mode 100644
index 0000000000..0ad907f052
--- /dev/null
+++ b/documentation/clientside/clientside-installing.asciidoc
@@ -0,0 +1,18 @@
+---
+title: Installing the Client-Side Development Environment
+order: 2
+layout: page
+---
+
+[[clientside.installing]]
+= Installing the Client-Side Development Environment
+
+The installation of the client-side development libraries is described in
+<<dummy/../../../framework/getting-started/getting-started-overview.asciidoc#getting-started.overview,"Getting
+Started with Vaadin">>. You especially need the [filename]#vaadin-client#
+library, which contains the client-side Java API, and
+[filename]#vaadin-client-compiler#, which contains the Vaadin Client Compiler
+for compiling Java to JavaScript.
+
+
+
diff --git a/documentation/clientside/clientside-module.asciidoc b/documentation/clientside/clientside-module.asciidoc
new file mode 100644
index 0000000000..4656264ce1
--- /dev/null
+++ b/documentation/clientside/clientside-module.asciidoc
@@ -0,0 +1,98 @@
+---
+title: Client-Side Module Descriptor
+order: 3
+layout: page
+---
+
+[[clientside.module]]
+= Client-Side Module Descriptor
+
+Client-side Vaadin modules, such as the Vaadin Client-Side Engine (widget set)
+or pure client-side applications, that are to be compiled to JavaScript, are
+defined in a __module descriptor__ ( [filename]#.gwt.xml#) file.
+
+When defining a widget set to build the Vaadin client-side engine, the only
+necessary task is to inherit a base widget set. If you are developing a regular
+widget set, you should normally inherit the [classname]#DefaultWidgetSet#.
+
+
+----
+
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE module PUBLIC
+  "-//Google Inc.//DTD Google Web Toolkit 1.7.0//EN"
+  "http://google-web-toolkit.googlecode.com/svn/tags/1.7.0/distro-source/core/src/gwt-module.dtd">
+
+<module>
+    <!-- Inherit the default widget set -->
+    <inherits name="com.vaadin.DefaultWidgetSet" />
+</module>
+----
+
+If you are developing a pure client-side application, you should instead inherit
+[classname]#com.vaadin.Vaadin#, as described in
+<<dummy/../../../framework/clientsideapp/clientsideapp-overview.asciidoc#clientsideapp.overview,"Client-Side
+Applications">>. In that case, the module descriptor also needs an entry-point.
+
+If you are using the Eclipse IDE, the New Vaadin Widget wizard will
+automatically create the GWT module descriptor. See
+<<dummy/../../../framework/gwt/gwt-eclipse#gwt.eclipse.widget,"Creating a
+Widget">> for detailed instructions.
+
+[[clientside.module.stylesheet]]
+== Specifying a Stylesheet
+
+A client-side module can include CSS stylesheets. When the module is compiled,
+these stylesheets are copied to the output target. In the module descriptor,
+define a [literal]#++stylesheet++# element.
+
+For example, if you are developing a custom widget and want to have a default
+stylesheet for it, you could define it as follows:
+
+
+----
+<stylesheet src="mywidget/styles.css"/>
+----
+
+The specified path is relative to the __public__ folder under the folder of the
+module descriptor.
+
+
+[[gwt.module.compilation-limiting]]
+== Limiting Compilation Targets
+
+Compiling widget sets takes considerable time. You can reduce the compilation
+time significantly by compiling the widget sets only for your browser, which is
+useful during development. You can do this by setting the
+[parameter]#user.agent# property in the module descriptor.
+
+
+----
+<set-property name="user.agent" value="gecko1_8"/>
+----
+
+The [parameter]#value# attribute should match your browser. The browsers
+supported by GWT depend on the GWT version, below is a list of browser
+identifiers supported by GWT.
+
+.GWT User Agents
+[options="header"]
+|===============
+|Identifier|Name
+|ie6|Internet Explorer 6
+|ie8|Internet Explorer 8
+|gecko1_8|Mozilla Firefox 1.5 and later
+|safari|Apple Safari and other Webkit-based browsers including Google Chrome
+|opera|Opera
+|ie9|Internet Explorer 9
+
+|===============
+
+
+
+
+For more information about the GWT Module XML Format, please see Google Web
+Toolkit Developer Guide.
+
+
+
diff --git a/documentation/clientside/clientside-overview.asciidoc b/documentation/clientside/clientside-overview.asciidoc
new file mode 100644
index 0000000000..8b475d812e
--- /dev/null
+++ b/documentation/clientside/clientside-overview.asciidoc
@@ -0,0 +1,49 @@
+---
+title: Overview
+order: 1
+layout: page
+---
+
+[[clientside.overview]]
+= Overview
+
+As noted in the introduction, Vaadin supports two development models:
+server-side and client-side. Client-side Vaadin code is executed in the web
+browser as JavaScript code. The code is written in Java, like all Vaadin code,
+and then compiled to JavaScript with the __Vaadin Client Compiler__. You can
+develop client-side widgets and integrate them with server-side counterpart
+components to allow using them in server-side Vaadin applications. That is how
+the components in the server-side framework and in most add-ons are done.
+Alternatively, you can create pure client-side GWT applications, which you can
+simply load in the browser from an HTML page and use even without server-side
+connectivity.
+
+The client-side framework is based on the Google Web Toolkit (GWT), with added
+features and bug fixes. Vaadin is compatible with GWT to the extent of the basic
+GWT feature set. Vaadin Ltd is a member of the GWT Steering Committee, working
+on the future direction of GWT together with Google and other supporters of GWT.
+
+
+[NOTE]
+.Widgets and Components
+====
+((("widget,
+definition")))
+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, while
+using the term __component__ in a general sense and also in the special sense
+for server-side components.
+
+====
+
+
+
+The main idea in server-side Vaadin development is to render the server-side
+components in the browser with the Client-Side Engine. The engine is essentially
+a set of widgets paired with __connectors__ that serialize their state and
+events with the server-side counterpart components. The client-side engine is
+technically called a __widget set__, to describe the fact that it mostly
+consists of widgets and that widget sets can be combined, as described later.
+
+
+
diff --git a/documentation/clientside/clientside-widget.asciidoc b/documentation/clientside/clientside-widget.asciidoc
new file mode 100644
index 0000000000..ed911a46b4
--- /dev/null
+++ b/documentation/clientside/clientside-widget.asciidoc
@@ -0,0 +1,76 @@
+---
+title: Creating a Custom Widget
+order: 5
+layout: page
+---
+
+[[clientside.widget]]
+= Creating a Custom Widget
+
+Creating a new Vaadin component usually begins from making a client-side widget,
+which is later integrated with a server-side counterpart to enable server-side
+development. In addition, you can also choose to make pure client-side widgets,
+a possibility which we also describe later in this section.
+
+[[clientside.widget.simple]]
+== A Basic Widget
+
+All widgets extend the [classname]#Widget# class or some of its subclasses. You
+can extend any core GWT or supplementary Vaadin widgets. Perhaps typically, an
+abstraction such as [classname]#Composite#. The basic GWT widget component
+hierarchy is illustrated in <<figure.clientside.widgets>>. Please see the GWT
+API documentation for a complete description of the widget classes.
+
+[[figure.clientside.widgets]]
+.GWT Widget Base Class Hierarchy
+image::img/gwt-widgets-hi.png[]
+
+For example, we could extend the [classname]#Label# widget to display some
+custom text.
+
+
+----
+package com.example.myapp.client;
+
+import com.google.gwt.user.client.ui.Label;
+
+public class MyWidget extends Label {
+    public static final String CLASSNAME = "mywidget";
+
+    public MyWidget() {
+        setStyleName(CLASSNAME);
+        setText("This is MyWidget");
+    }
+}
+----
+
+The above example is largely what the Eclipse plugin generates as a widget stub.
+It is a good practice to set a distinctive style class for the widget, to allow
+styling it with CSS.
+
+The client-side source code __must__ be contained in a [filename]#client#
+package under the package of the descriptor file, which is covered later.
+
+
+[[clientside.widget.using]]
+== Using the Widget
+
+You can use a custom widget just like you would use any widget, possibly
+integrating it with a server-side component, or in pure client-side modules such
+as the following:
+
+
+----
+public class MyEntryPoint implements EntryPoint {
+    @Override
+    public void onModuleLoad() {
+        // Use the custom widget
+        final MyWidget mywidget = new MyWidget();
+        RootPanel.get().add(mywidget);
+    }
+}
+----
+
+
+
+