diff options
Diffstat (limited to 'documentation/getting-started/getting-started-first-project.asciidoc')
| -rw-r--r-- | documentation/getting-started/getting-started-first-project.asciidoc | 292 |
1 files changed, 7 insertions, 285 deletions
diff --git a/documentation/getting-started/getting-started-first-project.asciidoc b/documentation/getting-started/getting-started-first-project.asciidoc index 3262b8a4b1..73ad178d68 100644 --- a/documentation/getting-started/getting-started-first-project.asciidoc +++ b/documentation/getting-started/getting-started-first-project.asciidoc @@ -18,220 +18,20 @@ Vaadin Plugin. The task will include the following steps: . 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/portal/portal-overview.asciidoc#portal.overview,"Portal Integration">> for instructions regarding the use of Vaadin with portals. -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 +. In the [guilabel]#New Project# window that opens, select "Vaadin > Vaadin 8 Project (Maven)" and click [guibutton]#Next#. + image::img/myproject-new-vaadin.png[width=70%, scaledwidth=90%] @@ -304,14 +104,11 @@ public class MyUI extends UI { name.setCaption("Type your name here:"); Button button = new Button("Click Me"); - button.addClickListener( e -> { + button.addClickListener(e -> layout.addComponent(new Label("Thanks " + name.getValue() - + ", it works!")); - }); + + ", it works!"))); layout.addComponents(name, button); - layout.setMargin(true); - layout.setSpacing(true); setContent(layout); } @@ -377,36 +174,16 @@ 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[] +. Select "Apache > Tomcat v8.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#. . 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 @@ -415,13 +192,6 @@ 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 @@ -438,15 +208,9 @@ 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 +== Updating the Vaadin Framework Libraries + +Updating the Vaadin plugin does not update Vaadin Framework 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. @@ -468,45 +232,3 @@ right-clicking the server and selecting [guilabel]#Clean# as well as 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 "**8.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[] |