----

-title: Installing Commercial Vaadin Add-on Licence

-order: 5

-layout: page

----

-

-[[addons.cval]]

-= Installing Commercial Vaadin Add-on Licence

-

-The commercial Vaadin add-ons require installing a license key before using

-them. The license keys are development licenses and checked during widget set

-compilation, or in Vaadin TestBench when executing tests, so you do not need

-them when deploying the application.

-

-[[addons.cval.obtaining]]

-== Obtaining License Keys

-

-You can purchase add-ons or obtain a free trial key from the Vaadin website. You

-need to register in the website to obtain a key.

-

-You can get license keys from

-link:https://vaadin.com/pro/licenses[vaadin.com/pro/licenses], where you can

-navigate by selecting in the Vaadin website "My Account > Licenses" or directly

-[menuchoice]#Licenses# if you are a Pro Tools subscriber.

-

-[[figure.addons.cval.obtaining]]

-.Obtaining CVAL License

-image::img/cval-pro-licenses-3.png[]

-

-Click on a license key to obtain the purchased or trial key.

-

-[[figure.addons.cval.obtaining]]

-.Obtaining CVAL License Key

-image::img/cval-pro-licenses-code.png[]

-

-

-[[addons.cval.installing]]

-== Installing License Key in License File

-

-To install the license key in a development workstation, you can copy and paste

-it verbatim to a file in your home directory.

-

-License for each product has a separate license file as follows:

-

-Vaadin Charts:: [filename]#.vaadin.charts.developer.license#

-Vaadin Spreadsheet:: [filename]#.vaadin.spreadsheet.developer.license#

-Vaadin TestBench:: [filename]#.vaadin.testbench.developer.license#

-Vaadin TouchKit:: [filename]#.vaadin.touchkit.developer.license#

-

-

-For example, in Linux and OS X:

-

-[subs="normal"]

-----

-[prompt]#$# [command]#echo# "[replaceable]#L1cen5e-c0de#" > [parameter]#~/.vaadin.[replaceable]+++#+++<product>+++#+++.developer.license#

-----

-

-[[addons.cval.systemproperty]]

-== Passing License Key as System Property

-

-You can also pass the key as a system property to the widget set compiler,

-usually with a [literal]#++-D++# option. For example, on the command-line:

-

-[subs="normal"]

-----

-[prompt]#$# [command]#java# -D[parameter]#vaadin.[replaceable]+++#+++<product>+++#+++.developer.license#=[replaceable]#L1cen5e-c0de# ...

-----

-ifdef::web[]

-See link:https://vaadin.com/directory/help/installing-cval-license[the CVAL

-license key installation instructions] for more details.

-endif::web[]

-

-[[addons.cval.systemproperty.environments]]

-=== Passing License Key in Different Environments

-

-How you actually pass the parameter to the widget set compiler depends on the

-development environment and the build system that you use to compile the widget

-set. Below are listed a few typical environments:

-

-Eclipse IDE:: To install the license key for all projects, select "Window > Preferences" and

-navigate to the "Java > Installed JREs" section. Select the JRE version that you

-use for the application and click [guibutton]#Edit#. In the [guilabel]#Default

-VM arguments#, give the [parameter]#-D# expression as shown above.

-

-Apache Ant:: If compiling the project with Apache Ant, you could set the key in the Ant

-script as follows:

-

-

-+

-[subs="normal"]

-----

-<sysproperty key="vaadin.[replaceable]#<product>#.developer.license"

- value="**L1cen5e-c0de**"/>

-----

-+

-However, you should never store license keys in a source repository, so if the

-Ant script is stored in a source repository, you should pass the license key to

-Ant as a property that you then use in the script for the value argument of the

-[literal]#++<sysproperty>++# as follows:

-

-

-+

-[subs="normal"]

-----

-&lt;sysproperty key="vaadin.[replaceable]#&lt;product&gt;#.developer.license"

- value="**${vaadin.[replaceable]#&lt;product&gt;#.developer.license}**"/&gt;

-----

-+

-When invoking Ant from the command-line, you can pass the property with a

-[parameter]#-D# parameter to Ant.

-

-Apache Maven:: If building the project with Apache Maven, you can pass the license key with a

-[literal]#++-D++# parameter to Maven:

-

-

-+

-[subs="normal"]

-----

-[prompt]#$# [command]#mvn# -D[parameter]#vaadin.[replaceable]+++#+++&lt;product&gt;+++#+++.developer.license#=[replaceable]#L1cen5e-c0de# package

-----

-Continuous Integration Systems:: In CIS systems, you can pass the license key to build runners as a system

-property in the build configuration. However, this only passes it to a runner.

-As described above, Ant does not pass it to sub-processes implicitly, so you

-need to forward it explicitly as described earlier.

-

-

-

-

-

-

-

----

-title: Downloading Add-ons from Vaadin Directory

-order: 2

-layout: page

----

-

-[[addons.downloading]]

-= Downloading Add-ons from Vaadin Directory

-

-If you are not using Maven or a Maven-compatible dependency manager such as Ivy,

-or want to manage for your libraries manually, you can download add-on packages

-from the details page of an add-on in Vaadin Directory.

-

-. Select the version; some add-ons have several versions available. The latest is

-shown by default, but you can choose another the version to download from the

-dropdown menu in the header of the details page.

-

-. Click [guibutton]#Download Now# and save the JAR or Zip file on your computer.

-

-. If the add-on is packaged in a Zip package, unzip the package and follow any

-instructions provided inside the package. Typically, you just need to copy a JAR

-file to your web project under the [filename]#WEB-INF/lib# directory.

-

-+

-Note that some add-ons may require other libraries. You can resolve such

-dependencies manually, but we recommend using a dependency manager such as Ivy

-or Maven in your project.

-

-. Update and recompile your project. In Eclipse, select the project and press F5.

-

-. You may need to compile the client-side implementations of the add-on

-components, that is, a __widget set__. This is the case for majority of add-ons,

-except for pure server-side, theme, or data binding add-ons. Compiling the

-widget set depends on the build environment. See <<addons.downloading.ant>>, or

-later in this chapter for instructions for compiling the widget set with Eclipse

-and

-Maven.+

-////

-See &lt;xref linkend="addons.compiling"/&gt; for

-instructions.

-////

-

-. Update the project in your development web server and possibly restart the

-server.

-

-

-[[addons.downloading.ant]]

-== Compiling Widget Sets with an Ant Script

-

-If you need to compile the widget set with an Ant script, you can find a script

-template package at the link:http://vaadin.com/download/[Vaadin download page].

-You can copy the files in the package to your project and, once configured, use

-it by running Ant in the directory.

-

-If you are using an IDE such as Eclipse, __always__ remember to refresh the

-project to synchronize it with the filesystem after compiling the widget set

-outside the IDE.

-

-

-

-

----

-title: Installing Add-ons in Eclipse with Ivy

-order: 3

-layout: page

----

-

-[[addons.eclipse]]

-= Installing Add-ons in Eclipse with Ivy

-

-The Vaadin Plugin for Eclipse uses Apache Ivy to resolve dependencies. The

-dependencies should be listed in the [filename]#ivy.xml# file in the project

-root. The Vaadin Directory allows dowloading add-ons from a Maven repository,

-which can be accessed also by Ivy.

-

-You can also use Ivy to resolve dependencies in an Ant script.

-

-. Open the add-on page in Vaadin Directory.

-

-. Select the version. The latest is shown by default, but you can choose another

-the version from the dropdown menu in the header of the add-on details page.

-

-. Click the [guilabel]#Maven/Ivy# to display the Ivy dependency declaration, as

-illustrated in Figure <<figure.addons.eclipse.ivybutton>>. If the add-on is

-available with multiple licenses, you will be prompted to select a license for

-the dependency.

-

-+

-[[figure.addons.eclipse.ivybutton]]

-.Ivy Dependency Declaration

-image::img/directory-ivy-dependency.png[]

-

-. Open the [filename]#ivysettings.xml# in your Eclipse project either in the XML

-or Ivy Editor (either double-click the file or right-click it and select "Open

-With > Ivy Editor").

-

-+

-Check that the settings file has the [literal]#++<ibiblio>++# entry given in the

-Directory page. It should be, if the file was created by the Vaadin project

-wizard in Eclipse. If not, copy it there.

-

-

-+

-----

-<chain name="default">

- ...

- <ibiblio name="vaadin-addons"

- usepoms="true"

- m2compatible="true"

- root="http://maven.vaadin.com/vaadin-addons"/>

- ...

-</chain>

-----

-+

-If you get Vaadin addons from another repository, such as the local repository

-if you have compiled them yourself, you need to define a resolver for the

-repository in the settings file.

-

-. Open the [filename]#ivy.xml# in your Eclipse project and copy the Ivy dependency

-to inside the [literal]#++dependencies++# element. It should be as follows:

-

-

-+

-[subs="normal"]

-----

-&lt;dependencies&gt;

- ...

- &lt;dependency org="**com.vaadin.addon**"

- name="**vaadin-charts**"

- rev="**1.0.0**"/&gt;

-&lt;/dependencies&gt;

-----

-+

-You can specify either a fixed version number or a dynamic revision tag, such as

-[literal]#++latest.release++#. You can find more information about the

-link:http://ant.apache.org/ivy/history/2.1.0/ivyfile/dependency.html[dependency

-declarations] in Ivy documentation.

-

-+

-If the [filename]#ivy.xml# does not have a [literal]#++<configurations

-defaultconfmapping="default->default">++# defined, you also need to have

-[literal]#++conf="default->default"++# in the dependency to resolve transient

-dependencies correctly.

-

-+

-IvyIDE immediately resolves the dependencies when you save the file.

-

-. Compile the add-on widget set

-////

-, as described in &lt;xref

-linkend="addons.compiling.eclipse"/&gt;.

-////

-by clicking the [guilabel]#Compile Vaadin widgets# button in the toolbar.

-

-+

-[[figure.addons.eclipse.toolbar]]

-.Compiling Widget Set in Eclipse

-image::img/widgetset-compiling-toolbar-hi.png[]

-

-

-If you experience problems with Ivy, first check all the dependency parameters.

-IvyDE can sometimes cause unexpected problems. You can clear the Ivy dependency

-cache by right-clicking the project and selecting "Ivy > Clean all caches". To

-refresh Ivy configuration, select "Ivy > Refresh". To try resolving again Ivy,

-select "Ivy > Resolve".

-

-

-

----

-title: Using Add-ons in a Maven Project

-order: 4

-layout: page

----

-

-[[addons.maven]]

-= Using Add-ons in a Maven Project

-

-((("Maven", "using add-ons", id="term.addons.maven", range="startofrange")))

-

-

-To use add-ons in a Maven project, you simply have to add them as dependencies

-in the project POM. Most add-ons include a widget set, which are compiled to the

-project widget set.

-

-Creating, compiling, and packaging a Vaadin project with Maven was described in

-<<dummy/../../../framework/getting-started/getting-started-maven#getting-started.maven,"Using

-Vaadin with Maven">>.

-

-[[addons.maven.dependency]]

-== Adding a Dependency

-

-Vaadin Directory provides a Maven repository for all the add-ons in the

-Directory.

-

-. Open the add-on page in Vaadin Directory.

-

-. Select the version. The latest is shown by default, but you can choose another

-the version from the dropdown menu in the header of the add-on details page.

-

-. Click the [guilabel]#Maven/Ivy# to display the Maven dependency declaration, as

-illustrated in Figure <<figure.addons.maven.pombutton>>. If the add-on is

-available with multiple licenses, you will be prompted to select a license for

-the dependency.

-

-+

-[[figure.addons.maven.pombutton]]

-.Maven POM Definitions

-image::img/directory-maven-pom.png[]

-

-. Copy the [literal]#++dependency++# declaration to the [filename]#pom.xml# file

-in your project, under the [literal]#++dependencies++# element.

-

-

-+

-[subs="normal"]

-----

- ...

- &lt;dependencies&gt;

- ...

- &lt;dependency&gt;

- &lt;groupId&gt;**com.vaadin.addon**&lt;/groupId&gt;

- &lt;artifactId&gt;**vaadin-charts**&lt;/artifactId&gt;

- &lt;version&gt;**1.0.0**&lt;/version&gt;

- &lt;/dependency&gt;

- &lt;/dependencies&gt;

-----

-+

-You can use an exact version number, as is done in the example above, or

-[literal]#++LATEST++# to always use the latest version of the add-on.

-

-+

-The POM excerpt given in Directory includes also a repository definition, but if

-you have used the [literal]#++vaadin-archetype-application++# to create your

-project, it already includes the definition.

-

-. Compile the widget set as described in the following section.

-

-

-

-[[addons.maven.compiling]]

-== Compiling the Project Widget Set

-

-If you have used the [literal]#++vaadin-archetype-application++# to create the

-project, the [filename]#pom.xml# includes all necessary declarations to compile

-the widget set. The widget set compilation occurs in standard Maven build phase,

-such as with [parameter]#package# or [parameter]#install# goal.

-

-[subs="normal"]

-----

-[prompt]#$# [command]#mvn# [parameter]#package#

-----

-Then, just deploy the WAR to your application server.

-

-[[addons.maven.compiling.recompiling]]

-=== Recompiling the Widget Set

-

-The Vaadin plugin for Maven tries to avoid recompiling the widget set unless

-necessary, which sometimes means that it is not compiled even when it should.

-Running the [literal]#++clean++# goal usually helps, but causes a full

-recompilation. You can compile the widget set manually by running the

-[parameter]#vaadin:compile# goal.

-

-[subs="normal"]

-----

-[prompt]#$# [command]#mvn# [parameter]#vaadin:compile#

-----

-Note that this does not update the project widget set by searching new widget

-sets from the class path. It must be updated if you add or remove add-ons, for

-example. You can do that by running the [literal]#++vaadin:update-widgetset++#

-goal in the project directory.

-

-[subs="normal"]

-----

-[prompt]#$# [command]#mvn# [parameter]#vaadin:update-widgetset#

-...

-[INFO] auto discovered modules [your.company.gwt.ProjectNameWidgetSet]

-[INFO] Updating widgetset your.company.gwt.ProjectNameWidgetSet

-[ERROR] 27.10.2011 19:22:34 com.vaadin.terminal.gwt.widgetsetutils.ClassPathExplorer getAvailableWidgetSets

-[ERROR] INFO: Widgetsets found from classpath:

-...

-

-----

-Do not mind the "ERROR" labels, they are just an issue with the Vaadin Plugin

-for Maven.

-

-After running the update, you need to run the [literal]#++vaadin:compile++# goal

