From d29c00fa27a4c9240b52ffcc540373d7d6303164 Mon Sep 17 00:00:00 2001 From: Henri Sara Date: Fri, 4 Mar 2016 16:43:18 +0200 Subject: Update getting started documentation using Maven Change-Id: I61f22511eefc8125f8cd84d768a5fa69b8707446 --- .../getting-started-eclipse.asciidoc | 30 +++- .../getting-started-first-project.asciidoc | 190 ++++++--------------- .../getting-started/img/debuggingMyProject.png | Bin 137355 -> 444103 bytes .../img/myproject-archetype-selection.png | Bin 0 -> 126127 bytes .../img/myproject-compilewidgetset.png | Bin 0 -> 60613 bytes .../getting-started/img/myproject-created.png | Bin 21785 -> 161562 bytes .../getting-started/img/myproject-new-vaadin.png | Bin 32682 -> 104835 bytes .../getting-started/img/myproject-settings.png | Bin 50386 -> 132401 bytes .../getting-started/img/runningMyProject.png | Bin 25713 -> 40320 bytes .../getting-started/img/tomcat-startserver-1.png | Bin 13794 -> 37348 bytes .../getting-started/img/tomcat-startserver-2.png | Bin 49846 -> 156483 bytes .../getting-started/img/tomcat-startserver-3.png | Bin 29085 -> 92646 bytes .../getting-started/img/tomcat-startserver-4.png | Bin 18603 -> 58063 bytes .../getting-started/img/tomcat-startserver-5.png | Bin 18426 -> 64013 bytes 14 files changed, 83 insertions(+), 137 deletions(-) create mode 100644 documentation/getting-started/img/myproject-archetype-selection.png create mode 100644 documentation/getting-started/img/myproject-compilewidgetset.png (limited to 'documentation/getting-started') diff --git a/documentation/getting-started/getting-started-eclipse.asciidoc b/documentation/getting-started/getting-started-eclipse.asciidoc index a380701d6f..5e10b560d7 100644 --- a/documentation/getting-started/getting-started-eclipse.asciidoc +++ b/documentation/getting-started/getting-started-eclipse.asciidoc @@ -73,8 +73,36 @@ Vaadin libraries, which are project specific. See below for instructions for updating the libraries. +[[getting-started.eclipse.mavenlibraryupdate]] +== Updating the Vaadin Libraries in Maven 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]#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. + +. If you have compiled the widget set for your project, recompile it by clicking +the [guibutton]#Compile Vaadin widgets# button in Eclipse toolbar. + +. 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". + + [[getting-started.eclipse.libraryupdate]] -== Updating the Vaadin Libraries +== 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 diff --git a/documentation/getting-started/getting-started-first-project.asciidoc b/documentation/getting-started/getting-started-first-project.asciidoc index d30e8c5187..e7a199a54d 100644 --- a/documentation/getting-started/getting-started-first-project.asciidoc +++ b/documentation/getting-started/getting-started-first-project.asciidoc @@ -34,126 +34,44 @@ 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#. +Project (Maven)" 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. +. 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-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. +image::img/myproject-archetype-selection.png[] -[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 <> and -<> 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. +. 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. + -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 -<>. 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. +image::img/myproject-settings.png[] -[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. +[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. +[guilabel]#Artifact Id#:: Give the project a name, for example, `myproject`. The artifact ID should +be a valid java identifier. +[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 just accept the defaults and 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 [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. +[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. + -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 -<> for more information on portlets. - - +You can change the version later in the [filename]#pom.xml#. + Finally, click [guibutton]#Finish# to create the project. @@ -164,8 +82,7 @@ Finally, click [guibutton]#Finish# to create the project. == 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 +you: a UI class skeleton has been written to the [filename]#src# directory. The project hierarchy shown in the Project Explorer is shown in <>. @@ -173,9 +90,9 @@ project hierarchy shown in the Project Explorer is shown in .A New Vaadin Project image::img/myproject-created.png[] -The Vaadin libraries and other dependencies are managed by Ivy. Notice that the +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 > ivy.xml" virtual folder. +in the "Java Resources > Libraries > Maven Dependencies" virtual folder. [[getting-started.first-project.exploring.ui]] === The UI Class @@ -190,46 +107,47 @@ 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 { - } +@Theme("mytheme") +@Widgetset("com.example.myproject.MyAppWidgetset") +public class MyUI extends UI { @Override - protected void init(VaadinRequest request) { + protected void init(VaadinRequest vaadinRequest) { final VerticalLayout layout = new VerticalLayout(); - layout.setMargin(true); - setContent(layout); + + final TextField name = new TextField(); + name.setCaption("Type your name here:"); Button button = new Button("Click Me"); - button.addClickListener(new Button.ClickListener() { - public void buttonClick(ClickEvent event) { - layout.addComponent( - new Label("Thank you for clicking")); - } + button.addClickListener( e -> { + layout.addComponent(new Label("Thanks " + name.getValue() + + ", it works!")); }); - layout.addComponent(button); + + 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 { } } ---- -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. +[[getting-started.first-project.widgetset]] +== Compiling the Widget Set and Theme -For a more detailed treatment of the deployment, see -<>. +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]] +.Compile Widgetset and Theme Menu +image::img/myproject-compilewidgetset.png[] [[getting-started.first-project.coding]] @@ -278,7 +196,7 @@ Follow the following steps. 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#. + +. 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#. + image::img/tomcat-startserver-2.png[] diff --git a/documentation/getting-started/img/debuggingMyProject.png b/documentation/getting-started/img/debuggingMyProject.png index 2baae3d191..4276fbd0e2 100644 Binary files a/documentation/getting-started/img/debuggingMyProject.png and b/documentation/getting-started/img/debuggingMyProject.png differ diff --git a/documentation/getting-started/img/myproject-archetype-selection.png b/documentation/getting-started/img/myproject-archetype-selection.png new file mode 100644 index 0000000000..26a0672436 Binary files /dev/null and b/documentation/getting-started/img/myproject-archetype-selection.png differ diff --git a/documentation/getting-started/img/myproject-compilewidgetset.png b/documentation/getting-started/img/myproject-compilewidgetset.png new file mode 100644 index 0000000000..ae6791277b Binary files /dev/null and b/documentation/getting-started/img/myproject-compilewidgetset.png differ diff --git a/documentation/getting-started/img/myproject-created.png b/documentation/getting-started/img/myproject-created.png index 0cebb5f0db..c9cc605325 100644 Binary files a/documentation/getting-started/img/myproject-created.png and b/documentation/getting-started/img/myproject-created.png differ diff --git a/documentation/getting-started/img/myproject-new-vaadin.png b/documentation/getting-started/img/myproject-new-vaadin.png index e2243d5c1a..7862bdcab1 100644 Binary files a/documentation/getting-started/img/myproject-new-vaadin.png and b/documentation/getting-started/img/myproject-new-vaadin.png differ diff --git a/documentation/getting-started/img/myproject-settings.png b/documentation/getting-started/img/myproject-settings.png index 20d4509317..a76e8d08da 100644 Binary files a/documentation/getting-started/img/myproject-settings.png and b/documentation/getting-started/img/myproject-settings.png differ diff --git a/documentation/getting-started/img/runningMyProject.png b/documentation/getting-started/img/runningMyProject.png index e4c4ebcd54..0e1617366d 100644 Binary files a/documentation/getting-started/img/runningMyProject.png and b/documentation/getting-started/img/runningMyProject.png differ diff --git a/documentation/getting-started/img/tomcat-startserver-1.png b/documentation/getting-started/img/tomcat-startserver-1.png index 3c2693ba01..8120911a0a 100644 Binary files a/documentation/getting-started/img/tomcat-startserver-1.png and b/documentation/getting-started/img/tomcat-startserver-1.png differ diff --git a/documentation/getting-started/img/tomcat-startserver-2.png b/documentation/getting-started/img/tomcat-startserver-2.png index 04ac7d87d0..1ae1ef5c1a 100644 Binary files a/documentation/getting-started/img/tomcat-startserver-2.png and b/documentation/getting-started/img/tomcat-startserver-2.png differ diff --git a/documentation/getting-started/img/tomcat-startserver-3.png b/documentation/getting-started/img/tomcat-startserver-3.png index 2cc17876e9..d9e4e3d2b9 100644 Binary files a/documentation/getting-started/img/tomcat-startserver-3.png and b/documentation/getting-started/img/tomcat-startserver-3.png differ diff --git a/documentation/getting-started/img/tomcat-startserver-4.png b/documentation/getting-started/img/tomcat-startserver-4.png index 7e704e772b..68ddcafe6a 100644 Binary files a/documentation/getting-started/img/tomcat-startserver-4.png and b/documentation/getting-started/img/tomcat-startserver-4.png differ diff --git a/documentation/getting-started/img/tomcat-startserver-5.png b/documentation/getting-started/img/tomcat-startserver-5.png index f860a0005b..55d1425f9b 100644 Binary files a/documentation/getting-started/img/tomcat-startserver-5.png and b/documentation/getting-started/img/tomcat-startserver-5.png differ -- cgit v1.2.3 From 354a04a9f32edf5dae84b2421ae1a3011357f97d Mon Sep 17 00:00:00 2001 From: Marko Gronroos Date: Fri, 11 Mar 2016 16:35:59 +0200 Subject: Added an installation steps diagram. Change-Id: Ifeb4bc84b148461547f10fd83a20cd4b386f4d27 --- .../getting-started-overview.asciidoc | 6 +- .../getting-started/img/installation-steps-hi.png | Bin 0 -> 139406 bytes .../installation-steps-constellation.svg | 7259 ++++++++++++++++++++ .../original-drawings/installation-steps.svg | 664 ++ 4 files changed, 7926 insertions(+), 3 deletions(-) create mode 100644 documentation/getting-started/img/installation-steps-hi.png create mode 100644 documentation/getting-started/original-drawings/installation-steps-constellation.svg create mode 100644 documentation/getting-started/original-drawings/installation-steps.svg (limited to 'documentation/getting-started') diff --git a/documentation/getting-started/getting-started-overview.asciidoc b/documentation/getting-started/getting-started-overview.asciidoc index 994ca48248..016196b3f6 100644 --- a/documentation/getting-started/getting-started-overview.asciidoc +++ b/documentation/getting-started/getting-started-overview.asciidoc @@ -12,6 +12,9 @@ that has the Java SDK and a Java Servlet container. Vaadin has special support for the Eclipse and NetBeans IDEs, but community support exists also for IntelliJ IDEA. You can use it with any Java IDE or no IDE at all. +.Vaadin installation steps +image::img/installation-steps-hi.png[] + Managing Vaadin and other Java libraries can get tedious to do manually, so using a build system that manages dependencies automatically is adviced. Vaadin is distributed in the Maven central repository, and can be used with any build @@ -25,6 +28,3 @@ managers, and you can also install it from an installation package: * With the Vaadin plugin for NetBeans IDE ( <>) or IntelliJ IDEA * With Maven, Ivy, Gradle, or other Maven-compatible dependency manager, under Eclipse, NetBeans, IDEA, or using command-line, as described in <> * From installation package without dependency management, as described in <> - - - diff --git a/documentation/getting-started/img/installation-steps-hi.png b/documentation/getting-started/img/installation-steps-hi.png new file mode 100644 index 0000000000..9dae72d61a Binary files /dev/null and b/documentation/getting-started/img/installation-steps-hi.png differ diff --git a/documentation/getting-started/original-drawings/installation-steps-constellation.svg b/documentation/getting-started/original-drawings/installation-steps-constellation.svg new file mode 100644 index 0000000000..7716b64f6c --- /dev/null +++ b/documentation/getting-started/original-drawings/installation-steps-constellation.svg @@ -0,0 +1,7259 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + On Windows On OS X On Linux InstallJDK Eclipse NetBeans IntelliJ IDEA Install an IDE Install aServer InstallVaadinPlugin FireBug ApacheTomcat TomEE GlassFish Other δ γ β α ε InstallOtherTools + M103 M52 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/getting-started/original-drawings/installation-steps.svg b/documentation/getting-started/original-drawings/installation-steps.svg new file mode 100644 index 0000000000..2af7752bd3 --- /dev/null +++ b/documentation/getting-started/original-drawings/installation-steps.svg @@ -0,0 +1,664 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + OnWindows + + + OnOS X + + + OnLinux + + + + + + + InstallJDK + + + + + EclipseIDE + + + NetBeansIDE + + + IntelliJIDEA + + + + + + Install an IDE + + + + ApacheTomcat + + + TomEE + + + Wildfly + + + GlassFish + + + Other + + + + + + Install aServer + + + + Firebug + + + + + + + Other Tools + + + GoCreate a Project + StartHere + -- cgit v1.2.3 From ca2e1a6bda8b5b67b86bdfec9225356ddd0bbada Mon Sep 17 00:00:00 2001 From: Marko Gronroos 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 ++++++++++++--- .../getting-started/img/installation-steps-hi.png | Bin 139406 -> 65439 bytes .../img/myproject-created-annotated-hi.png | Bin 0 -> 160057 bytes .../getting-started/img/myproject-ivy-created.png | Bin 0 -> 21785 bytes .../img/myproject-ivy-new-vaadin.png | Bin 0 -> 32682 bytes .../getting-started/img/myproject-ivy-settings.png | Bin 0 -> 50386 bytes .../getting-started/img/myproject-ivy-vaadin.png | Bin 0 -> 45886 bytes .../getting-started/img/myproject-ivy-web.png | Bin 0 -> 22378 bytes .../getting-started/original-drawings/Makefile | 13 + .../myproject-created-annotated.svg | 363 +++++++++++++++++++++ 10 files changed, 602 insertions(+), 45 deletions(-) create mode 100644 documentation/getting-started/img/myproject-created-annotated-hi.png create mode 100644 documentation/getting-started/img/myproject-ivy-created.png create mode 100644 documentation/getting-started/img/myproject-ivy-new-vaadin.png create mode 100644 documentation/getting-started/img/myproject-ivy-settings.png create mode 100644 documentation/getting-started/img/myproject-ivy-vaadin.png create mode 100644 documentation/getting-started/img/myproject-ivy-web.png create mode 100644 documentation/getting-started/original-drawings/Makefile create mode 100644 documentation/getting-started/original-drawings/myproject-created-annotated.svg (limited to 'documentation/getting-started') 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 <>._ +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 <> and <> 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 +<>. +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 +<> 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]] .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 +<>. +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]] +.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 <>. +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]] .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 diff --git a/documentation/getting-started/img/installation-steps-hi.png b/documentation/getting-started/img/installation-steps-hi.png index 9dae72d61a..06089e1e46 100644 Binary files a/documentation/getting-started/img/installation-steps-hi.png and b/documentation/getting-started/img/installation-steps-hi.png differ diff --git a/documentation/getting-started/img/myproject-created-annotated-hi.png b/documentation/getting-started/img/myproject-created-annotated-hi.png new file mode 100644 index 0000000000..c2d9a49221 Binary files /dev/null and b/documentation/getting-started/img/myproject-created-annotated-hi.png differ diff --git a/documentation/getting-started/img/myproject-ivy-created.png b/documentation/getting-started/img/myproject-ivy-created.png new file mode 100644 index 0000000000..0cebb5f0db Binary files /dev/null and b/documentation/getting-started/img/myproject-ivy-created.png differ diff --git a/documentation/getting-started/img/myproject-ivy-new-vaadin.png b/documentation/getting-started/img/myproject-ivy-new-vaadin.png new file mode 100644 index 0000000000..e2243d5c1a Binary files /dev/null and b/documentation/getting-started/img/myproject-ivy-new-vaadin.png differ diff --git a/documentation/getting-started/img/myproject-ivy-settings.png b/documentation/getting-started/img/myproject-ivy-settings.png new file mode 100644 index 0000000000..20d4509317 Binary files /dev/null and b/documentation/getting-started/img/myproject-ivy-settings.png differ diff --git a/documentation/getting-started/img/myproject-ivy-vaadin.png b/documentation/getting-started/img/myproject-ivy-vaadin.png new file mode 100644 index 0000000000..fff616e6fe Binary files /dev/null and b/documentation/getting-started/img/myproject-ivy-vaadin.png differ diff --git a/documentation/getting-started/img/myproject-ivy-web.png b/documentation/getting-started/img/myproject-ivy-web.png new file mode 100644 index 0000000000..ae47d37c0f Binary files /dev/null and b/documentation/getting-started/img/myproject-ivy-web.png differ diff --git a/documentation/getting-started/original-drawings/Makefile b/documentation/getting-started/original-drawings/Makefile new file mode 100644 index 0000000000..6b3bab4617 --- /dev/null +++ b/documentation/getting-started/original-drawings/Makefile @@ -0,0 +1,13 @@ +IMAGES = installation-steps myproject-created-annotated + +SRCIMAGES := $(foreach file, $(IMAGES), $(file).svg) +TRGIMAGES_HI := $(foreach file, $(IMAGES), ../img/$(file)-hi.png) +TRGIMAGES_LO := $(foreach file, $(IMAGES), ../img/$(file)-lo.png) + +images: $(TRGIMAGES_HI) FORCE +# Just do low now $(TRGIMAGES_LO) + +$(TRGIMAGES_HI): ../img/%-hi.png: %.svg + inkscape --export-png $@ --export-dpi=150 --export-area-drawing $< + +FORCE: diff --git a/documentation/getting-started/original-drawings/myproject-created-annotated.svg b/documentation/getting-started/original-drawings/myproject-created-annotated.svg new file mode 100644 index 0000000000..b639c5f160 --- /dev/null +++ b/documentation/getting-started/original-drawings/myproject-created-annotated.svg @@ -0,0 +1,363 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + The UI class skeleton + + + + + + + + + + + + + + + + + + + + + + + The widget set + The theme + Maven project configuration + Project README skeleton + + -- cgit v1.2.3 From ce1d609b9cb9fbe0129d91a0fc79d60079d5efae Mon Sep 17 00:00:00 2001 From: Marko Gronroos Date: Wed, 16 Mar 2016 15:09:46 +0200 Subject: Formatting fixes mainly to chapters 1-4. Change-Id: Ie7699ae777791689e0026e241efdf46274776bff --- .../application/application-declarative.asciidoc | 60 +++++++++------------ .../application/application-environment.asciidoc | 43 +++++++-------- .../architecture/architecture-overview.asciidoc | 7 +-- .../getting-started-environment.asciidoc | 38 +++++-------- .../getting-started-first-project.asciidoc | 33 +++++++----- .../getting-started/getting-started-idea.asciidoc | 44 +++++++-------- .../getting-started/getting-started-maven.asciidoc | 47 ++++++++++------ .../getting-started-package.asciidoc | 29 +++------- .../img/myproject-created-annotated-hi.png | Bin 160057 -> 159382 bytes .../myproject-created-annotated.svg | 44 +++++++-------- documentation/introduction/intro-eclipse.asciidoc | 34 +++++------- documentation/introduction/intro-goals.asciidoc | 17 +++--- .../introduction/intro-walkthrough.asciidoc | 11 ++-- documentation/themes/themes-fonticon.asciidoc | 38 ++++++------- 14 files changed, 194 insertions(+), 251 deletions(-) (limited to 'documentation/getting-started') diff --git a/documentation/application/application-declarative.asciidoc b/documentation/application/application-declarative.asciidoc index 3e6fea7633..b741cf1cab 100644 --- a/documentation/application/application-declarative.asciidoc +++ b/documentation/application/application-declarative.asciidoc @@ -29,7 +29,6 @@ See the http://demo.vaadin.com/book-examples-vaadin7/book#layout.orderedlayout.b You could define it declaractively with the following equivalent design: - [source, html] ---- @@ -38,7 +37,9 @@ You could define it declaractively with the following equivalent design: ---- +ifdef::web[] See the http://demo.vaadin.com/book-examples-vaadin7/book#layout.orderedlayout.basic[on-line example, window="_blank"]. +endif::web[] Declarative designs can be crafted by hand, but are most conveniently created with the Vaadin Designer. @@ -52,7 +53,7 @@ handling user interaction events. A design is an HTML document with custom elements for representing components and their configuration. A design has a single root component inside the HTML -body element. Enclosing [literal]#++++#, [literal]#++++#, +body element. Enclosing [literal]#++++#, [literal]#++++#, and [literal]#++++# are optional, but necessary if you need to make namespace definitions for custom components. Other regular HTML elements may not be used in the file, except inside components that specifically accept HTML content. @@ -61,7 +62,6 @@ In a design, each nested element corresponds to a Vaadin component in a component tree. Components can have explicitly given IDs to enable binding them to variables in the Java code, as well as optional attributes. - [source, html] ---- @@ -69,13 +69,14 @@ to variables in the Java code, as well as optional attributes. - Hello! - How are you? + Hello! - + How are you? - - + + @@ -95,15 +96,11 @@ Hierarchical UI">>. [[application.declarative.elements]] == Component Elements -HTML elements of the declarative syntax are directly mapped to Vaadin components -according to their Java class names. The tag of a component element has a -namespace prefix separated by a dash. Vaadin core components, which are defined -in the [package]#com.vaadin.ui# package, have [literal]#++vaadin-++# prefix. The rest -of an element tag is determined from the Java class name of the component, by -making it lower-case, while adding a dash ( [literal]#++-++#) before every -previously upper-case letter as a word separator. For example, -[classname]#ComboBox# component has declarative element tag -[literal]#++++#. +HTML elements of the declarative syntax are directly mapped to Vaadin components according to their Java class names. +The tag of a component element has a namespace prefix separated by a dash. +Vaadin core components, which are defined in the [package]#com.vaadin.ui# package, have [literal]#++vaadin-++# prefix. +The rest of an element tag is determined from the Java class name of the component, by making it lower-case, while adding a dash (`-`) before every previously upper-case letter as a word separator. +For example, [classname]#ComboBox# component has declarative element tag [vaadinelement]#vaadin-combo-box#. [[application.declarative.elements.prefix]] === Component Prefix to Package Mapping @@ -113,15 +110,14 @@ composite components, and add-on components. To do so, you need to define a mapping from an element prefix to the Java package of the component. The prefix is used as a sort of a namespace. -The mappings are defined in [literal]#++++# +The mappings are defined in `` elements in the HTML head. A [parameter]#content# attribute defines a mapping, in notation with a prefix separated from the corresponding Java package name -with a colon, such as " [literal]#++my:com.example.myapp++#". +with a colon, such as `my:com.example.myapp`. For example, consider that you have the following composite class [classname]#com.example.myapp.ExampleComponent#: - [source, java] ---- package com.example.myapp; @@ -140,12 +136,14 @@ You would make the package prefix mapping and then use the component as follows: <!DOCTYPE html> <html> <head> - **<meta name="package-mapping" content="my:com.example.myapp" />** + **<meta name="package-mapping" + content="my:com.example.myapp" />** </head> <body> <vaadin-vertical-layout> - <vaadin-label><b>Hello!</b> - How are you?</vaadin-label> + <vaadin-label><b>Hello!</b> - + How are you?</vaadin-label> <!-- Use it here --> **<my-example-component/>** @@ -221,12 +219,9 @@ Some attribute names are given by a shorthand. For example, you would set with [methodname]#setAlternateText()#, is given as the [literal]#++alt++# attribute. -Boolean values must be either " [literal]#++true++#" or " [literal]#++false++#". -The value can be omitted, in which case [literal]#++true++# is assumed. For -example, the [literal]#++enabled++# attribute is boolean and has default value " -[literal]#++true++#", so [literal]#++enabled="true"++# and -[literal]#++enabled++# and equivalent. - +Boolean values must be either `true` or `false`. +The value can be omitted, in which case `true` is assumed. +For example, the [literal]#++enabled++# attribute is boolean and has default value "`true`", so `enabled="true"` and `enabled` and equivalent. [source, html] ---- @@ -317,7 +312,7 @@ For example, the following class could be used to bind the design given earlier. public class MyViewDesign extends VerticalLayout { Tree mytree; Table mytable; - + public MyViewDesign() { Design.read("MyDeclarativeUI.html", this); @@ -326,7 +321,7 @@ public class MyViewDesign extends VerticalLayout { TreeExample.createTreeContent()); mytable.setContainerDataSource( TableExample.generateContent()); - + // Some interaction mytree.addItemClickListener(event -> // Java 8 Notification.show("Selected " + @@ -391,8 +386,3 @@ navigator.addView(MAINVIEW, new MainView()); See <> for a complete example. - - - - - diff --git a/documentation/application/application-environment.asciidoc b/documentation/application/application-environment.asciidoc index 8907222a24..0322c77e4a 100644 --- a/documentation/application/application-environment.asciidoc +++ b/documentation/application/application-environment.asciidoc @@ -25,9 +25,9 @@ that form an application. Such a Java web application is typically packaged as a WAR package for deployment. Server-side Vaadin UIs run as servlets within such a Java web application. There exists also other kinds of web applications. To avoid confusion with the general meaning of "web application", we often refer to -Java web applications with the slight misnomer "WAR" in this book.//TODO Vaadin -7: What is the relationship between servlet and -application? +Java web applications with the slight misnomer "WAR" in this book. + +// TODO Vaadin 7: What is the relationship between servlet and application? [[application.environment.war-eclipse]] == Creating Deployable WAR in Eclipse @@ -35,41 +35,34 @@ application? To deploy an application to a web server, you need to create a WAR package. Here we give the instructions for Eclipse. -. Select "File > Export" and then "Web > WAR File". Or, right-click the project in -the Project Explorer and select "Web > WAR File". +. Select "File > Export" and then "Web > WAR File". Or, right-click the project in the Project Explorer and select "Web > WAR File". -. Select the [guilabel]#Web project# to export. Enter [guilabel]#Destination# file -name ( [filename]#.war#). +. Select the [guilabel]#Web project# to export. Enter [guilabel]#Destination# file name ([filename]#.war#). . Make any other settings in the dialog, and click [guibutton]#Finish#. - - [[application.environment.war]] == Web Application Contents The following files are required in a web application in order to run it. -[filename]#WEB-INF/web.xml# (optional with Servlet 3.0):: This is the web application descriptor that defines how the application is -organized, that is, what servlets and such it has. You can refer to any Java -book about the contents of this file. It is not needed if you define the Vaadin -servlet with the [literal]#++@WebServlet++# annotation in Servlet API 3.0. - -[filename]#WEB-INF/lib/*.jar# :: These are the Vaadin libraries and their dependencies. They can be found in the -installation package or as loaded by a dependency management system such as -Maven or Ivy. - -Your UI classes:: You must include your UI classes either in a JAR file in [filename]#WEB-INF/lib# -or as classes in [filename]#WEB-INF/classes# - -Your own theme files (OPTIONAL):: If your application uses a special theme (look and feel), you must include it in -[filename]#VAADIN/themes/themename# directory. +[filename]#WEB-INF/web.xml# (optional with Servlet 3.0):: + his is the web application descriptor that defines how the application is rganized, that is, what servlets and such it has. +You can refer to any Java book about the contents of this file. +It is not needed if you define the Vaadin servlet with the [classname]#@WebServlet# annotation in Servlet API 3.0. -Widget sets (OPTIONAL):: If your application uses a project-specific widget set, it must be compiled in -the [filename]#VAADIN/widgetset/# directory. +[filename]#WEB-INF/lib/*.jar# :: +These are the Vaadin libraries and their dependencies. +They can be found in the installation package or as loaded by a dependency management system such as Maven or Ivy. +Your UI classes:: +You must include your UI classes either in a JAR file in [filename]#WEB-INF/lib# or as classes in [filename]#WEB-INF/classes# +Your own theme files (OPTIONAL):: +If your application uses a special theme (look and feel), you must include it in [filename]#VAADIN/themes/themename# directory. +Widget sets (OPTIONAL):: +If your application uses a project-specific widget set, it must be compiled in the [filename]#VAADIN/widgetset/# directory. [[application.environment.webservlet]] == Web Servlet Class diff --git a/documentation/architecture/architecture-overview.asciidoc b/documentation/architecture/architecture-overview.asciidoc index 4ff34c453c..9307b7b72c 100644 --- a/documentation/architecture/architecture-overview.asciidoc +++ b/documentation/architecture/architecture-overview.asciidoc @@ -63,7 +63,7 @@ User Interface Components/Widgets:: ((("component"))) ((("field"))) The user interface of a Vaadin application consists of components that are created and laid out by the application. Each server-side component has a -client-side counterpart, a " __widget__", by which it is rendered in the browser +client-side counterpart, a __widget__, by which it is rendered in the browser and with which the user interacts. The client-side widgets can also be used by client-side applications. The server-side components relay these events to the application logic. Field components that have a value, which the user can view @@ -155,8 +155,3 @@ run in the same servlet as the UI code, usually separated at least by a Java API, possibly as EJBs, or distributed to a remote back-end service. The data storage is usually distributed to a database management system, and is typically accessed through a persistence solution, such as JPA. - - - - - diff --git a/documentation/getting-started/getting-started-environment.asciidoc b/documentation/getting-started/getting-started-environment.asciidoc index 118742be38..457cf524ab 100644 --- a/documentation/getting-started/getting-started-environment.asciidoc +++ b/documentation/getting-started/getting-started-environment.asciidoc @@ -63,8 +63,6 @@ link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[http://w . Install the Java SDK by running the installer. The default options are fine. - - [[getting-started.environment.linux]] === Linux / UNIX @@ -83,12 +81,11 @@ link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[http://w . Decompress it under a suitable base directory, such as [filename]#/opt#. For example, for Java SDK, enter (either as root or with [command]#sudo# in Linux): - + [subs="normal"] ---- [prompt]#+++#+++# [command]#cd# [replaceable]#/opt# -[prompt]#+++#+++# [command]#sh# [replaceable]#(path-to-installation-package)/jdk-8u20-linux-x64.bin# +[prompt]#+++#+++# [command]#sh# [replaceable]####/jdk-[replaceable]####.bin ---- + and follow the instructions in the installer. @@ -99,10 +96,9 @@ installation directory. Also, include the [literal]#++$JAVA_HOME/bin++# in the Linux and using the Bash shell, you would add lines such as the following to the [filename]#.bashrc# or [filename]#.profile# script in your home directory: - + ---- -export JAVA_HOME=/opt/jdk1.8.0_20 +export JAVA_HOME=/opt/jdk1.8.0_31 export PATH=$PATH:$HOME/bin:$JAVA_HOME/bin ---- + @@ -117,8 +113,6 @@ window. Settings done in a [filename]#profile# file require that you log in into the system. You can, of course, also give the commands in the current shell. - - [[getting-started.environment.eclipse]] == Installing Eclipse IDE @@ -133,15 +127,15 @@ decompress the ZIP file by just double-clicking it and selecting "Extract all files" task from Windows compressed folder task. In our installation example, we use [filename]#C:\dev# as the target directory. - -Eclipse is now installed in [filename]#C:\dev\eclipse# and can be started from -there (by double clicking eclipse.exe). - +Eclipse is now installed in [filename]#C:\dev\eclipse#. +You can start it from there by double clicking [filename]#eclipse.exe#. === Linux / OS X / UNIX -We recommend that you install Eclipse manually in Linux and other UNIX variants -as follows. +We recommend that you install Eclipse manually in Linux and other UNIX variants. +They may have it available from a package repository, but using such an installation may cause problems with installing plug-ins. + +You can install Eclipse as follows: . Download Eclipse IDE for Java EE Developers from link:http://www.eclipse.org/downloads/[http://www.eclipse.org/downloads/] @@ -150,15 +144,14 @@ link:http://www.eclipse.org/downloads/[http://www.eclipse.org/downloads/] to make sure that there is no old Eclipse installation in the target directory. Installing a new version on top of an old one probably renders Eclipse unusable. -. Eclipse should normally be installed as a regular user, as this makes -installation of plugins easier. Eclipse also stores some user settings in the -installation directory. To install the package, enter: - - +. Eclipse should normally be installed as a regular user, which makes installation of plug-ins easier. +Eclipse also stores some user settings in the installation directory. ++ +To install the package, enter: + [subs="normal"] ---- -[prompt]#$# [command]#tar# zxf [replaceable]#(path-to-installation-package)/eclipse-jee-ganymede-SR2-linux-gtk.tar.gz# +[prompt]#$# [command]#tar# zxf [replaceable]####/eclipse-jee-[replaceable]####.tar.gz ---- + This will extract the package to a subdirectory with the name @@ -231,8 +224,3 @@ on an element and select [guilabel]#Inspect Element with Firebug# to inspect it. In addition to HTML tree, it also shows the CSS rules matching the element, which you can use for building themes. You can even edit the CSS styles live, to experiment with styling. - - - - - diff --git a/documentation/getting-started/getting-started-first-project.asciidoc b/documentation/getting-started/getting-started-first-project.asciidoc index cc8be595e1..8f2eff5a3c 100644 --- a/documentation/getting-started/getting-started-first-project.asciidoc +++ b/documentation/getting-started/getting-started-first-project.asciidoc @@ -164,7 +164,7 @@ project hierarchy shown in the Project Explorer is shown in [[figure.getting-started.first-project.exploring]] .A New Vaadin Project -image::img/myproject-ivy-created.png[] +image::img/myproject-ivy-created.png[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 @@ -361,7 +361,7 @@ server-side development. [[figure.getting-started.first-project.coding.import]] .Importing Classes Automatically -image::img/codingtips-automaticimports.png[] +image::img/codingtips-automaticimports.png[scaledwidth=80%] [[getting-started.first-project.server]] == Setting Up and Starting the Web Server @@ -377,22 +377,28 @@ 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". + +. 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 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#. + +. 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#. + +. 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. + +. 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#. ++ 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/. + +. 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]] @@ -410,13 +416,12 @@ 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. +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[] -Above, we described how to debug a server-side application. Debugging -client-side applications and widgets is described in -<>. +Above, we described how to debug a server-side application. +Debugging client-side applications and widgets is described in +<>. diff --git a/documentation/getting-started/getting-started-idea.asciidoc b/documentation/getting-started/getting-started-idea.asciidoc index 4461d80656..c0961dc534 100644 --- a/documentation/getting-started/getting-started-idea.asciidoc +++ b/documentation/getting-started/getting-started-idea.asciidoc @@ -31,17 +31,14 @@ used application servers. In the following, we configure Apache Tomcat: . Download and extract Tomcat installation package to a local directory, as -instructed in -<>. +instructed in <>. . Select "Configure > Settings". . Select "IDE Settings > Application Servers". -. Select "+ > Tomcat Server" to add a Tomcat server, or any of the other supported -servers. A WebSocket-enabled server, such as Glassfish or TomEE, is required for -server push. +. Click [guibutton]#+# and select [guilabel]#Tomcat Server# to add a Tomcat server, or any of the other supported servers. +A WebSocket-enabled server, such as Glassfish or TomEE, is required for server push. . In the Tomcat Server dialog, specify the home directory for the server. @@ -140,15 +137,16 @@ server using a run/debug configuration. . Select [menuchoice]#New Project# . In the [guilabel]#New Project# window, select [menuchoice]#Maven# - //<?dbfo-need height="8cm" ?> -. Enter a project name, location, and the Java SDK to be used for the project. -Vaadin requires at least Java 6. Click [guibutton]#Next#. +. Enter a project name, location, and the Java SDK to be used for the project. +Vaadin requires at least Java 6. + image::img/idea-maven-newproject-1.png[] - ++ +Click [guibutton]#Next#. //<?dbfo-need height="6cm" ?> + . Give a Maven [guilabel]#GroupID#, [guilabel]#ArtifactID#, and a [guilabel]#Version# for the project, or use the defaults. @@ -156,8 +154,8 @@ image::img/idea-maven-newproject-1.png[] image::img/idea-maven-newproject-2.png[] . Check [guilabel]#Create from archetype# - //<?dbfo-need height="6cm" ?> + . If the Vaadin archetype is not in the list, click [guibutton]#Add archetype#, enter [guilabel]#GroupId# [literal]#++com.vaadin++#, [guilabel]#ArtifactId# [literal]#++vaadin-archetype-application++#, and [guilabel]#Version# @@ -170,8 +168,8 @@ endif::web[] + Click [guibutton]#OK# in the dialog. - //<?dbfo-need height="8cm" ?> + . Select the [literal]#++com.vaadin:vaadin-archetype-application++#. ifdef::web[] @@ -181,17 +179,17 @@ endif::web[] + Click [guibutton]#Next#. - //<?dbfo-need height="8cm" ?> -. Review the general Maven settings and settings for the new project. You may need -to override the settings, especially if you are creating a Maven project for the -first time. Click [guibutton]#Finish#. + +. Review the general Maven settings and settings for the new project. +You may need to override the settings, especially if you are creating a Maven project for the first time. ifdef::web[] + image::img/idea-maven-newproject-5.png[] endif::web[] - ++ +Click [guibutton]#Finish#. Creating the Maven project takes some time as Maven fetches the dependencies. Once done, the project is created and the Maven POM is opened in the editor. @@ -226,11 +224,10 @@ launch a Vaadin Maven application on the light-weight Jetty web server. . Select "Run > Edit Configurations". -. Select "+ > Maven" to create a new Maven run/debug configuration. +. Click [guibutton]#+# and select menu:Maven[] to create a new Maven run/debug configuration. -. Enter a [guilabel]#Name# for the run configuration. For the [guilabel]#Command -line#, enter " [literal]#++package jetty:run++# to first compile and package the -project, and then launch Jetty to run it. +. Enter a [guilabel]#Name# for the run configuration. +For the [guilabel]#Command line#, enter "`package jetty:run`# to first compile and package the project, and then launch Jetty to run it. ifdef::web[] + @@ -253,8 +250,3 @@ Compiling the project takes some time on the first time, as it compiles the widget set and theme. Once the run console pane informs that Jetty Server has been started, you can open the browser at the default URL http://localhost:8080/. - - - - - diff --git a/documentation/getting-started/getting-started-maven.asciidoc b/documentation/getting-started/getting-started-maven.asciidoc index 3914e973aa..2845e92ab5 100644 --- a/documentation/getting-started/getting-started-maven.asciidoc +++ b/documentation/getting-started/getting-started-maven.asciidoc @@ -21,6 +21,10 @@ link:https://github.com/johndevs/gradle-vaadin-plugin[Gradle Vaadin Plugin]. Vaadin Plugin for Eclipse uses Ivy for resolving dependencies in Vaadin projects, and it should provide you with the basic Ivy configuration. +For an interactive guide, see the instructions at link:https://vaadin.com/maven[vaadin.com/maven]. +It automatically generates you the command to create a new project based on archetype selection. +It can also generate dependency declarations for Vaadin dependencies. + [[getting-started.maven.command-line]] == Working from Command-Line @@ -31,7 +35,7 @@ line): ---- [prompt]#$# [command]#mvn# archetype:generate \ -DarchetypeGroupId=com.vaadin \ - -DarchetypeArtifactId=[parameter]#vaadin-archetype-application# \ + -DarchetypeArtifactId=[replaceable]#vaadin-archetype-application# \ -DarchetypeVersion=[replaceable]#7.x.x# \ -DgroupId=[replaceable]#your.company# \ -DartifactId=[replaceable]#project-name# \ @@ -43,17 +47,32 @@ The parameters are as follows: [parameter]#archetypeGroupId#:: The group ID of the archetype is [literal]#++com.vaadin++# for Vaadin archetypes. -[parameter]#archetypeArtifactId#:: The archetype ID. Vaadin 7 currently supports -[literal]#++vaadin-archetype-application++# archetype for server-side -applications and [literal]#++vaadin-archetype-widget++# for client-side widget -development projects. - -+ -//TODO Vaadin 7: Not all these archetypes are supported -+ -//// -<itemizedlist> <listitem> <literal>vaadin-archetype-clean</literal> is a new project with a barebone skeleton for a regular Vaadin application. The <filename>pom.xml</filename> includes out-commented definitions for additional widgets. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-widget</literal> is a skeleton for a project with custom widgets. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-sample</literal> is also for a project with custom widgets, but the skeleton includes the Color Picker example used in <xref linkend="gwt"/>. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-addon</literal> is for Vaadin add-on projects. It packages the add-on so that it can be published in Vaadin Directory. The archetype is for server-side add-ons and does not include definitions needed for building a widget set. If your add-on includes or requires other than the widgets in the Vaadin core library, you need to copy the required definitions from a POM of a <literal>vaadin-archetype-clean</literal> project. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-touchkit</literal> is for projects using Vaadin TouchKit, described in <xref linkend="mobile"/>. Notice that this archetype uses the AGPL-licensed version of TouchKit, which requires that your project must also be licensed under the AGPL license. </listitem> </itemizedlist> -//// +[parameter]#archetypeArtifactId#:: The archetype ID. +Vaadin 7 currently supports the following archetypes: + +`vaadin-archetype-application`;; +A single-module project for simple applications. +Good for quick demos and trying out Vaadin. + +`vaadin-archetype-application-multimodule`;; +A complete Vaadin application development setup. +It features separate production and development profiles. + +`vaadin-archetype-application-example`;; +An example CRUD web application using multi-module project setup. + +`vaadin-archetype-widget`;; +A multi-module project for a new Vaadin add-on. +It has two modules: one for the add-on and another for a demo application. + +`vaadin-archetype-touchkit`;; +A mobile development starter project using Vaadin TouchKit. +See <>. +Notice that this archetype uses the AGPL-licensed version of TouchKit, which requires that your project must also be licensed under the AGPL license. + +`vaadin-archetype-liferay-portlet`;; +A portlet development setup for the open-source Liferay portal. + [parameter]#archetypeVersion#:: Version of the archetype to use. This should be [literal]#++LATEST++# for normal Vaadin releases. For prerelease versions it should be the exact version number, such as [literal]#++7.5.3++#. @@ -82,7 +101,7 @@ created project structure is shown in [[figure.getting-started.maven.archetype.created]] .A New Vaadin Project with Maven -image::img/maven-project-created.png[] +image::img/maven-project-created.png[scaledwidth=60%] [[getting-started.maven.compiling]] @@ -129,5 +148,3 @@ Maven Project">>. (((range="endofrange", startref="term.maven.addons"))) (((range="endofrange", startref="term.maven.creating"))) - - diff --git a/documentation/getting-started/getting-started-package.asciidoc b/documentation/getting-started/getting-started-package.asciidoc index 4dbe735958..9dd7ec81be 100644 --- a/documentation/getting-started/getting-started-package.asciidoc +++ b/documentation/getting-started/getting-started-package.asciidoc @@ -7,9 +7,7 @@ layout: page [[getting-started.package]] = Vaadin Installation Package -While the recommended way to install Vaadin is to use the Eclipse plugin, one of -the other IDE plugins, or a dependency management system, such as Maven, Vaadin -is also available as a ZIP distribution package. +While the recommended way to create a Vaadin project and install the libraries is to use an IDE plugin or a dependency management system, such as Maven, Vaadin is also available as a ZIP distribution package. You can download the newest Vaadin installation package from the download page at http://vaadin.com/download/. Please use a ZIP decompression utility available @@ -18,23 +16,17 @@ in your operating system to extract the files from the ZIP package. [[getting-started.package.contents]] == Package Contents -[filename]#README.TXT#:: This Readme file gives simple instructions for installing Vaadin in your -project. +[filename]#README.TXT#:: This README file gives simple instructions for installing Vaadin in your project. -[filename]#release-notes.html#:: The Release Notes contain information about the new features in the particular -release, give upgrade instructions, describe compatibility, etc. Please open the -HTML file with a web browser. +[filename]#release-notes.html#:: The Release Notes contain information about the new features in the particular release, give upgrade instructions, describe compatibility, etc. +Please open the HTML file with a web browser. -[filename]#license.html#:: Apache License version 2.0. Please open the HTML file with a web browser. - -[filename]#lib#folder:: All dependency libraries required by Vaadin are contained within the -[filename]#lib# folder. - -[filename]#*.jar#:: Vaadin libraries, as described in -<>. +[filename]#license.html#:: Apache License version 2.0. +Please open the HTML file with a web browser. +[filename]#lib# folder:: All dependency libraries required by Vaadin are contained within the [filename]#lib# folder. +[filename]#*.jar#:: Vaadin libraries, as described in <>. [[getting-started.package.install]] @@ -58,8 +50,3 @@ organization, which depends on the development environment. * In Eclipse Dynamic Web Application projects: [filename]#WebContent/WEB-INF/lib#. * In Maven projects: [filename]#src/main/webapp/WEB-INF/lib#. - - - - - diff --git a/documentation/getting-started/img/myproject-created-annotated-hi.png b/documentation/getting-started/img/myproject-created-annotated-hi.png index c2d9a49221..6927b883ed 100644 Binary files a/documentation/getting-started/img/myproject-created-annotated-hi.png and b/documentation/getting-started/img/myproject-created-annotated-hi.png differ diff --git a/documentation/getting-started/original-drawings/myproject-created-annotated.svg b/documentation/getting-started/original-drawings/myproject-created-annotated.svg index b639c5f160..70fc378bdc 100644 --- a/documentation/getting-started/original-drawings/myproject-created-annotated.svg +++ b/documentation/getting-started/original-drawings/myproject-created-annotated.svg @@ -72,8 +72,8 @@ inkscape:pageopacity="0.0" inkscape:pageshadow="2" inkscape:zoom="1.4" - inkscape:cx="236.02753" - inkscape:cy="570.52264" + inkscape:cx="191.07987" + inkscape:cy="356.49384" inkscape:document-units="px" inkscape:current-layer="layer1" inkscape:window-width="1920" @@ -101,7 +101,7 @@ spacingy="5px" /> The UI class skeleton + d="m 34.165936,419.09448 a 9.1659365,9.1659365 0 1 1 -18.331872,0 9.1659365,9.1659365 0 1 1 18.331872,0 z" + transform="matrix(0.54549827,0,0,0.54549827,31.362543,498.74687)" /> The widget set The theme Maven project configuration Project README skeleton diff --git a/documentation/introduction/intro-eclipse.asciidoc b/documentation/introduction/intro-eclipse.asciidoc index b2fb127f7b..09a8c50570 100644 --- a/documentation/introduction/intro-eclipse.asciidoc +++ b/documentation/introduction/intro-eclipse.asciidoc @@ -9,32 +9,24 @@ layout: page While Vaadin is not bound to any specific IDE, and you can in fact easily use it without any IDE altogether, we provide special support for the Eclipse IDE, -which has become the most used environment for Java development. The support is -provided in the Vaadin Plugin for Eclipse, which helps you in: +which has become the most used environment for Java development. -* Creating new Vaadin projects +*_Vaadin Plug-in for Eclipse_* helps you in: -* Creating custom themes +* creating new Vaadin projects, -* Creating custom client-side widgets +* creating custom themes, -* Easily upgrading to a newer version of the Vaadin library +* creating custom client-side widgets, and +* easily upgrading to a newer version of the Vaadin library. -Using the Vaadin Plugin for Eclipse is the recommended way of installing Vaadin -for development. Downloading the installation package that contains the JARs or -defining Vaadin as a Maven dependency is also possible. - -Installing and updating the Eclipse plugin is covered in -<> and the creation of a new Vaadin project using the plugin -in -<>. See -<> and -<> for instructions on using the different features of the plugin. - +Using the Vaadin plug-in for Eclipse is the recommended way of installing Vaadin for development. +Downloading the installation package that contains the JARs or defining Vaadin as a Maven dependency is also possible. +*_Vaadin Designer_* is a commercial Eclipse plug-in that enables visual editing of Vaadin UIs and composites. +See <> for its complete reference. +Installation of the Eclipse plug-in is covered in <>. +The creation of a new Vaadin project using the plug-in is covered in <>. +See <> and <> for instructions on using the different features of the plug-in. diff --git a/documentation/introduction/intro-goals.asciidoc b/documentation/introduction/intro-goals.asciidoc index 0972a998cf..e2173b0875 100644 --- a/documentation/introduction/intro-goals.asciidoc +++ b/documentation/introduction/intro-goals.asciidoc @@ -31,14 +31,13 @@ frameworks and ensuring that our implementation represents an ideal solution for its purpose without clutter or bloat. -== XML is not designed for programming - -The Web is inherently document-centered and very much bound to the declarative -presentation of user interfaces. While Vaadin allows for declarative designs of -views, layouts, and even entire UIs, the programmatic approach by building the -UIs from Java components frees the programmer from these limitations. To create -highly dynamic views, it is more natural to create them by programming. +== Choice between declarative and dynamic UIs +The Web is inherently document-centered and very much bound to the declarative presentation of user interfaces. +Vaadin allows for declarative designs of views, layouts, and even entire UIs. +Vaadin Designer enables creating such designs visually. +Nevertheless, the programmatic approach by building the UIs from Java components frees the programmer from its limitations. +To create highly dynamic views, it is more natural to create them by programming. == Tools should not limit your work @@ -47,7 +46,3 @@ some reason the user interface components do not support what you need to achieve, it must be easy to add new ones to your application. When you need to create new components, the role of the framework is critical: it makes it easy to create re-usable components that are easy to maintain. - - - - diff --git a/documentation/introduction/intro-walkthrough.asciidoc b/documentation/introduction/intro-walkthrough.asciidoc index 218e76b337..152817c0ed 100644 --- a/documentation/introduction/intro-walkthrough.asciidoc +++ b/documentation/introduction/intro-walkthrough.asciidoc @@ -8,8 +8,8 @@ layout: page = Example Application Walkthrough Let us follow the long tradition of first saying "Hello World!" when learning a -new programming framework. First, using the primary server-side API. - +new programming framework. +First, using the primary server-side API. [source, java] ---- @@ -29,7 +29,7 @@ public class HelloWorld extends UI { // Display the greeting content.addComponent(new Label("Hello World!")); - // Have a clickable button + // Have a clickable button content.addComponent(new Button("Push Me!", new ClickListener() { @Override @@ -77,7 +77,7 @@ The result of the Hello World application, when opened in a browser, is shown in [[figure.intro.walkthrough]] .Hello World Application -image::img/HelloWorld.png[] +image::img/HelloWorld.png[scaledwidth=70%] To run a program, you need to package it as a web application WAR package and deploy it to a server, as explained in @@ -106,6 +106,3 @@ to write client-side widgets, which you can then use from a server-side Vaadin application. For more information regarding client-side development, see <>. - - - diff --git a/documentation/themes/themes-fonticon.asciidoc b/documentation/themes/themes-fonticon.asciidoc index 624220fa05..2335417daf 100644 --- a/documentation/themes/themes-fonticon.asciidoc +++ b/documentation/themes/themes-fonticon.asciidoc @@ -21,16 +21,14 @@ automatically enabled in the Valo theme. For other themes, you need to include it with the following line in your project theme, after importing the base theme: - ---- @include fonticons; ---- If you use other icon fonts, as described in <>, and the font is not loaded by a base theme, you need to load it with a -[literal]#++font++# mixin in Sass, as described in -<>. +`font` mixin in Sass, as described in +<>. [[themes.fonticon.using]] @@ -46,7 +44,7 @@ of all the icons included in the font. Most typically, you set a component icon as follows: - +[source, Java] ---- TextField name = new TextField("Name"); name.setIcon(FontAwesome.USER); @@ -73,7 +71,6 @@ As font icons are regular text, you can specify their color with the HTML elements that display icons in Vaadin have the [literal]#++v-icon++# style name. - ---- .v-icon { color: blue; @@ -84,14 +81,13 @@ If you use the font icon resources in other ways, such as in an [classname]#Image# component, the style name will be different. - [[themes.fonticon.html]] == Using Font icons in HTML You can use font icons in HTML code, such as in a [classname]#Label#, by generating the HTML to display the icon with the [methodname]#getHtml()# method. - +[source, Java] ---- Label label = new Label("I " + FontAwesome.HEART.getHtml() + " Vaadin", @@ -101,9 +97,9 @@ layout.addComponent(label); ---- See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.html[on-line example, window="_blank"]. -The HTML code has the [literal]#++v-icon++# style, which you can modify in CSS: - +The HTML code has the [stylename]#v-icon# style, which you can modify in CSS: +[source, css] ---- .redicon .v-icon { color: red; @@ -111,10 +107,11 @@ The HTML code has the [literal]#++v-icon++# style, which you can modify in CSS: ---- See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.html[on-line example, window="_blank"]. -The result is illustrated in <>, with the color +The result is illustrated in <>, with the color styling described next. -[[figure.themes.fonticon.html]] +// The ID may not end in ".html" +[[figure.themes.fonticon-html.label]] .Using Font Icons in Label image::img/fonticons-html.png[] @@ -126,7 +123,6 @@ to use the correct font family and then use the hex-formatted Unicode codepoint for the icon. See for example the implementation of the [methodname]#getHtml()# method in [classname]#FontAwesome#: - ---- @Override public String getHtml() { @@ -212,30 +208,30 @@ using a normal sans-serif font built-in in the browser. // Font icon definition with a single symbol public enum MyFontIcon implements FontIcon { EURO(0x20AC); - + private int codepoint; - + MyFontIcon(int codepoint) { this.codepoint = codepoint; } - + @Override public String getMIMEType() { throw new UnsupportedOperationException( FontIcon.class.getSimpleName() + " should not be used where a MIME type is needed."); } - + @Override public String getFontFamily() { return "sans-serif"; } - + @Override public int getCodepoint() { return codepoint; } - + @Override public String getHtml() { return " Date: Thu, 17 Mar 2016 15:58:58 +0200 Subject: Reorganized the Getting Started chapter to separate installation and project creation chapters. #19639 Change-Id: I4aab29b8b9ab23091903016e9cc91850c4ca3b93 --- documentation/advanced/advanced-debug.asciidoc | 7 +- .../chapter-getting-started.asciidoc | 12 +- .../getting-started-archetypes.asciidoc | 34 + .../getting-started-eclipse.asciidoc | 148 - .../getting-started-environment.asciidoc | 226 - .../getting-started-first-project.asciidoc | 73 +- .../getting-started/getting-started-idea.asciidoc | 74 +- .../getting-started-libraries.asciidoc | 97 +- .../getting-started/getting-started-maven.asciidoc | 14 +- .../getting-started-netbeans.asciidoc | 103 +- .../getting-started/getting-started-overview.adoc | 22 + .../getting-started-overview.asciidoc | 30 - .../getting-started-package.asciidoc | 2 +- .../getting-started/getting-started-scala.asciidoc | 2 +- documentation/getting-started/img/firebug.png | Bin 59376 -> 0 bytes .../getting-started/img/idea-server-1.png | Bin 10365 -> 0 bytes .../getting-started/img/idea-server-2.png | Bin 36365 -> 0 bytes .../getting-started/img/installation-steps-hi.png | Bin 65439 -> 0 bytes .../img/netbeans-created-annotated-hi.png | Bin 0 -> 99367 bytes .../getting-started/img/netbeans-newproject-1.png | Bin 0 -> 55377 bytes .../getting-started/img/netbeans-newproject-2.png | Bin 0 -> 49508 bytes .../img/netbeans-newproject-created.png | Bin 0 -> 22317 bytes .../getting-started/img/netbeans-server.png | Bin 0 -> 27387 bytes .../getting-started/img/plugin-install-addsite.png | Bin 14375 -> 0 bytes .../img/plugin-install-available.png | Bin 52009 -> 0 bytes documentation/getting-started/img/toolchain-hi.png | Bin 227400 -> 0 bytes documentation/getting-started/img/toolchain-lo.png | Bin 58261 -> 0 bytes .../getting-started/original-drawings/Makefile | 2 +- .../installation-steps-constellation.svg | 7259 -------------------- .../original-drawings/installation-steps.svg | 664 -- .../netbeans-created-annotated.svg | 324 + .../original-drawings/toolchain.svg | 1149 ---- .../installing/chapter-installing.asciidoc | 20 + documentation/installing/img/firebug.png | Bin 0 -> 59376 bytes documentation/installing/img/idea-server-1.png | Bin 0 -> 10365 bytes documentation/installing/img/idea-server-2.png | Bin 0 -> 36365 bytes .../installing/img/installation-eclipse-hi.png | Bin 0 -> 64185 bytes .../installing/img/installation-netbeans-hi.png | Bin 0 -> 34582 bytes .../installing/img/installation-steps-hi.png | Bin 0 -> 65439 bytes .../installing/img/installing-netbeans-1.png | Bin 0 -> 49371 bytes .../installing/img/installing-netbeans-2.png | Bin 0 -> 75999 bytes .../installing/img/installing-netbeans-3.png | Bin 0 -> 41441 bytes .../installing/img/installing-netbeans-4.png | Bin 0 -> 40150 bytes .../installing/img/installing-netbeans-5.png | Bin 0 -> 47869 bytes .../img/installing-netbeans-plugin-1.png | Bin 0 -> 52690 bytes .../img/installing-netbeans-plugin-2.png | Bin 0 -> 21920 bytes .../img/installing-netbeans-plugin-3.png | Bin 0 -> 35024 bytes .../installing/img/plugin-install-addsite.png | Bin 0 -> 14375 bytes .../installing/img/plugin-install-available.png | Bin 0 -> 52009 bytes documentation/installing/img/toolchain-hi.png | Bin 0 -> 227400 bytes documentation/installing/img/toolchain-lo.png | Bin 0 -> 58261 bytes documentation/installing/installing-eclipse.adoc | 135 + documentation/installing/installing-idea.asciidoc | 54 + documentation/installing/installing-java.adoc | 72 + .../installing/installing-netbeans.asciidoc | 112 + documentation/installing/installing-other.adoc | 38 + documentation/installing/installing-overview.adoc | 28 + documentation/installing/installing-server.adoc | 44 + documentation/installing/installing-toolchain.adoc | 41 + .../installing/original-drawings/Makefile | 13 + .../original-drawings/installation-eclipse.svg | 536 ++ .../original-drawings/installation-netbeans.svg | 334 + .../installation-steps-constellation.svg | 7259 ++++++++++++++++++++ .../original-drawings/installation-steps.svg | 664 ++ .../original-drawings/steps-constellation.png | Bin 0 -> 55123 bytes .../original-drawings/steps-constellation.svg | 6812 ++++++++++++++++++ .../installing/original-drawings/toolchain.svg | 1149 ++++ documentation/introduction/intro-eclipse.asciidoc | 4 +- 68 files changed, 17898 insertions(+), 9659 deletions(-) create mode 100644 documentation/getting-started/getting-started-archetypes.asciidoc delete mode 100644 documentation/getting-started/getting-started-eclipse.asciidoc delete mode 100644 documentation/getting-started/getting-started-environment.asciidoc create mode 100644 documentation/getting-started/getting-started-overview.adoc delete mode 100644 documentation/getting-started/getting-started-overview.asciidoc delete mode 100644 documentation/getting-started/img/firebug.png delete mode 100644 documentation/getting-started/img/idea-server-1.png delete mode 100644 documentation/getting-started/img/idea-server-2.png delete mode 100644 documentation/getting-started/img/installation-steps-hi.png create mode 100644 documentation/getting-started/img/netbeans-created-annotated-hi.png create mode 100644 documentation/getting-started/img/netbeans-newproject-1.png create mode 100644 documentation/getting-started/img/netbeans-newproject-2.png create mode 100644 documentation/getting-started/img/netbeans-newproject-created.png create mode 100644 documentation/getting-started/img/netbeans-server.png delete mode 100644 documentation/getting-started/img/plugin-install-addsite.png delete mode 100644 documentation/getting-started/img/plugin-install-available.png delete mode 100644 documentation/getting-started/img/toolchain-hi.png delete mode 100644 documentation/getting-started/img/toolchain-lo.png delete mode 100644 documentation/getting-started/original-drawings/installation-steps-constellation.svg delete mode 100644 documentation/getting-started/original-drawings/installation-steps.svg create mode 100644 documentation/getting-started/original-drawings/netbeans-created-annotated.svg delete mode 100644 documentation/getting-started/original-drawings/toolchain.svg create mode 100644 documentation/installing/chapter-installing.asciidoc create mode 100644 documentation/installing/img/firebug.png create mode 100644 documentation/installing/img/idea-server-1.png create mode 100644 documentation/installing/img/idea-server-2.png create mode 100644 documentation/installing/img/installation-eclipse-hi.png create mode 100644 documentation/installing/img/installation-netbeans-hi.png create mode 100644 documentation/installing/img/installation-steps-hi.png create mode 100644 documentation/installing/img/installing-netbeans-1.png create mode 100644 documentation/installing/img/installing-netbeans-2.png create mode 100644 documentation/installing/img/installing-netbeans-3.png create mode 100644 documentation/installing/img/installing-netbeans-4.png create mode 100644 documentation/installing/img/installing-netbeans-5.png create mode 100644 documentation/installing/img/installing-netbeans-plugin-1.png create mode 100644 documentation/installing/img/installing-netbeans-plugin-2.png create mode 100644 documentation/installing/img/installing-netbeans-plugin-3.png create mode 100644 documentation/installing/img/plugin-install-addsite.png create mode 100644 documentation/installing/img/plugin-install-available.png create mode 100644 documentation/installing/img/toolchain-hi.png create mode 100644 documentation/installing/img/toolchain-lo.png create mode 100644 documentation/installing/installing-eclipse.adoc create mode 100644 documentation/installing/installing-idea.asciidoc create mode 100644 documentation/installing/installing-java.adoc create mode 100644 documentation/installing/installing-netbeans.asciidoc create mode 100644 documentation/installing/installing-other.adoc create mode 100644 documentation/installing/installing-overview.adoc create mode 100644 documentation/installing/installing-server.adoc create mode 100644 documentation/installing/installing-toolchain.adoc create mode 100644 documentation/installing/original-drawings/Makefile create mode 100644 documentation/installing/original-drawings/installation-eclipse.svg create mode 100644 documentation/installing/original-drawings/installation-netbeans.svg create mode 100644 documentation/installing/original-drawings/installation-steps-constellation.svg create mode 100644 documentation/installing/original-drawings/installation-steps.svg create mode 100644 documentation/installing/original-drawings/steps-constellation.png create mode 100644 documentation/installing/original-drawings/steps-constellation.svg create mode 100644 documentation/installing/original-drawings/toolchain.svg (limited to 'documentation/getting-started') diff --git a/documentation/advanced/advanced-debug.asciidoc b/documentation/advanced/advanced-debug.asciidoc index 9731c650af..5415d0655e 100644 --- a/documentation/advanced/advanced-debug.asciidoc +++ b/documentation/advanced/advanced-debug.asciidoc @@ -143,8 +143,7 @@ properties. To view the HTML structure and CSS styles in more detail, you can use Firebug in Firefox, or the Developer Tools in Chrome, as described in -<>. Firefox also has a built-in feature for inspecting HTML and CSS. +<>. Firefox also has a built-in feature for inspecting HTML and CSS. [[advanced.debug.hierarchy.analyze]] @@ -208,7 +207,3 @@ The [guilabel]#Menu# tab in the window opens a sub-menu to select various settings. Here you can also launch the GWT SuperDevMode, as described in <>. - - - - diff --git a/documentation/getting-started/chapter-getting-started.asciidoc b/documentation/getting-started/chapter-getting-started.asciidoc index 9705f0a966..22397eb352 100644 --- a/documentation/getting-started/chapter-getting-started.asciidoc +++ b/documentation/getting-started/chapter-getting-started.asciidoc @@ -1,18 +1,16 @@ [[getting-started]] -== Getting Started with Vaadin +== Creating a Vaadin Application -This chapter gives practical instructions for installing the recommended -toolchain, the Vaadin libraries and its dependencies, and creating a new Vaadin -project. +This chapter gives practical instructions for creating a Vaadin application project and deploying it to a server to run it. We also consider topics such as debugging. +The instructions are given separately for the Eclipse IDE, NetBeans, and IntelliJ IDEA. -include::getting-started-overview.asciidoc[leveloffset=+2] -include::getting-started-environment.asciidoc[leveloffset=+2] +include::getting-started-overview.adoc[leveloffset=+2] include::getting-started-libraries.asciidoc[leveloffset=+2] -include::getting-started-eclipse.asciidoc[leveloffset=+2] +include::getting-started-archetypes.asciidoc[leveloffset=+2] include::getting-started-first-project.asciidoc[leveloffset=+2] diff --git a/documentation/getting-started/getting-started-archetypes.asciidoc b/documentation/getting-started/getting-started-archetypes.asciidoc new file mode 100644 index 0000000000..fbb75093e1 --- /dev/null +++ b/documentation/getting-started/getting-started-archetypes.asciidoc @@ -0,0 +1,34 @@ +--- +title: Maven Archetypes +order: 30 +layout: page +--- + +[[getting-started.archetypes]] += Overview of Maven Archetypes + +Vaadin currently offers the following Maven archetypes for different kinds of projects: + +`vaadin-archetype-application`:: +This is a single-module project for simple applications. +It is good for quick demos and trying out Vaadin. +It is also useful when you are experienced with Vaadin and want to build all the aspects of the application yourself. + +`vaadin-archetype-application-multimodule`:: +A complete Vaadin application development setup. +It features separate production and development profiles. + +`vaadin-archetype-application-example`:: +An example CRUD web application using multi-module project setup. + +`vaadin-archetype-widget`:: +A multi-module project for a new Vaadin add-on. +It has two modules: one for the add-on and another for a demo application. + +`vaadin-archetype-touchkit`:: +A mobile development starter project using Vaadin TouchKit. +See <>. +Notice that this archetype uses the AGPL-licensed version of TouchKit, which requires that your project must also be licensed under the AGPL license. + +`vaadin-archetype-liferay-portlet`:: +A portlet development setup for the open-source Liferay portal. diff --git a/documentation/getting-started/getting-started-eclipse.asciidoc b/documentation/getting-started/getting-started-eclipse.asciidoc deleted file mode 100644 index 5e10b560d7..0000000000 --- a/documentation/getting-started/getting-started-eclipse.asciidoc +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Vaadin Plugin for Eclipse -order: 4 -layout: page ---- - -[[getting-started.eclipse]] -= Vaadin Plugin for Eclipse - -If you are using the Eclipse IDE, using the Vaadin Plugin for Eclipse helps -greatly. The plugin includes wizards for creating new Vaadin-based projects, -themes, and client-side widgets and widget sets. Notice that you can also create -Vaadin projects as Maven projects in Eclipse. - -[[getting-started.eclipse.vaadin-plugin]] -== Installing the Vaadin Plugin - -You can install the plugin as follows: - -. Select "Help > Install New Software...". - -. Add the Vaadin plugin update site by clicking [guibutton]#Add...# button. - -+ -image::img/plugin-install-addsite.png[] - -+ -Enter a name such as "Vaadin Update Site" and the URL of the update site: -http://vaadin.com/eclipse. If you want or need to use the latest unstable -plugin, which is usually more compatible with development and beta releases of -Vaadin, you can use http://vaadin.com/eclipse/experimental and give it a -distinctive name such as "Vaadin Experimental Site". Then click [guibutton]#OK#. -The Vaadin site should now appear in the [guilabel]#Available Software# window. - -. Currently, if using the stable plugin, the [guilabel]#Group items by category# should be enabled. If using the experimental plugin, it should be disabled. This may change in future. -. Select all the Vaadin plugins in the tree. - -+ -image::img/plugin-install-available.png[] - -+ -Then, click [guibutton]#Next#. - -. Review the installation details and click [guibutton]#Next#. - -. Accept or unaccept the license. Finally, click [guibutton]#Finish#. - -. After the plugin is installed, Eclipse will ask to restart itself. Click -[guibutton]#Restart#. - - -More installation instructions for the Eclipse plugin can be found at -http://vaadin.com/eclipse. - - -[[getting-started.eclipse.update]] -== Updating the Plugins - -If you have automatic updates enabled in Eclipse (see "Window > Preferences > -Install/Update > Automatic Updates"), the Vaadin plugin will be updated -automatically along with other plugins. Otherwise, you can update the Vaadin -plugin manually as follows: - -. Select "Help > Check for Updates". Eclipse will contact the update sites of the -installed software. - -. After the updates are installed, Eclipse will ask to restart itself. Click -[guibutton]#Restart#. - - -Notice that updating the Vaadin plugin updates only the plugin and __not__ the -Vaadin libraries, which are project specific. See below for instructions for -updating the libraries. - - -[[getting-started.eclipse.mavenlibraryupdate]] -== Updating the Vaadin Libraries in Maven 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]#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. - -. If you have compiled the widget set for your project, recompile it by clicking -the [guibutton]#Compile Vaadin widgets# button in Eclipse toolbar. - -. 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". - - -[[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 [guibutton]#Compile Vaadin widgets# button in Eclipse toolbar. - -. 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. - - - - diff --git a/documentation/getting-started/getting-started-environment.asciidoc b/documentation/getting-started/getting-started-environment.asciidoc deleted file mode 100644 index 457cf524ab..0000000000 --- a/documentation/getting-started/getting-started-environment.asciidoc +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: Setting up the Development Environment -order: 2 -layout: page ---- - -[[getting-started.environment]] -= Setting up the Development Environment - -This section guides you step-by-step in setting up a reference development -environment. Vaadin supports a wide variety of tools, so you can use any IDE for -writing the code, almost any Java web server for deploying the application, most -web browsers for using it, and any operating system platform supported by Java. - -In this example, we use the following toolchain: - -* Windows, Linux, or Mac OS X -* link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[Oracle Java SE 8] (Java 6 or newer is required) -* link:http://www.eclipse.org/downloads/[Eclipse IDE for Java EE Developers] -* link:http://tomcat.apache.org/[Apache Tomcat 8.0 (Core)] -* link:http://www.getfirefox.com/[Mozilla Firefox] browser -* link:http://www.getfirebug.com/[Firebug] debug tool (optional) -* link:http://vaadin.com/download/[Vaadin Framework] - -The above reference toolchain is a good choice of tools, but you can use almost -any tools you are comfortable with. - -We recommend using Java 8 for Vaadin development, but you need to make sure that -your entire toolchain supports it. A server supporting Servlet 3.0 is -recommended. It is required for using Vaadin CDI, for which also a CDI container -is required, a standard feature in Java EE 6 or newer servers. It is also -required by the Vaadin Spring add-on. Server push can benefit from using -communication modes, such as WebSocket, enabled by features in some latest -servers. For Java EE containers, at least Wildfly, Glassfish, and Apache TomEE -Web Profile are recommended. - -[[figure.toolchain]] -.Development Toolchain and Process -image::img/toolchain-hi.png[] - -<> illustrates the development toolchain. You develop your -application as an Eclipse project. The project must include, in addition to your -source code, the Vaadin libraries. It can also include project-specific themes. - -You need to compile and deploy a project to a web container before you can use -it. You can deploy a project through the Web Tools Platform (WTP) for Eclipse -(included in the Eclipse EE package), which allows automatic deployment of web -applications from Eclipse. You can also deploy a project manually, by creating a -web application archive (WAR) and deploying it to the web container. - -[[getting-started.environment.java]] -== Installing Java SDK - -Java SDK is required by Vaadin and also by the Eclipse IDE. Vaadin is compatible -with Java 1.6 and later editions. Java EE 7 is required for proper server push -support with WebSockets. - -[[getting-started.environment.java.windows]] -=== Windows - -. Download Oracle Java SE 8.0 from -link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[http://www.oracle.com/technetwork/java/javase/downloads/index.html] - -. Install the Java SDK by running the installer. The default options are fine. - -[[getting-started.environment.linux]] -=== Linux / UNIX - -Most Linux systems either have JDK preinstalled or allow installing it through a -package management system. Notice however that they have OpenJDK as the default -Java implementation. While it is known to have worked with Vaadin and possibly -also with the development toolchain, we do not especially support it. - -Regarding OS X, notice that JDK 1.6 or newer is included in OS X 10.6 and newer. - -Otherwise: - -. Download Oracle Java SE 8.0 from -link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[http://www.oracle.com/technetwork/java/javase/downloads/] - -. Decompress it under a suitable base directory, such as [filename]#/opt#. For -example, for Java SDK, enter (either as root or with [command]#sudo# in Linux): - -+ -[subs="normal"] ----- -[prompt]#+++#+++# [command]#cd# [replaceable]#/opt# -[prompt]#+++#+++# [command]#sh# [replaceable]####/jdk-[replaceable]####.bin ----- -+ -and follow the instructions in the installer. - -. Set up the [literal]#++JAVA_HOME++# environment variable to point to the Java -installation directory. Also, include the [literal]#++$JAVA_HOME/bin++# in the -[literal]#++PATH++#. How you do that varies by the UNIX variant. For example, in -Linux and using the Bash shell, you would add lines such as the following to the -[filename]#.bashrc# or [filename]#.profile# script in your home directory: - -+ ----- -export JAVA_HOME=/opt/jdk1.8.0_31 -export PATH=$PATH:$HOME/bin:$JAVA_HOME/bin ----- -+ -You could also make the setting system-wide in a file such as -[filename]#/etc/bash.bashrc#, [filename]#/etc/profile#, or an equivalent file. -If you install Apache Ant or Maven, you may also want to set up those in the -path. - -+ -Settings done in a [filename]#bashrc# file require that you open a new shell -window. Settings done in a [filename]#profile# file require that you log in into -the system. You can, of course, also give the commands in the current shell. - - -[[getting-started.environment.eclipse]] -== Installing Eclipse IDE - -=== Windows - -. Download the Eclipse IDE for Java EE Developers from -link:http://www.eclipse.org/downloads/[http://www.eclipse.org/downloads/] - -. Decompress the Eclipse IDE package to a suitable directory. You are free to -select any directory and to use any ZIP decompressor, but in this example we -decompress the ZIP file by just double-clicking it and selecting "Extract all -files" task from Windows compressed folder task. In our installation example, we -use [filename]#C:\dev# as the target directory. - -Eclipse is now installed in [filename]#C:\dev\eclipse#. -You can start it from there by double clicking [filename]#eclipse.exe#. - -=== Linux / OS X / UNIX - -We recommend that you install Eclipse manually in Linux and other UNIX variants. -They may have it available from a package repository, but using such an installation may cause problems with installing plug-ins. - -You can install Eclipse as follows: - -. Download Eclipse IDE for Java EE Developers from -link:http://www.eclipse.org/downloads/[http://www.eclipse.org/downloads/] - -. Decompress the Eclipse package into a suitable base directory. It is important -to make sure that there is no old Eclipse installation in the target directory. -Installing a new version on top of an old one probably renders Eclipse unusable. - -. Eclipse should normally be installed as a regular user, which makes installation of plug-ins easier. -Eclipse also stores some user settings in the installation directory. -+ -To install the package, enter: -+ -[subs="normal"] ----- -[prompt]#$# [command]#tar# zxf [replaceable]####/eclipse-jee-[replaceable]####.tar.gz ----- -+ -This will extract the package to a subdirectory with the name -[filename]#eclipse#. - -. If you wish to enable starting Eclipse from command-line, you need to add the -Eclipse installation directory to your system or user PATH, or make a symbolic -link or script to point to the executable. - - -An alternative to the above procedure would be to use an Eclipse version -available through the package management system of your operating system. It is, -however, __not recommended__, because you will need write access to the Eclipse -installation directory to install Eclipse plugins, and you may face -incompatibility issues with Eclipse plugins installed by the package management -of the operating system. - - - -[[getting-started.environment.tomcat]] -== Installing Apache Tomcat - -Apache Tomcat is a lightweight Java web server suitable for both development and -production. There are many ways to install it, but here we simply decompress the -installation package. - -__Apache Tomcat should be installed with user permissions.__ During development, -you will be running Eclipse or some other IDE with user permissions, but -deploying web applications to a Tomcat server that is installed system-wide -requires administrator or root permissions. - -. Download the installation package: - -+ -Apache Tomcat 8.0 (Core Binary Distribution) from http://tomcat.apache.org/ - -. Decompress Apache Tomcat package to a suitable target directory, such as -[filename]#C:\dev# (Windows) or [filename]#/opt# (Linux or Mac OS X). The Apache -Tomcat home directory will be [filename]#C:\dev\apache-tomcat-8.0.x# or -[filename]#/opt/apache-tomcat-8.0.x#, respectively. - - - -[[getting-started.environment.firefox]] -== Firefox and Firebug - -Vaadin supports many web browsers and you can use any of them for development. -If you plan to create a custom theme, customized layouts, or create new -components, we recommend that you use either Firefox together with Firebug or -Google Chrome, which has built-in developer tools similar to Firebug. - -[[getting-started.environment.firefox.firebug]] -=== Using Firebug with Vaadin - -After installing Firefox, use it to open -link:http://www.getfirebug.com/[http://www.getfirebug.com/]. Follow the -instructions on the site to install the latest stable version of Firebug -available for the browser. You may need to allow Firefox to install the plugin -by clicking the yellow warning bar at the top of the browser window. - -After Firebug is installed, it can be enabled at any time from the Firefox -toolbar. <> shows Firebug in action. - -[[figure.firebug.calc]] -.Firebug Debugger for Firefox -image::img/firebug.png[] - -The most important feature in Firebug is inspecting HTML elements. Right-click -on an element and select [guilabel]#Inspect Element with Firebug# to inspect it. -In addition to HTML tree, it also shows the CSS rules matching the element, -which you can use for building themes. You can even edit the CSS styles live, to -experiment with styling. diff --git a/documentation/getting-started/getting-started-first-project.asciidoc b/documentation/getting-started/getting-started-first-project.asciidoc index 8f2eff5a3c..f1adf842c3 100644 --- a/documentation/getting-started/getting-started-first-project.asciidoc +++ b/documentation/getting-started/getting-started-first-project.asciidoc @@ -1,11 +1,11 @@ --- -title: Creating and Running a Project with Eclipse -order: 5 +title: Creating a Project in Eclipse +order: 100 layout: page --- [[getting-started.first-project]] -= Creating and Running a Project with Eclipse += 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: @@ -26,8 +26,8 @@ Eclipse and set up your development environment, as instructed in <>. -[[getting-started.first-project.creation]] ifdef::web[] +[[getting-started.first-project.ivy]] == Creating the Project endif::web[] @@ -222,7 +222,7 @@ For a more detailed treatment of the deployment, see <>. endif::web[] -[[getting-started.first-project.maven]] +[[getting-started.first-project.creation]] == Creating a Maven Project ifdef::web[] @@ -425,3 +425,66 @@ image::img/debuggingMyProject.png[] Above, we described how to debug a server-side application. Debugging client-side applications and widgets is described in <>. + +[[getting-started.eclipse.mavenlibraryupdate]] +== Updating the Vaadin Libraries in Maven 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]#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. + +. If you have compiled the widget set for your project, recompile it by clicking +the [guibutton]#Compile Vaadin widgets# button in Eclipse toolbar. + +. 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". + +[[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 [guibutton]#Compile Vaadin widgets# button in Eclipse toolbar. + +. 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. diff --git a/documentation/getting-started/getting-started-idea.asciidoc b/documentation/getting-started/getting-started-idea.asciidoc index c0961dc534..c573770755 100644 --- a/documentation/getting-started/getting-started-idea.asciidoc +++ b/documentation/getting-started/getting-started-idea.asciidoc @@ -1,17 +1,15 @@ --- -title: Creating a Project with IntelliJ IDEA -order: 8 +title: Creating a Project in IntelliJ +order: 120 layout: page --- [[getting-started.idea]] = Creating a Project with IntelliJ IDEA -The Ultimate Edition of IntelliJ IDEA includes support for creating Vaadin -applications and running or debugging them in an integrated application server. -With the Community Edition, you can create a Vaadin application most easily with -a Maven archetype and deploy it to a server with a Maven run/debug -configuration. +The Ultimate Edition of IntelliJ IDEA includes support for creating Vaadin applications and running or debugging them in an integrated application server. + +With the Community Edition, you can create a Vaadin application most easily with a Maven archetype and deploy it to a server with a Maven run/debug configuration. ifdef::web[] For more information, see the article " @@ -20,66 +18,24 @@ a simple Web application and deploying it to Tomcat]" in the IntelliJ IDEA Encyclopedia wiki. endif::web[] -[[getting-started.idea.server]] -== Configuring an Application Server - -To run the application during development in the Ultimate Edition of IntelliJ -IDEA, you first need to install and configure an application server that is -integrated with the IDE. The edition includes integration with many commonly -used application servers. - -In the following, we configure Apache Tomcat: - -. Download and extract Tomcat installation package to a local directory, as -instructed in <>. - -. Select "Configure > Settings". - -. Select "IDE Settings > Application Servers". - -. Click [guibutton]#+# and select [guilabel]#Tomcat Server# to add a Tomcat server, or any of the other supported servers. -A WebSocket-enabled server, such as Glassfish or TomEE, is required for server push. - -. In the Tomcat Server dialog, specify the home directory for the server. - -+ -image::img/idea-server-1.png[] - -+ -Click [guibutton]#OK#. - -. Review the application server settings page to check that it is OK. - -+ -image::img/idea-server-2.png[] - -+ -Then, click [guibutton]#OK#. - - - [[getting-started.idea.project]] == Creating a Vaadin Web Application Project In the welcome page, do the following: -. Download and exctract the Vaadin installation package to a local folder, as -instructed in -<>. +. Download and extract the Vaadin installation package to a local folder, as +instructed in <>. . Select [menuchoice]#New Project# . In the [guilabel]#New Project# window, select [menuchoice]#Java# . Enter a [guilabel]#Project name# and [guilabel]#Project location#, and select -the [guilabel]#Java SDK# to be used for the project. Vaadin requires at least -Java 6. If you have not configured a Java SDK previously, you can configure it -here. - +the [guilabel]#Java SDK# to be used for the project. +Vaadin requires at least Java 6. +If you have not configured a Java SDK previously, you can configure it here. + image::img/idea-newproject-1.png[] - + Click [guibutton]#Next#. @@ -88,16 +44,13 @@ Click [guibutton]#Next#. . Select Vaadin [guilabel]#Version# and [guilabel]#Distribution# installation path. You probably also want an application stub, so select [guilabel]#Create sample application# and give a name for the generated UI class. - + image::img/idea-newproject-2.png[] - + Do __not__ click [guibutton]#Finish# yet. -. Select [guilabel]#Application Server# in the same window. Set it as an -integrated server that you have configured in IntelliJ IDEA, as described -previously in <>. +. Select [guilabel]#Application Server# in the same window. +Set it as an integrated server that you have configured in IntelliJ IDEA, as described previously in <>. ifdef::web[] + @@ -106,7 +59,6 @@ endif::web[] . Click [guibutton]#Finish#. - The project is created with the UI class stub and a [filename]#web.xml# deployment descriptor. @@ -124,8 +76,6 @@ To deploy the application to the integrated web server, right-click the 'index.jsp'#. This starts the integrated server, if it was not already running, and launches the default browser with the application page. - - [[getting-started.idea.maven]] == Creating a Maven Project diff --git a/documentation/getting-started/getting-started-libraries.asciidoc b/documentation/getting-started/getting-started-libraries.asciidoc index 013a4f445c..785444b5ea 100644 --- a/documentation/getting-started/getting-started-libraries.asciidoc +++ b/documentation/getting-started/getting-started-libraries.asciidoc @@ -1,75 +1,58 @@ --- -title: Overview of Vaadin Libraries -order: 3 +title: Vaadin Libraries +order: 20 layout: page --- [[getting-started.libraries]] -= Overview of Vaadin Libraries += Vaadin Libraries Vaadin comes as a set of library JARs, of which some are optional or alternative ones, depending on whether you are developing server-side or client-side applications, whether you use add-on components, or use CSS or Sass themes. -[filename]#vaadin-server-7.x.x.jar#:: The main library for developing server-side Vaadin applications, as described in -<>. It requires the [filename]#vaadin-shared# and -the [filename]#vaadin-themes# libraries. You can use the prebuilt -[filename]#vaadin-client-compiled# for server-side development, unless you need -add-on components or custom widgets. - -[filename]#vaadin-shared-7.x.x.jar#:: A shared library for server-side and client-side development. It is always -needed. - -[filename]#vaadin-client-7.x.x.jar#:: The client-side Vaadin framework, including the basic GWT API and -Vaadin-specific widgets and other additions. It is required when using the -[filename]#vaadin-client-compiler# to compile client-side modules. It is not -needed if you just use the server-side framework with the precompiled -Client-Side Engine. You should not deploy it with a web application. - -[filename]#vaadin-client-compiler-7.x.x.jar#:: The Vaadin Client Compiler is a Java-to-JavaScript compiler that allows building -client-side modules, such as the Client-Side Engine (widget set) required for -server-side applications. The compiler is needed, for example, for compiling -add-on components to the application widget set, as described in -<>. +[filename]#vaadin-server-7.x.x.jar#:: +The main library for developing server-side Vaadin applications, as described in +<>. +It requires the [filename]#vaadin-shared# and the [filename]#vaadin-themes# libraries. +You can use the pre-built [filename]#vaadin-client-compiled# for server-side development, unless you need add-on components or custom widgets. + +[filename]#vaadin-shared-7.x.x.jar#:: +A shared library for server-side and client-side development. +It is always needed. + +[filename]#vaadin-client-7.x.x.jar#:: +The client-side Vaadin framework, including the basic GWT API and Vaadin-specific widgets and other additions. +It is required when using the [filename]#vaadin-client-compiler# to compile client-side modules. +It is not needed if you just use the server-side framework with the pre-compiled Client-Side Engine. +You should not deploy it with a web application. + +[filename]#vaadin-client-compiler-7.x.x.jar#:: +The Vaadin Client Compiler is a Java-to-JavaScript compiler that allows building client-side modules, such as the Client-Side Engine (widget set) required for server-side applications. +The compiler is needed, for example, for compiling add-on components to the application widget set, as described in <>. + -//TODO There's a need for such -section. +//TODO There's a need for such section. For detailed information regarding the compiler, see -<>. Note that you should not deploy this library with a web -application. - -[filename]#vaadin-client-compiled-7.x.x.jar#:: A precompiled Vaadin Client-Side Engine (widget set) that includes all the basic -built-in widgets in Vaadin. This library is not needed if you compile the -application widget set with the Vaadin Client Compiler. - -[filename]#vaadin-themes-7.x.x.jar#:: Vaadin built-in themes both as SCSS source files and precompiled CSS files. The -library is required both for basic use with CSS themes and for compiling custom -Sass themes. - -[filename]#vaadin-sass-compiler-1.x.x.jar#:: The Vaadin Sass Compiler compiles Sass themes to CSS, as described in -<>. It requires the [filename]#vaadin-themes-7.x.x.jar# -library, which contains the Sass sources for the built-in themes. The library -needs to be included in deployment in development mode to allow on-the-fly -compilation of themes, but it is not needed in production deployment, when the -themes are compiled before deployment. - - +<>. +Note that you should not deploy this library with a web application. -Some of the libraries depend on each other as well as on the dependency -libraries provided in the [filename]#lib# folder of the installation package, -especially the [filename]#lib/vaadin-shared-deps.jar#. +[filename]#vaadin-client-compiled-7.x.x.jar#:: +A pre-compiled Vaadin Client-Side Engine (widget set) that includes all the basic built-in widgets in Vaadin. +This library is not needed if you compile the application widget set with the Vaadin Client Compiler. -The different ways to install the libraries are described in the subsequent -sections. +[filename]#vaadin-themes-7.x.x.jar#:: +Vaadin built-in themes both as SCSS source files and precompiled CSS files. +The library is required both for basic use with CSS themes and for compiling custom Sass themes. -Note that the [filename]#vaadin-client-compiler# and [filename]#vaadin-client# -JARs should not be deployed with the web application by including them in -[filename]#WEB-INF/lib#. Some other libraries, such as -[filename]#vaadin-sass-compiler#, are not needed in production deployment. +[filename]#vaadin-sass-compiler-1.x.x.jar#:: +The Vaadin Sass Compiler compiles Sass themes to CSS, as described in <>. +It requires the [filename]#vaadin-themes-7.x.x.jar# library, which contains the Sass sources for the built-in themes. +The library needs to be included in deployment in development mode to allow on-the-fly compilation of themes, but it is not needed in production deployment, when the themes are compiled before deployment. +Some of the libraries depend on each other as well as on the dependency libraries provided in the [filename]#lib# folder of the installation package, especially the [filename]#lib/vaadin-shared-deps.jar#. +The different ways to install the libraries are described in the subsequent sections. +Note that the [filename]#vaadin-client-compiler# and [filename]#vaadin-client# JARs should not be deployed with the web application by including them in [filename]#WEB-INF/lib#. +Some other libraries, such as [filename]#vaadin-sass-compiler#, are not needed in production deployment. diff --git a/documentation/getting-started/getting-started-maven.asciidoc b/documentation/getting-started/getting-started-maven.asciidoc index 2845e92ab5..79f3b2febb 100644 --- a/documentation/getting-started/getting-started-maven.asciidoc +++ b/documentation/getting-started/getting-started-maven.asciidoc @@ -1,19 +1,17 @@ --- -title: Using Vaadin with Maven -order: 6 +title: Creating a Project with Maven +order: 200 layout: page --- [[getting-started.maven]] -= Using Vaadin with Maven += Creating a Project with Maven ((("Maven", "creating a project", id="term.maven.creating", range="startofrange"))) - -Maven is a commonly used build and dependency management system. The Vaadin core -library and all Vaadin add-ons are available through Maven. You can use a Maven -with a front-end from Eclipse or NetBeans, or by using the command-line as -described in this section. +In previous sections, we looked into creating a Vaadin Maven project in different IDEs. +In this section, we look how to create such a project on command-line. +You can then import such a project to your IDE. In addition to regular Maven, you can use any Maven-compatible build or dependency management system, such as Ivy or Gradle. For Gradle, see the diff --git a/documentation/getting-started/getting-started-netbeans.asciidoc b/documentation/getting-started/getting-started-netbeans.asciidoc index 6e2fa660de..eff1697243 100644 --- a/documentation/getting-started/getting-started-netbeans.asciidoc +++ b/documentation/getting-started/getting-started-netbeans.asciidoc @@ -1,18 +1,15 @@ --- -title: Creating a Project with NetBeans IDE -order: 7 +title: Creating a Project in NetBeans +order: 110 layout: page --- [[getting-started.netbeans]] -= Creating a Project with NetBeans IDE += Creating a Project with the NetBeans IDE -The easiest way to develop Vaadin application with the NetBeans IDE is to use -the Vaadin Plugin for NetBeans. It allows you to create new Vaadin projects -easily and provides many features for working on a project. You can download the -plugin at http://plugins.netbeans.org/plugin/50531/vaadin-plug-in-for-netbeans. -The download page contains a link to a plugin features overview in NetBeans -Wiki. +In the following, we walk you through the creation of a Vaadin project in NetBeans and show how to run it. + +Installation of NetBeans and the Vaadin plugin is covered in <>. Without the plugin, you can most easily create a Vaadin project as a Maven project using a Vaadin archetype. You can also create a Vaadin project as a @@ -20,42 +17,82 @@ regular web application project, but it requires many manual steps to install all the Vaadin libraries, create the UI class, configure the servlet, create theme, and so on. -[[getting-started.netbeans.maven]] -== Maven Project from a Vaadin Archetype +[[getting-started.netbeans.creating]] +== Creating a Project + +. Select "File > Net Project..." from the main menu or press kbd:[Ctrl+Shift+N]. -Creating a Maven project with a Vaadin archetype creates an application skeleton -with a UI class and project theme, defines the [filename]#web.xml# deployment -descriptor, and also retrieves the latest Vaadin library automatically. +. In the [guilabel]#New Project# window that opens, select the [guilabel]#Vaadin# category and one of the Vaadin archetypes from the right. ++ +image::img/netbeans-newproject-1.png[] ++ +The archetypes are described in more detail in <>. -. Select "File > New Project". +. In the [guilabel]#Name and Location# step, enter the project parameters. ++ +image::img/netbeans-newproject-2.png[] -. Select "Maven > Project from Archetype" and click [guibutton]#Next#. +[guilabel]#Project Name#:: A project name. +The name must be a valid identifier that may only contains alphanumerics, minus, and underscore. +It is appended to the group ID to obtain the Java package name for the sources. -. Find [literal]#++vaadin-archetype-application++#, select it, and click -[guilabel]#Next#. +[guilabel]#Project Location#:: +Path to the folder where the project is to be created. -. In the [guilabel]#Name and Location# step, enter [guilabel]#Project Name#, which -is recommended to be only lower-case alphabetics, as it is used also as a -suggestion for the Java package name of the project. Modify the other parameters -for your project and click [guibutton]#Finish#. +[guilabel]#Group Id#:: A Maven group ID for your project. +It is normally your organization domain name in reverse order, such as `com.example`. +The group ID is also used as a prefix for the Java source package, so it should be Java-compatible package name. -+ -[[figure.getting-started.netbeans.maven.new-project]] -.Adding a New Maven Project in NetBeans -image::img/netbeans-maven-newproject-name.png[] +[guilabel]#Version#:: Initial version of your application. +The number must obey the Maven version numbering format. +[guilabel]#Package#:: The Java package name to put sources in. + +[guilabel]#Additional Creation Properties#:: +The properties control various names. +They are specific to the archetype you chose. + ++ +Click [guibutton]#Finish#. Creating the project can take a while as Maven loads all the needed -dependencies. Once created, you can run it by right-clicking on the project in -the [guilabel]#Projects# view and selecting [guilabel]#Run#. In the -[guilabel]#Select deployment server# window that opens, select -[guilabel]#Glassfish# or [guilabel]#Apache Tomcat#, and click [guibutton]#OK#. +dependencies. + +[[getting-started.netbeans.exploring]] +== Exploring a Project + +The project wizard 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.netbeans.exploring]] +.A new Vaadin project in NetBeans +image::img/netbeans-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.netbeans.running]] +== Running the Application + +Once created, you can run it in a server as follows. + +. In [guilabel]#Projects# tab, select the project and click in the [guilabel]#Run Project# button in the tool bar (or press kbd:[F6]). + +. In the [guilabel]#Select deployment server#, select a server from the [guilabel]#Server# list. +It should show either GlassFish or Apache Tomcat, depending on what you chose in NetBeans installation. ++ +image::img/netbeans-server.png[width=60%] ++ +Also, select [guilabel]#Remember Permanently# if you want to use the same server also in future while developing applications. ++ +Click [guibutton]#OK#. +. +It will compile the widget set at this point, which may take a while. + If all goes well, NetBeans starts the server in port 8080 and, depending on your system configuration, launches the default browser to display the web application. If not, you can open it manually, for example, at http://localhost:8080/myproject. The project name is used by default as the context path of the application. - - - +Now when you edit the UI class in the source editor and save it, NetBeans will automatically redeploy the application. After it has finished after a few seconds, you can reload the application in the browser. diff --git a/documentation/getting-started/getting-started-overview.adoc b/documentation/getting-started/getting-started-overview.adoc new file mode 100644 index 0000000000..d9fa9d6fe6 --- /dev/null +++ b/documentation/getting-started/getting-started-overview.adoc @@ -0,0 +1,22 @@ +--- +title: Overview +order: 1 +layout: page +--- + +[[getting-started.overview]] += Overview + +Once you have installed a development environment, as described in the previous chapter, creating a Vaadin project proceeds in the IDE that you have chosen. + +The Vaadin core library and all Vaadin add-ons are available through Maven, a commonly used build and dependency management system. + +The recommended way to create a Vaadin application project is to use a Maven archetype. +The archetypes contain all the needed dependencies, which Maven takes care of. +The Eclipse IDE plugin currently also supports creating a normal Eclipse web project using the Ivy dependency manager. + +In this chapter, we give: + +. An overview of the Vaadin libraries +. List the available Maven archetypes +. Step-by-step instructions for creating a project in the Eclipse IDE, NetBeans IDE, and IntelliJ IDEA, as well as with command-line. diff --git a/documentation/getting-started/getting-started-overview.asciidoc b/documentation/getting-started/getting-started-overview.asciidoc deleted file mode 100644 index 016196b3f6..0000000000 --- a/documentation/getting-started/getting-started-overview.asciidoc +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Overview -order: 1 -layout: page ---- - -[[getting-started.overview]] -= Overview - -You can develop Vaadin applications in essentially any development environment -that has the Java SDK and a Java Servlet container. Vaadin has special support -for the Eclipse and NetBeans IDEs, but community support exists also for -IntelliJ IDEA. You can use it with any Java IDE or no IDE at all. - -.Vaadin installation steps -image::img/installation-steps-hi.png[] - -Managing Vaadin and other Java libraries can get tedious to do manually, so -using a build system that manages dependencies automatically is adviced. Vaadin -is distributed in the Maven central repository, and can be used with any build -or dependency management system that can access Maven repository, such as Ivy or -Gradle, in addition to Maven. - -Vaadin has a multitude of installation options for different IDEs, dependency -managers, and you can also install it from an installation package: - -* With the Eclipse IDE, use the Vaadin Plugin for Eclipse, as described in <> -* With the Vaadin plugin for NetBeans IDE ( <>) or IntelliJ IDEA -* With Maven, Ivy, Gradle, or other Maven-compatible dependency manager, under Eclipse, NetBeans, IDEA, or using command-line, as described in <> -* From installation package without dependency management, as described in <> diff --git a/documentation/getting-started/getting-started-package.asciidoc b/documentation/getting-started/getting-started-package.asciidoc index 9dd7ec81be..a5bcedb3fc 100644 --- a/documentation/getting-started/getting-started-package.asciidoc +++ b/documentation/getting-started/getting-started-package.asciidoc @@ -1,6 +1,6 @@ --- title: Vaadin Installation Package -order: 9 +order: 900 layout: page --- diff --git a/documentation/getting-started/getting-started-scala.asciidoc b/documentation/getting-started/getting-started-scala.asciidoc index bfd91cc256..f31a16b1e8 100644 --- a/documentation/getting-started/getting-started-scala.asciidoc +++ b/documentation/getting-started/getting-started-scala.asciidoc @@ -1,6 +1,6 @@ --- title: Using Vaadin with Scala -order: 10 +order: 1000 layout: page --- diff --git a/documentation/getting-started/img/firebug.png b/documentation/getting-started/img/firebug.png deleted file mode 100644 index 81512b615d..0000000000 Binary files a/documentation/getting-started/img/firebug.png and /dev/null differ diff --git a/documentation/getting-started/img/idea-server-1.png b/documentation/getting-started/img/idea-server-1.png deleted file mode 100644 index f0e0fb7f9b..0000000000 Binary files a/documentation/getting-started/img/idea-server-1.png and /dev/null differ diff --git a/documentation/getting-started/img/idea-server-2.png b/documentation/getting-started/img/idea-server-2.png deleted file mode 100644 index 2375f44c48..0000000000 Binary files a/documentation/getting-started/img/idea-server-2.png and /dev/null differ diff --git a/documentation/getting-started/img/installation-steps-hi.png b/documentation/getting-started/img/installation-steps-hi.png deleted file mode 100644 index 06089e1e46..0000000000 Binary files a/documentation/getting-started/img/installation-steps-hi.png and /dev/null differ diff --git a/documentation/getting-started/img/netbeans-created-annotated-hi.png b/documentation/getting-started/img/netbeans-created-annotated-hi.png new file mode 100644 index 0000000000..fd94e88321 Binary files /dev/null and b/documentation/getting-started/img/netbeans-created-annotated-hi.png differ diff --git a/documentation/getting-started/img/netbeans-newproject-1.png b/documentation/getting-started/img/netbeans-newproject-1.png new file mode 100644 index 0000000000..4100e315f8 Binary files /dev/null and b/documentation/getting-started/img/netbeans-newproject-1.png differ diff --git a/documentation/getting-started/img/netbeans-newproject-2.png b/documentation/getting-started/img/netbeans-newproject-2.png new file mode 100644 index 0000000000..ee5711cfa8 Binary files /dev/null and b/documentation/getting-started/img/netbeans-newproject-2.png differ diff --git a/documentation/getting-started/img/netbeans-newproject-created.png b/documentation/getting-started/img/netbeans-newproject-created.png new file mode 100644 index 0000000000..6fc0bd8978 Binary files /dev/null and b/documentation/getting-started/img/netbeans-newproject-created.png differ diff --git a/documentation/getting-started/img/netbeans-server.png b/documentation/getting-started/img/netbeans-server.png new file mode 100644 index 0000000000..026c70eac2 Binary files /dev/null and b/documentation/getting-started/img/netbeans-server.png differ diff --git a/documentation/getting-started/img/plugin-install-addsite.png b/documentation/getting-started/img/plugin-install-addsite.png deleted file mode 100644 index baa36c5416..0000000000 Binary files a/documentation/getting-started/img/plugin-install-addsite.png and /dev/null differ diff --git a/documentation/getting-started/img/plugin-install-available.png b/documentation/getting-started/img/plugin-install-available.png deleted file mode 100644 index d9c305de62..0000000000 Binary files a/documentation/getting-started/img/plugin-install-available.png and /dev/null differ diff --git a/documentation/getting-started/img/toolchain-hi.png b/documentation/getting-started/img/toolchain-hi.png deleted file mode 100644 index 88d9dfcc4c..0000000000 Binary files a/documentation/getting-started/img/toolchain-hi.png and /dev/null differ diff --git a/documentation/getting-started/img/toolchain-lo.png b/documentation/getting-started/img/toolchain-lo.png deleted file mode 100644 index e42b94bc2f..0000000000 Binary files a/documentation/getting-started/img/toolchain-lo.png and /dev/null differ diff --git a/documentation/getting-started/original-drawings/Makefile b/documentation/getting-started/original-drawings/Makefile index 6b3bab4617..eb59278a4a 100644 --- a/documentation/getting-started/original-drawings/Makefile +++ b/documentation/getting-started/original-drawings/Makefile @@ -1,4 +1,4 @@ -IMAGES = installation-steps myproject-created-annotated +IMAGES = myproject-created-annotated netbeans-created-annotated SRCIMAGES := $(foreach file, $(IMAGES), $(file).svg) TRGIMAGES_HI := $(foreach file, $(IMAGES), ../img/$(file)-hi.png) diff --git a/documentation/getting-started/original-drawings/installation-steps-constellation.svg b/documentation/getting-started/original-drawings/installation-steps-constellation.svg deleted file mode 100644 index 7716b64f6c..0000000000 --- a/documentation/getting-started/original-drawings/installation-steps-constellation.svg +++ /dev/null @@ -1,7259 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - On Windows On OS X On Linux InstallJDK Eclipse NetBeans IntelliJ IDEA Install an IDE Install aServer InstallVaadinPlugin FireBug ApacheTomcat TomEE GlassFish Other δ γ β α ε InstallOtherTools - M103 M52 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/documentation/getting-started/original-drawings/installation-steps.svg b/documentation/getting-started/original-drawings/installation-steps.svg deleted file mode 100644 index 2af7752bd3..0000000000 --- a/documentation/getting-started/original-drawings/installation-steps.svg +++ /dev/null @@ -1,664 +0,0 @@ - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - - - OnWindows - - - OnOS X - - - OnLinux - - - - - - - InstallJDK - - - - - EclipseIDE - - - NetBeansIDE - - - IntelliJIDEA - - - - - - Install an IDE - - - - ApacheTomcat - - - TomEE - - - Wildfly - - - GlassFish - - - Other - - - - - - Install aServer - - - - Firebug - - - - - - - Other Tools - - - GoCreate a Project - StartHere - diff --git a/documentation/getting-started/original-drawings/netbeans-created-annotated.svg b/documentation/getting-started/original-drawings/netbeans-created-annotated.svg new file mode 100644 index 0000000000..3b87ce23e0 --- /dev/null +++ b/documentation/getting-started/original-drawings/netbeans-created-annotated.svg @@ -0,0 +1,324 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + The UI class skeleton + + + + + + + + + + + + + + + + + + The widget set + The theme + Maven project configuration + + diff --git a/documentation/getting-started/original-drawings/toolchain.svg b/documentation/getting-started/original-drawings/toolchain.svg deleted file mode 100644 index 63148883f3..0000000000 --- a/documentation/getting-started/original-drawings/toolchain.svg +++ /dev/null @@ -1,1149 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - User Project Developer Tools - - - - Eclipse IDE (optional) - - - Java SDK - Web Application (WAR) - - VaadinLibrary & Themes - - - UserSources & Themes - - - VaadinLibrary & Themes - - - User Executable& Themes - - - Apache Tomcat or any other web container - Application Server - - - Mozilla Firefox or any otherbrowser - - - Firebug Plugin (optional) - - - - - Vaadin Plugin (optional) - Deploy and Control Compile and Package - - diff --git a/documentation/installing/chapter-installing.asciidoc b/documentation/installing/chapter-installing.asciidoc new file mode 100644 index 0000000000..7e987bcea8 --- /dev/null +++ b/documentation/installing/chapter-installing.asciidoc @@ -0,0 +1,20 @@ +[[installing]] +== Installing the Development Toolchain + +This chapter gives practical instructions for installing the development tools. + +include::installing-overview.adoc[leveloffset=+2] + +include::installing-toolchain.adoc[leveloffset=+2] + +include::installing-java.adoc[leveloffset=+2] + +include::installing-server.adoc[leveloffset=+2] + +include::installing-eclipse.adoc[leveloffset=+2] + +include::installing-netbeans.asciidoc[leveloffset=+2] + +include::installing-idea.asciidoc[leveloffset=+2] + +include::installing-other.adoc[leveloffset=+2] diff --git a/documentation/installing/img/firebug.png b/documentation/installing/img/firebug.png new file mode 100644 index 0000000000..81512b615d Binary files /dev/null and b/documentation/installing/img/firebug.png differ diff --git a/documentation/installing/img/idea-server-1.png b/documentation/installing/img/idea-server-1.png new file mode 100644 index 0000000000..f0e0fb7f9b Binary files /dev/null and b/documentation/installing/img/idea-server-1.png differ diff --git a/documentation/installing/img/idea-server-2.png b/documentation/installing/img/idea-server-2.png new file mode 100644 index 0000000000..2375f44c48 Binary files /dev/null and b/documentation/installing/img/idea-server-2.png differ diff --git a/documentation/installing/img/installation-eclipse-hi.png b/documentation/installing/img/installation-eclipse-hi.png new file mode 100644 index 0000000000..cf2b4efb04 Binary files /dev/null and b/documentation/installing/img/installation-eclipse-hi.png differ diff --git a/documentation/installing/img/installation-netbeans-hi.png b/documentation/installing/img/installation-netbeans-hi.png new file mode 100644 index 0000000000..c0a54f544f Binary files /dev/null and b/documentation/installing/img/installation-netbeans-hi.png differ diff --git a/documentation/installing/img/installation-steps-hi.png b/documentation/installing/img/installation-steps-hi.png new file mode 100644 index 0000000000..06089e1e46 Binary files /dev/null and b/documentation/installing/img/installation-steps-hi.png differ diff --git a/documentation/installing/img/installing-netbeans-1.png b/documentation/installing/img/installing-netbeans-1.png new file mode 100644 index 0000000000..c2edcae32e Binary files /dev/null and b/documentation/installing/img/installing-netbeans-1.png differ diff --git a/documentation/installing/img/installing-netbeans-2.png b/documentation/installing/img/installing-netbeans-2.png new file mode 100644 index 0000000000..b3d0a07e03 Binary files /dev/null and b/documentation/installing/img/installing-netbeans-2.png differ diff --git a/documentation/installing/img/installing-netbeans-3.png b/documentation/installing/img/installing-netbeans-3.png new file mode 100644 index 0000000000..63a59df0d7 Binary files /dev/null and b/documentation/installing/img/installing-netbeans-3.png differ diff --git a/documentation/installing/img/installing-netbeans-4.png b/documentation/installing/img/installing-netbeans-4.png new file mode 100644 index 0000000000..a3c03eb0ca Binary files /dev/null and b/documentation/installing/img/installing-netbeans-4.png differ diff --git a/documentation/installing/img/installing-netbeans-5.png b/documentation/installing/img/installing-netbeans-5.png new file mode 100644 index 0000000000..345bffc12e Binary files /dev/null and b/documentation/installing/img/installing-netbeans-5.png differ diff --git a/documentation/installing/img/installing-netbeans-plugin-1.png b/documentation/installing/img/installing-netbeans-plugin-1.png new file mode 100644 index 0000000000..45b69f626b Binary files /dev/null and b/documentation/installing/img/installing-netbeans-plugin-1.png differ diff --git a/documentation/installing/img/installing-netbeans-plugin-2.png b/documentation/installing/img/installing-netbeans-plugin-2.png new file mode 100644 index 0000000000..9c695de0d9 Binary files /dev/null and b/documentation/installing/img/installing-netbeans-plugin-2.png differ diff --git a/documentation/installing/img/installing-netbeans-plugin-3.png b/documentation/installing/img/installing-netbeans-plugin-3.png new file mode 100644 index 0000000000..8eecbb7624 Binary files /dev/null and b/documentation/installing/img/installing-netbeans-plugin-3.png differ diff --git a/documentation/installing/img/plugin-install-addsite.png b/documentation/installing/img/plugin-install-addsite.png new file mode 100644 index 0000000000..baa36c5416 Binary files /dev/null and b/documentation/installing/img/plugin-install-addsite.png differ diff --git a/documentation/installing/img/plugin-install-available.png b/documentation/installing/img/plugin-install-available.png new file mode 100644 index 0000000000..d9c305de62 Binary files /dev/null and b/documentation/installing/img/plugin-install-available.png differ diff --git a/documentation/installing/img/toolchain-hi.png b/documentation/installing/img/toolchain-hi.png new file mode 100644 index 0000000000..88d9dfcc4c Binary files /dev/null and b/documentation/installing/img/toolchain-hi.png differ diff --git a/documentation/installing/img/toolchain-lo.png b/documentation/installing/img/toolchain-lo.png new file mode 100644 index 0000000000..e42b94bc2f Binary files /dev/null and b/documentation/installing/img/toolchain-lo.png differ diff --git a/documentation/installing/installing-eclipse.adoc b/documentation/installing/installing-eclipse.adoc new file mode 100644 index 0000000000..244a2a7b7d --- /dev/null +++ b/documentation/installing/installing-eclipse.adoc @@ -0,0 +1,135 @@ +--- +title: Installing Eclipse IDE +order: 100 +layout: page +--- + +[[installing.eclipse]] += Installing the Eclipse IDE and Plugin + +If you are using the Eclipse IDE, using the Vaadin Plugin for Eclipse helps +greatly. The plugin includes wizards for creating new Vaadin-based projects, +themes, and client-side widgets and widget sets. Notice that you can also create +Vaadin projects as Maven projects in Eclipse. + +Using Eclipse IDE for Vaadin development requires installing the IDE itself and the Vaadin Plugin for Eclipse. +You are adviced to also configure a web server in Eclipse. +You can then use the server for running the Vaadin applications that you create. + +.Installation of the Eclipse IDE toolchain +image::img/installation-eclipse-hi.png[] + +Vaadin Designer is a visual design tool for professional developers. +It allows for easy creation of declarative designs. +It is also good as a sketching tool, as well as an easy way to learn about Vaadin components and layouts. + +Once you have installed the Eclipse IDE and the plug-in, you can create a Vaadin application project as described in <>. + +[[installing.eclipse.ide]] +== Installing the Eclipse IDE + +=== Windows + +. Download the Eclipse IDE for Java EE Developers from +link:http://www.eclipse.org/downloads/[http://www.eclipse.org/downloads/] + +. Decompress the Eclipse IDE package to a suitable directory. +You are free to select any directory and to use any ZIP decompressor, but in this example we decompress the ZIP file by just double-clicking it and selecting "Extract all files" task from Windows compressed folder task. +In our installation example, we use [filename]#C:\dev# as the target directory. + +Eclipse is now installed in [filename]#C:\dev\eclipse#. +You can start it from there by double clicking [filename]#eclipse.exe#. + +=== Linux / OS X / UNIX + +We recommend that you install Eclipse manually in Linux and other UNIX variants. +They may have it available from a package repository, but using such an installation may cause problems with installing plug-ins. + +You can install Eclipse as follows: + +. Download Eclipse IDE for Java EE Developers from +link:http://www.eclipse.org/downloads/[http://www.eclipse.org/downloads/] + +. Decompress the Eclipse package into a suitable base directory. +It is important to make sure that there is no old Eclipse installation in the target directory. +Installing a new version on top of an old one probably renders Eclipse unusable. + +. Eclipse should normally be installed as a regular user, which makes installation of plug-ins easier. +Eclipse also stores some user settings in the installation directory. ++ +To install the package, enter: ++ +[subs="normal"] +---- +[prompt]#$# [command]#tar# zxf [replaceable]####/eclipse-jee-[replaceable]####.tar.gz +---- ++ +This will extract the package to a subdirectory with the name +[filename]#eclipse#. + +. If you wish to enable starting Eclipse from command-line, you need to add the +Eclipse installation directory to your system or user PATH, or make a symbolic +link or script to point to the executable. + +An alternative to the above procedure would be to use an Eclipse version +available through the package management system of your operating system. It is, +however, __not recommended__, because you will need write access to the Eclipse +installation directory to install Eclipse plugins, and you may face +incompatibility issues with Eclipse plugins installed by the package management +of the operating system. + +[[installing.eclipse.plugin]] +== Installing the Vaadin Plugin + +You can install the plugin as follows: + +. Select "Help > Install New Software...". + +. Add the Vaadin plugin update site by clicking [guibutton]#Add...# button. + ++ +image::img/plugin-install-addsite.png[] + ++ +Enter a name such as "Vaadin Update Site" and the URL of the update site: +http://vaadin.com/eclipse. If you want or need to use the latest unstable +plugin, which is usually more compatible with development and beta releases of +Vaadin, you can use http://vaadin.com/eclipse/experimental and give it a +distinctive name such as "Vaadin Experimental Site". Then click [guibutton]#OK#. +The Vaadin site should now appear in the [guilabel]#Available Software# window. + +. Currently, if using the stable plugin, the [guilabel]#Group items by category# should be enabled. If using the experimental plugin, it should be disabled. This may change in future. + +. Select all the Vaadin plugins in the tree. ++ +image::img/plugin-install-available.png[] ++ +Then, click [guibutton]#Next#. + +. Review the installation details and click [guibutton]#Next#. + +. Accept or unaccept the license. Finally, click [guibutton]#Finish#. + +. After the plugin is installed, Eclipse will ask to restart itself. Click +[guibutton]#Restart#. + +More installation instructions for the Eclipse plugin can be found at +http://vaadin.com/eclipse. + +[[installing.eclipse.update]] +== Updating the Plugins + +If you have automatic updates enabled in Eclipse (see "Window > Preferences > +Install/Update > Automatic Updates"), the Vaadin plugin will be updated +automatically along with other plugins. Otherwise, you can update the Vaadin +plugin manually as follows: + +. Select "Help > Check for Updates". +Eclipse will contact the update sites of the installed software. + +. After the updates are installed, Eclipse will ask to restart itself. +Click [guibutton]#Restart#. + +Notice that updating the Vaadin plugin only updates the plugin and __not__ the +Vaadin libraries, which are project specific. See below for instructions for +updating the libraries. diff --git a/documentation/installing/installing-idea.asciidoc b/documentation/installing/installing-idea.asciidoc new file mode 100644 index 0000000000..95779dab55 --- /dev/null +++ b/documentation/installing/installing-idea.asciidoc @@ -0,0 +1,54 @@ +--- +title: Installing IntelliJ IDEA +order: 120 +layout: page +--- + +[[intalling.idea]] += Installing and Configuring IntelliJ IDEA + +With IntelliJ IDEA, you have two choices: use the commercial Ultimate Edition or the free Community Edition. +In the following, we cover the installation and configuration of them both. + +The Ultimate Edition:: +The Ultimate Edition includes built-in support for creating Vaadin applications and running or debugging them in an integrated application server. + +Community Edition:: +You can create a Vaadin application most easily with a Maven archetype and deploy it to a server using a Maven run/debug configuration. + +You can get the both editions from the website at https://www.jetbrains.com/idea/[jetbrains.com/idea]. + +[[installing.idea.ultimate]] +== Installing the Ultimate Edition + +Follow the installation instructions given at the website. + +[[installing.idea.ultimate.server]] +=== Configuring an Application Server + +To run a Vaadin application during development in the Ultimate Edition of IntelliJ IDEA, you first need to install and configure an application server that is integrated with the IDE. +The edition includes integration with many commonly used application servers. + +In the following, we configure Apache Tomcat: + +. Download and extract Tomcat installation package to a local directory, as +instructed in <>. + +. Select "Configure > Settings". + +. Select "IDE Settings > Application Servers". + +. Click [guibutton]#+# and select [guilabel]#Tomcat Server# to add a Tomcat server, or any of the other supported servers. +A WebSocket-enabled server, such as Glassfish or TomEE, is required for server push. + +. In the Tomcat Server dialog, specify the home directory for the server. ++ +image::img/idea-server-1.png[] ++ +Click [guibutton]#OK#. + +. Review the application server settings page to check that it is OK. ++ +image::img/idea-server-2.png[] ++ +Then, click [guibutton]#OK#. diff --git a/documentation/installing/installing-java.adoc b/documentation/installing/installing-java.adoc new file mode 100644 index 0000000000..adee81c05a --- /dev/null +++ b/documentation/installing/installing-java.adoc @@ -0,0 +1,72 @@ +--- +title: Installing Java +order: 30 +layout: page +--- + +[[installing.java]] += Installing Java SDK + +A Java SDK is required by Vaadin and also by any of the Java IDEs. +Vaadin is compatible with Java 1.6 and later editions, be we recommend using Java 8 for Vaadin development. +Java EE 7 is required for proper server push support with WebSockets. + +[[installing.java.windows]] +== Windows + +Follow the following steps: + +. Download Oracle Java SE 8.0 from +link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[http://www.oracle.com/technetwork/java/javase/downloads/index.html] + +. Install the Java SDK by running the installer. +The default options are fine. + +[[installing.linux]] +== Linux / UNIX + +Most Linux systems either have JDK preinstalled or allow installing it through a +package management system. Notice however that they have OpenJDK as the default +Java implementation. While it is known to have worked with Vaadin and possibly +also with the development toolchain, we do not especially support it. + +Regarding OS X, notice that JDK 1.6 or newer is included in OS X 10.6 and newer. + +Otherwise: + +. Download Oracle Java SE 8.0 from +link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[http://www.oracle.com/technetwork/java/javase/downloads/] + +. Decompress it under a suitable base directory, such as [filename]#/opt#. For +example, for Java SDK, enter (either as root or with [command]#sudo# in Linux): + ++ +[subs="normal"] +---- +[prompt]#+++#+++# [command]#cd# [replaceable]#/opt# +[prompt]#+++#+++# [command]#sh# [replaceable]####/jdk-[replaceable]####.bin +---- ++ +and follow the instructions in the installer. + +. Set up the [literal]#++JAVA_HOME++# environment variable to point to the Java +installation directory. Also, include the [literal]#++$JAVA_HOME/bin++# in the +[literal]#++PATH++#. How you do that varies by the UNIX variant. For example, in +Linux and using the Bash shell, you would add lines such as the following to the +[filename]#.bashrc# or [filename]#.profile# script in your home directory: + ++ +---- +export JAVA_HOME=/opt/jdk1.8.0_31 +export PATH=$PATH:$HOME/bin:$JAVA_HOME/bin +---- ++ +You could also make the setting system-wide in a file such as +[filename]#/etc/bash.bashrc#, [filename]#/etc/profile#, or an equivalent file. +If you install Apache Ant or Maven, you may also want to set up those in the +path. + ++ +Settings done in a [filename]#bashrc# file require that you open a new shell +window. Settings done in a [filename]#profile# file require that you log in into +the system. You can, of course, also give the commands in the current shell. diff --git a/documentation/installing/installing-netbeans.asciidoc b/documentation/installing/installing-netbeans.asciidoc new file mode 100644 index 0000000000..35d7b96c16 --- /dev/null +++ b/documentation/installing/installing-netbeans.asciidoc @@ -0,0 +1,112 @@ +--- +title: Installing NetBeans IDE +order: 110 +layout: page +--- + +[[installing.netbeans]] += Installing the NetBeans IDE and Plugin + +Vaadin offers official support for the NetBeans IDE. +The Vaadin Plug-in for NetBeans supports creating Vaadin projects, updating Vaadin libraries, compiling widget sets, and more. +It also allows directly downloading Vaadin add-ons from the Vaadin Directory. + +.Installation of the NetBeans IDE toolchain +image::img/installation-netbeans-hi.png[width=60%] + +The installation bundle includes a web server, so you do not need that. + +Once done with the installation, you can proceed to create a Vaadin project, as described in <>. + +[[installing.netbeans.ide]] +== Installing the NetBeans IDE + +Download NetBeans IDE from the website at https://netbeans.org/downloads/[netbeans.org]. +We recommend using the _Java EE_ download bundle, which includes support for Java EE, and also both the GlassFish and Tomcat application servers. + +. Run the installer + +.. In OS X and Linux: ++ +[subs="normal"] +---- +[prompt]#$# [command]#sh# [replaceable]#netbeans-.sh# +---- + +. Select to install either GlassFish or Apache Tomcat, or both. +GlassFish supports Java EE, which is required by Vaadin CDI and Vaadin Spring add-ons, while standard Tomcat does not support it. +Click [guibutton]#Next#. +ifdef::web[] ++ +image::img/installing-netbeans-1.png[width=60%] +endif::web[] + +. If you accept the license, click [guibutton]#Next#. + +. Choose installation folder and Java SDK. +ifdef::web[] ++ +image::img/installing-netbeans-3.png[width=60%] +endif::web[] ++ +In OS X and Linux, if you ran the installer with root permissions or can write to [filename]#/opt#, the [filename]#/opt# path is standard for such system-wide packages. ++ +Click [guibutton]#Next#. + +. Choose the folder for installing the server. +ifdef::web[] ++ +image::img/installing-netbeans-4.png[width=60%] +endif::web[] + +. Check the settings. +ifdef::web[] ++ +image::img/installing-netbeans-5.png[width=60%] +endif::web[] ++ +Click [guibutton]#Finish#. +It takes a while to install the NetBeans IDE. + +. Finally, click [guibutton]#Done# to exit the installer. + +You can now start NetBeans by starting the [filename]#bin/netbeans# from under the installation folder. + +In Linux and OS X: + +[subs="normal"] +---- +[prompt]#$# [replaceable]#/opt/netbeans-8.1#/bin/netbeans +---- + +You can now proceed to install the Vaadin Plug-in for NetBeans IDE. + +[[installing.netbeans.plugin]] +== Installing the Vaadin Plug-in for NetBeans IDE + +You can install the plug-in from the NetBeans Plugin Portal Update Center as follows. + +. Select "Tools > Plugins" from the NetBeans main menu. + +. Select the [guilabel]#Available Plugins# tab. +.. Type "Vaadin" in the [guilabel]#Search# box and press kbd:Enter[]. +.. Select the [guilabel]#Install# check box for the [guilabel]#Vaadin Plugin for NetBeans#. +ifdef::web[] ++ +image::img/installing-netbeans-plugin-1.png[width=80%] +endif::web[] + +.. Click [guibutton]#Install#. + +. In the plugin installation window, click [guibutton]#Next#. +. Accept the license if choose to do so. +Click [guibutton]#Install#. + +. The Vaadin Plugin is not signed, so you need to verify the certificate. +Click [guibutton]#Continue#. + +. In the final step, select [guilabel]#Restart IDE now" and click [guibutton]#Finish#. + +You can now proceed to create a Vaadin project, as described in <>. + +The Vaadin Plug-in for NetBeans IDE can also be downloaded from the plug-in page at http://plugins.netbeans.org/plugin/50531/vaadin-plug-in-for-netbeans[plugins.netbeans.org/plugin/50531/vaadin-plug-in-for-netbeans]. diff --git a/documentation/installing/installing-other.adoc b/documentation/installing/installing-other.adoc new file mode 100644 index 0000000000..b7ff51dfea --- /dev/null +++ b/documentation/installing/installing-other.adoc @@ -0,0 +1,38 @@ +--- +title: Installing Other Tools +order: 200 +layout: page +--- + += Installing Other Tools + +We recommend using a browser with either integrated or external development tools. + +At least Mozilla Firefox and Google Chrome have an integrated web inspector, which supports inspecting the DOM structure of a web page, as well as CSS styles and debug JavaScript execution. + +[[installing.other.firefox]] +== Firefox and Firebug + +While Firefox has an integrated web inspector, the Firebug inspector has some additional features. + +[[installing.other.firefox.firebug]] +=== Using Firebug with Vaadin + +After installing Firefox, use it to open +link:http://www.getfirebug.com/[http://www.getfirebug.com/]. Follow the +instructions on the site to install the latest stable version of Firebug +available for the browser. You may need to allow Firefox to install the plugin +by clicking the yellow warning bar at the top of the browser window. + +After Firebug is installed, it can be enabled at any time from the Firefox +toolbar. <> shows Firebug in action. + +[[figure.firebug.calc]] +.Firebug Debugger for Firefox +image::img/firebug.png[] + +The most important feature in Firebug is inspecting HTML elements. Right-click +on an element and select [guilabel]#Inspect Element with Firebug# to inspect it. +In addition to HTML tree, it also shows the CSS rules matching the element, +which you can use for building themes. You can even edit the CSS styles live, to +experiment with styling. diff --git a/documentation/installing/installing-overview.adoc b/documentation/installing/installing-overview.adoc new file mode 100644 index 0000000000..7075c10172 --- /dev/null +++ b/documentation/installing/installing-overview.adoc @@ -0,0 +1,28 @@ +--- +title: Overview +order: 1 +layout: page +--- + +[[installing.overview]] += Overview + +You can develop Vaadin applications in essentially any development environment +that has the Java SDK and deploys to a Java Servlet container. +You can use Vaadin with any Java IDE or no IDE at all. +Vaadin has special support for the Eclipse and NetBeans IDEs, as well as for IntelliJ IDEA. + +.Vaadin installation steps +image::img/installation-steps-hi.png[] + +Managing Vaadin and other Java libraries can get tedious to do manually, so using a build system that manages dependencies automatically is adviced. +Vaadin is distributed in the Maven central repository, and can be used with any build or dependency management system that can access Maven repositories, such as Ivy or Gradle, in addition to Maven. + +Vaadin has a multitude of installation options for different IDEs and dependency +managers. +You can also install it from an installation package: + +* With the Eclipse IDE, use the Vaadin Plugin for Eclipse, as described in <> +* With the Vaadin plugin for NetBeans IDE ( <>) or IntelliJ IDEA +* With Maven, Ivy, Gradle, or other Maven-compatible dependency manager, under Eclipse, NetBeans, IDEA, or using command-line, as described in <> +* From installation package without dependency management, as described in <> diff --git a/documentation/installing/installing-server.adoc b/documentation/installing/installing-server.adoc new file mode 100644 index 0000000000..59874ab154 --- /dev/null +++ b/documentation/installing/installing-server.adoc @@ -0,0 +1,44 @@ +--- +title: Installing a Web Server +order: 40 +layout: page +--- + +[[installing.server]] += Installing a Web Server + +You can run Vaadin applications in any Java servlet container that supports at least Servlet API 2.4. +However, a server supporting Servlet API 3.0 is recommended. +It is required for using Vaadin CDI, for which also a CDI container is required, a standard feature in Java EE 6 or newer servers. +It is also required by the Vaadin Spring add-on. +Server push can benefit from using communication modes, such as WebSocket, enabled by features in some latest servers. +For Java EE containers, at least Wildfly, Glassfish, and Apache TomEE Web Profile are recommended. + +Also, if you use Java 8 for Vaadin development, you need to make sure that the server supports it. + +Some Java IDEs have server integration, so we describe installation of the server before the IDEs. + +Some IDE bundles also include a development server; for example, NetBeans IDE includes GlassFish and Apache Tomcat. + +You can also opt to install a development server from a Maven dependency and let the IDE control it through Maven executions. + +[[installing.server.tomcat]] +== Installing Apache Tomcat + +Apache Tomcat is a lightweight Java web server suitable for both development and +production. There are many ways to install it, but here we simply decompress the +installation package. + +__Apache Tomcat should be installed with user permissions.__ +During development, you will be running Eclipse or some other IDE with user permissions, but deploying web applications to a Tomcat server that is installed system-wide requires administrator or root permissions. + +. Download the installation package: ++ +Apache Tomcat 8.0 (Core Binary Distribution) from http://tomcat.apache.org/ + +. Decompress Apache Tomcat package to a suitable target directory, such as +[filename]#C:\dev# (Windows) or [filename]#/opt# (Linux or Mac OS X). +The Apache Tomcat home directory will be [filename]#C:\dev\apache-tomcat-8.0.x# or [filename]#/opt/apache-tomcat-8.0.x#, respectively. + +Do not start the server. +If you use an IDE integration, the IDE will control starting and stopping the server. diff --git a/documentation/installing/installing-toolchain.adoc b/documentation/installing/installing-toolchain.adoc new file mode 100644 index 0000000000..08ad190a8d --- /dev/null +++ b/documentation/installing/installing-toolchain.adoc @@ -0,0 +1,41 @@ +--- +title: A Reference Toolchain +order: 20 +layout: page +--- + +[[getting-started.environment]] += A Reference Toolchain + +This section presents a reference development environment. +Vaadin supports a wide variety of tools, so you can use any IDE for writing the code, almost any Java web server for deploying the application, most web browsers for using it, and any operating system platform supported by Java. + +In this example, we use the following toolchain: + +* Windows, Linux, or Mac OS X +* link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[Oracle Java SE 8] (Java 6 or newer is required) +* link:http://www.eclipse.org/downloads/[Eclipse IDE for Java EE Developers] +* link:http://tomcat.apache.org/[Apache Tomcat 8.0 (Core)] +* link:http://www.getfirefox.com/[Mozilla Firefox] browser +* link:http://www.getfirebug.com/[Firebug] debug tool (optional) +* link:http://vaadin.com/download/[Vaadin Framework] + +The above reference toolchain is a good choice of tools, but you can use almost +any tools you are comfortable with. + +We recommend using Java 8 for Vaadin development, but you need to make sure that +your entire toolchain supports it. + +[[figure.toolchain]] +.Development Toolchain and Process +image::img/toolchain-hi.png[width=70%] + +<> illustrates the development toolchain. You develop your +application as an Eclipse project. The project must include, in addition to your +source code, the Vaadin libraries. It can also include project-specific themes. + +You need to compile and deploy a project to a web container before you can use +it. You can deploy a project through the Web Tools Platform (WTP) for Eclipse +(included in the Eclipse EE package), which allows automatic deployment of web +applications from Eclipse. You can also deploy a project manually, by creating a +web application archive (WAR) and deploying it to the web container. diff --git a/documentation/installing/original-drawings/Makefile b/documentation/installing/original-drawings/Makefile new file mode 100644 index 0000000000..44e9b07461 --- /dev/null +++ b/documentation/installing/original-drawings/Makefile @@ -0,0 +1,13 @@ +IMAGES = installation-steps installation-eclipse installation-netbeans + +SRCIMAGES := $(foreach file, $(IMAGES), $(file).svg) +TRGIMAGES_HI := $(foreach file, $(IMAGES), ../img/$(file)-hi.png) +TRGIMAGES_LO := $(foreach file, $(IMAGES), ../img/$(file)-lo.png) + +images: $(TRGIMAGES_HI) FORCE +# Just do low now $(TRGIMAGES_LO) + +$(TRGIMAGES_HI): ../img/%-hi.png: %.svg + inkscape --export-png $@ --export-dpi=150 --export-area-drawing $< + +FORCE: diff --git a/documentation/installing/original-drawings/installation-eclipse.svg b/documentation/installing/original-drawings/installation-eclipse.svg new file mode 100644 index 0000000000..40baf66dd5 --- /dev/null +++ b/documentation/installing/original-drawings/installation-eclipse.svg @@ -0,0 +1,536 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + OnWindows + + + OnOS X + + + OnLinux + + + + + + + InstallEclipse + + + + + + + + Install theVaadin Plugin + Install Vaadin Designer + + + + + ApacheTomcat + + + TomEE + + + Wildfly + + + GlassFish + + + Other + + + + + + Configurea Server + + GoCreate a Project + StartHere + diff --git a/documentation/installing/original-drawings/installation-netbeans.svg b/documentation/installing/original-drawings/installation-netbeans.svg new file mode 100644 index 0000000000..d1f66a3852 --- /dev/null +++ b/documentation/installing/original-drawings/installation-netbeans.svg @@ -0,0 +1,334 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + OnWindows + + + OnOS X + + + OnLinux + + + + + + + InstallNetBeans + + + + + + + + Install theVaadin Plugin + + GoCreate a Project + StartHere + diff --git a/documentation/installing/original-drawings/installation-steps-constellation.svg b/documentation/installing/original-drawings/installation-steps-constellation.svg new file mode 100644 index 0000000000..7716b64f6c --- /dev/null +++ b/documentation/installing/original-drawings/installation-steps-constellation.svg @@ -0,0 +1,7259 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + On Windows On OS X On Linux InstallJDK Eclipse NetBeans IntelliJ IDEA Install an IDE Install aServer InstallVaadinPlugin FireBug ApacheTomcat TomEE GlassFish Other δ γ β α ε InstallOtherTools + M103 M52 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/installing/original-drawings/installation-steps.svg b/documentation/installing/original-drawings/installation-steps.svg new file mode 100644 index 0000000000..2af7752bd3 --- /dev/null +++ b/documentation/installing/original-drawings/installation-steps.svg @@ -0,0 +1,664 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + OnWindows + + + OnOS X + + + OnLinux + + + + + + + InstallJDK + + + + + EclipseIDE + + + NetBeansIDE + + + IntelliJIDEA + + + + + + Install an IDE + + + + ApacheTomcat + + + TomEE + + + Wildfly + + + GlassFish + + + Other + + + + + + Install aServer + + + + Firebug + + + + + + + Other Tools + + + GoCreate a Project + StartHere + diff --git a/documentation/installing/original-drawings/steps-constellation.png b/documentation/installing/original-drawings/steps-constellation.png new file mode 100644 index 0000000000..5e760d6fbe Binary files /dev/null and b/documentation/installing/original-drawings/steps-constellation.png differ diff --git a/documentation/installing/original-drawings/steps-constellation.svg b/documentation/installing/original-drawings/steps-constellation.svg new file mode 100644 index 0000000000..33cc6ec4a0 --- /dev/null +++ b/documentation/installing/original-drawings/steps-constellation.svg @@ -0,0 +1,6812 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + You Are Here + FireBug Apache Tomcat TomEE Wildfly GlassFish Other + + + + + + + + + + + + + + + + + + + + + + + + + + + Windows OS χ Linux InstallJDK Eclipse NetBeans IntelliJ IDEA Install an IDE Install aServer InstallOtherTools Start Here FireBug + diff --git a/documentation/installing/original-drawings/toolchain.svg b/documentation/installing/original-drawings/toolchain.svg new file mode 100644 index 0000000000..63148883f3 --- /dev/null +++ b/documentation/installing/original-drawings/toolchain.svg @@ -0,0 +1,1149 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + User Project Developer Tools + + + + Eclipse IDE (optional) + + + Java SDK + Web Application (WAR) + + VaadinLibrary & Themes + + + UserSources & Themes + + + VaadinLibrary & Themes + + + User Executable& Themes + + + Apache Tomcat or any other web container + Application Server + + + Mozilla Firefox or any otherbrowser + + + Firebug Plugin (optional) + + + + + Vaadin Plugin (optional) + Deploy and Control Compile and Package + + diff --git a/documentation/introduction/intro-eclipse.asciidoc b/documentation/introduction/intro-eclipse.asciidoc index 09a8c50570..ef7a642af1 100644 --- a/documentation/introduction/intro-eclipse.asciidoc +++ b/documentation/introduction/intro-eclipse.asciidoc @@ -27,6 +27,6 @@ Downloading the installation package that contains the JARs or defining Vaadin a *_Vaadin Designer_* is a commercial Eclipse plug-in that enables visual editing of Vaadin UIs and composites. See <> for its complete reference. -Installation of the Eclipse plug-in is covered in <>. -The creation of a new Vaadin project using the plug-in is covered in <>. +Installation of the Eclipse IDE and the plug-in is covered in <>. +The creation of a new Vaadin project using the plug-in is covered in <>. See <> and <> for instructions on using the different features of the plug-in. -- cgit v1.2.3 From 3db9dc11b20c8c3ea256cd20478c70b07642cea7 Mon Sep 17 00:00:00 2001 From: Marko Gronroos Date: Thu, 17 Mar 2016 17:46:59 +0200 Subject: Fixed some broken xrefs. #19639 Change-Id: Ia509c4426a7632c0a9471ec62bd32ea51273b4cb --- .../getting-started/getting-started-first-project.asciidoc | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) (limited to 'documentation/getting-started') diff --git a/documentation/getting-started/getting-started-first-project.asciidoc b/documentation/getting-started/getting-started-first-project.asciidoc index f1adf842c3..0ec7ed9c58 100644 --- a/documentation/getting-started/getting-started-first-project.asciidoc +++ b/documentation/getting-started/getting-started-first-project.asciidoc @@ -21,10 +21,8 @@ Vaadin Plugin. The task will include the following steps: 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 -<>. +This walkthrough assumes that you have already installed the Eclipse IDE, the Vaadin Plugin, and a development server, as instructed in +<>. ifdef::web[] [[getting-started.first-project.ivy]] @@ -32,7 +30,7 @@ ifdef::web[] 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 <>._ +_The following describes the creation of an Ivy project. The upcoming version of the Eclipse plug-in creates Maven projects. For that, see <>._ endif::web[] ifdef::web[] -- cgit v1.2.3 From ef406ae250aa650a52111a60369d9f0796714b00 Mon Sep 17 00:00:00 2001 From: Marko Gronroos Date: Fri, 18 Mar 2016 15:52:20 +0200 Subject: Fixed some missing images and broken xrefs, as well as problems in the getting-started chapter (#19639). Change-Id: Ie8e371c059f70600bafcf781938ef35878f41324 --- .../advanced/advanced-architecture.asciidoc | 40 +- documentation/advanced/advanced-debug.asciidoc | 6 +- .../advanced/img/three-layer-architecture-hi.png | Bin 0 -> 39007 bytes documentation/advanced/original-drawings/Makefile | 13 + .../original-drawings/three-layer-architecture.svg | 1069 ++++++++++++++++ .../clientside/clientside-widget.asciidoc | 7 +- documentation/clientside/img/gwt-widgets-hi.png | Bin 0 -> 190196 bytes .../clientside/original-drawings/Makefile | 13 + .../clientside/original-drawings/gwt-widgets.svg | 1337 ++++++++++++++++++++ .../getting-started-archetypes.asciidoc | 2 +- .../getting-started/getting-started-maven.asciidoc | 32 +- .../getting-started-netbeans.asciidoc | 20 +- .../img/netbeans-created-annotated-hi.png | Bin 99367 -> 100861 bytes .../netbeans-created-annotated.svg | 2 +- .../gwt/original-drawings/gwt-widgets.svg | 1337 -------------------- documentation/installing/installing-eclipse.adoc | 2 - documentation/portal/img/project-new-portlet-1.png | Bin 0 -> 51283 bytes documentation/portal/img/project-new-portlet-3.png | Bin 0 -> 43571 bytes 18 files changed, 2474 insertions(+), 1406 deletions(-) create mode 100644 documentation/advanced/img/three-layer-architecture-hi.png create mode 100644 documentation/advanced/original-drawings/Makefile create mode 100644 documentation/advanced/original-drawings/three-layer-architecture.svg create mode 100644 documentation/clientside/img/gwt-widgets-hi.png create mode 100644 documentation/clientside/original-drawings/Makefile create mode 100644 documentation/clientside/original-drawings/gwt-widgets.svg delete mode 100644 documentation/gwt/original-drawings/gwt-widgets.svg create mode 100644 documentation/portal/img/project-new-portlet-1.png create mode 100644 documentation/portal/img/project-new-portlet-3.png (limited to 'documentation/getting-started') diff --git a/documentation/advanced/advanced-architecture.asciidoc b/documentation/advanced/advanced-architecture.asciidoc index 437c6f4a1d..219443b470 100644 --- a/documentation/advanced/advanced-architecture.asciidoc +++ b/documentation/advanced/advanced-architecture.asciidoc @@ -29,14 +29,13 @@ model and the "business logic" of the application, typically as beans or POJOs. A user interface is built on top of the domain model, in our context with the Vaadin Framework. The Vaadin user interface could be bound directly to the data model through the Vaadin Data Model, described in -<>. Beneath the domain model lies a data store, such as a -relational database. The dependencies between the layers are restricted so that -a higher layer may depend on a lower one, but never the other way around. +<>. +Beneath the domain model lies a data store, such as a relational database. +The dependencies between the layers are restricted so that a higher layer may depend on a lower one, but never the other way around. [[figure.advanced.architecture.layering]] -.Three-Layer Architecture -image::img/three-layer-architecture-hi.png[] +.Three-layer architecture +image::img/three-layer-architecture-hi.png[width=80%] An __application layer__ (or __service layer__) is often distinguished from the domain layer, offering the domain logic as a service, which can be used by the @@ -65,8 +64,8 @@ implementation better than in MVC and allows easier unit testing of the presenter and model. [[figure.advanced.architecture.mvp]] -.Model-View-Presenter Pattern -image::img/mvp-pattern-hi.png[] +.Model-View-Presenter pattern +image::img/mvp-pattern-hi.png[width=60%] <> illustrates the MVP pattern with a simple calculator. The domain model is realized in the [classname]#Calculator# class, @@ -88,10 +87,10 @@ the following example: // Create the model and the Vaadin view implementation CalculatorModel model = new CalculatorModel(); CalculatorViewImpl view = new CalculatorViewImpl(); - + // The presenter binds the model and view together new CalculatorPresenter(model, view); - + // The view implementation is a Vaadin component layout.addComponent(view); ---- @@ -111,7 +110,7 @@ for manipulating it. /** The model **/ class CalculatorModel { private double value = 0.0; - + public void clear() { value = 0.0; } @@ -128,11 +127,11 @@ class CalculatorModel { if (arg != 0.0) value /= arg; } - + public double getValue() { return value; } - + public void setValue(double value) { this.value = value; } @@ -181,7 +180,7 @@ class CalculatorViewImpl extends CustomComponent // Create a result label that spans over all // the 4 columns in the first row layout.addComponent(display, 0, 0, 3, 0); - + // The operations for the calculator in the order // they appear on the screen (left to right, top // to bottom) @@ -196,7 +195,7 @@ class CalculatorViewImpl extends CustomComponent setCompositionRoot(layout); } - + public void setDisplay(double value) { display.setValue(Double.toString(value)); } @@ -239,13 +238,13 @@ class CalculatorPresenter private double current = 0.0; private char lastOperationRequested = 'C'; - + public CalculatorPresenter(CalculatorModel model, CalculatorView view) { this.model = model; this.view = view; - - view.setDisplay(current); + + view.setDisplay(current); view.addListener(this); } @@ -291,8 +290,3 @@ class CalculatorPresenter In the above example, we held some state information in the presenter. Alternatively, we could have had an intermediate controller between the presenter and the model to handle the low-level button logic. - - - - - diff --git a/documentation/advanced/advanced-debug.asciidoc b/documentation/advanced/advanced-debug.asciidoc index 5415d0655e..3bbd6eb931 100644 --- a/documentation/advanced/advanced-debug.asciidoc +++ b/documentation/advanced/advanced-debug.asciidoc @@ -154,8 +154,8 @@ currently visible UI and makes a report of possible layout related problems. All detected layout problems are displayed in the log and also printed to the console. -[[]] -.Debug Window Showing the Result of Layout Analysis. +[[figure.advanced.debug.hierarchy.analyze]] +.Debug window showing the result of layout analysis. image::img/debug-window-analyze-layouts.png[] Clicking on a reported problem highlights the component with the problem in the @@ -166,7 +166,7 @@ relative size inside a container (layout) that has undefined size in the particular direction (height or width). For example, adding a [classname]#Button# with 100% width inside a [classname]#VerticalLayout# with undefined width. In such a case, the error would look as shown in -<>. +<>. [classname]#CustomLayout# components can not be analyzed in the same way as other layouts. For custom layouts, the button analyzes all contained diff --git a/documentation/advanced/img/three-layer-architecture-hi.png b/documentation/advanced/img/three-layer-architecture-hi.png new file mode 100644 index 0000000000..dbdd8a3e49 Binary files /dev/null and b/documentation/advanced/img/three-layer-architecture-hi.png differ diff --git a/documentation/advanced/original-drawings/Makefile b/documentation/advanced/original-drawings/Makefile new file mode 100644 index 0000000000..ea22c86fac --- /dev/null +++ b/documentation/advanced/original-drawings/Makefile @@ -0,0 +1,13 @@ +IMAGES = three-layer-architecture + +SRCIMAGES := $(foreach file, $(IMAGES), $(file).svg) +TRGIMAGES_HI := $(foreach file, $(IMAGES), ../img/$(file)-hi.png) +TRGIMAGES_LO := $(foreach file, $(IMAGES), ../img/$(file)-lo.png) + +images: $(TRGIMAGES_HI) FORCE +# Just do low now $(TRGIMAGES_LO) + +$(TRGIMAGES_HI): ../img/%-hi.png: %.svg + inkscape --export-png $@ --export-dpi=150 --export-area-drawing $< + +FORCE: diff --git a/documentation/advanced/original-drawings/three-layer-architecture.svg b/documentation/advanced/original-drawings/three-layer-architecture.svg new file mode 100644 index 0000000000..64e3792e7c --- /dev/null +++ b/documentation/advanced/original-drawings/three-layer-architecture.svg @@ -0,0 +1,1069 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + Presentation Layer + + + class Comet { int id; String name; ...} + Domain Layer + + + Data Access Layer CREATE TABLE Comets ( id INTEGER PRIMARY KEY, name VARCHAR(20))INSERT INTO Comets (id, name) VALUES (1, 'Halley');... + + + + + + + diff --git a/documentation/clientside/clientside-widget.asciidoc b/documentation/clientside/clientside-widget.asciidoc index ed911a46b4..2fab75ed18 100644 --- a/documentation/clientside/clientside-widget.asciidoc +++ b/documentation/clientside/clientside-widget.asciidoc @@ -22,13 +22,12 @@ hierarchy is illustrated in <>. Please see the GWT API documentation for a complete description of the widget classes. [[figure.clientside.widgets]] -.GWT Widget Base Class Hierarchy +.GWT widget base class hierarchy image::img/gwt-widgets-hi.png[] For example, we could extend the [classname]#Label# widget to display some custom text. - ---- package com.example.myapp.client; @@ -70,7 +69,3 @@ public class MyEntryPoint implements EntryPoint { } } ---- - - - - diff --git a/documentation/clientside/img/gwt-widgets-hi.png b/documentation/clientside/img/gwt-widgets-hi.png new file mode 100644 index 0000000000..e09b60c422 Binary files /dev/null and b/documentation/clientside/img/gwt-widgets-hi.png differ diff --git a/documentation/clientside/original-drawings/Makefile b/documentation/clientside/original-drawings/Makefile new file mode 100644 index 0000000000..5479a473e9 --- /dev/null +++ b/documentation/clientside/original-drawings/Makefile @@ -0,0 +1,13 @@ +IMAGES = gwt-widgets + +SRCIMAGES := $(foreach file, $(IMAGES), $(file).svg) +TRGIMAGES_HI := $(foreach file, $(IMAGES), ../img/$(file)-hi.png) +TRGIMAGES_LO := $(foreach file, $(IMAGES), ../img/$(file)-lo.png) + +images: $(TRGIMAGES_HI) FORCE +# Just do low now $(TRGIMAGES_LO) + +$(TRGIMAGES_HI): ../img/%-hi.png: %.svg + inkscape --export-png $@ --export-dpi=150 --export-area-drawing $< + +FORCE: diff --git a/documentation/clientside/original-drawings/gwt-widgets.svg b/documentation/clientside/original-drawings/gwt-widgets.svg new file mode 100644 index 0000000000..258fa50172 --- /dev/null +++ b/documentation/clientside/original-drawings/gwt-widgets.svg @@ -0,0 +1,1337 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + My Widget + Google Web Toolkit + + + Widget + + + + + UIObject + + + + + FocusWidget + + + + Composite + + + + + Panel + + + + + + + + ? + + + + ? + + + + ? + + + + ? + + + + + ComplexPanel + + + + SimplePanel + + + + HTMLTable + + + + + + FileUpload + Hidden + Image + Label + MenuBar + Hyperlink + TabBar + TabPanel + DisclosurePanel + SuggestBox + TextBoxBase + ButtonBase + ListBox + + + + diff --git a/documentation/getting-started/getting-started-archetypes.asciidoc b/documentation/getting-started/getting-started-archetypes.asciidoc index fbb75093e1..18d1eda56d 100644 --- a/documentation/getting-started/getting-started-archetypes.asciidoc +++ b/documentation/getting-started/getting-started-archetypes.asciidoc @@ -27,7 +27,7 @@ It has two modules: one for the add-on and another for a demo application. `vaadin-archetype-touchkit`:: A mobile development starter project using Vaadin TouchKit. -See <>. +See <>. Notice that this archetype uses the AGPL-licensed version of TouchKit, which requires that your project must also be licensed under the AGPL license. `vaadin-archetype-liferay-portlet`:: diff --git a/documentation/getting-started/getting-started-maven.asciidoc b/documentation/getting-started/getting-started-maven.asciidoc index 79f3b2febb..5d4618cb94 100644 --- a/documentation/getting-started/getting-started-maven.asciidoc +++ b/documentation/getting-started/getting-started-maven.asciidoc @@ -46,34 +46,12 @@ The parameters are as follows: archetypes. [parameter]#archetypeArtifactId#:: The archetype ID. -Vaadin 7 currently supports the following archetypes: +See the list of available archetypes in <>. -`vaadin-archetype-application`;; -A single-module project for simple applications. -Good for quick demos and trying out Vaadin. - -`vaadin-archetype-application-multimodule`;; -A complete Vaadin application development setup. -It features separate production and development profiles. - -`vaadin-archetype-application-example`;; -An example CRUD web application using multi-module project setup. - -`vaadin-archetype-widget`;; -A multi-module project for a new Vaadin add-on. -It has two modules: one for the add-on and another for a demo application. - -`vaadin-archetype-touchkit`;; -A mobile development starter project using Vaadin TouchKit. -See <>. -Notice that this archetype uses the AGPL-licensed version of TouchKit, which requires that your project must also be licensed under the AGPL license. - -`vaadin-archetype-liferay-portlet`;; -A portlet development setup for the open-source Liferay portal. - -[parameter]#archetypeVersion#:: Version of the archetype to use. This should be [literal]#++LATEST++# for normal -Vaadin releases. For prerelease versions it should be the exact version number, -such as [literal]#++7.5.3++#. +[parameter]#archetypeVersion#:: +Version of the archetype to use. +This should be [literal]#++LATEST++# for normal Vaadin releases. +For prerelease versions it should be the exact version number, such as [literal]#++7.6.4++#. [parameter]#groupId#:: A Maven group ID for your project. It is normally your organization domain name in reverse order, such as com.example. The group ID is also used as a prefix for diff --git a/documentation/getting-started/getting-started-netbeans.asciidoc b/documentation/getting-started/getting-started-netbeans.asciidoc index eff1697243..f5fa0afb14 100644 --- a/documentation/getting-started/getting-started-netbeans.asciidoc +++ b/documentation/getting-started/getting-started-netbeans.asciidoc @@ -59,7 +59,7 @@ Creating the project can take a while as Maven loads all the needed dependencies. [[getting-started.netbeans.exploring]] -== Exploring a Project +== Exploring the Project The project wizard 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 <>. @@ -68,6 +68,14 @@ The project hierarchy shown in the Project Explorer is shown in <> for information about themes. + +[filename]#MyUI.java#:: +The UI class, which is the main entry-point of your application. +See <> for information about the basic structure of Vaadin applications. + 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. @@ -78,16 +86,16 @@ Once created, you can run it in a server as follows. . In [guilabel]#Projects# tab, select the project and click in the [guilabel]#Run Project# button in the tool bar (or press kbd:[F6]). -. In the [guilabel]#Select deployment server#, select a server from the [guilabel]#Server# list. -It should show either GlassFish or Apache Tomcat, depending on what you chose in NetBeans installation. +. In the [guilabel]#Select deployment server# window, select a server from the [guilabel]#Server# list. +It should show either GlassFish or Apache Tomcat or both, depending on what you chose in NetBeans installation. + -image::img/netbeans-server.png[width=60%] +image::img/netbeans-server.png[width=75%] + Also, select [guilabel]#Remember Permanently# if you want to use the same server also in future while developing applications. + Click [guibutton]#OK#. -. -It will compile the widget set at this point, which may take a while. ++ +The widget set will be compiled at this point, which may take a while. If all goes well, NetBeans starts the server in port 8080 and, depending on your system configuration, launches the default browser to display the web diff --git a/documentation/getting-started/img/netbeans-created-annotated-hi.png b/documentation/getting-started/img/netbeans-created-annotated-hi.png index fd94e88321..5abea08c58 100644 Binary files a/documentation/getting-started/img/netbeans-created-annotated-hi.png and b/documentation/getting-started/img/netbeans-created-annotated-hi.png differ diff --git a/documentation/getting-started/original-drawings/netbeans-created-annotated.svg b/documentation/getting-started/original-drawings/netbeans-created-annotated.svg index 3b87ce23e0..ae0176f25b 100644 --- a/documentation/getting-started/original-drawings/netbeans-created-annotated.svg +++ b/documentation/getting-started/original-drawings/netbeans-created-annotated.svg @@ -297,7 +297,7 @@ sodipodi:role="line" id="tspan13163-0" x="354.74399" - y="839.23932">The widget set + y="839.23932">The widget set definition - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - - My Widget - Google Web Toolkit - - - Widget - - - - - UIObject - - - - - FocusWidget - - - - Composite - - - - - Panel - - - - - - - - ? - - - - ? - - - - ? - - - - ? - - - - - ComplexPanel - - - - SimplePanel - - - - HTMLTable - - - - - - FileUpload - Hidden - Image - Label - MenuBar - Hyperlink - TabBar - TabPanel - DisclosurePanel - SuggestBox - TextBoxBase - ButtonBase - ListBox - - - - diff --git a/documentation/installing/installing-eclipse.adoc b/documentation/installing/installing-eclipse.adoc index 244a2a7b7d..8139c1d164 100644 --- a/documentation/installing/installing-eclipse.adoc +++ b/documentation/installing/installing-eclipse.adoc @@ -86,10 +86,8 @@ You can install the plugin as follows: . Select "Help > Install New Software...". . Add the Vaadin plugin update site by clicking [guibutton]#Add...# button. - + image::img/plugin-install-addsite.png[] - + Enter a name such as "Vaadin Update Site" and the URL of the update site: http://vaadin.com/eclipse. If you want or need to use the latest unstable diff --git a/documentation/portal/img/project-new-portlet-1.png b/documentation/portal/img/project-new-portlet-1.png new file mode 100644 index 0000000000..e1ef5837d5 Binary files /dev/null and b/documentation/portal/img/project-new-portlet-1.png differ diff --git a/documentation/portal/img/project-new-portlet-3.png b/documentation/portal/img/project-new-portlet-3.png new file mode 100644 index 0000000000..d8eeaa71bc Binary files /dev/null and b/documentation/portal/img/project-new-portlet-3.png differ -- cgit v1.2.3