From 9c6831bab067ccdb47c3063f2e77d3c0e7fe3440 Mon Sep 17 00:00:00 2001
From: Pekka Hyvönen <pekka@vaadin.com>
Date: Mon, 2 Jan 2017 13:40:48 +0200
Subject: Update documentation, BoV chapters 1 - 5.3 (#8085)

* Update documentation chapters 1 - 5.3

Images and diagrams have not been updated,
but unnecessary images have been removed.

* Sync application declarative and architecture sections source code.

Screenshot image is updated to match the source code.

* Old datamodel image is removed.

* Ivy install image is removed.

* Remove unnecessary linking / reference
---
 .../getting-started-first-project.asciidoc         | 292 +--------------------
 1 file changed, 7 insertions(+), 285 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 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"]
-----
-&lt;!ENTITY vaadin.version "**8.x.x**"&gt;
-----
-+
-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[]
-- 
cgit v1.2.3

