From ca2e1a6bda8b5b67b86bdfec9225356ddd0bbada Mon Sep 17 00:00:00 2001
From: Marko Gronroos <magi@vaadin.com>
Date: Tue, 15 Mar 2016 14:14:56 +0200
Subject: Restored Ivy project creation until Maven support becomes official in
 the plugin. Various fixes and improved the diagrams in the section as well.

Change-Id: If32f877b7bfa569d91eaf3fc9d8543e4e4599aa1
---
 .../getting-started-first-project.asciidoc         | 271 +++++++++++++++++----
 1 file changed, 226 insertions(+), 45 deletions(-)

(limited to 'documentation/getting-started/getting-started-first-project.asciidoc')

diff --git a/documentation/getting-started/getting-started-first-project.asciidoc b/documentation/getting-started/getting-started-first-project.asciidoc
index e7a199a54d..cc8be595e1 100644
--- a/documentation/getting-started/getting-started-first-project.asciidoc
+++ b/documentation/getting-started/getting-started-first-project.asciidoc
@@ -27,78 +27,267 @@ Eclipse and set up your development environment, as instructed in
 up the Development Environment">>.
 
 [[getting-started.first-project.creation]]
+ifdef::web[]
 == Creating the Project
+endif::web[]
 
+ifdef::web[]
+_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.maven>>._
+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 (Maven)" and click [guibutton]#Next#.
+Project" and click [guibutton]#Next#.
++
+image::img/myproject-ivy-new-vaadin.png[width=70%]
 
+. 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-new-vaadin.png[]
+image::img/myproject-ivy-settings.png[width=70%]
 
-. 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#.
+[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.
 
-+
-image::img/myproject-archetype-selection.png[]
+[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.
 
-. 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.
+[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)#
 
 +
-image::img/myproject-settings.png[]
+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.
 
-[guilabel]#Group Id#:: Give the project a namespace that is typically used as a prefix
-for your package names, for example, [packagename]#com.example#. The group ID should be a
-valid java package name.
++
+You can change the version later in the [filename]#ivy.xml#.
 
-[guilabel]#Artifact Id#:: Give the project a name, for example, `myproject`. The artifact ID should
-be a valid java identifier.
+[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.
 
-[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.
++
+You can click [guibutton]#Finish# here to use the defaults for the rest of the
+settings, or click [guibutton]#Next#.
 
-[guilabel]#Package#:: Give the base package name for the project, for example,
-[packagename]#com.example.myproject#. By default, this is generated from the group ID and
-the artifact ID.
+. 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[]
+
+[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]#Properties#:: Enter values for the archetype specific properties that control naming
-of various elements in the created project, such as the UI class name.
+[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 change the version later in the [filename]#pom.xml#.
+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.
 +
-Finally, click [guibutton]#Finish# to create the project.
+image::img/myproject-vaadin.png[]
+
+[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: a UI class skeleton has been written to the [filename]#src# directory. The
+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-created.png[]
+image::img/myproject-ivy-created.png[]
 
-The Vaadin libraries and other dependencies are managed by Maven. Notice that the
+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 > Maven Dependencies" virtual folder.
+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.maven]]
+== Creating a Maven Project
+
+ifdef::web[]
+_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%]
+
+. 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%]
+
+. 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%]
+
+[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%]
+
+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]
 ----
@@ -114,20 +303,20 @@ 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() 
+            layout.addComponent(new Label("Thanks " + name.getValue()
                     + ", it works!"));
         });
-        
+
         layout.addComponents(name, button);
         layout.setMargin(true);
         layout.setSpacing(true);
-        
+
         setContent(layout);
     }
 
@@ -138,17 +327,14 @@ public class MyUI extends UI {
 }
 ----
 
-
 [[getting-started.first-project.widgetset]]
 == Compiling the Widget Set and Theme
 
-Before running the project for the first time, select [guilabel]#Compile Widgetset and Theme#
-from the menu shown in <<figure.getting-started.first-project.compilewidgetset>>.
+Before running the project for the first time, select [guilabel]#Compile Widgetset and Theme# from the menu shown in <<figure.getting-started.first-project.compilewidgetset>>.
 
 [[figure.getting-started.first-project.compilewidgetset]]
 .Compile Widgetset and Theme Menu
-image::img/myproject-compilewidgetset.png[]
-
+image::img/myproject-compilewidgetset.png[width=50%]
 
 [[getting-started.first-project.coding]]
 == Coding Tips for Eclipse
@@ -177,7 +363,6 @@ server-side development.
 .Importing Classes Automatically
 image::img/codingtips-automaticimports.png[]
 
-
 [[getting-started.first-project.server]]
 == Setting Up and Starting the Web Server
 
@@ -190,7 +375,7 @@ 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.
+Follow the following steps:
 
 . Switch to the 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". +
 image::img/tomcat-startserver-1.png[]
@@ -207,13 +392,9 @@ image::img/tomcat-startserver-3.png[]
 . 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 Debug. To start the server in non-debug mode, select Start. +
 image::img/tomcat-startserver-4.png[]
 
-
 . The server starts and the WebContent directory of the project is published to the server on http://localhost:8080/myproject/. +
 image::img/tomcat-startserver-5.png[]
 
-
-
-
 [[getting-started.first-project.run]]
 == Running and Debugging
 
@@ -222,7 +403,7 @@ Starting your application is as easy as selecting [guilabel]#myproject# from the
 Eclipse then opens the application in built-in web browser.
 
 .Running a Vaadin Application
-image::img/runningMyProject.png[]
+image::img/runningMyProject.png[width=60%]
 
 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
-- 
cgit v1.2.3

