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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
|
---
title: Creating a Project in Eclipse
order: 100
layout: page
---
[[getting-started.first-project]]
= Creating and Running a Project in Eclipse
This section gives instructions for creating a new Eclipse project using the
Vaadin Plugin. The task will include the following steps:
. Create a new project
. Write the source code
. Configure and start web server
. Open a web browser to use the web application
We also show how you can debug the application in the debug mode in Eclipse.
This walkthrough assumes that you have already installed the Eclipse IDE, the Vaadin Plugin, and a development server, as instructed in
<<dummy/../../../framework/installing/installing-eclipse#installing.eclipse, "Installing the Eclipse IDE and Plugin">>.
ifdef::web[]
[[getting-started.first-project.ivy]]
== Creating an Ivy Project
endif::web[]
ifdef::web[]
NOTE: The following describes the creation of an Ivy project. The upcoming version of the Eclipse plug-in creates Maven projects. For that, see <<getting-started.first-project.creation>>.
endif::web[]
ifdef::web[]
Let us create the first application project with the tools installed in the
previous section. First, launch Eclipse and follow the following steps:
. Start creating a new project by selecting from the menu "File > New > Project...".
. In the [guilabel]#New Project# window that opens, select "Vaadin > Vaadin 7
Project" and click [guibutton]#Next#.
+
image::img/myproject-ivy-new-vaadin.png[width=70%, scaledwidth=100%]
. In the [guilabel]#Vaadin Project# step, you need to set the basic web project
settings. You need to give at least the __project name__ and the runtime; the
default values should be good for the other settings.
+
image::img/myproject-ivy-settings.png[width=70%, scaledwidth=100%]
[guilabel]#Project name#:: Give the project a name. The name should be a valid identifier usable
cross-platform as a filename and inside a URL, so using only lower-case
alphanumerics, underscore, and minus sign is recommended.
[guilabel]#Use default location#:: Define the directory under which the project is created. The default is under
your workspace folder, and you should normally leave it as it is. You may need
to set the directory, for example, if you are creating an Eclipse project on top
of a version-controlled source tree.
[guilabel]#Target runtime#:: Define the application server to use for deploying the application. The server
that you have installed, for example Apache Tomcat, should be selected
automatically. If not, click [guibutton]#New# to configure a new server under
Eclipse.
[guilabel]#Configuration#:: Select the configuration to use; you should normally use the default
configuration for the application server. If you need to modify the project
facets, click [guibutton]#Modify#. The recommended Servlet 3.0 configuration
uses the @WebServlet deployment, while Servlet 2.4 uses the old
[filename]#web.xml# deployment.
[guilabel]#Deployment configuration#:: This setting defines the environment to which the application will be deployed,
to generate the appropriate project directory layout and configuration files.
The choises are:
*** [guilabel]#Servlet# (default)
*** [guilabel]#Google App Engine Servlet#
*** [guilabel]#Generic Portlet (Portlet 2.0)#
+
The further steps in the New Project Wizard depend on the selected deployment
configuration; the steps listed in this section are for the default servlet
configuration.
ifdef::web[]
See <<dummy/../../../framework/advanced/advanced-gae#advanced.gae,"Google App
Engine Integration">> and <<dummy/../../../framework/portal/portal-overview.asciidoc#portal.overview,"Portal Integration">> for instructions regarding the use of Vaadin in the alternative
environments.
endif::web[]
[guilabel]#Vaadin version#:: Select the Vaadin version to use. The drop-down list shows, by default, the
latest available version of Vaadin. The selection includes nightly
[literal]#++SNAPSHOT++# builds, if you want to keep up with the absolutely
latest unstable versions.
+
You can change the version later in the [filename]#ivy.xml#.
[guilabel]#Create TestBench test#:: When enabled, the application stub will include a test case for testing the UI
with Vaadin TestBench, as described in
<<dummy/../../../testbench/testbench-overview.asciidoc#testbench.overview,"Vaadin TestBench">>.
Vaadin TestBench API library will be included in [filename]#ivy.xml# as a dependency.
Vaadin version 7.3 or later is required to create the stub.
+
You can click [guibutton]#Finish# here to use the defaults for the rest of the
settings, or click [guibutton]#Next#.
. The settings in the [guilabel]#Web Module# step define the basic web application
(WAR) deployment settings and the structure of the web application project. All
the settings are pre-filled, and you should normally accept them as they are.
+
image::img/myproject-ivy-web.png[scaledwidth=100%]
[guilabel]#Context Root#:: The context root (of the application) identifies the application in the URL used
for accessing it. For example, if the project has a [literal]#++myproject++#
context and a single UI at the context root, the URL would be
http://example.com/myproject. The wizard will suggest the project name given in
the first step as the context name. You can change the context root later in the
Eclipse project properties.
[guilabel]#Content Directory#:: The directory containing all the content to be included in the web application
(WAR) that is deployed to the web server. The directory is relative to the root
directory of the project.
+
You can just accept the defaults and click [guibutton]#Next#.
. The [guilabel]#Vaadin project# step page has various Vaadin-specific application settings.
If you are trying out Vaadin for the first time, you should not need
to change anything. You can set most of the settings afterwards, except the
creation of the portlet configuration.
+
image::img/myproject-vaadin.png[scaledwidth=100%]
[guilabel]#Create project template#:: Make the wizard create an UI class stub.
[guilabel]#Application Name#:: A name for the application UI, shown in the title bar of the browser window.
[guilabel]#Base package name#:: The name of the Java package under which the UI class of the application is to
be placed.
[guilabel]#Application/UI class name#:: The name of the UI class for the application, in which the user interface is
developed.
[guilabel]#Portlet version#:: When a portlet version is selected (only Portlet 2.0 is supported), the wizard
will create the files needed for running the application in a portal. See
<<dummy/../../../framework/portal/portal-overview.asciidoc#portal.overview,"Portal
Integration">> for more information on portlets.
+
Finally, click [guibutton]#Finish# to create the project.
[[getting-started.first-project.exploring]]
== Exploring the Project
After the [guilabel]#New Project# wizard exits, it has done all the work for
you: an UI class skeleton has been written to [filename]#src# directory and the
[filename]#WebContent/WEB-INF/web.xml# contains a deployment descriptor. The
project hierarchy shown in the Project Explorer is shown in
<<figure.getting-started.first-project.exploring>>.
[[figure.getting-started.first-project.exploring]]
.A New Vaadin Project
image::img/myproject-ivy-created.png[width=40%, scaledwidth=60%]
The Vaadin libraries and other dependencies are managed by Ivy. Notice that the
libraries are not stored under the project folder, even though they are listed
in the "Java Resources > Libraries > ivy.xml" virtual folder.
[[getting-started.first-project.exploring.ui]]
=== The UI Class
The UI class created by the plugin contains the following code:
[source, java]
----
package com.example.myproject;
import com.vaadin.ui.UI;
...
@SuppressWarnings("serial")
@Theme("myproject")
public class MyprojectUI extends UI {
@WebServlet(value = "/*", asyncSupported = true)
@VaadinServletConfiguration(
productionMode = false,
ui = MyprojectUI.class)
public static class Servlet extends VaadinServlet {
}
@Override
protected void init(VaadinRequest request) {
final VerticalLayout layout = new VerticalLayout();
layout.setMargin(true);
setContent(layout);
Button button = new Button("Click Me");
button.addClickListener(new Button.ClickListener() {
public void buttonClick(ClickEvent event) {
layout.addComponent(
new Label("Thank you for clicking"));
}
});
layout.addComponent(button);
}
}
----
In a Servlet 3.0 project, the deployment is configured with servlet class and a
[literal]#++@WebServlet++# annotation. The stub includes the servlet class as a
static inner class. You may want to refactor it to a separate normal class.
In a Servlet 2.3 project, you would have a [filename]#web.xml# deployment
descriptor.
For a more detailed treatment of the deployment, see
<<dummy/../../../framework/application/application-environment#application.environment.web-xml,"Using a web.xml Deployment Descriptor">>.
endif::web[]
[[getting-started.first-project.creation]]
== Creating a Maven Project
ifdef::web[]
NOTE: The following describes project creation in the upcoming version of the Eclipse plug-in, which creates Maven rather than Ivy projects.
To use it, you must have installed the experimental version of the plug-in.
endif::web[]
Let us create the first application project with the tools installed in the previous section.
First, launch Eclipse and follow the following steps:
. Start creating a new project by selecting from the menu "File > New > Project...".
. In the [guilabel]#New Project# window that opens, select "Vaadin > Vaadin 7
Project (Maven)" and click [guibutton]#Next#.
+
image::img/myproject-new-vaadin.png[width=70%, scaledwidth=90%]
. In the [guilabel]#Select a Maven archetype# step, you need to select the project type.
To create a simple test project, select the [guilabel]#Single-module Application Project#.
+
image::img/myproject-archetype-selection.png[width=70%, scaledwidth=90%]
. In the [guilabel]#Specify archetype parameters# step, you need to give at least the [guilabel]#Group Id# and the [guilabel]#Artifact Id#.
The default values should be good for the other settings.
+
image::img/myproject-settings.png[width=70%, scaledwidth=90%]
[guilabel]#Group Id#::
Give the project an organization-level identifier, for example, [packagename]#com.example#.
It is used as a prefix for your Java package names, and hence must be a valid Java package name itself.
[guilabel]#Artifact Id#:: Give the project a name, for example, `myproject`.
The artifact ID must be a valid Java sub-package name.
[guilabel]#Version#:: Give the project a Maven compatible version number, for example, `1.0-SNAPSHOT`.
The version number should typically start with two or more integers separated with dots, and
should not contain spaces.
[guilabel]#Package#:: Give the base package name for the project, for example,
[packagename]#com.example.myproject#.
It is by default generated from the group ID and the artifact ID.
[guilabel]#Properties#:: Enter values for archetype-specific properties that control naming of various elements in the created project, such as the UI class name.
+
You can change the version later in the [filename]#pom.xml#.
+
Finally, click [guibutton]#Finish# to create the project.
[[getting-started.first-project.exploring]]
== Exploring the Project
After the [guilabel]#New Project# wizard exits, it has done all the work for you.
A UI class skeleton has been written to the [filename]#src# directory.
The project hierarchy shown in the Project Explorer is shown in <<figure.getting-started.first-project.exploring>>.
[[figure.getting-started.first-project.exploring]]
.A new Vaadin project
image::img/myproject-created-annotated-hi.png[width=80%, scaledwidth=100%]
The Vaadin libraries and other dependencies are managed by Maven.
Notice that the libraries are not stored under the project folder, even though they are listed in the "Java Resources > Libraries > Maven Dependencies" virtual folder.
[[getting-started.first-project.exploring.ui]]
=== The UI Class
The UI class created by the plug-in contains the following code:
[source, java]
----
package com.example.myproject;
import com.vaadin.ui.UI;
...
@Theme("mytheme")
public class MyUI extends UI {
@Override
protected void init(VaadinRequest vaadinRequest) {
final VerticalLayout layout = new VerticalLayout();
final TextField name = new TextField();
name.setCaption("Type your name here:");
Button button = new Button("Click Me");
button.addClickListener( e -> {
layout.addComponent(new Label("Thanks " + name.getValue()
+ ", it works!"));
});
layout.addComponents(name, button);
layout.setMargin(true);
layout.setSpacing(true);
setContent(layout);
}
@WebServlet(urlPatterns = "/*", name = "MyUIServlet", asyncSupported = true)
@VaadinServletConfiguration(ui = MyUI.class, productionMode = false)
public static class MyUIServlet extends VaadinServlet {
}
}
----
[[getting-started.first-project.theme]]
== Compiling the Theme
Before running the project for the first time, click the [guilabel]#Compile Vaadin Theme# button in the toolbar, as shown in <<figure.getting-started.first-project.compiletheme>>.
[[figure.getting-started.first-project.compiletheme]]
.Compile Vaadin Theme
image::img/myproject-compiletheme.png[width=40%, scaledwidth=60%]
[[getting-started.first-project.coding]]
== Coding Tips for Eclipse
=== Code Completion
One of the most useful features in Eclipse is __code completion__. Pressing
kbd:[Ctrl+Space] in the editor will display a pop-up list of possible class name and
method name completions, as shown in
<<figure.getting-started.first-project.coding.codecompletion>>, depending on the
context of the cursor position.
[[figure.getting-started.first-project.coding.codecompletion]]
.Java Code Completion in Eclipse
image::img/codingtips-codecompletion.png[scaledwidth=100%]
=== Generating Imports
To automatically add an [literal]#++import++# statement for a class, such as
[classname]#Button#, simply press kbd:[Ctrl+Shift+O] or click the red error indicator on the left side of the editor window.
If the class is available in multiple packages, a list of the alternatives is displayed, as shown in <<figure.getting-started.first-project.coding.import>>.
[[figure.getting-started.first-project.coding.import]]
.Importing classes automatically
image::img/codingtips-automaticimports.png[scaledwidth=70%]
For server-side Vaadin development, you should generally use the classes under the [package]#com.vaadin.ui# or [package]#com.vaadin.server# packages.
_You can not use client-side classes (under [package]#com.vaadin.client#) or GWT classes for server-side development._
[[getting-started.first-project.server]]
== Setting Up and Starting the Web Server
Eclipse IDE for Java EE Developers has the Web Standard Tools package installed,
which supports control of various web servers and automatic deployment of web
content to the server when changes are made to a project.
Make sure that Tomcat was installed with user permissions. Configuration of the
web server in Eclipse will fail if the user does not have write permissions to
the configuration and deployment directories under the Tomcat installation
directory.
Follow the following steps:
. Switch to the [guilabel]#Servers# tab in the lower panel in Eclipse.
List of servers should be empty after Eclipse is installed.
Right-click on the empty area in the panel and select "New > Server".
ifdef::web[]
+
image::img/tomcat-startserver-1.png[width=60%, scaledwidth=100%]
endif::web[]
. Select "Apache > Tomcat v7.0 Server" and set [guilabel]#Server's host name# as [literal]#++localhost++#, which should be the default. If you have only one Tomcat installed, [guilabel]#Server runtime# has only one choice. Click [guibutton]#Next#.
ifdef::web[]
+
image::img/tomcat-startserver-2.png[width=60%, scaledwidth=100%]
endif::web[]
. Add your project to the server by selecting it on the left and clicking [guibutton]#Add# to add it to the configured projects on the right. Click [guibutton]#Finish#.
ifdef::web[]
+
image::img/tomcat-startserver-3.png[width=60%, scaledwidth=100%]
endif::web[]
. The server and the project are now installed in Eclipse and are shown in the [guilabel]#Servers# tab.
To start the server, right-click on the server and select [guilabel]#Debug#.
To start the server in non-debug mode, select [guilabel]#Start#.
ifdef::web[]
+
image::img/tomcat-startserver-4.png[width=60%, scaledwidth=100%]
endif::web[]
. The server starts and the WebContent directory of the project is published to the server on http://localhost:8080/myproject/.
ifdef::web[]
+
image::img/tomcat-startserver-5.png[width=60%, scaledwidth=100%]
endif::web[]
[[getting-started.first-project.run]]
== Running and Debugging
Starting your application is as easy as selecting [guilabel]#myproject# from the
[guilabel]#Project Explorer# and then "Run > Debug As > Debug on Server".
Eclipse then opens the application in built-in web browser.
////
// This is rather irrelevant
//
.Running a Vaadin Application
image::img/runningMyProject.png[width=60%, scaledwidth=80%]
////
You can insert break points in the Java code by double-clicking on the left
margin bar of the source code window. For example, if you insert a breakpoint in
the [methodname]#buttonClick()# method and click the [guibutton]#What is the
time?# button, Eclipse will ask to switch to the Debug perspective. Debug
perspective will show where the execution stopped at the breakpoint. You can
examine and change the state of the application.
To continue execution, select [guilabel]#Resume# from [guilabel]#Run# menu.
.Debugging a Vaadin Application
image::img/debuggingMyProject.png[scaledwidth=100%]
Above, we described how to debug a server-side application.
Debugging client-side applications and widgets is described in
<<dummy/../../../framework/clientside/clientside-debugging#clientside.debugging,"Debugging Client-Side Code">>.
[[getting-started.eclipse.mavenlibraryupdate]]
ifdef::web[]
== Updating the Vaadin Libraries in Maven Projects
endif::web[]
// The book only describes Maven projects
ifndef::web[]
== Updating the Vaadin Libraries
endif::web[]
Updating the Vaadin plugin does not update Vaadin libraries. The libraries are
project specific, as a different version might be required for different
projects, so you have to update them separately for each project.
. Open the [filename]#pom.xml# in an editor in Eclipse.
. Edit the [propertyname]#vaadin.version# property to set the Vaadin version.
+
Updating the libraries can take several minutes. You can see the progress in the
Eclipse status bar. You can get more details about the progress by clicking the
indicator.
. _In Vaadin 7.6 and older_: if you have compiled the widget set for your project, recompile it by clicking the *Compile Vaadin Widgetset* button in the Eclipse toolbar.
+
image::img/myproject-compilewidgetset.png[width=50%, scaledwidth=60%]
. Stop the integrated Tomcat (or other server) in Eclipse, clear its caches by
right-clicking the server and selecting [guilabel]#Clean# as well as
[guilabel]#Clean Tomcat Work Directory#, and restart it.
If you experience problems after updating the libraries, you can try using
"Maven > Update Project".
ifdef::web[]
[[getting-started.eclipse.libraryupdate]]
== Updating the Vaadin Libraries in Ivy Projects
Updating the Vaadin plugin does not update Vaadin libraries.
The libraries are project specific, as a different version might be required for different projects, so you have to update them separately for each project.
. Open the [filename]#ivy.xml# in an editor in Eclipse.
. Edit the entity definition at the beginning of the file to set the Vaadin
version.
+
[subs="normal"]
----
<!ENTITY vaadin.version "**7.x.x**">
----
+
You can specify either a fixed version number, as shown in the above example, or
a dynamic revision tag such as [literal]#++latest.release++#.
You can find more information about the dependency declarations in Ivy documentation.
. Right-click the project and select "Ivy > Resolve".
+
Updating the libraries can take several minutes. You can see the progress in the
Eclipse status bar. You can get more details about the progress by clicking the
indicator.
. If you have compiled the widget set for your project, recompile it by clicking the *Compile Vaadin Widgetset* button in Eclipse toolbar.
+
image::img/myproject-compilewidgetset.png[width=50%, scaledwidth=60%]
. Stop the integrated Tomcat (or other server) in Eclipse, clear its caches by
right-clicking the server and selecting Clean as well as Clean Tomcat Work
Directory, and restart it.
If you experience problems after updating the libraries, you can try clearing
the Ivy resolution caches by right-clicking the project and selecting "Ivy >
Clean all caches".
Then, do the "Ivy > Resolve" and other tasks again.
endif::web[]
|