-to actually compile the widget set.

-

-

-

-[[addons.maven.widgetset]]

-== Enabling Widget Set Compilation

-

-If you are not using a POM created with the proper Vaadin archetype, you may

-need to enable widget set compilation manually. The simplest way to do that is

-to copy the definitions from a POM created with the archetype. Specifically, you

-need to copy the [literal]#++plugin++# definitions. You also need the Vaadin

-dependencies.

-

-You need to create an empty widget set definition file, which the widget set

-compilation will populate with widget sets found from the class path. Create a

-[filename]#src/main/java/com/example/AppWidgetSet.gwt.xml# file (in the project

-package) with an empty [literal]#++<module>++# element as follows:

-

-

-----

-<module>

-</module>

-----

-

-[[addons.maven.widgetset.web]]

-=== Enabling the Widget Set in the UI

-

-If you have previously used the default widget set in the project, you need to

-enable the project widget set in the [filename]#web.xml# deployment descriptor.

-Edit the [filename]#src/main/webapp/WEB-INF/web.xml# file and add or modify the

-[literal]#++widgetset++# parameter for the servlet as follows.

-

-[subs="normal"]

-----

-&lt;servlet&gt;

- ...

- &lt;init-param&gt;

- &lt;description&gt;Widget Set to Use&lt;/description&gt;

- &lt;param-name&gt;widgetset&lt;/param-name&gt;

- &lt;param-value&gt;**com.example.AppWidgetSet**&lt;/param-value&gt;

- &lt;/init-param&gt;

-&lt;/servlet&gt;

-----

-The parameter is the class name of the widget set, that is, without the

-[filename]#.gwt.xml# extension and with the Java dot notation for class names

-that include the package name.

-

-

-

-(((range="endofrange", startref="term.addons.maven")))

-

-

----

-title: Overview

-order: 1

-layout: page

----

-

-[[addons.overview]]

-= Overview

-

-In addition to the components, layouts, themes, and data sources built in into

-the core Vaadin library, many others are available as add-ons.

-link:http://vaadin.com/directory/[Vaadin Directory] provides a rich collection

-of add-ons for Vaadin, and you may find others from independent sources. Add-ons

-are also one way to share your own components between projects.

-

-Installation of add-ons from Vaadin Directory is simple, just adding an Ivy or

-Maven dependency, or downloading the JAR package and and dropping it in the web

-library folder of the project. Most add-ons include a widget set, which you need

-to compile, but it's usually just a click of a button or a single command.

-

-After trying out an add-on, you can give some feedback to the author of the

-add-on by rating the add-on with one to five stars and optionally leaving a

-comment. Most add-ons also have a discussion forum thread for user feedback and

-questions.

-

-Add-ons available from Vaadin Directory are distributed under different

-licenses, of which some are commercial. While the add-ons can be downloaded

-directly, you should note their license and other terms and conditions. Many are

-offered under a dual licensing agreement so that they can be used in open source

-projects for free, and many have a trial period for closed-source development.

-Commercial Vaadin add-ons distributed under the CVAL license require installing

-a license key as instructed in

-<<dummy/../../../framework/addons/addons-cval#addons.cval,"Installing Commercial

-Vaadin Add-on Licence">>.

-

-

-

----

-title: Troubleshooting

-order: 6

-layout: page

----

-

-[[addons.troubleshooting]]

-= Troubleshooting

-

-If you experience problems with using add-ons, you can try the following:

-

-* Check the [filename]#.gwt.xml# descriptor file under the the project root

-package. For example, if the project root package is

-[filename]#com.example.myproject#, the widget set definition file is typically

-at [filename]#com/example/project/AppWidgetset.gwt.xml#. The location is not

-fixed and it can be elsewhere, as long as references to it match. See

-<<dummy/../../../framework/clientside/clientside-module#clientside.module,"Client-Side

-Module Descriptor">> for details on the contents of the client-side module

-descriptor, which is used to define a widget set.

-

-* Check the [filename]#WEB-INF/web.xml# deployment descriptor and see that the

-servlet for your UI has a widget set parameter, such as the following:

-

-

-+

-----

-<init-param>

- <description>UI widgetset</description>

- <param-name>widgetset</param-name>

- <param-value>com.example.project.AppWidgetSet</param-value>

-</init-param>

-----

-+

-Check that the widget set class corresponds with the [filename]#.gwt.xml# file

-in the source tree.

-

-* See the [filename]#VAADIN/widgetsets# directory and check that the widget set

-appears there. You can remove it and recompile the widget set to see that the

-compilation works properly.

-

-* Use the [guilabel]#Net# tab in Firebug to check that the widget set (and theme)

-is loaded properly.

-

-* Use the ?debug parameter for the application to open the debug window and check

-if there is any version conflict between the widget set and the Vaadin library,

-or the themes. See

-<<dummy/../../../framework/advanced/advanced-debug#advanced.debug,"Debug Mode

-and Window">> for details.

-

-* Refresh and recompile the project. In Eclipse, select the project and press F5,

-stop the server, clean the server temporary directories, and restart it.

-

-* Check the Error Log view in Eclipse (or in the IDE you use).

-

-

-

-

-[[addons]]

-== Using Vaadin Add-ons

-

-This chapter describes the installation of add-on components, themes,

-containers, and other tools from the Vaadin Directory and the use of commercial

-add-ons offered by Vaadin.

-

-

-include::addons-overview.asciidoc[leveloffset=+2]

-

-include::addons-downloading.asciidoc[leveloffset=+2]

-

-include::addons-eclipse.asciidoc[leveloffset=+2]

-

-include::addons-maven.asciidoc[leveloffset=+2]

-

-include::addons-cval.asciidoc[leveloffset=+2]

-

-include::addons-troubleshooting.asciidoc[leveloffset=+2]

-<?xml version="1.0" encoding="UTF-8" standalone="no"?>

