From 05003bafeb84f8251db6168746893e27bb3b0138 Mon Sep 17 00:00:00 2001 From: Henri Sara Date: Tue, 1 Mar 2016 14:00:23 +0200 Subject: Omit timings in production mode (#19644) * UIDL responses only include server side timing information when not in production mode. * Update documentation accordingly. Change-Id: I961d1fdc96b3d04f22254fcd13a5412f17118b42 --- documentation/advanced/advanced-debug.asciidoc | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'documentation/advanced/advanced-debug.asciidoc') diff --git a/documentation/advanced/advanced-debug.asciidoc b/documentation/advanced/advanced-debug.asciidoc index 9a0d8d7ba8..9731c650af 100644 --- a/documentation/advanced/advanced-debug.asciidoc +++ b/documentation/advanced/advanced-debug.asciidoc @@ -14,14 +14,20 @@ debug features for Vaadin developers: * Debug Window * Display debug information in the Debug Window and server console * On-the-fly compilation of Sass themes +* Timings of server calls for Vaadin TestBench + +It is recommended to always deploy production applications in production mode +for security reasons. [[advanced.debug.mode]] == Enabling the Debug Mode The debug mode is enabled and production mode disabled by default in the UI -templates created with the Eclipse plugin or the Maven archetypes. The debug -mode can be enabled by giving a [parameter]#productionMode=false# parameter to -the Vaadin servlet configuration: +templates created with the Eclipse plugin or the Maven archetypes. Some +archetypes have a separate module and profile for producing a production mode +application. The debug mode can be enabled by giving a +[parameter]#productionMode=false# parameter to the Vaadin servlet +configuration: [subs="normal"] ---- -- cgit v1.2.3 From fa2497f0c63855545b68b29b53d35b17406bf6f2 Mon Sep 17 00:00:00 2001 From: Marko Gronroos 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/advanced/advanced-debug.asciidoc') 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 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/advanced/advanced-debug.asciidoc') 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