From 99d6de546c74f0eed230ea8253dda6b85109d2e7 Mon Sep 17 00:00:00 2001 From: Markus Koivisto Date: Fri, 22 Jan 2016 14:55:18 +0200 Subject: Add documentation to master branch Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674 --- .../chapter-getting-started.asciidoc | 27 + .../getting-started-eclipse.asciidoc | 120 ++ .../getting-started-environment.asciidoc | 238 ++++ .../getting-started-first-project.asciidoc | 323 ++++++ .../getting-started/getting-started-idea.asciidoc | 260 +++++ .../getting-started-libraries.asciidoc | 75 ++ .../getting-started/getting-started-maven.asciidoc | 133 +++ .../getting-started-netbeans.asciidoc | 61 ++ .../getting-started-overview.asciidoc | 30 + .../getting-started-package.asciidoc | 65 ++ .../getting-started/getting-started-scala.asciidoc | 110 ++ .../img/codingtips-automaticimports.png | Bin 0 -> 20450 bytes .../img/codingtips-codecompletion.png | Bin 0 -> 35622 bytes .../getting-started/img/debuggingMyProject.png | Bin 0 -> 137355 bytes documentation/getting-started/img/firebug.png | Bin 0 -> 59376 bytes .../img/idea-maven-newproject-1.png | Bin 0 -> 48841 bytes .../img/idea-maven-newproject-2.png | Bin 0 -> 11459 bytes .../img/idea-maven-newproject-3.png | Bin 0 -> 10116 bytes .../img/idea-maven-newproject-4.png | Bin 0 -> 55547 bytes .../img/idea-maven-newproject-5.png | Bin 0 -> 25660 bytes .../getting-started/img/idea-maven-run-1.png | Bin 0 -> 26057 bytes .../getting-started/img/idea-maven-run-2.png | Bin 0 -> 2793 bytes .../getting-started/img/idea-newproject-1.png | Bin 0 -> 47846 bytes .../getting-started/img/idea-newproject-2.png | Bin 0 -> 48811 bytes .../getting-started/img/idea-newproject-3.png | Bin 0 -> 47603 bytes .../getting-started/img/idea-newproject-4.png | Bin 0 -> 54209 bytes .../getting-started/img/idea-server-1.png | Bin 0 -> 10365 bytes .../getting-started/img/idea-server-2.png | Bin 0 -> 36365 bytes .../img/ivyde-install-available.png | Bin 0 -> 63226 bytes .../getting-started/img/maven-project-created.png | Bin 0 -> 18769 bytes .../getting-started/img/myproject-created.png | Bin 0 -> 21785 bytes .../getting-started/img/myproject-new-vaadin.png | Bin 0 -> 32682 bytes .../getting-started/img/myproject-settings.png | Bin 0 -> 50386 bytes .../getting-started/img/myproject-vaadin.png | Bin 0 -> 45886 bytes .../getting-started/img/myproject-web.png | Bin 0 -> 22378 bytes .../img/netbeans-maven-newproject-name.png | Bin 0 -> 35940 bytes .../getting-started/img/plugin-install-addsite.png | Bin 0 -> 14375 bytes .../img/plugin-install-available.png | Bin 0 -> 52009 bytes .../getting-started/img/runningMyProject.png | Bin 0 -> 25713 bytes .../getting-started/img/tomcat-startserver-1.png | Bin 0 -> 13794 bytes .../getting-started/img/tomcat-startserver-2.png | Bin 0 -> 49846 bytes .../getting-started/img/tomcat-startserver-3.png | Bin 0 -> 29085 bytes .../getting-started/img/tomcat-startserver-4.png | Bin 0 -> 18603 bytes .../getting-started/img/tomcat-startserver-5.png | Bin 0 -> 18426 bytes documentation/getting-started/img/toolchain-hi.png | Bin 0 -> 227400 bytes documentation/getting-started/img/toolchain-lo.png | Bin 0 -> 58261 bytes .../original-drawings/toolchain.svg | 1149 ++++++++++++++++++++ 47 files changed, 2591 insertions(+) create mode 100644 documentation/getting-started/chapter-getting-started.asciidoc create mode 100644 documentation/getting-started/getting-started-eclipse.asciidoc create mode 100644 documentation/getting-started/getting-started-environment.asciidoc create mode 100644 documentation/getting-started/getting-started-first-project.asciidoc create mode 100644 documentation/getting-started/getting-started-idea.asciidoc create mode 100644 documentation/getting-started/getting-started-libraries.asciidoc create mode 100644 documentation/getting-started/getting-started-maven.asciidoc create mode 100644 documentation/getting-started/getting-started-netbeans.asciidoc create mode 100644 documentation/getting-started/getting-started-overview.asciidoc create mode 100644 documentation/getting-started/getting-started-package.asciidoc create mode 100644 documentation/getting-started/getting-started-scala.asciidoc create mode 100644 documentation/getting-started/img/codingtips-automaticimports.png create mode 100644 documentation/getting-started/img/codingtips-codecompletion.png create mode 100644 documentation/getting-started/img/debuggingMyProject.png create mode 100644 documentation/getting-started/img/firebug.png create mode 100644 documentation/getting-started/img/idea-maven-newproject-1.png create mode 100644 documentation/getting-started/img/idea-maven-newproject-2.png create mode 100644 documentation/getting-started/img/idea-maven-newproject-3.png create mode 100644 documentation/getting-started/img/idea-maven-newproject-4.png create mode 100644 documentation/getting-started/img/idea-maven-newproject-5.png create mode 100644 documentation/getting-started/img/idea-maven-run-1.png create mode 100644 documentation/getting-started/img/idea-maven-run-2.png create mode 100644 documentation/getting-started/img/idea-newproject-1.png create mode 100644 documentation/getting-started/img/idea-newproject-2.png create mode 100644 documentation/getting-started/img/idea-newproject-3.png create mode 100644 documentation/getting-started/img/idea-newproject-4.png create mode 100644 documentation/getting-started/img/idea-server-1.png create mode 100644 documentation/getting-started/img/idea-server-2.png create mode 100644 documentation/getting-started/img/ivyde-install-available.png create mode 100644 documentation/getting-started/img/maven-project-created.png create mode 100644 documentation/getting-started/img/myproject-created.png create mode 100644 documentation/getting-started/img/myproject-new-vaadin.png create mode 100644 documentation/getting-started/img/myproject-settings.png create mode 100644 documentation/getting-started/img/myproject-vaadin.png create mode 100644 documentation/getting-started/img/myproject-web.png create mode 100644 documentation/getting-started/img/netbeans-maven-newproject-name.png create mode 100644 documentation/getting-started/img/plugin-install-addsite.png create mode 100644 documentation/getting-started/img/plugin-install-available.png create mode 100644 documentation/getting-started/img/runningMyProject.png create mode 100644 documentation/getting-started/img/tomcat-startserver-1.png create mode 100644 documentation/getting-started/img/tomcat-startserver-2.png create mode 100644 documentation/getting-started/img/tomcat-startserver-3.png create mode 100644 documentation/getting-started/img/tomcat-startserver-4.png create mode 100644 documentation/getting-started/img/tomcat-startserver-5.png create mode 100644 documentation/getting-started/img/toolchain-hi.png create mode 100644 documentation/getting-started/img/toolchain-lo.png create mode 100644 documentation/getting-started/original-drawings/toolchain.svg (limited to 'documentation/getting-started') diff --git a/documentation/getting-started/chapter-getting-started.asciidoc b/documentation/getting-started/chapter-getting-started.asciidoc new file mode 100644 index 0000000000..9705f0a966 --- /dev/null +++ b/documentation/getting-started/chapter-getting-started.asciidoc @@ -0,0 +1,27 @@ +[[getting-started]] +== Getting Started with Vaadin + +This chapter gives practical instructions for installing the recommended +toolchain, the Vaadin libraries and its dependencies, and creating a new Vaadin +project. + + +include::getting-started-overview.asciidoc[leveloffset=+2] + +include::getting-started-environment.asciidoc[leveloffset=+2] + +include::getting-started-libraries.asciidoc[leveloffset=+2] + +include::getting-started-eclipse.asciidoc[leveloffset=+2] + +include::getting-started-first-project.asciidoc[leveloffset=+2] + +include::getting-started-maven.asciidoc[leveloffset=+2] + +include::getting-started-netbeans.asciidoc[leveloffset=+2] + +include::getting-started-idea.asciidoc[leveloffset=+2] + +include::getting-started-package.asciidoc[leveloffset=+2] + +include::getting-started-scala.asciidoc[leveloffset=+2] diff --git a/documentation/getting-started/getting-started-eclipse.asciidoc b/documentation/getting-started/getting-started-eclipse.asciidoc new file mode 100644 index 0000000000..a380701d6f --- /dev/null +++ b/documentation/getting-started/getting-started-eclipse.asciidoc @@ -0,0 +1,120 @@ +--- +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.libraryupdate]] +== Updating the Vaadin Libraries + +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 new file mode 100644 index 0000000000..118742be38 --- /dev/null +++ b/documentation/getting-started/getting-started-environment.asciidoc @@ -0,0 +1,238 @@ +--- +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]#(path-to-installation-package)/jdk-8u20-linux-x64.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_20 +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# and can be started from +there (by double clicking eclipse.exe). + + +=== Linux / OS X / UNIX + +We recommend that you install Eclipse manually in Linux and other UNIX variants +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, as this makes +installation of plugins 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# +---- ++ +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 new file mode 100644 index 0000000000..d30e8c5187 --- /dev/null +++ b/documentation/getting-started/getting-started-first-project.asciidoc @@ -0,0 +1,323 @@ +--- +title: Creating and Running a Project with Eclipse +order: 5 +layout: page +--- + +[[getting-started.first-project]] += Creating and Running a Project with Eclipse + +This section gives instructions for creating a new Eclipse project using the +Vaadin Plugin. The task will include the following steps: + +. Create a new project + +. Write the source code + +. Configure and start Tomcat (or some other web server) + +. Open a web browser to use the web application + + +We also show how you can debug the application in the debug mode in Eclipse. + +This walkthrough assumes that you have already installed the Vaadin Plugin for +Eclipse and set up your development environment, as instructed in +<>. + +[[getting-started.first-project.creation]] +== Creating the Project + +Let us create the first application project with the tools installed in the +previous section. First, launch Eclipse and follow the following steps: + +. Start creating a new project by selecting from the menu "File > New > Project...". +. In the [guilabel]#New Project# window that opens, select "Vaadin > Vaadin 7 +Project" and click [guibutton]#Next#. + ++ +image::img/myproject-new-vaadin.png[] + +. In the [guilabel]#Vaadin Project# step, you need to set the basic web project +settings. You need to give at least the __project name__ and the runtime; the +default values should be good for the other settings. + ++ +image::img/myproject-settings.png[] + +[guilabel]#Project name#:: Give the project a name. The name should be a valid identifier usable +cross-platform as a filename and inside a URL, so using only lower-case +alphanumerics, underscore, and minus sign is recommended. + +[guilabel]#Use default location#:: Define the directory under which the project is created. The default is under +your workspace folder, and you should normally leave it as it is. You may need +to set the directory, for example, if you are creating an Eclipse project on top +of a version-controlled source tree. + +[guilabel]#Target runtime#:: Define the application server to use for deploying the application. The server +that you have installed, for example Apache Tomcat, should be selected +automatically. If not, click [guibutton]#New# to configure a new server under +Eclipse. + +[guilabel]#Configuration#:: Select the configuration to use; you should normally use the default +configuration for the application server. If you need to modify the project +facets, click [guibutton]#Modify#. The recommended Servlet 3.0 configuration +uses the @WebServlet deployment, while Servlet 2.4 uses the old +[filename]#web.xml# deployment. + +[guilabel]#Deployment configuration#:: This setting defines the environment to which the application will be deployed, +to generate the appropriate project directory layout and configuration files. +The choises are: + +*** [guilabel]#Servlet# (default) +*** [guilabel]#Google App Engine Servlet# +*** [guilabel]#Generic Portlet (Portlet 2.0)# + ++ +The further steps in the New Project Wizard depend on the selected deployment +configuration; the steps listed in this section are for the default servlet +configuration. +ifdef::web[] +See <> 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. + ++ +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. + +[guilabel]#Content Directory#:: The directory containing all the content to be included in the web application +(WAR) that is deployed to the web server. The directory is relative to the root +directory of the project. + + + ++ +You can just accept the defaults and click [guibutton]#Next#. + +. The [guilabel]#Vaadin project# step page has various Vaadin-specific application +settings. If you are trying out Vaadin for the first time, you should not need +to change anything. You can set most of the settings afterwards, except the +creation of the portlet configuration. + ++ +image::img/myproject-vaadin.png[] + +[guilabel]#Create project template#:: Make the wizard create an UI class stub. + +[guilabel]#Application Name#:: A name for the application UI, shown in the title bar of the browser window. + +[guilabel]#Base package name#:: The name of the Java package under which the UI class of the application is to +be placed. + +[guilabel]#Application/UI class name#:: The name of the UI class for the application, in which the user interface is +developed. + +[guilabel]#Portlet version#:: When a portlet version is selected (only Portlet 2.0 is supported), the wizard +will create the files needed for running the application in a portal. See +<> for more information on portlets. + + + ++ +Finally, click [guibutton]#Finish# to create the project. + + + +[[getting-started.first-project.exploring]] +== Exploring the Project + +After the [guilabel]#New Project# wizard exits, it has done all the work for +you: an UI class skeleton has been written to [filename]#src# directory and the +[filename]#WebContent/WEB-INF/web.xml# contains a deployment descriptor. The +project hierarchy shown in the Project Explorer is shown in +<>. + +[[figure.getting-started.first-project.exploring]] +.A New Vaadin Project +image::img/myproject-created.png[] + +The Vaadin libraries and other dependencies are managed by Ivy. Notice that the +libraries are not stored under the project folder, even though they are listed +in the "Java Resources > Libraries > ivy.xml" virtual folder. + +[[getting-started.first-project.exploring.ui]] +=== The UI Class + +The UI class created by the plugin contains the following code: + + +[source, java] +---- +package com.example.myproject; + +import com.vaadin.ui.UI; +... + +@SuppressWarnings("serial") +@Theme("myproject") +public class MyprojectUI extends UI { + + @WebServlet(value = "/*", asyncSupported = true) + @VaadinServletConfiguration( + productionMode = false, + ui = MyprojectUI.class) + public static class Servlet extends VaadinServlet { + } + + @Override + protected void init(VaadinRequest request) { + final VerticalLayout layout = new VerticalLayout(); + layout.setMargin(true); + setContent(layout); + + Button button = new Button("Click Me"); + button.addClickListener(new Button.ClickListener() { + public void buttonClick(ClickEvent event) { + layout.addComponent( + new Label("Thank you for clicking")); + } + }); + layout.addComponent(button); + } +} +---- + +In a Servlet 3.0 project, the deployment is configured with servlet class and a +[literal]#++@WebServlet++# annotation. The stub includes the servlet class as a +static inner class. You may want to refactor it to a separate normal class. + +In a Servlet 2.3 project, you would have a [filename]#web.xml# deployment +descriptor. + +For a more detailed treatment of the deployment, see +<>. + + + +[[getting-started.first-project.coding]] +== Coding Tips for Eclipse + +One of the most useful features in Eclipse is __code completion__. Pressing +kbd:[Ctrl+Space] in the editor will display a pop-up list of possible class name and +method name completions, as shown in +<>, depending on the +context of the cursor position. + +[[figure.getting-started.first-project.coding.codecompletion]] +.Java Code Completion in Eclipse +image::img/codingtips-codecompletion.png[] + +To add an [literal]#++import++# statement for a class, such as +[classname]#Button#, simply press kbd:[Ctrl+Shift+O] or click the red error indicator on +the left side of the editor window. If the class is available in multiple +packages, a list of the alternatives is displayed, as shown in +<>. For server-side +development, you should normally use the classes under the +[package]#com.vaadin.ui# or [package]#com.vaadin.server# packages. You can not +use client-side classes (under [package]#com.vaadin.client#) or GWT classes for +server-side development. + +[[figure.getting-started.first-project.coding.import]] +.Importing Classes Automatically +image::img/codingtips-automaticimports.png[] + + +[[getting-started.first-project.server]] +== Setting Up and Starting the Web Server + +Eclipse IDE for Java EE Developers has the Web Standard Tools package installed, +which supports control of various web servers and automatic deployment of web +content to the server when changes are made to a project. + +Make sure that Tomcat was installed with user permissions. Configuration of the +web server in Eclipse will fail if the user does not have write permissions to +the configuration and deployment directories under the Tomcat installation +directory. + +Follow the following steps. + +. Switch to the Servers tab in the lower panel in Eclipse. List of servers should be empty after Eclipse is installed. Right-click on the empty area in the panel and select "New > Server". + +image::img/tomcat-startserver-1.png[] + + +. Select "Apache > Tomcat v7.0 Server" and set [guilabel]#Server's host name# as [literal]#++localhost++#, which should be the default. If you have only one Tomcat installed, [guilabel]#Server runtime# has only one choice. Click [guibutton]#Next#. + +image::img/tomcat-startserver-2.png[] + + +. Add your project to the server by selecting it on the left and clicking [guibutton]#Add# to add it to the configured projects on the right. Click [guibutton]#Finish#. + +image::img/tomcat-startserver-3.png[] + + +. The server and the project are now installed in Eclipse and are shown in the [guilabel]#Servers# tab. To start the server, right-click on the server and select Debug. To start the server in non-debug mode, select Start. + +image::img/tomcat-startserver-4.png[] + + +. The server starts and the WebContent directory of the project is published to the server on http://localhost:8080/myproject/. + +image::img/tomcat-startserver-5.png[] + + + + +[[getting-started.first-project.run]] +== Running and Debugging + +Starting your application is as easy as selecting [guilabel]#myproject# from the +[guilabel]#Project Explorer# and then "Run > Debug As > Debug on Server". +Eclipse then opens the application in built-in web browser. + +.Running a Vaadin Application +image::img/runningMyProject.png[] + +You can insert break points in the Java code by double-clicking on the left +margin bar of the source code window. For example, if you insert a breakpoint in +the [methodname]#buttonClick()# method and click the [guibutton]#What is the +time?# button, Eclipse will ask to switch to the Debug perspective. Debug +perspective will show where the execution stopped at the breakpoint. You can +examine and change the state of the application. To continue execution, select +Resume from Run menu. + +.Debugging a Vaadin Application +image::img/debuggingMyProject.png[] + +Above, we described how to debug a server-side application. Debugging +client-side applications and widgets is described in +<>. diff --git a/documentation/getting-started/getting-started-idea.asciidoc b/documentation/getting-started/getting-started-idea.asciidoc new file mode 100644 index 0000000000..4461d80656 --- /dev/null +++ b/documentation/getting-started/getting-started-idea.asciidoc @@ -0,0 +1,260 @@ +--- +title: Creating a Project with IntelliJ IDEA +order: 8 +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. + +ifdef::web[] +For more information, see the article " +link:http://wiki.jetbrains.net/intellij/Creating_a_simple_Web_application_and_deploying_it_to_Tomcat[Creating +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". + +. 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. + +. 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 +<>. + +. 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. + ++ +image::img/idea-newproject-1.png[] + ++ +Click [guibutton]#Next#. + +. Select "Web Application > Vaadin" to add Vaadin technology to the project. + +. 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 <>. + +ifdef::web[] ++ +image::img/idea-newproject-3.png[] +endif::web[] + +. Click [guibutton]#Finish#. + + +The project is created with the UI class stub and a [filename]#web.xml# +deployment descriptor. + +image::img/idea-newproject-4.png[] + +The wizard does not currently create a servlet class automatically, and uses +Servlet 2.4 compatible deployment with a [filename]#web.xml# deployment +descriptor. + +[[getting-started.idea.project.running]] +=== Deploying the Project + +To deploy the application to the integrated web server, right-click the +[filename]#index.jsp# file in the project and select [menuchoice]#Run +'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 + +You can choose to create a Maven project in IntelliJ IDEA. This is the +recommended way when using the Community Edition. You will not have the +application server integration, but can deploy the application to an application +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#. + ++ +image::img/idea-maven-newproject-1.png[] + +//<?dbfo-need height="6cm" ?> +. Give a Maven [guilabel]#GroupID#, [guilabel]#ArtifactID#, and a +[guilabel]#Version# for the project, or use the defaults. + ++ +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# +[literal]#++LATEST++# (or a specific version number). + +ifdef::web[] ++ +image::img/idea-maven-newproject-3.png[] +endif::web[] + ++ +Click [guibutton]#OK# in the dialog. + +//<?dbfo-need height="8cm" ?> +. Select the [literal]#++com.vaadin:vaadin-archetype-application++#. + +ifdef::web[] ++ +image::img/idea-maven-newproject-4.png[] +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#. + +ifdef::web[] ++ +image::img/idea-maven-newproject-5.png[] +endif::web[] + + +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. + +[[getting-started.idea.maven.compiling]] +=== Compiling the Project + +To compile a Vaadin application using Maven, you can define a run/debug +configuration to execute a goal such as [literal]#++package++# to build the +deployable WAR package. It will also compile the widget set and theme, if +necessary. See +<> for more details. + +Compilation is included in the following instructions for deploying the +application. + + +[[getting-started.idea.maven.deploying]] +=== Deploying to a Server + +There exists Maven plugins for deploying to various application servers. For +example, to deploy to Apache Tomcat, you can to configure the +[literal]#++tomcat-maven-plugin++# and then execute the +[literal]#++tomcat:deploy++# goal. See the documentation of the plugin that you +use for more details. If no Maven plugin exists for a particular server, you can +always use some lower-level method to deploy the application, such as running an +Ant task. + +In the following, we create a run/debug configuration to build, deploy, and +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. + +. 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. + +ifdef::web[] ++ +image::img/idea-maven-run-1.png[] +endif::web[] + ++ +Click [guibutton]#OK#. + +. Select the run configuration in the toolbar and click the [guibutton]#Run# +button beside it. + +ifdef::web[] ++ +image::img/idea-maven-run-2.png[] +endif::web[] + + +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-libraries.asciidoc b/documentation/getting-started/getting-started-libraries.asciidoc new file mode 100644 index 0000000000..013a4f445c --- /dev/null +++ b/documentation/getting-started/getting-started-libraries.asciidoc @@ -0,0 +1,75 @@ +--- +title: Overview of Vaadin Libraries +order: 3 +layout: page +--- + +[[getting-started.libraries]] += Overview of 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 +<>. ++ +//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. + + + +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 new file mode 100644 index 0000000000..3914e973aa --- /dev/null +++ b/documentation/getting-started/getting-started-maven.asciidoc @@ -0,0 +1,133 @@ +--- +title: Using Vaadin with Maven +order: 6 +layout: page +--- + +[[getting-started.maven]] += Using Vaadin 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 addition to regular Maven, you can use any Maven-compatible build or +dependency management system, such as Ivy or Gradle. For Gradle, see the +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. + +[[getting-started.maven.command-line]] +== Working from Command-Line + +You can create a new Maven project with the following command (given in one +line): + +[subs="normal"] +---- +[prompt]#$# [command]#mvn# archetype:generate \ + -DarchetypeGroupId=com.vaadin \ + -DarchetypeArtifactId=[parameter]#vaadin-archetype-application# \ + -DarchetypeVersion=[replaceable]#7.x.x# \ + -DgroupId=[replaceable]#your.company# \ + -DartifactId=[replaceable]#project-name# \ + -Dversion=[replaceable]#0.1# \ + -Dpackaging=war +---- +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]#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]#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 +the Java package in the sources, so it should be Java compatible - only +alphanumerics and an underscore. + +[parameter]#artifactId#:: Identifier of the artifact, that is, your project. The identifier may contain +alphanumerics, minus, and underscore. It is appended to the group ID to obtain +the Java package name for the sources. For example, if the group ID is +com.example and artifact ID is myproject, the project sources would be placed in +com.example.myproject package. + +[parameter]#version#:: Initial version number of your application. The number must obey the Maven +version numbering format. + +[parameter]#packaging#:: How will the project be packaged. It is normally [literal]#++war++#. + + + +Creating a project can take a while as Maven fetches all the dependencies. The +created project structure is shown in +<>. + +[[figure.getting-started.maven.archetype.created]] +.A New Vaadin Project with Maven +image::img/maven-project-created.png[] + + +[[getting-started.maven.compiling]] +== Compiling and Running the Application + +((("Maven", "compiling", id="term.maven.compiling", range="startofrange"))) + + +Before the application can be deployed, it must be compiled and packaged as a +WAR package. You can do this with the [literal]#++package++# goal as follows: + +[subs="normal"] +---- +[prompt]#$# [command]#mvn# package +---- +The location of the resulting WAR package should be displayed in the command +output. You can then deploy it to your favorite application server. + +The easiest way to run Vaadin applications with Maven is to use the light-weight +Jetty web server. After compiling the package, all you need to do is type: + +[subs="normal"] +---- +[prompt]#$# [command]#mvn# jetty:run +---- +The special goal starts the Jetty server in port 8080 and deploys the +application. You can then open it in a web browser at +http://localhost:8080/project-name. + +(((range="endofrange", startref="term.maven.compiling"))) + +[[getting-started.maven.addons]] +== Using Add-ons and Custom Widget Sets + +((("Maven", "using add-ons", id="term.maven.addons", range="startofrange"))) + + +If you use Vaadin add-ons that include a widget set or make your custom widgets, +you need to enable widget set compilation in the POM. The required configuration +is described in +<>. + + +(((range="endofrange", startref="term.maven.addons"))) +(((range="endofrange", startref="term.maven.creating"))) + + diff --git a/documentation/getting-started/getting-started-netbeans.asciidoc b/documentation/getting-started/getting-started-netbeans.asciidoc new file mode 100644 index 0000000000..6e2fa660de --- /dev/null +++ b/documentation/getting-started/getting-started-netbeans.asciidoc @@ -0,0 +1,61 @@ +--- +title: Creating a Project with NetBeans IDE +order: 7 +layout: page +--- + +[[getting-started.netbeans]] += Creating a Project with 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. + +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 +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 + +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. + +. Select "File > New Project". + +. Select "Maven > Project from Archetype" and click [guibutton]#Next#. + +. Find [literal]#++vaadin-archetype-application++#, select it, and click +[guilabel]#Next#. + +. 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#. + ++ +[[figure.getting-started.netbeans.maven.new-project]] +.Adding a New Maven Project in NetBeans +image::img/netbeans-maven-newproject-name.png[] + + +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#. +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. + + + + diff --git a/documentation/getting-started/getting-started-overview.asciidoc b/documentation/getting-started/getting-started-overview.asciidoc new file mode 100644 index 0000000000..994ca48248 --- /dev/null +++ b/documentation/getting-started/getting-started-overview.asciidoc @@ -0,0 +1,30 @@ +--- +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. + +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 new file mode 100644 index 0000000000..4dbe735958 --- /dev/null +++ b/documentation/getting-started/getting-started-package.asciidoc @@ -0,0 +1,65 @@ +--- +title: Vaadin Installation Package +order: 9 +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. + +You can download the newest Vaadin installation package from the download page +at http://vaadin.com/download/. Please use a ZIP decompression utility available +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]#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 +<>. + + + + +[[getting-started.package.install]] +== Installing the Libraries + +You can install the Vaadin ZIP package in a few simple steps: + +. Copy the JAR files at the package root folder to the [filename]#WEB-APP/lib# web +library folder in the project. Some of the libraries are optional, as explained +in +<>. + +. Also copy the dependency JAR files at the [filename]#lib# folder to the +[filename]#WEB-APP/lib# web library folder in the project. + + +The location of the [filename]#WEB-APP/lib# folder depends on the project +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/getting-started-scala.asciidoc b/documentation/getting-started/getting-started-scala.asciidoc new file mode 100644 index 0000000000..bfd91cc256 --- /dev/null +++ b/documentation/getting-started/getting-started-scala.asciidoc @@ -0,0 +1,110 @@ +--- +title: Using Vaadin with Scala +order: 10 +layout: page +--- + +[[getting-started.scala]] += Using Vaadin with Scala + +You can use Vaadin with any JVM compatible language, such as Scala or Groovy. +There are, however, some caveats related to libraries and project set-up. In the +following, we give instructions for creating a Scala UI in Eclipse, with the +Scala IDE for Eclipse and the Vaadin Plugin for Eclipse. + +. Install the link:http://scala-ide.org/[Scala IDE for Eclipse], either from an +Eclipse update site or as a bundled Eclipse distribution. + +. Open an existing Vaadin Java project or create a new one as outlined in +<>. You can delete the UI class created by +the wizard. + +. Switch to the Scala perspective by clicking the perspective in the upper-right +corner of the Eclipse window. + +. Right-click on the project folder in [guilabel]#Project Explorer# and select +"Configure > Add Scala Nature". + +. The web application needs [filename]#scala-library.jar# in its class path. If +using Scala IDE, you can copy it from somewhere under your Eclipse installation +to the class path of the web application, that is, either to the +[filename]#WebContent/WEB-INF/lib# folder in the project or to the library path +of the application server. If copying outside Eclipse to a project, refresh the +project by selecting it and pressing kbd:[F5]. + ++ +You could also get it with an Ivy or Maven dependency, just make sure that the +version is same as what the Scala IDE uses. + + +You should now be able to create a Scala UI class, such as the following: + + +[source, scala] +---- +@Theme("mytheme") +class MyScalaUI extends UI { + override def init(request: VaadinRequest) = { + val content: VerticalLayout = new VerticalLayout + setContent(content) + + val label: Label = new Label("Hello, world!") + content addComponent label + + // Handle user interaction + content addComponent new Button("Click Me!", + new ClickListener { + override def buttonClick(event: ClickEvent) = + Notification.show("The time is " + new Date) + }) + } +} +---- + +Eclipse and Scala IDE should be able to import the Vaadin classes automatically +when you press kbd:[Ctrl+Shift+O]. + +You need to define the Scala UI class either in a servlet class (in Servlet 3.0 +project) or in a [filename]#web.xml# deployment descriptor, just like described +in +<> for Java UIs. + +ifdef::web[] +The link:https://github.com/henrikerola/scaladin[Scaladin add-on] offers a more +Scala-like API for Vaadin. A Vaadin 7 compatible version is under development. +endif::web[] + +ifdef::web[] +[[getting-started.scala.lambdas]] +== Defining Listeners with Lambda Expressions + +Scala does not support use of lambda expressions for calling functional +interfaces, like Java 8 does. Hence, we can't just use a lambda expression for +the [interfacename]#ClickListener# in the example above. You can, however, +define implicit conversions from lambda expressions to such interface +implementations. For example, for click listeners: + + +[source, scala] +---- +implicit def clickListener(f: ClickEvent => Unit) = + new ClickListener { + override def buttonClick(event: ClickEvent) { + f(event) + } + } +---- + +You could then use a lambda expression as follows: + + +[source, scala] +---- +content addComponent new Button("Click Me!", + (event: ClickEvent) => + Notification.show("The time is " + new Date)) +---- + +endif::web[] diff --git a/documentation/getting-started/img/codingtips-automaticimports.png b/documentation/getting-started/img/codingtips-automaticimports.png new file mode 100644 index 0000000000..1a66204235 Binary files /dev/null and b/documentation/getting-started/img/codingtips-automaticimports.png differ diff --git a/documentation/getting-started/img/codingtips-codecompletion.png b/documentation/getting-started/img/codingtips-codecompletion.png new file mode 100644 index 0000000000..3f648da0bc Binary files /dev/null and b/documentation/getting-started/img/codingtips-codecompletion.png differ diff --git a/documentation/getting-started/img/debuggingMyProject.png b/documentation/getting-started/img/debuggingMyProject.png new file mode 100644 index 0000000000..2baae3d191 Binary files /dev/null and b/documentation/getting-started/img/debuggingMyProject.png differ diff --git a/documentation/getting-started/img/firebug.png b/documentation/getting-started/img/firebug.png new file mode 100644 index 0000000000..81512b615d Binary files /dev/null and b/documentation/getting-started/img/firebug.png differ diff --git a/documentation/getting-started/img/idea-maven-newproject-1.png b/documentation/getting-started/img/idea-maven-newproject-1.png new file mode 100644 index 0000000000..6a24a14ea8 Binary files /dev/null and b/documentation/getting-started/img/idea-maven-newproject-1.png differ diff --git a/documentation/getting-started/img/idea-maven-newproject-2.png b/documentation/getting-started/img/idea-maven-newproject-2.png new file mode 100644 index 0000000000..2f31ac2c35 Binary files /dev/null and b/documentation/getting-started/img/idea-maven-newproject-2.png differ diff --git a/documentation/getting-started/img/idea-maven-newproject-3.png b/documentation/getting-started/img/idea-maven-newproject-3.png new file mode 100644 index 0000000000..b0b56b311a Binary files /dev/null and b/documentation/getting-started/img/idea-maven-newproject-3.png differ diff --git a/documentation/getting-started/img/idea-maven-newproject-4.png b/documentation/getting-started/img/idea-maven-newproject-4.png new file mode 100644 index 0000000000..9dc571499f Binary files /dev/null and b/documentation/getting-started/img/idea-maven-newproject-4.png differ diff --git a/documentation/getting-started/img/idea-maven-newproject-5.png b/documentation/getting-started/img/idea-maven-newproject-5.png new file mode 100644 index 0000000000..1e22e8d6d8 Binary files /dev/null and b/documentation/getting-started/img/idea-maven-newproject-5.png differ diff --git a/documentation/getting-started/img/idea-maven-run-1.png b/documentation/getting-started/img/idea-maven-run-1.png new file mode 100644 index 0000000000..976711c36a Binary files /dev/null and b/documentation/getting-started/img/idea-maven-run-1.png differ diff --git a/documentation/getting-started/img/idea-maven-run-2.png b/documentation/getting-started/img/idea-maven-run-2.png new file mode 100644 index 0000000000..a567bb6661 Binary files /dev/null and b/documentation/getting-started/img/idea-maven-run-2.png differ diff --git a/documentation/getting-started/img/idea-newproject-1.png b/documentation/getting-started/img/idea-newproject-1.png new file mode 100644 index 0000000000..739b210fdc Binary files /dev/null and b/documentation/getting-started/img/idea-newproject-1.png differ diff --git a/documentation/getting-started/img/idea-newproject-2.png b/documentation/getting-started/img/idea-newproject-2.png new file mode 100644 index 0000000000..882a4eed18 Binary files /dev/null and b/documentation/getting-started/img/idea-newproject-2.png differ diff --git a/documentation/getting-started/img/idea-newproject-3.png b/documentation/getting-started/img/idea-newproject-3.png new file mode 100644 index 0000000000..fe35a7c787 Binary files /dev/null and b/documentation/getting-started/img/idea-newproject-3.png differ diff --git a/documentation/getting-started/img/idea-newproject-4.png b/documentation/getting-started/img/idea-newproject-4.png new file mode 100644 index 0000000000..ae14aea8b4 Binary files /dev/null and b/documentation/getting-started/img/idea-newproject-4.png differ diff --git a/documentation/getting-started/img/idea-server-1.png b/documentation/getting-started/img/idea-server-1.png new file mode 100644 index 0000000000..f0e0fb7f9b Binary files /dev/null and b/documentation/getting-started/img/idea-server-1.png differ diff --git a/documentation/getting-started/img/idea-server-2.png b/documentation/getting-started/img/idea-server-2.png new file mode 100644 index 0000000000..2375f44c48 Binary files /dev/null and b/documentation/getting-started/img/idea-server-2.png differ diff --git a/documentation/getting-started/img/ivyde-install-available.png b/documentation/getting-started/img/ivyde-install-available.png new file mode 100644 index 0000000000..9b8500c356 Binary files /dev/null and b/documentation/getting-started/img/ivyde-install-available.png differ diff --git a/documentation/getting-started/img/maven-project-created.png b/documentation/getting-started/img/maven-project-created.png new file mode 100644 index 0000000000..075e2e49ea Binary files /dev/null and b/documentation/getting-started/img/maven-project-created.png differ diff --git a/documentation/getting-started/img/myproject-created.png b/documentation/getting-started/img/myproject-created.png new file mode 100644 index 0000000000..0cebb5f0db Binary files /dev/null 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 new file mode 100644 index 0000000000..e2243d5c1a Binary files /dev/null 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 new file mode 100644 index 0000000000..20d4509317 Binary files /dev/null and b/documentation/getting-started/img/myproject-settings.png differ diff --git a/documentation/getting-started/img/myproject-vaadin.png b/documentation/getting-started/img/myproject-vaadin.png new file mode 100644 index 0000000000..fff616e6fe Binary files /dev/null and b/documentation/getting-started/img/myproject-vaadin.png differ diff --git a/documentation/getting-started/img/myproject-web.png b/documentation/getting-started/img/myproject-web.png new file mode 100644 index 0000000000..ae47d37c0f Binary files /dev/null and b/documentation/getting-started/img/myproject-web.png differ diff --git a/documentation/getting-started/img/netbeans-maven-newproject-name.png b/documentation/getting-started/img/netbeans-maven-newproject-name.png new file mode 100644 index 0000000000..90a1ad517e Binary files /dev/null and b/documentation/getting-started/img/netbeans-maven-newproject-name.png differ diff --git a/documentation/getting-started/img/plugin-install-addsite.png b/documentation/getting-started/img/plugin-install-addsite.png new file mode 100644 index 0000000000..baa36c5416 Binary files /dev/null and b/documentation/getting-started/img/plugin-install-addsite.png differ diff --git a/documentation/getting-started/img/plugin-install-available.png b/documentation/getting-started/img/plugin-install-available.png new file mode 100644 index 0000000000..d9c305de62 Binary files /dev/null and b/documentation/getting-started/img/plugin-install-available.png differ diff --git a/documentation/getting-started/img/runningMyProject.png b/documentation/getting-started/img/runningMyProject.png new file mode 100644 index 0000000000..e4c4ebcd54 Binary files /dev/null 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 new file mode 100644 index 0000000000..3c2693ba01 Binary files /dev/null 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 new file mode 100644 index 0000000000..04ac7d87d0 Binary files /dev/null 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 new file mode 100644 index 0000000000..2cc17876e9 Binary files /dev/null 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 new file mode 100644 index 0000000000..7e704e772b Binary files /dev/null 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 new file mode 100644 index 0000000000..f860a0005b Binary files /dev/null and b/documentation/getting-started/img/tomcat-startserver-5.png differ diff --git a/documentation/getting-started/img/toolchain-hi.png b/documentation/getting-started/img/toolchain-hi.png new file mode 100644 index 0000000000..88d9dfcc4c Binary files /dev/null and b/documentation/getting-started/img/toolchain-hi.png differ diff --git a/documentation/getting-started/img/toolchain-lo.png b/documentation/getting-started/img/toolchain-lo.png new file mode 100644 index 0000000000..e42b94bc2f Binary files /dev/null and b/documentation/getting-started/img/toolchain-lo.png differ diff --git a/documentation/getting-started/original-drawings/toolchain.svg b/documentation/getting-started/original-drawings/toolchain.svg new file mode 100644 index 0000000000..63148883f3 --- /dev/null +++ b/documentation/getting-started/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 + + -- cgit v1.2.3