-<!-- Created with Inkscape (http://www.inkscape.org/) -->

-<svg

- xmlns:dc="http://purl.org/dc/elements/1.1/"

- xmlns:cc="http://creativecommons.org/ns#"

- xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"

- xmlns:svg="http://www.w3.org/2000/svg"

- xmlns="http://www.w3.org/2000/svg"

- xmlns:xlink="http://www.w3.org/1999/xlink"

- xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"

- xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"

- width="210mm"

- height="297mm"

- id="svg1901"

- sodipodi:version="0.32"

- inkscape:version="0.46"

- sodipodi:docname="widgetset-compiling-toolbar.svg"

- sodipodi:docbase="/home/tsoots/ohj/translations/po"

- inkscape:output_extension="org.inkscape.output.svg.inkscape">

- <defs

- id="defs1903">

- <inkscape:perspective

- sodipodi:type="inkscape:persp3d"

- inkscape:vp_x="0 : 526.18109 : 1"

- inkscape:vp_y="0 : 1000 : 0"

- inkscape:vp_z="744.09448 : 526.18109 : 1"

- inkscape:persp3d-origin="372.04724 : 350.78739 : 1"

- id="perspective7" />

- <inkscape:perspective

- id="perspective2499"

- inkscape:persp3d-origin="372.04724 : 350.78739 : 1"

- inkscape:vp_z="744.09448 : 526.18109 : 1"

- inkscape:vp_y="0 : 1000 : 0"

- inkscape:vp_x="0 : 526.18109 : 1"

- sodipodi:type="inkscape:persp3d" />

- <linearGradient

- y2="471.38400"

- y1="45.132561"

- xlink:href="#linearGradient7601"

- x2="1370.5586"

- x1="-526.86133"

- spreadMethod="reflect"

- inkscape:collect="always"

- id="linearGradient10877"

- gradientUnits="userSpaceOnUse"

- gradientTransform="matrix(8.892150e-2,0.000000,0.000000,0.155616,635.7169,9.380527)" />

- <linearGradient

- y2="471.38400"

- y1="45.132561"

- xlink:href="#linearGradient7601"

- x2="1370.5586"

- x1="-526.86133"

- spreadMethod="reflect"

- inkscape:collect="always"

- id="linearGradient10869"

- gradientUnits="userSpaceOnUse"

- gradientTransform="matrix(0.323979,0.000000,0.000000,0.566975,399.6324,14.15086)" />

- <linearGradient

- y2="471.38400"

- y1="45.132561"

- xlink:href="#linearGradient7601"

- x2="1370.5586"

- x1="-526.86133"

- spreadMethod="reflect"

- inkscape:collect="always"

- id="linearGradient7607"

- gradientUnits="userSpaceOnUse"

- gradientTransform="matrix(0.755921,0,0,1.32289,-36,0)" />

- <linearGradient

- inkscape:collect="always"

- id="linearGradient7601">

- <stop

- style="stop-color:#000000;stop-opacity:1;"

- offset="0"

- id="stop7603" />

- <stop

- style="stop-color:#000000;stop-opacity:0;"

- offset="1"

- id="stop7605" />

- </linearGradient>

- <inkscape:perspective

- id="perspective13602"

- inkscape:persp3d-origin="372.04724 : 350.78739 : 1"

- inkscape:vp_z="744.09448 : 526.18109 : 1"

- inkscape:vp_y="0 : 1000 : 0"

- inkscape:vp_x="0 : 526.18109 : 1"

- sodipodi:type="inkscape:persp3d" />

- <inkscape:perspective

- id="perspective2529"

- inkscape:persp3d-origin="372.04724 : 350.78739 : 1"

- inkscape:vp_z="744.09448 : 526.18109 : 1"

- inkscape:vp_y="0 : 1000 : 0"

- inkscape:vp_x="0 : 526.18109 : 1"

- sodipodi:type="inkscape:persp3d" />

- </defs>

- <sodipodi:namedview

- id="base"

- pagecolor="#ffffff"

- bordercolor="#666666"

- borderopacity="1.0"

- inkscape:pageopacity="0.0"

- inkscape:pageshadow="2"

- inkscape:zoom="2.8"

- inkscape:cx="295.42901"

- inkscape:cy="873.26277"

- inkscape:document-units="px"

- inkscape:current-layer="layer1"

- gridtolerance="10000"

- inkscape:window-width="1333"

- inkscape:window-height="739"

- inkscape:window-x="1493"

- inkscape:window-y="131"

- showgrid="false" />

- <metadata

- id="metadata1906">

- <rdf:RDF>

- <cc:Work

- rdf:about="">

- <dc:format>image/svg+xml</dc:format>

- <dc:type

- rdf:resource="http://purl.org/dc/dcmitype/StillImage" />

- </cc:Work>

- </rdf:RDF>

- </metadata>

- <g

- inkscape:label="Taso 1"

- inkscape:groupmode="layer"

- id="layer1"

- style="opacity:1">

- <image

- y="116.93364"

- x="125.21431"

- id="image2501"

- height="48"

- width="281"

- sodipodi:absref="/home/magi/itmill/book-7/manual/img/addons/widgetset-compiling-toolbar.png"

- xlink:href="/home/magi/itmill/book-7/manual/img/addons/widgetset-compiling-toolbar.png" />

- <rect

- style="opacity:1;fill:#eeeff2;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2.0999999;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:1.29999998;stroke-opacity:1;visibility:visible;display:inline;overflow:visible;enable-background:accumulate"

- id="rect2535"

- width="24.496172"

- height="16.667501"

- x="204.80843"

- y="122.51678" />

- <image

- y="122.34544"

- x="208.74406"

- id="image2531"

- height="17.262691"

- width="17.262691"

- sodipodi:absref="//home/magi/itmill/book-7/manual/img/addons/compile-widgetset-16.png"

- xlink:href="/home/magi/itmill/book-7/manual/img/addons/compile-widgetset-16.png"

- style="fill:#eeeff2;fill-opacity:1" />

- <g

- style="display:inline"

- inkscape:label="Layer 1"

- id="g13611"

- transform="matrix(2.4577007e-2,0,0,2.4577007e-2,218.45402,137.72183)">

- <g

- id="g1317">

- <path

- style="fill:url(#linearGradient7607);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;display:inline"

- id="path6080"

- d="M 70.29035,24.82601 L 70.29035,627.16976 L 105.72785,627.16976 L 105.72785,591.73226 L 141.16535,591.73226 L 141.16535,556.32601 L 176.5716,556.32601 L 176.5716,520.88851 L 212.0091,520.88851 L 247.4466,520.88851 L 247.4466,591.73226 L 282.8841,591.73226 L 282.8841,662.60726 L 318.3216,662.60726 L 318.3216,733.48226 L 353.7591,733.48226 L 353.7591,768.91976 L 424.60285,768.91976 L 424.60285,733.48226 L 460.04035,733.48226 L 460.04035,662.60726 L 424.60285,662.60726 L 424.60285,591.73226 L 389.1966,591.73226 L 389.1966,520.88851 L 353.7591,520.88851 L 353.7591,450.01351 L 495.47785,450.01351 L 495.47785,414.57601 L 460.04035,414.57601 L 460.04035,379.13851 L 424.60285,379.13851 L 424.60285,343.70101 L 389.1966,343.70101 L 389.1966,308.29476 L 353.7591,308.29476 L 353.7591,272.85726 L 318.3216,272.85726 L 318.3216,237.41976 L 282.8841,237.41976 L 282.8841,201.98226 L 247.4466,201.98226 L 247.4466,166.54476 L 212.0091,166.54476 L 212.0091,131.10726 L 176.5716,131.10726 L 176.5716,95.669761 L 141.16535,95.669761 L 141.16535,60.26351 L 105.72785,60.26351 L 105.72785,24.82601 L 70.29035,24.82601 z" />

- <path

- style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"

- id="rect1430"

- d="M 35.4375,24.8125 L 35.4375,627.15625 L 70.875,627.15625 L 70.875,591.71875 L 106.3125,591.71875 L 106.3125,556.3125 L 70.875,556.3125 L 70.875,95.65625 L 106.3125,95.65625 L 106.3125,60.25 L 70.875,60.25 L 70.875,24.8125 L 35.4375,24.8125 z M 106.3125,95.65625 L 106.3125,131.09375 L 141.71875,131.09375 L 141.71875,95.65625 L 106.3125,95.65625 z M 141.71875,131.09375 L 141.71875,166.53125 L 177.15625,166.53125 L 177.15625,131.09375 L 141.71875,131.09375 z M 177.15625,166.53125 L 177.15625,201.96875 L 212.59375,201.96875 L 212.59375,166.53125 L 177.15625,166.53125 z M 212.59375,201.96875 L 212.59375,237.40625 L 248.03125,237.40625 L 248.03125,201.96875 L 212.59375,201.96875 z M 248.03125,237.40625 L 248.03125,272.84375 L 283.46875,272.84375 L 283.46875,237.40625 L 248.03125,237.40625 z M 283.46875,272.84375 L 283.46875,308.28125 L 318.90625,308.28125 L 318.90625,272.84375 L 283.46875,272.84375 z M 318.90625,308.28125 L 318.90625,343.6875 L 354.34375,343.6875 L 354.34375,308.28125 L 318.90625,308.28125 z M 354.34375,343.6875 L 354.34375,379.125 L 389.75,379.125 L 389.75,343.6875 L 354.34375,343.6875 z M 389.75,379.125 L 389.75,414.5625 L 283.46875,414.5625 L 283.46875,450 L 283.46875,520.875 L 318.90625,520.875 L 318.90625,450 L 460.625,450 L 460.625,414.5625 L 425.1875,414.5625 L 425.1875,379.125 L 389.75,379.125 z M 318.90625,520.875 L 318.90625,591.71875 L 354.34375,591.71875 L 354.34375,520.875 L 318.90625,520.875 z M 354.34375,591.71875 L 354.34375,662.59375 L 389.75,662.59375 L 389.75,591.71875 L 354.34375,591.71875 z M 389.75,662.59375 L 389.75,733.46875 L 425.1875,733.46875 L 425.1875,662.59375 L 389.75,662.59375 z M 389.75,733.46875 L 318.90625,733.46875 L 318.90625,768.90625 L 389.75,768.90625 L 389.75,733.46875 z M 318.90625,733.46875 L 318.90625,662.59375 L 283.46875,662.59375 L 283.46875,733.46875 L 318.90625,733.46875 z M 283.46875,662.59375 L 283.46875,591.71875 L 248.03125,591.71875 L 248.03125,662.59375 L 283.46875,662.59375 z M 248.03125,591.71875 L 248.03125,520.875 L 212.59375,520.875 L 212.59375,591.71875 L 248.03125,591.71875 z M 212.59375,520.875 L 212.59375,450 L 177.15625,450 L 177.15625,485.4375 L 141.71875,485.4375 L 141.71875,520.875 L 177.15625,520.875 L 212.59375,520.875 z M 141.71875,520.875 L 106.3125,520.875 L 106.3125,556.3125 L 141.71875,556.3125 L 141.71875,520.875 z" />

- <path

- style="fill:#ffffff;fill-opacity:1;stroke:none"

- id="rect3779"

- d="M 70.875,95.65625 L 70.875,556.3125 L 106.3125,556.3125 L 106.3125,520.875 L 141.71875,520.875 L 141.71875,485.4375 L 177.15625,485.4375 L 177.15625,450 L 212.59375,450 L 212.59375,520.875 L 248.03125,520.875 L 248.03125,591.71875 L 283.46875,591.71875 L 283.46875,662.59375 L 318.90625,662.59375 L 318.90625,733.46875 L 354.34375,733.46875 L 389.75,733.46875 L 389.75,662.59375 L 354.34375,662.59375 L 354.34375,591.71875 L 318.90625,591.71875 L 318.90625,520.875 L 283.46875,520.875 L 283.46875,414.5625 L 318.90625,414.5625 L 354.34375,414.5625 L 389.75,414.5625 L 389.75,379.125 L 354.34375,379.125 L 354.34375,343.6875 L 318.90625,343.6875 L 318.90625,308.28125 L 283.46875,308.28125 L 283.46875,272.84375 L 248.03125,272.84375 L 248.03125,237.40625 L 212.59375,237.40625 L 212.59375,201.96875 L 177.15625,201.96875 L 177.15625,166.53125 L 141.71875,166.53125 L 141.71875,131.09375 L 106.3125,131.09375 L 106.3125,95.65625 L 70.875,95.65625 z" />

- </g>

- </g>

- </g>

-</svg>

----

-title: Advanced Application Architectures

-order: 10

-layout: page

----

-

-[[advanced.architecture]]

-= Advanced Application Architectures

-

-In this section, we continue from the basic application architectures described

-in

-<<dummy/../../../framework/application/application-architecture#application.architecture,"Building

-the UI">> and discuss some of the more advanced patterns that are often used in

-Vaadin applications.

-

-[[advanced.architecture.layering]]

-== Layered Architectures

-

-Layered architectures, where each layer has a clearly distinct responsibility,

-are probably the most common architectures. Typically, applications follow at

-least a three-layer architecture:

-

-* User interface (or presentation) layer

-* Domain layer

-* Data store layer

-

-Such an architecture starts from a __domain model__, which defines the data

-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

-<<dummy/../../../framework/datamodel/datamodel-overview.asciidoc#datamodel.overview,"Binding

-Components to Data">>. 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[]

-

-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

-user interface layer, as well as for other uses. In Java EE development,

-Enterprise JavaBeans (EJBs) are typically used for building this layer.

-

-An __infrastructure layer__ (or __data access layer__) is often distinguished

-from the data store layer, with a purpose to abstract the data store. For

-example, it could involve a persistence solution such as JPA and an EJB

-container. This layer becomes relevant with Vaadin when binding Vaadin

-components to data with the JPAContainer, as described in

-<<dummy/../../../framework/jpacontainer/jpacontainer-overview.asciidoc#jpacontainer.overview,"Vaadin

-JPAContainer">>.

-

-

-[[advanced.architecture.mvp]]

-== Model-View-Presenter Pattern

-

-The Model-View-Presenter (MVP) pattern is one of the most common patterns in

-developing large applications with Vaadin. It is similar to the older

-Model-View-Controller (MVC) pattern, which is not as meaningful in Vaadin

-development. Instead of an implementation-aware controller, there is an

-implementation-agnostic presenter that operates the view through an interface.

-The view does not interact directly with the model. This isolates the view

-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[]

-

-<<figure.advanced.architecture.mvp>> illustrates the MVP pattern with a simple

-calculator. The domain model is realized in the [classname]#Calculator# class,

-which includes a data model and some model logic operations. The

-[classname]#CalculatorViewImpl# is a Vaadin implementation of the view, defined

-in the [interfacename]#CalculatorView# interface. The

-[classname]#CalculatorPresenter# handles the user interface logic. User

-interaction events received in the view are translated into

-implementation-independent events for the presenter to handle (the view

-implementation could also just call the presenter).

-

-Let us first look how the model and view are bound together by the presenter in

-the following example:

-

-

-[source, java]

-----

-

-// 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);

-----

-

-You could add the view anywhere in a Vaadin application, as it is a composite

-component.

-

-[[advanced.architecture.mvp.model]]

-=== The Model

-

-Our business model is quite simple, with one value and a number of operations

-for manipulating it.

-

-

-[source, java]

-----

-/** The model **/

-class CalculatorModel {

- private double value = 0.0;

-

- public void clear() {

- value = 0.0;

- }

-

- public void add(double arg) {

- value += arg;

- }

-

- public void multiply(double arg) {

- value *= arg;

- }

-

- public void divide(double arg) {

- if (arg != 0.0)

- value /= arg;

- }

-

- public double getValue() {

- return value;

- }

-

- public void setValue(double value) {

- this.value = value;

- }

-}

-----

-

-

-[[advanced.architecture.mvp.view]]

-=== The View

-

-The purpose of the view in MVP is to display data and receive user interaction.

-It relays the user interaction to the presenter in an fashion that is

-independent of the view implementation, that is, no Vaadin events. It is defined

-as a UI framework interface that can have multiple implementations.

-

-

-[source, java]

-----

-interface CalculatorView {

- public void setDisplay(double value);

-

- interface CalculatorViewListener {

- void buttonClick(char operation);

- }

- public void addListener(CalculatorViewListener listener);

-}

-----

-

-The are design alternatives for the view. It could receive the listener in its

-constructor, or it could just know the presenter. Here, we forward button clicks

-as an implementation-independent event.

-

-As we are using Vaadin, we make a Vaadin implementation of the interface as

-follows:

-

-

-[source, java]

-----

-class CalculatorViewImpl extends CustomComponent

- implements CalculatorView, ClickListener {

- private Label display = new Label("0.0");

-

- public CalculatorViewImpl() {

- GridLayout layout = new GridLayout(4, 5);

-

- // 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)

- String[] operations = new String[] {

- "7", "8", "9", "/", "4", "5", "6",

- "*", "1", "2", "3", "-", "0", "=", "C", "+" };

-

- // Add buttons and have them send click events

- // to this class

- for (String caption: operations)

- layout.addComponent(new Button(caption, this));

-

- setCompositionRoot(layout);

- }

-

- public void setDisplay(double value) {

- display.setValue(Double.toString(value));

- }

-

- /* Only the presenter registers one listener... */

- List<CalculatorViewListener> listeners =

- new ArrayList<CalculatorViewListener>();

-

- public void addListener(CalculatorViewListener listener) {

- listeners.add(listener);

- }

-

- /** Relay button clicks to the presenter with an

- * implementation-independent event */

- @Override

- public void buttonClick(ClickEvent event) {

- for (CalculatorViewListener listener: listeners)

- listener.buttonClick(event.getButton()

- .getCaption().charAt(0));

- }

-}

-----

-

-

-[[advanced.architecture.mvp.presenter]]

-=== The Presenter

-

-The presenter in MVP is a middle-man that handles all user interaction logic,

-but in an implementation-independent way, so that it doesn't actually know

-anything about Vaadin. It shows data in the view and receives user interaction

-back from it.

-

-

-[source, java]

-----

-class CalculatorPresenter

- implements CalculatorView.CalculatorViewListener {

- CalculatorModel model;

- CalculatorView view;

-

- 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.addListener(this);

- }

-

- @Override

- public void buttonClick(char operation) {

- // Handle digit input

- if ('0' <= operation && operation <= '9') {

- current = current * 10

- + Double.parseDouble("" + operation);

- view.setDisplay(current);

- return;

- }

-

- // Execute the previously input operation

- switch (lastOperationRequested) {

- case '+':

- model.add(current);

- break;

- case '-':

- model.add(-current);

- break;

- case '/':

- model.divide(current);

- break;

- case '*':

- model.multiply(current);

- break;

- case 'C':

- model.setValue(current);

- break;

- } // '=' is implicit

-

- lastOperationRequested = operation;

-

- current = 0.0;

- if (operation == 'C')

- model.clear();

- view.setDisplay(model.getValue());

- }

-}

-----

-

-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.

-

-

-

-

-

----

-title: Vaadin CDI Add-on

-order: 17

-layout: page

----

-

-[[advanced.cdi]]

-= Vaadin CDI Add-on

-

-((("Contexts and Dependency Injection", id="term.advanced.cdi.cdilong", range="startofrange")))

-

-

-((("CDI", id="term.advanced.cdi.cdi", range="startofrange")))

-

-

-((("Vaadin CDI Add-on", id="term.advanced.cdi.cdiaddon", range="startofrange")))

-

-

-Vaadin CDI add-on makes it easier to use contexts and dependency injection (CDI)

-in Vaadin applications. CDI is a Java EE feature especially targeted for web

-applications, which have well-defined contextual scopes, such as sessions,

-views, requests, and so forth. The lifecycle of objects, such as beans, can be

-managed by binding their lifecycles to such contexts. Vaadin CDI enables these

-features with two additional kinds of Vaadin-specific contextual scopes: UIs and

-navigation views.

-

-To learn more about Vaadin CDI, the link:[Vaadin CDI Tutorial] gives a hands-on

-introduction. The source code of the CDI Tutorial demo is available for browsing

-or cloning at https://github.com/vaadin-samples/cdi-tutorial.

-

-[[advanced.cdi.cdi]]

-== CDI Overview

-

-Contexts and dependency injection, defined in the JSR-299 standard, is a Java EE

-feature that, through a set of services, helps in improving application

-architecture by decoupling the management of service object lifecycles from

-client objects using them. The lifecycle of objects stored in a CDI container is

-defined by a context. The managed objects or beans are accessed using dependency

-injection.

-

-CDI builds on the Java concept of beans, but with somewhat different definition

-and requirements.

-

-Regarding general CDI topics, such as use of qualifiers, interceptors,

-decorators, event notifications, and other CDI features, we refer you to CDI

-documentation.

-

-ifdef::web[]

-* link:http://jaxenter.com/tutorial-introduction-to-cdi-contexts-and-dependency-injection-for-java-ee-jsr-299-104536.html[Introduction

-to CDI]. Pete Muir and Mark Struberg, JAXenter.

-

-* link:http://docs.jboss.org/weld/reference/latest/en-US/html_single/[Weld - CDI

-Reference Implementation]

-

-* link:http://cdi-spec.org/[CDI Specification]

-

-* link:https://vaadin.com/wiki?p_p_id=36&amp;p_p_lifecycle=0&amp;p_p_state=normal&amp;p_p_mode=view&amp;p_p_col_id=row-1&amp;p_p_col_pos=1&amp;p_p_col_count=3&amp;p_r_p_185834411_title=Vaadin+CDI&amp;p_r_p_185834411_nodeName=vaadin.com+wiki&amp;_36_struts_action=%2Fwiki%2Fview[Vaadin

-CDI Tutorial]

-

-endif::web[]

-

-[[advanced.cdi.cdi.injection]]

-=== Dependency Injection

-

-__Dependency injection__ is a way to pass dependencies (service objects) to

-dependent objects (clients) by injecting them in member variables or initializer

-parameters, instead of managing the lifecycle in the clients or passing them

-explicitly as parameters. In CDI, injection of a service object to a client is

-specified by the [classname]#@Inject# annotation.

-

-For example, if we have a UI view that depends on user data, we could inject the

-data in the client as follows:

-

-

-[source, java]

-----

-public class MainView extends CustomComponent implements View {

- @Inject

- User user;

-

- ...

- @Override

- public void enter(ViewChangeEvent event) {

- greeting.setValue("Hello, " + user.getName());

- }

-}

-----

-

-In addition to injecting managed beans with the annotation, you can query for

-them from the bean manager.

-

-

-[[advanced.cdi.cdi.contexts]]

-=== Contexts and Scopes

-

-__Contexts__ in CDI are services that manage the lifecycle of objects and handle

-their injection. Generally speaking, a context is a situation in which an

-instance is used with a unique identity. Such objects are essentially

-"singletons" in the context. While conventional singletons are application-wide,

-objects managed by a CDI container can be "singletons" in a more narrow

-__scope__: a user session, a particular UI instance associated with the session,

-a view within the UI, or even just a single request. Such a context defines the

-lifecycle of the object: its creation, use, and finally its destruction.

-

-As a very typical example in a web application, you would have a user data

-object associated with a user session.

-

-

-[source, java]

