summaryrefslogtreecommitdiffstats
path: root/documentation/gwt/gwt-eclipse.asciidoc
blob: 1f3ed106f683d21d55961a64d110048d8ad55838 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
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
<<../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
<<../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
<<../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")))