diff options
Diffstat (limited to 'documentation/gwt/gwt-eclipse.asciidoc')
| -rw-r--r-- | documentation/gwt/gwt-eclipse.asciidoc | 162 |
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"] +---- +<init-param> + <description>Application widgetset</description> + <param-name>widgetset</param-name> + <param-value>__com.example.myproject.widgetset.MyprojectApplicationWidgetset__</param-value> +</init-param> +---- +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"))) + + |