-----

-@SessionScoped

-public class User {

- private String name;

-

- public void setName(String name) {this.name = name;}

- public String getName() {return name;}

-}

-----

-

-Now, when you need to refer to the user, you can use CDI injection to inject the

-session-scoped "singleton" to a member variable or a constructor parameter.

-

-

-[source, java]

-----

-public class MainView extends CustomComponent implements View {

- @Inject

- User user;

-

- ...

-

- @Override

- public void enter(ViewChangeEvent event) {

- greeting.setValue("Hello, " + user.getName());

- }

-}

-----

-

-

-

-[[advanced.cdi.installation]]

-== Installing Vaadin CDI Add-on

-

-Vaadin CDI requires a Java EE 7 compatible servlet container, such as Glassfish

-or Apache TomEE Web Profile, as mentioned for the reference toolchain in

-<<dummy/../../../framework/getting-started/getting-started-environment#getting-started.environment,"Setting

-up the Development Environment">>.

-

-To install the Vaadin CDI add-on, either define it as an Ivy or Maven dependency

-or download it from the Vaadin Directory add-on page at

-<<,vaadin.com/directory#addon/vaadin-cdi>>. See

-<<dummy/../../../framework/addons/addons-overview.asciidoc#addons.overview,"Using

-Vaadin Add-ons">> for general instructions for installing and using Vaadin

-add-ons.

-

-The Ivy dependency is as follows:

-

-[subs="normal"]

-----

- &lt;dependency org="com.vaadin" name="vaadin-cdi"

- rev="[replaceable]#latest.release#"/&gt;

-----

-The Maven dependency is as follows:

-

-[subs="normal"]

-----

- &lt;dependency&gt;

- &lt;groupId&gt;com.vaadin&lt;/groupId&gt;

- &lt;artifactId&gt;vaadin-cdi&lt;/artifactId&gt;

- &lt;version&gt;[replaceable]#LATEST#&lt;/version&gt;

- &lt;/dependency&gt;

- &lt;dependency&gt;

- &lt;groupId&gt;javax.enterprise&lt;/groupId&gt;

- &lt;artifactId&gt;cdi-api&lt;/artifactId&gt;

- &lt;version&gt;[replaceable]#1.2#&lt;/version&gt;

- &lt;/dependency&gt;

-----

-

-[[advanced.cdi.peparing]]

-== Preparing Application for CDI

-

-A Vaadin application that uses CDI must have a file named [filename]#beans.xml#

-in the [filename]#WEB-INF# directory. The file can be completely empty (it has

-content only in certain limited situations), but it must be present.

-

-The application should not have a servlet extending [classname]#VaadinServlet#,

-as Vaadin servlet has its own [classname]#VaadinCDIServlet# that is deployed

-automatically. If you need multiple servlets or need to customize the Vaadin CDI

-servlet, see <<advanced.cdi.deployment>>.

-

-

-[[advanced.cdi.cdiui]]

-== Injecting a UI with [classname]#@CDIUI#

-

-((("[classname]#@CDIUI#", id="term.advanced.cdi.cdiui", range="startofrange")))

-

-

-Vaadin CDI offers an easier way to instantiate UIs and to define the URL mapping

-for them than the usual ways described in

-<<dummy/../../../framework/application/application-environment#application.environment,"Deploying

-an Application">>. To define a UI class that should be instantiated for a given

-URL, you simply need to annotate the class with [classname]#@CDIUI#. It takes an

-optional URL path as parameter.

-

-

-[source, java]

-----

-@CDIUI("myniceui")

-@Theme("valo")

