1 files changed, 327 insertions, 0 deletions
diff --git a/documentation/getting-started/getting-started-first-project.asciidoc b/documentation/getting-started/getting-started-first-project.asciidoc
new file mode 100644
index 0000000000..318279924b
--- /dev/null
+++ b/documentation/getting-started/getting-started-first-project.asciidoc
@@ -0,0 +1,327 @@
+---
+title: Creating and Running a Project with Eclipse
+order: 5
+layout: page
+---
+
+[[getting-started.first-project]]
+= Creating and Running a Project with 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 Tomcat (or some other 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 Vaadin Plugin for
+Eclipse and set up your development environment, as instructed in
+<<dummy/../../../framework/getting-started/getting-started-environment#getting-started.environment,"Setting
+up the Development Environment">>.
+
+[[getting-started.first-project.creation]]
+== Creating the Project
+
+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-new-vaadin.png[]
+
+. 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-settings.png[]
+
+[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-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]#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[]
+
+[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-created.png[]
+
+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">>.
+
+
+
+[[getting-started.first-project.coding]]
+== Coding Tips for Eclipse
+
+One of the most useful features in Eclipse is __code completion__. Pressing
+CtrlSpace in the editor will display a popup 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[]
+
+To add an [literal]#++import++# statement for a class, such as
+[classname]#Button#, simply press CtrlShiftO 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>>. For server-side
+development, you should normally 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.
+
+[[figure.getting-started.first-project.coding.import]]
+.Importing Classes Automatically
+image::img/codingtips-automaticimports.png[]
+
+
+[[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 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[]
+
+
+. 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#. +
+image::img/tomcat-startserver-2.png[]
+
+
+. 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#. +
+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
+
+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.
+
+.Running a Vaadin Application
+image::img/runningMyProject.png[]
+
+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
+Resume from Run menu.
+
+.Debugging a Vaadin Application
+image::img/debuggingMyProject.png[]
+
+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">>.
+
+
+
+