Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 162 insertions, 0 deletions

diff --git a/documentation/gwt/gwt-eclipse.asciidoc b/documentation/gwt/gwt-eclipse.asciidoc
new file mode 100644
index 0000000000..adbaf9fea1
--- /dev/null
+++ b/documentation/gwt/gwt-eclipse.asciidoc
@@ -0,0 +1,162 @@
+---
+title: Starting It Simple With Eclipse
+order: 2
+layout: page
+---
+
+[[gwt.eclipse]]
+= Starting It Simple With Eclipse
+
+((("Eclipse", "widget development", id="term.gwt.eclipse", range="startofrange")))
+
+
+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.
+
+[[gwt.eclipse.widget]]
+== Creating a Widget
+
+. Right-click the project in the Project Explorer and select "New > Other...".
+
+. In the wizard selection, select "Vaadin > Vaadin Widget" and click
+[guibutton]#Next#.
+
+ifdef::web[]
++
+image::img/widget-new-select.png[]
+endif::web[]
+
+. In the [guilabel]#New Component Wizard#, make the following settings.
+
++
+image::img/widget-new-settings.png[]
+
+[guilabel]#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.
+
+[guilabel]#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 [package]#widgetset# subpackage. The subpackage will contain the
+[filename]#.gwt.xml# descriptor that defines the widget set and the new widget
+stub under the [package]#widgetset.client# subpackage.
+
+[guilabel]#Name#:: The class name of the new __server-side component__. The name of the client-side
+widget stub will be the same but with "- [classname]#Widget#" suffix, for
+example, [classname]#MyComponentWidget#. You can rename the classes afterwards.
+
+[guilabel]#Superclass#:: The superclass of the server-side component. It is
+[classname]#AbstractComponent# by default, but
+[classname]#com.vaadin.ui.AbstractField# or
+[classname]#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.
+
+[guilabel]#Template#:: Select which template to use. The default is [guilabel]#Full fledged#, which
+creates the server-side component, the client-side widget, the connector, a
+shared state object, and an RPC object. The [guilabel]#Connector only# leaves
+the shared state and RPC objects out.
+
+
+
++
+Finally, click [guibutton]#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 ( [filename]#.gwt.xml#) in the base package and modifies
+the servlet class or the [filename]#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 [filename]#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 [guibutton]#Compile widget set# button in
+the Eclipse toolbar. See <<gwt.eclipse.compiling>> 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
+[filename]#WebContent/VAADIN/widgetsets# folder. When you need to recompile the
+widget set in Eclipse, see <<gwt.eclipse.compiling>>. For detailed information
+on compiling widget sets, see
+<<dummy/../../../framework/clientside/clientside-compiling#clientside.compiling,"Compiling
+a Client-Side Module">>.
+
+The following setting is inserted in the [filename]#web.xml# deployment
+descriptor to enable the widget set:
+
+[subs="normal"]
+----
+&lt;init-param&gt;
+    &lt;description&gt;Application widgetset&lt;/description&gt;
+    &lt;param-name&gt;widgetset&lt;/param-name&gt;
+    &lt;param-value&gt;__com.example.myproject.widgetset.MyprojectApplicationWidgetset__&lt;/param-value&gt;
+&lt;/init-param&gt;
+----
+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 " [filename]#client#" or a package defined with a [literal]#++source++#
+element in the widget set descriptor.
+
+
+[[gwt.eclipse.compiling]]
+== 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-side source file. If this gets
+annoying, you can disable the automatic recompilation in the Vaadin category in
+project settings, by selecting the [guilabel]#Suspend automatic widgetset
+builds# option.
+
+You can compile the widget set manually by clicking the [guibutton]#Compile
+widgetset# button in the Eclipse toolbar, shown in
+<<figure.gwt.eclipse.compiling.toolbar>>, while the project is open and
+selected. If the project has multiple widget set definition files, you need to
+select the one to compile in the Project Explorer.
+
+[[figure.gwt.eclipse.compiling.toolbar]]
+.The [guibutton]#Compile Widgetset# Button in Eclipse Toolbar
+image::img/widgetset-compiling-toolbar-hi.png[]
+
+The compilation progress is shown in the [guilabel]#Console# panel in Eclipse,
+illustrated in <<figure.gwt.eclipse.compiling>>. You should note especially the
+list of widget sets found in the class path.
+
+[[figure.gwt.eclipse.compiling]]
+.Compiling a Widget Set
+image::img/widgetset-compiling.png[]
+
+The compilation output is written under the
+[filename]#WebContent/VAADIN/widgetsets# folder, in a widget set specific
+folder.
+
+You can speed up the compilation significantly by compiling the widget set only
+for your browser during development. The generated [filename]#.gwt.xml#
+descriptor stub includes a disabled element that specifies the target browser.
+See
+<<dummy/../../../framework/clientside/clientside-module#gwt.module.compilation-limiting,"Limiting
+Compilation Targets">> for more details on setting the [literal]#++user-agent++#
+property.
+
+For more information on compiling widget sets, see
+<<dummy/../../../framework/clientside/clientside-compiling#clientside.compiling,"Compiling
+a Client-Side Module">>. Should you compile a widget set outside Eclipse, you
+need to refresh the project by selecting it in [guilabel]#Project Explorer# and
+pressing F5.
+
+
+(((range="endofrange", startref="term.gwt.eclipse")))
+
+