-public class MyNiceUI extends UI {

- ...

-----

-

-Giving empty UI path maps the UI to the root of the application context.

-

-

-[source, java]

-----

-@CDIUI("")

-----

-

-If the optional UI path is not given, the path is determined automatically from

-the class name by removing a possible "-UI" suffix in the class name, making it

-lower-case, and for capitalized letters, a hyphen is added. For example, a UI

-with class name [classname]#MyNiceUI# would have path [literal]#++my-nice++#.

-The URL consists of the server address, application context, and the UI path.

-For example, when running a Vaadin application in a development workstation, you

-would have URL such as http://localhost:8080/myproject/my-nice.

-

-UI path mappings are reported in the server log during deployment.

-

-See <<advanced.cdi.deployment>> for how to handle servlet URL mapping of CDI UIs

-when working with multiple servlets in the same web application.

-

-(((range="endofrange", startref="term.advanced.cdi.cdiui")))

-

-[[advanced.cdi.scopes]]

-== Scopes

-

-((("CDI", "scopes", id="term.advanced.cdi.scopes", range="startofrange")))

-

-

-As in programming languages, where a variable name refers to a unique object

-within the scope of the variable, a CDI scope is a context in which an object

-has unique identity. In CDI, objects to be injected are identified by their type

-and any qualifiers they may have. The scope can be defined as an annotation to

-the service class as follows:

-

-

-[source, java]

-----

-@SessionScoped

-public class User {

- ...

-----

-

-CDI defines a number of scopes. Note that the standard CDI scopes are defined

-under the [package]#javax.enterprise.context# package and Vaadin CDI scopes

-under [package]#com.vaadin.cdi#, while JSF scopes are defined in

-[package]#javax.faces.bean#.

-

-[[advanced.cdi.scopes.ui]]

-=== UI Scope

-

-UI-scoped beans are uniquely identified within a UI instance, that is, a browser

-window or tab.

-

-Vaadin CDI provides two annotations for the UI scope, differing in how they

-enable proxies, as explained later.

-

-[classname]#@UIScoped#([package]#com.vaadin.cdi#):: ((("[classname]#@UIScoped#", id="term.advanced.cdi.scopes.uiscoped", range="startofrange")))

-

-

-+

-Injection with this annotation will create a direct reference to the bean rather

-than a proxy. There are some limitations when not using proxies. Circular

-references (injecting A to B and B to A) will not work, and neither do CDI

-interceptors and decorators.

-

-(((range="endofrange", startref="term.advanced.cdi.scopes.uiscoped")))

-[classname]#@NormalUIScoped#([package]#com.vaadin.cdi#):: As [classname]#@UIScoped#, but injecting a managed bean having this annotation

-injects a proxy for the bean instead of a direct reference. This is the normal

-behaviour with CDI, as many CDI features utilize the proxy.

-

-

-

-Defining a CDI view (annotated with [classname]#@CDIView# as described later) as

-[classname]#@UIScoped# makes the view retain the same instance when the user

-navigates away and back to the view.

-

-

-[[advanced.cdi.scopes.view]]

-=== View Scopes

-

-The lifecycle of a view-scoped bean starts when the user navigates to a view

-referring to the object and ends when the user navigates out of the view (or

-when the UI is closed or expires).

-

-Vaadin CDI provides two annotations for the view scope, differing in how they

-enable proxies, as explained later.

-

-[classname]#@ViewScoped#([package]#com.vaadin.cdi#):: Injection with this annotation will create a direct reference to the bean rather

-than a proxy. There are some limitations when not using proxies. Circular

-references (injecting A to B and B to A) will not work, and neither do CDI

-interceptors and decorators.

-

-[classname]#@NormalViewScoped#([package]#com.vaadin.cdi#):: As [classname]#@NormalScoped#, except that injecting with this annotation will

-create a proxy for the contextual instance rather than provide the contextual

-instance itself. See the explanation of proxies below.

-

-

-

-

-[[advanced.cdi.scopes.cdi]]

-=== Standard CDI Scopes

-

-[classname]#@ApplicationScoped#:: ((("[classname]#@ApplicationScoped#", id="term.advanced.cdi.scopes.applicationscoped", range="startofrange")))

-

-

-+

-Application-scoped beans are shared by all servlets in the web application, and

-are essentially equal to singletons.//TODO This is just a guess - is it

-true?

-Note that referencing application-scoped beans is not thread-safe and access

-must be synchronized.

-

-(((range="endofrange", startref="term.advanced.cdi.scopes.applicationscoped")))

-[classname]#@SessionScoped#:: ((("[classname]#@SessionScoped#", id="term.advanced.cdi.scopes.sessionscoped", range="startofrange")))

-

-

-+

-The lifecycle and visibility of session-scoped beans is bound to a HTTP or user

-session, which in Vaadin applications is associated with the

-[classname]#VaadinSession# (see

-<<dummy/../../../framework/application/application-lifecycle#application.lifecycle.session,"User

-Session">>). This is a very typical scope to store user data, as is done in many

-examples in this section, or database connections. The lifecycle of

-session-scoped beans starts when a user opens the page for a UI in the browser,

-and ends when the session expires after the last UI in the session is closed.

-

-(((range="endofrange", startref="term.advanced.cdi.scopes.sessionscoped")))

-

-

-

-[[advanced.cdi.scopes.proxies]]

-=== Proxies vs Direct References

-

-CDI uses proxy objects to enable many of the CDI features, by hooking into

-message-passing from client to service beans. Under the hood, a proxy is an

-instance of an automatically generated class that extends the proxied bean type,

-so communicating through a proxy occurs transparently, as it has the same

-polymorphic type as the actual bean. Whether proxying is enabled or not is

-defined in the scope: CDI scopes are either __normal scopes__, which can be

-proxied, or __pseudoscopes__, which use direct references to injected beans.

-

-The proxying mechanism creates some requirements for injecting objects in normal

-scope:

-

-* The objects may not be primitive types or arrays

-

-* The bean class must not be final

-

-* The bean class must not have final methods

-

-

-Beans annotated with [classname]#@UIScoped# or [classname]#@ViewScoped# use a

-pseudoscope, and are therefore injected with direct references to the bean

-instances, while [classname]#@NormalUIScoped# and [classname]#@NormalViewScoped#

-beans will use a proxy for communicating with the beans.

-

-When using proxies, be aware that it is not guaranteed that the

-[methodname]#hashCode()# or [methodname]#equals()# will match when comparing a

-proxy to its underlying instance. It is imperative to be aware of this when, for

-example, adding proxies to a [interfacename]#Collection#.

-

-You should avoid using normal scopes with Vaadin components, as proxies may not

-work correctly within the Vaadin framework. If Vaadin CDI plugin detects such

-use, it displays a warning such as the following:

-

-

-----

-INFO: The following Vaadin components are injected

-into normal scoped contexts:

- @NormalUIScoped org.example.User

-This approach uses proxy objects and has not been

-extensively tested with the framework. Please report

-any unexpected behavior. Switching to a pseudo-scoped

-context may also resolve potential issues.

-----

-

-

-(((range="endofrange", startref="term.advanced.cdi.scopes")))

-

-[[advanced.cdi.deployment]]

-== Deploying CDI UIs and Servlets

-

-Vaadin CDI hooks into Vaadin framework by using a special

-[classname]#VaadinCDIServlet#. As described earlier, you do not need to map an

-URL path to a UI, as it is handled by Vaadin CDI. However, in the following, we

-go through some cases where you need to customize the servlet or use CDI with

-non-CDI servlets and UIs in a web application.

-

-[[advanced.cdi.deployment.urlmapping]]

-=== Defining Servlet Root with [classname]#@URLMapping#

-

-CDI UIs are managed by a CDI servlet ( [classname]#VaadinCDIServlet#), which is

-by default mapped to the root of the application context. For example, if the

-name of a CDI UI is " [literal]#++my-cdi++#" and application context is

-[literal]#++/myproject++#, the UI would by default have URL "

-[literal]#++/myproject/my-cdi++#". If you do not want to have the servlet mapped

-to context root, you can use the [classname]#@URLMapping# annotation to map all

-CDI UIs to a sub-path. The annotation must be given to only one CDI UI, usually

-the one with the default ("") path.

-

-For example, if we have a root UI and another:

-

-

-[source, java]

-----

-@CDIUI("") // At CDI servlet root

-@URLMapping("mycdiuis") // Define CDI Servlet root

-public class MyCDIRootUI extends UI {...}

-

-@CDIUI("another")

-public class AnotherUI extends UI {...}

-----

-

-These two UIs would have URLs /myproject/mycdiuis and

-/myproject/mycdiuis/another, respectively.

-

-You can also map the CDI servlet to another URL in servlet definition in

-[filename]#web.xml#, as described the following.

-

-

-[[advanced.cdi.servlets.mixing]]

-=== Mixing With Other Servlets

-

-The [classname]#VaadinCDIServlet# is normally used as the default servlet, but

-if you have other servlets in the application, such as for non-CDI UIs, you need

-to define the CDI servlet explicitly in the [filename]#web.xml#. You can map the

-servlet to any URL path, but perhaps typically, you define it as the default

-servlet as follows, and map the other servlets to other URL paths:

-

-[subs="normal"]

-----

-&lt;web-app&gt;

- ...

-

- &lt;servlet&gt;

- &lt;servlet-name&gt;Default&lt;/servlet-name&gt;

- &lt;servlet-class&gt;

- com.vaadin.cdi.internal.VaadinCDIServlet

- &lt;/servlet-class&gt;

- &lt;/servlet&gt;

-

- &lt;servlet-mapping&gt;

- &lt;servlet-name&gt;Default&lt;/servlet-name&gt;

- &lt;url-pattern&gt;[replaceable]#/mycdiuis/*#&lt;/url-pattern&gt;

- &lt;/servlet-mapping&gt;

-

- &lt;servlet-mapping&gt;

- &lt;servlet-name&gt;Default&lt;/servlet-name&gt;

- &lt;url-pattern&gt;/VAADIN/*&lt;/url-pattern&gt;

- &lt;/servlet-mapping&gt;

-&lt;/web-app&gt;

-----

-With such a setting, paths to CDI UIs would have base path

-[filename]#/myapp/mycdiuis#, to which the (optional) UI path would be appended.

-The [filename]#/VAADIN/*# only needs to be mapped to the servlet if there are no

-other Vaadin servlets.

-

-

-[[advanced.cdi.servlets.custom]]

-=== Custom Servlets

-

-When customizing the Vaadin servlet, as outlined in

-<<dummy/../../../framework/application/application-lifecycle#application.lifecycle.servlet-service,"Vaadin

-Servlet, Portlet, and Service">>, you simply need to extend

-[classname]#com.vaadin.cdi.internal.VaadinCDIServlet# instead of

-[classname]#com.vaadin.servlet.VaadinServlet#.

-

-The custom servlet must not have [classname]#@WebServlet# annotation or

-[classname]#@VaadinServletConfiguration#, as you would normally with a Vaadin

-servlet, as described in

-<<dummy/../../../framework/application/application-environment#application.environment,"Deploying

-an Application">>.

-

-

-

-ifdef::web[]

-[[advanced.cdi.navigation]]

-== View Navigation

-

-Vaadin CDI extends the navigation framework in Vaadin, described in

-<<dummy/../../../framework/advanced/advanced-navigator#advanced.navigator,"Navigating

-in an Application">>. It manages CDI views with a special view provider and

-enables view scoping.

-

-[[advanced.cdi.navigation.ui]]

-=== Preparing the UI

-

-You can define navigation for any single-component container, as described in

-<<dummy/../../../framework/advanced/advanced-navigator#advanced.navigator.navigating,"Setting

-Up for Navigation">>, but typically you set up navigation for the entire UI

-content. To use Vaadin CDI views, you need to inject a

-[classname]#CDIViewProvider# in the UI and add it as a provider for the

-navigator.

-

-

-[source, java]

-----

-@CDIUI("mycdiui")

-public class MyCDIUI extends UI {

- @Inject

- CDIViewProvider viewProvider;

-

- @Override

- protected void init(VaadinRequest request) {

- Navigator navigator = new Navigator(this, this);

- navigator.addProvider(viewProvider);

-

- // Navigate to start view

- navigator.navigateTo("");

- }

-}

-----

-

-

-[[advanced.cdi.navigation.view]]

-=== The View

-

-A view managed by Vaadin CDI only needs to have the [classname]#@CDIView#

-annotation.

-

-

-[source, java]

-----

-@CDIView("main")

-public class MainView extends CustomComponent implements View {

- ...

-----

-

-The annotation can have the following optional paramers:

-

-value (optional):: Specifies the view name by which it can be accessed programmatically and by the

-URI fragment.

-

-

-+

-[source, java]

-----

-@CDIView("main")

-----

-+

-If other optional parameters are given, the value must be given by the named

-[parameter]#value# parameter.

-

-+

-If the view name is not given, it is derived from the class name by removing a

-possible "View" suffix, making it lower case, and using a dash ("-") to separate

-words originally denoted by capital letters. Thereby, a view class such as

-[classname]#MyFunnyView# would have name " [literal]#++my-funny++#".

-

-supportsParameters:: Specifies whether view parameters can be passed to the view as a suffix to the

-name in the navigation state, that is, in the form of

-[literal]#++viewname+viewparameters++#. The view name is merely a prefix and

-there is no separator nor format for the parameters, but those are left for the

-view to handle. The parameter support mode is disabled by default.

-

-

-+

-[source, java]

-----

-@CDIView(value="myview", supportsParameters=true)

-----

-+

-You could then navigate to the state with a URI fragment such as

-[literal]#++#!myview/someparameter++# or programmatically with:

-

-

-+

-[source, java]

-----

-getUI().getNavigator().navigateTo("myview/someparameter");

-----

-+

-The [methodname]#enter()# method of the view gets the URI fragment as parameter

-as is and can interpret it in any application-defined way.

-

-+

-Note that in this mode, matching a navigation state to a view is done by the

-prefix of the fragment! Thereby, no other views may start with the name of the

-view as prefix. For example, if the view name is " [literal]#++main++#", you

-must not have a view named " [literal]#++maintenance++#".

-

-uis:: If the application has multiple UIs that use [classname]#CDIViewProvider#, you

-can use this parameter to specify which UIs can show the view.

-

-

-+

-[source, java]

-----

-@CDIView(value="myview", uis={MyCDIUI.class})

-----

-+

-If the list contains [parameter]#UI.class#, the view is available to all UIs.

-

-

-+

-[source, java]

-----

-@CDIView(value="myview", uis={UI.class})

-----

-

-

-In the following, we have a login view that accesses a session-scoped user

-object. Here, we use a constant to define the view name, so that we can use the

-constant when navigating to it.

-

-

-[source, java]

-----

-@CDIView(LoginView.VIEWNAME)

-public class LoginView extends CustomComponent

- implements View {

- public final static String VIEWNAME = "";

-

- // Here we inject to the constructor and actually do

- // not store the injected object to use it later

- @Inject

- public LoginView(User user) {

- VerticalLayout layout = new VerticalLayout();

-

- // An input field for editing injected data

- BeanItem<User> item = new BeanItem<User>(user);

- TextField username = new TextField("User name",

- item.getItemProperty("name"));

- username.setNullRepresentation("");

- layout.addComponent(username);

-

- // Login button (authentication omitted) / Java 8

- layout.addComponent(new Button("Login", e ->

- getUI().getNavigator().

- navigateTo(MainView.VIEWNAME)));

-

- setCompositionRoot(layout);

- }

-

- @Override

- public void enter(ViewChangeEvent event) {}

-}

-----

-

-You could now navigate to the view from any other view in the UI with:

-

-

-[source, java]

-----

-getUI().getNavigator().navigateTo(LoginView.VIEWNAME);

-----

-

-

-endif::web[]

-

-ifdef::web[]

-[[advanced.cdi.events]]

-== CDI Events

-

-((("CDI", "events", id="term.advanced.cdi.events", range="startofrange")))

-

-

-CDI events can be used for many purposes in Vaadin applications, such as passing

-messages between different parts of a view, between views, between UIs, or

-between users. Some cases require special consideration, such as when

-communicating between UIs and how injected components should be scoped.

-

-[[advanced.cdi.events.intro]]

-=== Observing Events

-

-Let us consider a case where changes in one part of the UI (or view) require

-updating other parts of the UI. This is typical in master-detail views, for

-updating the master view after editing details, or when handling input from a

-sub-window. While you can handle such a situation with a custom call-back

-listener, CDI event mechanism simplifies the task.

-

-Let us consider the following simple UI containing two panels. The input panel

-will send events, which are received by other parts of the UI, in this case a

-display panel. The panels need to be injected to enable CDI event passing in

-them.

-

-

-[source, java]

-----

-@CDIUI("cdievents")

-@Theme("valo")

-public class CDIEventUI extends UI {

- @Inject

- InputPanel inputPanel;

-

- @Inject

- DisplayPanel displayPanel;

-

- @Override

- protected void init(VaadinRequest request) {

- Layout content =

- new HorizontalLayout(inputPanel, displayPanel);

- setContent(content);

- }

-}

-----

-

-Now, let us look closer at the sending panel. To send messages, it needs to

-inject a [classname]#javax.enterprise.event.Event# object. As we are injecting

-the event to a component class, we need to specify the full package name to

-avoid confusion with Vaadin [classname]#Component.Event#.

-

-

-[source, java]

-----

-class InputPanel extends Panel {

- @Inject

- private javax.enterprise.event.Event<MyEvent> event;

-

- public InputPanel() {

- super("Input");

-

- TextField editor = new TextField();

- Button save = new Button("Save", e -> // Java 8

- event.fire(new MyEvent(editor.getValue())));

-

- setContent(new VerticalLayout(editor, save));

- }

-}

-----

-

-Firing an event is done with the [methodname]#fire()# method on the injected

-event object. In our example, the event is as follows:

-

-

-[source, java]

-----

-public class MyEvent implements Serializable {

- private String text;

-

- public MyEvent(String text) {

- this.text = text;

- }

-

- public String getName() {

- return text;

- }

-}

-----

-

-The event is received by any method (in an injected object) marked by

-[classname]#@Observes# annotation for the event parameter to observe the event

-type.

-

-

-[source, java]

-----

-@UIScoped

-class DisplayPanel extends Panel {

- Label display = new Label("-nothing to display-");

-

- public DisplayPanel() {

- super("Display");

- setContent(display);

- }

-

- void myEventObserver(@Observes MyEvent event) {

- display.setValue("Observed: " + event.getName());

- }

-}

-----

-

-Such a component that observes events from other components must be scoped to

-the UI or view, as otherwise it will be request-scoped and a new instance is

-created for receiving each event.

-

-The UI with interaction is shown in <<figure.advanced.cdi.events.intro>>.

-

-[[figure.advanced.cdi.events.intro]]

-.Observing CDI Events

-image::img/cdi-events-observing.png[]

-

-Any injection qualifiers defined for the event object in the sender are matched

-in the observers, which feature we will use later to avoid receiving unwanted

-events.

-

-

-[[advanced.cdi.events.broadcasting]]

-=== Communicating Between UIs

-

-((("broadcasting", id="term.advanced.cdi.events.broadcasting", range="startofrange")))

-

-

-CDI events are not propagated to inactive contexts, and only the context of the

-currently processed UI is active. Further, as explained in

-<<dummy/../../../framework/advanced/advanced-push#advanced.push.running,"Accessing

-UI from Another Thread">>, other Vaadin UIs may not be accessed without proper

-synchronization, as their requests are processed concurrently in different

-server threads. Therefore, you need to pass the events through an

-application-scoped messaging service and synchronize the access to other UIs by

-using the [methodname]#access()# method.

-

-In

-<<dummy/../../../framework/advanced/advanced-push#advanced.push.pusharound,"Broadcasting

-to Other Users">> we looked into how to pass messages to all other UIs using a

-broadcasting service. In that example, we used static variables and methods to

-store references and to access the service. With CDI, we can let the context

-manage its lifecycle, access it by injection, and pass messages by CDI events.

-By scoping the messaging service to application, we essentially make it a

-singleton.

-

-

-[source, java]

-----

-@ApplicationScoped

-public class CDIBroadcaster implements Serializable {

-----

-

-As we can not let CDI deliver the messages, the messaging service needs to keep

-book of the messaging clients (UIs) waiting to receive messages.

-

-

-[source, java]

-----

- private Collection<UI> uis = new HashSet<UI>();

-

- public synchronized void register(UI listener) {

- uis.add(listener);

- }

-

- public synchronized void unregister(UI listener) {

- uis.remove(listener);

- }

-----

-

-The main logic of the messaging service is to observe messages and fire them in

-the recipient UIs. As we are broadcasting to all UIs here, we again use an

-executor service to execute the code. To lock on the session when accessing the

-UIs, we use the [methodname]#access()# method.

-

-

-[source, java]

-----

- // Inject event to be fired

- @Inject

- private javax.enterprise.event.Event<BroadcastMessage>

- messageEvent;

-

- ExecutorService executorService =

- Executors.newSingleThreadExecutor();

-

- // Observe messages (only from clients)

- @SuppressWarnings("unused")

- private synchronized void observeMessage(

- @Observes @OriginalSender

- final BroadcastMessage message) {

- for (final UI listener: uis)

- executorService.execute(() ->

- listener.access(()->

- messageEvent.fire(message)));

- }

-}

-----

-

-Here we use a [classname]#@OriginalSender# qualifier to receive events only from

-a client (original sender), not from the messaging service itself, which would

-cause an infinite event loop. The qualifier is defined as follows:

-

-((("CDI", "qualifiers")))

-

-[source, java]

-----

-@Qualifier

-@Retention(RUNTIME)

-@Target({PARAMETER, FIELD})

-public @interface OriginalSender {}

-----

-

-The message type is a simple POJO as follows:

-

-

-[source, java]

-----

-public class BroadcastMessage {

- private String text;

- private Object sender; // For checking if sent by self

-

- ... constructor, getters, and setters ...

-}

-----

-

-Let us take a look at the UI class, which manages both the messaging service and

-the client components. The UI just needs to register itself in the messaging

-service and build the UI, including the UI components doing messaging. We could,

-of course, do that also at view level.

-

-((("[classname]#@Push#")))

-

-[source, java]

-----

-@CDIUI("cdichat")

-@Push

-public class CDIChatUI extends UI {

- @Inject

- CDIBroadcaster broadcaster;

-

- @Inject

- ChatBox chatbox;

-

- @Override

- protected void init(VaadinRequest request) {

- setContent(chatbox);

-

- // Register to receive broadcasts

- broadcaster.register(this);

- }

-

- // Must also unregister when the UI expires or is closed

- @Override

- public void detach() {

- broadcaster.unregister(this);

- super.detach();

- }

-}

-----

-

-Now for an actual messaging client, we look at the chat box component. Most of

-the UI code is omitted from the example. As noted earlier, the component

-receiving events must be scoped to the UI, to avoid creation of invalid

-instances.

-

-((("[classname]#@UIScoped#")))

-

-[source, java]

-----

-@UIScoped

-class ChatBox extends CustomComponent {

- VerticalLayout messages = new VerticalLayout();

-

- public ChatBox(CDIChatUI cdiChatUI) {

- ... build the composite ...

-

- TextField input = new TextField();

-

- Button send = new Button("Send", e -> { // Java 8

- // Broadcast the input

- broadcast(input.getValue());

- addMessage(input.getValue()); // Add to self

- });

- ...

- }

-

- @Inject

- @OriginalSender

- private javax.enterprise.event.Event<BroadcastMessage>

- messageEvent;

-

- // Sends a message

- private void broadcast(String msg) {

- messageEvent.fire(new BroadcastMessage(msg, this));

- }

-

- // Receives messages

- @SuppressWarnings("unused")

- private void observeMessage(

- @Observes BroadcastMessage event) {

- if (event.getSender() != this)

- addMessage(event.getText());

- }

-

- private void addMessage(String msg) {

- messages.addComponent(new Label(msg));

- }

-}

-----

-

-((("CDI", "qualifiers")))

-Note that the client object is completely unaware of the fact that the messages

-are delivered through a messaging service; we have successfully decoupled the

-messaging logic required by Vaadin UIs from the component. Only the requirement

-for using the event qualifier remains (notice that its use is not checked at

-compile time).

-

-(((range="endofrange", startref="term.advanced.cdi.events.broadcasting")))

-

-(((range="endofrange", startref="term.advanced.cdi.events")))

-endif::web[]

-

-(((range="endofrange", startref="term.advanced.cdi.cdilong")))

-(((range="endofrange", startref="term.advanced.cdi.cdi")))

-(((range="endofrange", startref="term.advanced.cdi.cdiaddon")))

-

-

----

-title: Debug Mode and Window

-order: 3

-layout: page

----

-

-[[advanced.debug]]

-= Debug Mode and Window

-

-Vaadin applications can be run in two modes: __debug mode__ and __production

-mode__. The debug mode, which is on by default, enables a number of built-in

-debug features for Vaadin developers:

-

-* Debug Window

-* Display debug information in the Debug Window and server console

-* On-the-fly compilation of Sass themes

-

-[[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:

-

-[subs="normal"]

-----

-@VaadinServletConfiguration(

- productionMode = **false**,

- ui = **MyprojectUI.class**)

-----

-Or with a context parameter in the [filename]#web.xml# deployment descriptor:

-

-[subs="normal"]

-----

-&lt;context-param&gt;

- &lt;description&gt;Vaadin production mode&lt;/description&gt;

- &lt;param-name&gt;productionMode&lt;/param-name&gt;

- &lt;param-value&gt;**false**&lt;/param-value&gt;

-&lt;/context-param&gt;

-----

-Enabling the production mode disables the debug features, thereby preventing

-users from easily inspecting the inner workings of the application from the

-browser.

-

-

-[[advanced.debug.open]]

-== Opening the Debug Window

-

-Running an application in the debug mode enables the client-side Debug Window in

-the browser. You can open the Debug Window by adding " ?debug" parameter to the

-URL of the UI, for example, http://localhost:8080/myapp/?debug. The Debug Window

-has buttons for controlling the debugging features and a scrollable log of debug

-messages.

-

-[[]]

-.Debug Window

-image::img/debug-window-annotated-hi.png[]

-

-The functionalities are described in detail in the subsequent sections. You can

-move the window by dragging it from the title bar and resize it from the

-corners. The [guibutton]#Minimize# button minimizes the debug window in the

-corner of the browser window, and the [guibutton]#Close# button closes it.

-

-If you use the Firebug plugin for Firefox or the Developer Tools console in

-Chrome, the log messages will also be printed to the Firebug console. In such a

-case, you may want to enable client-side debugging without showing the Debug

-Window with " ?debug=quiet" in the URL. In the quiet debug mode, log messages

-will only be printed to the console of the browser debugger.

-

-

-[[advanced.debug.log]]

-== Debug Message Log

-

-The debug message log displays client-side debug messages, with time counter in

-milliseconds. The control buttons allow you to clear the log, reset the timer,

-and lock scrolling.

-

-[[]]

-.Debug Message Log

-image::img/debug-log-hi.png[]

-

-[[advanced.debug.log.custom]]

-=== Logging to Debug Window

-

-You can take advantage of the debug mode when developing client-side components,

-by using the standard Java [classname]#Logger# to write messages to the log. The

-messages will be written to the debug window and Firebug console. No messages

-are written if the debug window is not open or if the application is running in

-production mode.

-

-

-

-[[advanced.debug.info]]

-== General Information

-

-The [guilabel]#General information about the application(s)# tab displays

-various information about the UI, such as version numbers of the client and

-servlet engine, and the theme. If they do not match, you may need to compile the

-widget set or theme.

-

-[[]]

-.General Information

-image::img/debug-info.png[]

-

-

-[[advanced.debug.hierarchy]]

-== Inspecting Component Hierarchy

-

-The [guilabel]#Component Hierarchy# tab has several sub-modes that allow

-debugging the component tree in various ways.

-

-[[advanced.debug.hierarchy.tree]]

-=== Connector Hierarchy Tree

-

-The [guibutton]#Show the connector hierarchy tree# button displays the

-client-side connector hierarchy. As explained in

-<<dummy/../../../framework/gwt/gwt-overview.asciidoc#gwt.overview,"Integrating

-with the Server-Side">>, client-side widgets are managed by connectors that

-handle communication with the server-side component counterparts. The connector

-hierarchy therefore corresponds with the server-side component tree, but the

-client-side widget tree and HTML DOM tree have more complexity.

-

-[[]]

-.Connector Hierarchy Tree

-image::img/debug-hierarchy-tree.png[]

-

-Clicking on a connector highlights the widget in the UI.

-

-

-[[advanced.debug.hierarchy.inspect]]

-=== Inspecting a Component

-

-The [guibutton]#Select a component in the page to inspect it# button lets you

-select a component in the UI by clicking it and display its client-side

-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

-<<dummy/../../../framework/getting-started/getting-started-environment#getting-started.environment.firefox,"Firefox

-and Firebug">>. Firefox also has a built-in feature for inspecting HTML and CSS.

-

-

-[[advanced.debug.hierarchy.analyze]]

-=== Analyzing Layout Problems

-

-The [guilabel]#Check layouts for potential problems# button analyzes the

-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.

-image::img/debug-window-analyze-layouts.png[]

-

-Clicking on a reported problem highlights the component with the problem in the

-UI.

-

-The most common layout problem is caused by placing a component that has a

-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

-<<dummy/../../../framework//-overview.asciidoc#figure.advanced.debug.hierarchy.analyze,"">>.

-

-[classname]#CustomLayout# components can not be analyzed in the same way as

-other layouts. For custom layouts, the button analyzes all contained

-relative-sized components and checks if any relative dimension is calculated to

-zero so that the component will be invisible. The error log will display a

-warning for each of these invisible components. It would not be meaningful to

-emphasize the component itself as it is not visible, so when you select such an

-error, the parent layout of the component is emphasized if possible.

-

-

-[[advanced.debug.hierarchy.used]]

-=== Displaying Used Connectors

-

-The last button, [guibutton]#Show used connectors and how to optimize widget

-set#, displays a list of all currently visible connectors. It also generates a

-connector bundle loader factory, which you can use to optimize the widget set so

-that it only contains the widgets actually used in the UI. Note, however, that

-it only lists the connectors visible in the current UI state, and you usually

-have more connectors than that.

-

-

-

-[[advanced.debug.communication]]

-== Communication Log

-

-The [guilabel]#Communication# tab displays all server requests. You can unfold

-the requests to view details, such as the connectors involved. Clicking on a

-connector highlights the corresponding element in the UI.

-

-You can use Firebug or Developer Tools in Firefox or Chrome, respectively, to

-get more detailed information about the requests and responses.

-

-

-[[advanced.debug.devmodes]]

-== Debug Modes

-

-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

-<<dummy/../../../framework/clientside/clientside-debugging#clientside.debugging,"Debugging

-Client-Side Code">>.

-

-

-

-

----

-title: Drag and Drop

-order: 12

-layout: page

----

-

-[[advanced.dragndrop]]

-= Drag and Drop

-

-((("Drag and Drop", id="term.advanced.dragndrop", range="startofrange")))

-

-

-Dragging an object from one location to another by grabbing it with mouse,

-holding the mouse button pressed, and then releasing the button to "drop" it to

-the other location is a common way to move, copy, or associate objects. For

-example, most operating systems allow dragging and dropping files between

-folders or dragging a document on a program to open it. In Vaadin, it is

-possible to drag and drop components and parts of certain components.

-

-Dragged objects, or __transferables__, are essentially data objects. You can

-drag and drop rows in [classname]#Table# and nodes in [classname]#Tree#

-components, either within or between the components. You can also drag entire

-components by wrapping them inside [classname]#DragAndDropWrapper#.

-

-Dragging starts from a __drag source__, which defines the transferable.

-Transferables implement the [classname]#Transferable# interfaces. For trees and

-tables, which are bound to [classname]#Container# data sources, a node or row

-transferable is a reference to an [classname]#Item# in the Vaadin Data Model.

-Dragged components are referenced with a [classname]#WrapperTransferable#.

-Starting dragging does not require any client-server communication, you only

-need to enable dragging. All drag and drop logic occurs in two operations:

-determining ( __accepting__) where dropping is allowed and actually dropping.

-Drops can be done on a __drop target__, which implements the

-[classname]#DropTarget# interface. Three components implement the interface:

-[classname]#Tree#, [classname]#Table#, and [classname]#DragAndDropWrapper#.

-These accept and drop operations need to be provided in a __drop handler__.

-Essentially all you need to do to enable drag and drop is to enable dragging in

-the drag source and implement the [methodname]#getAcceptCriterion()# and

-[methodname]#drop()# methods in the [classname]#DropHandler# interface.

-

-The client-server architecture of Vaadin causes special requirements for the

-drag and drop functionality. The logic for determining where a dragged object

-can be dropped, that is, __accepting__ a drop, should normally be done on the

-client-side, in the browser. Server communications are too slow to have much of

-such logic on the server-side. The drag and drop feature therefore offers a

-number of ways to avoid the server communications to ensure a good user

-experience.

-

-[[advanced.dragndrop.drophandler]]

-== Handling Drops

-

-Most of the user-defined drag and drop logic occurs in a __drop handler__, which

-is provided by implementing the [methodname]#drop()# method in the

-[classname]#DropHandler# interface. A closely related definition is the drop

-accept criterion, which is defined in the [methodname]#getAcceptCriterion()#

-method in the same interface. It is described in

-<<advanced.dragndrop.acceptcriteria>> later.

-

-The [methodname]#drop()# method gets a [classname]#DragAndDropEvent# as its

-parameters. The event object provides references to two important object:

-[classname]#Transferable# and [classname]#TargetDetails#.

-

-A [classname]#Transferable# contains a reference to the object (component or

-data item) that is being dragged. A tree or table item is represented as a

-[classname]#TreeTransferable# or [classname]#TableTransferable# object, which

-carries the item identifier of the dragged tree or table item. These special

-transferables, which are bound to some data in a container, are

-[classname]#DataBoundTransferable#. Dragged components are represented as

-[classname]#WrapperTransferable# objects, as the components are wrapped in a

-[classname]#DragAndDropWrapper#.

-

-The [classname]#TargetDetails# object provides information about the exact

-location where the transferable object is being dropped. The exact class of the

-details object depends on the drop target and you need to cast it to the proper

-subclass to get more detailed information. If the target is selection component,

-essentially a tree or a table, the [classname]#AbstractSelectTargetDetails#

-object tells the item on which the drop is being made. For trees, the

-[classname]#TreeTargetDetails# gives some more details. For wrapped components,

-the information is provided in a [classname]#WrapperDropDetails# object. In

-addition to the target item or component, the details objects provide a __drop

-location__. For selection components, the location can be obtained with the

-[methodname]#getDropLocation()# and for wrapped components with

-[methodname]#verticalDropLocation()# and [methodname]#horizontalDropLocation()#.

-The locations are specified as either [classname]#VerticalDropLocation# or

-[classname]#HorizontalDropLocation# objects. The drop location objects specify

-whether the transferable is being dropped above, below, or directly on (at the

-middle of) a component or item.

-

-Dropping on a [classname]#Tree#, [classname]#Table#, and a wrapped component is

-explained further in the following sections.

-

-

-[[advanced.dragndrop.treedrop]]

-== Dropping Items On a [classname]#Tree#

-

-You can drag items from, to, or within a [classname]#Tree#. Making tree a drag

-source requires simply setting the drag mode with [methodname]#setDragMode()#.

-[classname]#Tree# currently supports only one drag mode,

-[literal]#++TreeDragMode.NODE++#, which allows dragging single tree nodes. While

-dragging, the dragged node is referenced with a [classname]#TreeTransferable#

-object, which is a [classname]#DataBoundTransferable#. The tree node is

-identified by the item ID of the container item.

-

-When a transferable is dropped on a tree, the drop location is stored in a

-[classname]#TreeTargetDetails# object, which identifies the target location by

-item ID of the tree node on which the drop is made. You can get the item ID with

-[methodname]#getItemIdOver()# method in

-[classname]#AbstractSelectTargetDetails#, which the

-[classname]#TreeTargetDetails# inherits. A drop can occur directly on or above

-or below a node; the exact location is a [classname]#VerticalDropLocation#,

-which you can get with the [methodname]#getDropLocation()# method.

-

-In the example below, we have a [classname]#Tree# and we allow reordering the

-tree items by drag and drop.

-

-

-[source, java]

-----

-final Tree tree = new Tree("Inventory");

-tree.setContainerDataSource(TreeExample.createTreeContent());

-layout.addComponent(tree);

-

-// Expand all items

-for (Iterator<?> it = tree.rootItemIds().iterator(); it.hasNext();)

- tree.expandItemsRecursively(it.next());

-

-// Set the tree in drag source mode

-tree.setDragMode(TreeDragMode.NODE);

-

-// Allow the tree to receive drag drops and handle them

-tree.setDropHandler(new DropHandler() {

- public AcceptCriterion getAcceptCriterion() {

- return AcceptAll.get();

- }

-

- public void drop(DragAndDropEvent event) {

- // Wrapper for the object that is dragged

- Transferable t = event.getTransferable();

-

- // Make sure the drag source is the same tree

- if (t.getSourceComponent() != tree)

- return;

-

- TreeTargetDetails target = (TreeTargetDetails)

- event.getTargetDetails();

-

- // Get ids of the dragged item and the target item

- Object sourceItemId = t.getData("itemId");

- Object targetItemId = target.getItemIdOver();

-

- // On which side of the target the item was dropped

- VerticalDropLocation location = target.getDropLocation();

-

- HierarchicalContainer container = (HierarchicalContainer)

- tree.getContainerDataSource();

-

- // Drop right on an item -> make it a child

- if (location == VerticalDropLocation.MIDDLE)

- tree.setParent(sourceItemId, targetItemId);

-

- // Drop at the top of a subtree -> make it previous

- else if (location == VerticalDropLocation.TOP) {

- Object parentId = container.getParent(targetItemId);

- container.setParent(sourceItemId, parentId);

- container.moveAfterSibling(sourceItemId, targetItemId);

- container.moveAfterSibling(targetItemId, sourceItemId);

- }

-

- // Drop below another item -> make it next

- else if (location == VerticalDropLocation.BOTTOM) {

- Object parentId = container.getParent(targetItemId);

- container.setParent(sourceItemId, parentId);

- container.moveAfterSibling(sourceItemId, targetItemId);

- }

- }

-});

-----

-

-[[advanced.dragndrop.treedrop.criteria]]

-=== Accept Criteria for Trees

-

-[classname]#Tree# defines some specialized accept criteria for trees.

-

-[classname]#TargetInSubtree#(client-side):: Accepts if the target item is in the specified sub-tree. The sub-tree is specified by the item ID of the root of the sub-tree in the constructor. The second constructor includes a depth parameter, which specifies how deep from the given root node are drops accepted. Value [literal]#++-1++# means infinite, that is, the entire sub-tree, and is therefore the same as the simpler constructor.

-[classname]#TargetItemAllowsChildren#(client-side):: Accepts a drop if the tree has [methodname]#setChildrenAllowed()# enabled for the target item. The criterion does not require parameters, so the class is a singleton and can be acquired with [methodname]#Tree.TargetItemAllowsChildren.get()#. For example, the following composite criterion accepts drops only on nodes that allow children, but between all nodes:

-+

-[source, java]

-----

-return new Or (Tree.TargetItemAllowsChildren.get(), new Not(VerticalLocationIs.MIDDLE));

-----

-

-[classname]#TreeDropCriterion#(server-side):: Accepts drops on only some items, which as specified by a set of item IDs. You must extend the abstract class and implement the [methodname]#getAllowedItemIds()# to return the set. While the criterion is server-side, it is lazy-loading, so that the list of accepted target nodes is loaded only once from the server for each drag operation. See <<advanced.dragndrop.acceptcriteria>> for an example.

-

-

-In addition, the accept criteria defined in [classname]#AbstractSelect# are

-available for a [classname]#Tree#, as listed in

-<<advanced.dragndrop.acceptcriteria>>.

-

-

-

-[[advanced.dragndrop.tabledrop]]

-== Dropping Items On a [classname]#Table#

-

-You can drag items from, to, or within a [classname]#Table#. Making table a drag

-source requires simply setting the drag mode with [methodname]#setDragMode()#.

-[classname]#Table# supports dragging both single rows, with

-[literal]#++TableDragMode.ROW++#, and multiple rows, with

-[literal]#++TableDragMode.MULTIROW++#. While dragging, the dragged node or nodes

-are referenced with a [classname]#TreeTransferable# object, which is a

-[classname]#DataBoundTransferable#. Tree nodes are identified by the item IDs of

-the container items.

-

-When a transferable is dropped on a table, the drop location is stored in a

-[classname]#AbstractSelectTargetDetails# object, which identifies the target row

-by its item ID. You can get the item ID with [methodname]#getItemIdOver()#

-method. A drop can occur directly on or above or below a row; the exact location

-is a [classname]#VerticalDropLocation#, which you can get with the

-[methodname]#getDropLocation()# method from the details object.

-

-[[advanced.dragndrop.tabledrop.criteria]]

-=== Accept Criteria for Tables

-

-[classname]#Table# defines one specialized accept criterion for tables.

-

-[classname]#TableDropCriterion#(server-side):: Accepts drops only on (or above or below) items that are specified by a set of item IDs. You must extend the abstract class and implement the [methodname]#getAllowedItemIds()# to return the set. While the criterion is server-side, it is lazy-loading, so that the list of accepted target items is loaded only once from the server for each drag operation.

-

-

-

-

-[[advanced.dragndrop.acceptcriteria]]

-== Accepting Drops

-

-((("Drag and Drop", "Accept Criteria", id="term.advanced.dragndrop.acceptcriteria", range="startofrange")))

-

-

-You can not drop the objects you are dragging around just anywhere. Before a

-drop is possible, the specific drop location on which the mouse hovers must be

-__accepted__. Hovering a dragged object over an accepted location displays an

-__accept indicator__, which allows the user to position the drop properly. As

-such checks have to be done all the time when the mouse pointer moves around the

-drop targets, it is not feasible to send the accept requests to the server-side,

-so drops on a target are normally accepted by a client-side __accept

-criterion__.

-

-A drop handler must define the criterion on the objects which it accepts to be

-dropped on the target. The criterion needs to be provided in the

-[classname]#getAcceptCriterion()# method of the [classname]#DropHandler#

-interface. A criterion is represented in an [classname]#AcceptCriterion# object,

-which can be a composite of multiple criteria that are evaluated using logical

-operations. There are two basic types of criteria: __client-side__ and

-__server-side criteria__. The various built-in criteria allow accepting drops

-based on the identity of the source and target components, and on the __data

-flavor__ of the dragged objects.

-

-To allow dropping any transferable objects, you can return a universal accept

-criterion, which you can get with [methodname]#AcceptAll.get()#.

-

-

-[source, java]

-----

-tree.setDropHandler(new DropHandler() {

- public AcceptCriterion getAcceptCriterion() {

- return AcceptAll.get();

- }

- ...

-----

-

-[[advanced.dragndrop.acceptcriteria.client-side]]

-=== Client-Side Criteria

-

-The __client-side criteria__, which inherit the

-[classname]#ClientSideCriterion#, are verified on the client-side, so server

-requests are not needed for verifying whether each component on which the mouse

-pointer hovers would accept a certain object.

-

-The following client-side criteria are define in

-[package]#com.vaadin.event.dd.acceptcriterion#:

-

-[classname]#AcceptAll#:: Accepts all transferables and targets.

-[classname]#And#:: Performs the logical AND operation on two or more client-side criteria; accepts the transferable if all the given sub-criteria accept it.

-[classname]#ContainsDataFlavour#:: The transferable must contain the defined data flavour.

-[classname]#Not#:: Performs the logical NOT operation on a client-side criterion; accepts the transferable if and only if the sub-criterion does not accept it.

-[classname]#Or#:: Performs the logical OR operation on two or more client-side criteria; accepts the transferable if any of the given sub-criteria accepts it.

-[classname]#SourceIs#:: Accepts all transferables from any of the given source components

-[classname]#SourceIsTarget#:: Accepts the transferable only if the source component is the same as the target. This criterion is useful for ensuring that items are dragged only within a tree or a table, and not from outside it.

-[classname]#TargetDetailIs#:: Accepts any transferable if the target detail, such as the item of a tree node or table row, is of the given data flavor and has the given value.

-

-

-In addition, target components such as [classname]#Tree# and [classname]#Table#

-define some component-specific client-side accept criteria. See

-<<advanced.dragndrop.treedrop>> for more details.

-

-[classname]#AbstractSelect# defines the following criteria for all selection

-components, including [classname]#Tree# and [classname]#Table#.

-

-[classname]#AcceptItem#:: Accepts only specific items from a specific selection component. The selection component, which must inherit [classname]#AbstractSelect#, is given as the first parameter for the constructor. It is followed by a list of allowed item identifiers in the drag source.

-[classname]#AcceptItem.ALL#:: Accepts all transferables as long as they are items.

-[classname]#TargetItemIs#:: Accepts all drops on the specified target items. The constructor requires the target component ( [classname]#AbstractSelect#) followed by a list of allowed item identifiers.

-[classname]#VerticalLocationIs.MIDDLE#,[classname]#TOP#, and[classname]#BOTTOM#:: The three static criteria accepts drops on, above, or below an item. For example, you could accept drops only in between items with the following:

-[source, java]

-----

-public AcceptCriterion getAcceptCriterion() {

- return new Not(VerticalLocationIs.MIDDLE);

-}

-----

-

-

-

-

-

-[[advanced.dragndrop.acceptcriteria.server-side]]

-=== Server-Side Criteria

-

-The __server-side criteria__ are verified on the server-side with the

-[methodname]#accept()# method of the [classname]#ServerSideCriterion# class.

-This allows fully programmable logic for accepting drops, but the negative side

-is that it causes a very large amount of server requests. A request is made for

-every target position on which the pointer hovers. This problem is eased in many

-cases by the component-specific lazy loading criteria

-[classname]#TableDropCriterion# and [classname]#TreeDropCriterion#. They do the

-server visit once for each drag and drop operation and return all accepted rows

-or nodes for current [classname]#Transferable# at once.

-

-The [methodname]#accept()# method gets the drag event as a parameter so it can

-perform its logic much like in [methodname]#drop()#.

-

-

-[source, java]

-----

-public AcceptCriterion getAcceptCriterion() {

- // Server-side accept criterion that allows drops on any other

- // location except on nodes that may not have children

- ServerSideCriterion criterion = new ServerSideCriterion() {

- public boolean accept(DragAndDropEvent dragEvent) {

- TreeTargetDetails target = (TreeTargetDetails)

- dragEvent.getTargetDetails();

-

- // The tree item on which the load hovers

- Object targetItemId = target.getItemIdOver();

-

- // On which side of the target the item is hovered

- VerticalDropLocation location = target.getDropLocation();

- if (location == VerticalDropLocation.MIDDLE)

- if (! tree.areChildrenAllowed(targetItemId))

- return false; // Not accepted

-

- return true; // Accept everything else

- }

- };

- return criterion;

-}

-----

-

-The server-side criteria base class [classname]#ServerSideCriterion# provides a

-generic [methodname]#accept()# method. The more specific

-[classname]#TableDropCriterion# and [classname]#TreeDropCriterion# are

-conveniency extensions that allow definiting allowed drop targets as a set of

-items. They also provide some optimization by lazy loading, which reduces server

-communications significantly.

-

-

-[source, java]

-----

-public AcceptCriterion getAcceptCriterion() {

- // Server-side accept criterion that allows drops on any

- // other tree node except on node that may not have children

- TreeDropCriterion criterion = new TreeDropCriterion() {

- @Override

- protected Set<Object> getAllowedItemIds(

- DragAndDropEvent dragEvent, Tree tree) {

- HashSet<Object> allowed = new HashSet<Object>();

- for (Iterator<Object> i =

- tree.getItemIds().iterator(); i.hasNext();) {

- Object itemId = i.next();

- if (tree.hasChildren(itemId))

- allowed.add(itemId);

- }

- return allowed;

- }

- };

- return criterion;

-}

-----

-

-

-[[advanced.dragndrop.acceptcriteria.indicators]]

-=== Accept Indicators

-

-When a dragged object hovers on a drop target, an __accept indicator__ is

-displayed to show whether or not the location is accepted. For

-[parameter]#MIDDLE# location, the indicator is a box around the target (tree

-node, table row, or component). For vertical drop locations, the accepted

-locations are shown as horizontal lines, and for horizontal drop locations as

-vertical lines.

-

-For [classname]#DragAndDropWrapper# drop targets, you can disable the accept

-indicators or __drag hints__ with the [parameter]#no-vertical-drag-hints#,

-[parameter]#no-horizontal-drag-hints#, and [parameter]#no-box-drag-hints#

-styles. You need to add the styles to the __layout that contains__ the wrapper,

-not to the wrapper itself.

-

-

-[source, java]

-----

-// Have a wrapper

-DragAndDropWrapper wrapper = new DragAndDropWrapper(c);

-layout.addComponent(wrapper);

-

-// Disable the hints

-layout.addStyleName("no-vertical-drag-hints");

-layout.addStyleName("no-horizontal-drag-hints");

-layout.addStyleName("no-box-drag-hints");

-----

-

-

-(((range="endofrange", startref="term.advanced.dragndrop.acceptcriteria")))

-

-[[advanced.dragndrop.dragging]]

-== Dragging Components

-

-Dragging a component requires wrapping the source component within a

-[classname]#DragAndDropWrapper#. You can then allow dragging by putting the

-wrapper (and the component) in drag mode with [methodname]#setDragStartMode()#.

-The method supports two drag modes: [parameter]#DragStartMode.WRAPPER# and

-[parameter]#DragStartMode.COMPONENT#, which defines whether the entire wrapper

-is shown as the drag image while dragging or just the wrapped component.

-

-

-[source, java]

-----

-// Have a component to drag

-final Button button = new Button("An Absolute Button");

-

-// Put the component in a D&D wrapper and allow dragging it

-final DragAndDropWrapper buttonWrap = new DragAndDropWrapper(button);

-buttonWrap.setDragStartMode(DragStartMode.COMPONENT);

-

-// Set the wrapper to wrap tightly around the component

-buttonWrap.setSizeUndefined();

-

-// Add the wrapper, not the component, to the layout

-layout.addComponent(buttonWrap, "left: 50px; top: 50px;");

-----

-

-The default height of [classname]#DragAndDropWrapper# is undefined, but the

-default width is 100%. If you want to ensure that the wrapper fits tightly

-around the wrapped component, you should call [methodname]#setSizeUndefined()#

-for the wrapper. Doing so, you should make sure that the wrapped component does

-not have a relative size, which would cause a paradox.

-

-Dragged components are referenced in the [classname]#WrapperTransferable#. You

-can get the reference to the dragged component with

-[methodname]#getDraggedComponent()#. The method will return [literal]#++null++#

-if the transferable is not a component. Also HTML 5 drags (see later) are held

-in wrapper transferables.

-

-

-[[advanced.dragndrop.drop-on-component]]

-== Dropping on a Component

-

-Drops on a component are enabled by wrapping the component in a

-[classname]#DragAndDropWrapper#. The wrapper is an ordinary component; the

-constructor takes the wrapped component as a parameter. You just need to define

-the [classname]#DropHandler# for the wrapper with

-[methodname]#setDropHandler()#.

-

-In the following example, we allow moving components in an absolute layout.

-Details on the drop handler are given later.

-

-

-[source, java]

-----

-// A layout that allows moving its contained components

-// by dragging and dropping them

-final AbsoluteLayout absLayout = new AbsoluteLayout();

-absLayout.setWidth("100%");

-absLayout.setHeight("400px");

-

-... put some (wrapped) components in the layout ...

-

-// Wrap the layout to allow handling drops

-DragAndDropWrapper layoutWrapper =

- new DragAndDropWrapper(absLayout);

-

-// Handle moving components within the AbsoluteLayout

-layoutWrapper.setDropHandler(new DropHandler() {

- public AcceptCriterion getAcceptCriterion() {

- return AcceptAll.get();

- }

-

- public void drop(DragAndDropEvent event) {

- ...

- }

-});

-----

-

-[[advanced.dragndrop.drop-on-component.details]]

-=== Target Details for Wrapped Components

-

-The drop handler receives the drop target details in a

-[classname]#WrapperTargetDetails# object, which implements the

-[classname]#TargetDetails# interface.

-

-

-[source, java]

-----

-public void drop(DragAndDropEvent event) {

- WrapperTransferable t =

- (WrapperTransferable) event.getTransferable();

- WrapperTargetDetails details =

- (WrapperTargetDetails) event.getTargetDetails();

-----

-

-The wrapper target details include a [classname]#MouseEventDetails# object,

-which you can get with [methodname]#getMouseEvent()#. You can use it to get the

-mouse coordinates for the position where the mouse button was released and the

-drag ended. Similarly, you can find out the drag start position from the

-transferable object (if it is a [classname]#WrapperTransferable#) with

-[methodname]#getMouseDownEvent()#.

-

-

-[source, java]

-----

-// Calculate the drag coordinate difference

-int xChange = details.getMouseEvent().getClientX()

- - t.getMouseDownEvent().getClientX();

-int yChange = details.getMouseEvent().getClientY()

- - t.getMouseDownEvent().getClientY();

-

-// Move the component in the absolute layout

-ComponentPosition pos =

- absLayout.getPosition(t.getSourceComponent());

-pos.setLeftValue(pos.getLeftValue() + xChange);

-pos.setTopValue(pos.getTopValue() + yChange);

-----

-

-You can get the absolute x and y coordinates of the target wrapper with

-[methodname]#getAbsoluteLeft()# and [methodname]#getAbsoluteTop()#, which allows

-you to translate the absolute mouse coordinates to coordinates relative to the

-wrapper. Notice that the coordinates are really the position of the wrapper, not

-the wrapped component; the wrapper reserves some space for the accept

-indicators.

-

-The [methodname]#verticalDropLocation()# and

-[methodname]#horizontalDropLocation()# return the more detailed drop location in

-the target.

-

-

-

-[[advanced.dragndrop.external]]

-== Dragging Files from Outside the Browser

-

-The [classname]#DragAndDropWrapper# allows dragging files from outside the

-browser and dropping them on a component wrapped in the wrapper. Dropped files

-are automatically uploaded to the application and can be acquired from the

-wrapper with [methodname]#getFiles()#. The files are represented as

-[classname]#Html5File# objects as defined in the inner class. You can define an

-upload [classname]#Receiver# to receive the content of a file to an

-[classname]#OutputStream#.

-

-Dragging and dropping files to browser is supported in HTML 5 and requires a

-compatible browser, such as Mozilla Firefox 3.6 or newer.

-

-

-(((range="endofrange", startref="term.advanced.dragndrop")))

-

-

----

-title: Embedding UIs in Web Pages

-order: 2

-layout: page

----

-

-[[advanced.embedding]]

-= Embedding UIs in Web Pages

-

-Many web sites are not all Vaadin, but Vaadin UIs are used only for specific

-functionalities. In practice, many web applications are a mixture of dynamic web

-pages, such as JSP, and Vaadin UIs embedded in such pages.

-

-Embedding Vaadin UIs in web pages is easy and there are several different ways

-to embed them. One is to have a [literal]#++<div>++# placeholder for the UI and

-load the Vaadin Client-Side Engine with some simple JavaScript code. Another

-method is even easier, which is to simply use the [literal]#++<iframe>++#

-element. Both of these methods have advantages and disadvantages. One

-disadvantage of the [literal]#++<iframe>++# method is that the size of the

-[literal]#++<iframe>++# element is not flexible according to the content while

-the [literal]#++<div>++# method allows such flexibility. The following sections

-look closer into these two embedding methods.

-

-[[advanced.embedding.div]]

-== Embedding Inside a [literal]#++div++# Element

-

-You can embed one or more Vaadin UIs inside a web page with a method that is

-equivalent to loading the initial page content from the Vaadin servlet in a

-non-embedded UI. Normally, the [classname]#VaadinServlet# generates an initial

-page that contains the correct parameters for the specific UI. You can easily

-configure it to load multiple Vaadin UIs in the same page. They can have

-different widget sets and different themes.

-

-Embedding an UI requires the following basic tasks:

-

-* Set up the page header

-* Include a GWT history frame in the page

-* Call the [filename]#vaadinBootstrap.js# file

-* Define the [literal]#++<div>++# element for the UI

-* Configure and initialize the UI

-

-Notice that you can view the loader page for the UI easily by opening the UI in

-a web browser and viewing the HTML source code of the page. You could just copy

-and paste the embedding code from the page, but some modifications and

-additional settings are required, mainly related to the URLs that have to be

-made relative to the page instead of the servlet URL.

-

-ifdef::web[]

-[[advanced.embedding.div.head]]

-=== The Head Matter

-

-The HTML page in which the Vaadin UI is embedded should be a valid HTML 5

-document. The content of the head element is largely up to you. The character

-encoding must be UTF-8. Some meta declarations are necessary for compatibility.

-You can also set the page favicon in the head element.

-

-[subs="normal"]

-----

-&lt;!DOCTYPE html&gt;

-&lt;html&gt;

- &lt;head&gt;

- &lt;meta http-equiv="Content-Type"

- content="text/html; charset=UTF-8" /&gt;

- &lt;meta http-equiv="X-UA-Compatible"

- content="IE=9;chrome=1" /&gt;

-

- &lt;title&gt;[replaceable]#This is my Embedding Page#&lt;/title&gt;

-

- &lt;!-- Set up the favicon from the Vaadin theme --&gt;

- &lt;link rel="shortcut icon" type="image/vnd.microsoft.icon"

- href="/VAADIN/themes/[replaceable]#reindeer#/favicon.ico" /&gt;

- &lt;link rel="icon" type="image/vnd.microsoft.icon"

- href="/VAADIN/themes/[replaceable]#reindeer#/favicon.ico" /&gt;

- &lt;/head&gt;

-----

-endif::web[]

-

-ifdef::web[]

-[[advanced.embedding.div.body]]

-=== The Body Matter

-

-The page content must include some Vaadin-related definitions before you can

-embed Vaadin UIs in it.

-

-The [filename]#vaadinBootstrap.js# script makes definitions for starting up the

-UI. It must be called before initializing the UI. The source path must be

-relative to the path of the embedding page.

-

-[subs="normal"]

-----

-&lt;body&gt;

- &lt;script type="text/javascript"

- src="[replaceable]#./#VAADIN/vaadinBootstrap.js"&gt;&lt;/script&gt;

-----

-The bootstrap script is served by the Vaadin servlet from inside the

-[filename]#vaadin-server# JAR.

-

-Vaadin, or more precisely GWT, requires an invisible history frame, which is

-used for tracking the page or fragment history in the browser.

-

-

-[source, html]

-----

- <iframe tabindex="-1" id="__gwt_historyFrame"

- style="position: absolute; width: 0; height: 0;

- border: 0; overflow: hidden"

- src="javascript:false"></iframe>

-----

-

-endif::web[]

-

-ifdef::web[]

-[[advanced.embedding.div.div]]

-=== UI Placeholder Element

-

-A Vaadin UI is embedded in a placeholder [literal]#++<div>++# element. It should

-have the following features:

-

-* The [literal]#++<div>++# element must have an [literal]#++id++# attribute, which must be a unique ID in the page, normally something that identifies the servlet of the UI uniquely.

-* It must have at least the [literal]#++v-app++# style class.

-* it should have a nested [literal]#++<div>++# element with [literal]#++v-app-loading++# style class. This is a placeholder for the loading indicator that is displayed while the UI is being loaded.

-* It should also contain a [literal]#++<noscript>++# element that is shown if the browser does not support JavaScript or it has been disabled. The content of the element should instruct the use to enable JavaScript in the browser.

-

-The placeholder element can include style settings, typically a width and

-height. If the sizes are not defined, the UI will have an undefined size in the

-particular dimension, which must be in accordance with the sizing of the UI

-components.

-

-For example:

-

-[subs="normal"]

-----

-&lt;div style="[replaceable]#width: 300px; border: 2px solid green;#"

- id="helloworldui" class="v-app"&gt;

- &lt;div class="v-app-loading"&gt;&lt;/div&gt;

- &lt;noscript&gt;[replaceable]#You have to enable javascript in your browser to#

- [replaceable]#use an application built with Vaadin.#&lt;/noscript&gt;

-&lt;/div&gt;

-----

-endif::web[]

-

-ifdef::web[]

-[[advanced.embedding.div.init]]

-=== Initializing the UI

-

-The UI is loaded by calling the [literal]#++initApplication()++# method for the

-[literal]#++vaadin++# object defined in the bootstrap script. Before calling it,

-you should check that the bootstrap script was loaded properly.

-

-[subs="normal"]

-----

-&lt;script type="text/javascript"&gt;//&lt;![CDATA[

- if (!window.vaadin)

- alert("[replaceable]#Failed to load the bootstrap JavaScript:#"+

- "[replaceable]#VAADIN/vaadinBootstrap.js#");

-----

-The [literal]#++initApplication()++# takes two parameters. The first parameter

-is the UI identifier, exactly as given as the [literal]#++id++# attribute of the

-placeholder element. The second parameter is an associative map that contains

-parameters for the UI.

-

-The map must contain the following items:

-

-[parameter]#browserDetailsUrl#:: This should be the URL path (relative to the embedding page) to the Vaadin

-servlet of the UI. It is used by the bootstrap to communicate browser details. A

-trailing slash may be needed in some cases.

-

-+

-Notice that this parameter is not included in the loader page generated by the

-servlet, because in that case, it can default to the current URL.

-

-[parameter]#serviceUrl#:: This is used for server requests after initial loading and should be same as for

-[parameter]#browserDetailsUrl#. The two parameters are redundant and either may

-be removed in

-future.+

-//Bug

-#10122

-

-[parameter]#widgetset#:: This should be the exact class name of the widget set for the UI, that is, without the [filename]#.gwt.xml# file name extension. If the UI has no custom widget set, you can use the [classname]#com.vaadin.DefaultWidgetSet#.

-[parameter]#theme#:: Name of the theme, such as one of the built-in themes ( [literal]#++reindeer++#, [literal]#++runo++#, or [literal]#++chameleon++#) or a custom theme. It must exist under the [filename]#VAADIN/themes# folder.

-[parameter]#versionInfo#:: This parameter is itself an associative map that can contain two parameters: [parameter]#vaadinVersion# contains the version number of the Vaadin version used by the application. The [parameter]#applicationVersion# parameter contains the version of the particular application. The contained parameters are optional, but the [parameter]#versionInfo# parameter itself is not.

-[parameter]#vaadinDir#:: Relative path to the [filename]#VAADIN# directory. It is relative to the URL of the embedding page.

-[parameter]#heartbeatInterval#:: The [parameter]#hearbeatInterval# parameter defines the frequency of the keep-alive hearbeat for the UI in seconds, as described in <<dummy/../../../framework/application/application-lifecycle#application.lifecycle.ui-expiration,"UI Expiration">>.

-[parameter]#debug#:: The parameter defines whether the debug window, as described in <<dummy/../../../framework/advanced/advanced-debug#advanced.debug,"Debug Mode and Window">>, is enabled.

-[parameter]#standalone#:: This parameter should be [parameter]#false# when embedding. The parameter defines whether the UI is rendered on its own in the browser window or in some context. A standalone UI may do things that might interfere with other parts of the page, such as change the page title and request focus when it is loaded. When embedding, the UI is not standalone.

-[parameter]#authErrMsg#,[parameter]#comErrMsg#, and[parameter]#sessExpMsg#:: These three parameters define the client-side error messages for authentication error, communication error, and session expiration, respectively. The parameters are associative maps themselves and must contain two key-value pairs: [parameter]#message#, which should contain the error text in HTML, and [parameter]#caption#, which should be the error caption.

-

-

-For example:

-

-[subs="normal"]

-----

- vaadin.initApplication("[replaceable]#helloworldui#", {

- "browserDetailsUrl": "[replaceable]#helloworld#/",

- "serviceUrl": "[replaceable]#helloworld#/",

- "widgetset": "[replaceable]#com.example.MyWidgetSet#",

- "theme": "[replaceable]#mytheme#",

- "versionInfo": {"vaadinVersion": "[replaceable]#7.0.0#"},

- "vaadinDir": "[replaceable]#VAADIN/#",

- "heartbeatInterval": [replaceable]#300#,

- "debug": [replaceable]#true#,

- "standalone": false,

- "authErrMsg": {

- "message": "[replaceable]#Take note of any unsaved data, "+ "and &lt;u&gt;click here&lt;\/u&gt; to continue.#",

- "caption": "Authentication problem"

- },

- "comErrMsg": {

- "message": "[replaceable]#Take note of any unsaved data, "+ "and &lt;u&gt;click here&lt;\/u&gt; to continue.#",

- "caption": "Communication problem"

- },

- "sessExpMsg": {

- "message": "[replaceable]#Take note of any unsaved data, "+ "and &lt;u&gt;click here&lt;\/u&gt; to continue.#",

- "caption": "Session Expired"

- }

- });//]]&gt;

-&lt;/script&gt;

-----

-Notice that many of the parameters are normally deployment parameters, specified

-in the deployment descriptor, as described in

-<<dummy/../../../framework/application/application-environment#application.environment.parameters,"Other

-Servlet Configuration Parameters">>.

-

-endif::web[]

-

-ifdef::web[]

-[[advanced.embedding.div.summary]]

-=== Summary of Div Embedding

-

-Below is a complete example of embedding an UI in a [literal]#++<div>++#

-element.

-

-

-[source, html]

-----

-<?xml version="1.0" encoding="UTF-8" ?>

-<!DOCTYPE html>

-<html>

-<head>

- <meta http-equiv="Content-Type"

- content="text/html; charset=UTF-8" />

- <meta http-equiv="X-UA-Compatible"

- content="IE=9;chrome=1" />

-

- <title>Embedding a Vaadin Application in HTML Page</title>

-

- <!-- Set up the favicon from the Vaadin theme -->

- <link rel="shortcut icon" type="image/vnd.microsoft.icon"

- href="/VAADIN/themes/reindeer/favicon.ico" />

- <link rel="icon" type="image/vnd.microsoft.icon"

- href="/VAADIN/themes/reindeer/favicon.ico" />

-</head>

-

-<body>

- <!-- Loads the Vaadin widget set, etc. -->

- <script type="text/javascript"

- src="VAADIN/vaadinBootstrap.js"></script>

-

- <!-- GWT requires an invisible history frame. It is -->

- <!-- needed for page/fragment history in the browser. -->

- <iframe tabindex="-1" id="__gwt_historyFrame"

- style="position: absolute; width: 0; height: 0;

- border: 0; overflow: hidden"

- src="javascript:false"></iframe>

-

- <h1>Embedding a Vaadin UI</h1>

-

- <p>This is a static web page that contains an embedded Vaadin

- application. It's here:</p>

-

- <!-- So here comes the div element in which the Vaadin -->

- <!-- application is embedded. -->

- <div style="width: 300px; border: 2px solid green;"

- id="helloworld" class="v-app">

-

- <!-- Optional placeholder for the loading indicator -->

- <div class=" v-app-loading"></div>

-

- <!-- Alternative fallback text -->

- <noscript>You have to enable javascript in your browser to

- use an application built with Vaadin.</noscript>

- </div>

-

- <script type="text/javascript">//<![CDATA[

- if (!window.vaadin)

- alert("Failed to load the bootstrap JavaScript: "+

- "VAADIN/vaadinBootstrap.js");

-

- /* The UI Configuration */

- vaadin.initApplication("helloworld", {

- "browserDetailsUrl": "helloworld/",

- "serviceUrl": "helloworld/",

- "widgetset": "com.example.MyWidgetSet",

- "theme": "mytheme",

- "versionInfo": {"vaadinVersion": "7.0.0"},

- "vaadinDir": "VAADIN/",

- "heartbeatInterval": 300,

- "debug": true,

- "standalone": false,

- "authErrMsg": {

- "message": "Take note of any unsaved data, "+

- "and <u>click here<\/u> to continue.",

- "caption": "Authentication problem"

- },

- "comErrMsg": {

- "message": "Take note of any unsaved data, "+

- "and <u>click here<\/u> to continue.",

- "caption": "Communication problem"

- },

- "sessExpMsg": {

- "message": "Take note of any unsaved data, "+

- "and <u>click here<\/u> to continue.",

- "caption": "Session Expired"

- }