Файл: book-of-vaadin.pdf

Chapter 17

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.

17.1. 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. Vaadin Directory [http://vaadin.com/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.

Using Vaadin Add-ons

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.

17.2. Downloading Add-ons from Vaadin Directory

If you are not using a Maven-compatible dependency manager 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.

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

2.Click Download Now and save the JAR or Zip file on your computer.

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

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

5.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 Section 17.2.1, “Compiling Widget Sets with an Ant Script”, or later in this chapter for instructions for compiling the widget set with Eclipse and Maven.

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

17.2.1.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 Vaadin download page [http://vaadin.com/download/].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.

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

Using Vaadin Add-ons

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

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

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

3.Click the Maven POM to display the Maven dependency declaration, as illustrated in Figure 17.1. If the add-on is available with multiple licenses, you will be prompted to select a license for the dependency.

Figure 17.1. Maven Dependency Definition

4. Open the ivy.xml in your Eclipse project either in the XML or Ivy Editor (either doubleclick the file or right-click it and select Open With Ivy Editor).

5.At the end of the dependencies element, add a new dependency declaration as follows, with the organization, name, and revision of the add-on as given in the Maven POM declaration:

<dependencies>

...

<dependency org="com.vaadin.addon" name="vaadin-charts" rev="1.0.0" />

</dependencies>

You can specify either a fixed version number or a dynamic revision tag such as latest.release. You can find more information about the dependency declarations in Ivy documentation.

Using Vaadin Add-ons

IvyIDE immediately resolves the dependencies when you save the file.

6.Compile the add-on widget set by clicking the Compile Vaadin widgets button in the toolbar.

Figure 17.2. Compiling Widget Set in Eclipse

The vaadin-addons repository mentioned in the Maven POM declaration is included in the default ivysettings.xml file generated by the Vaadin Plugin for Eclipse. If you get Vaadin addons from another repository, such as the local repository, you need to define a resolver for the repository in the settings file.

17.4. Using Add-ons in a Maven Project

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 Section 2.6, “Using Vaadin with Maven”.

17.4.1. Adding a Dependency

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

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

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

3.Click the Maven POM to display the Maven dependency declaration, as illustrated in Figure 17.3. If the add-on is available with multiple licenses, you will be prompted to select a license for the dependency.

Using Vaadin Add-ons

Figure 17.3. Maven POM Definitions

4.Copy the dependency declaration to the pom.xml file in your project, under the dependencies element.

...

<dependencies>

...

<dependency> <groupId>com.vaadin.addon</groupId> <artifactId>vaadin-charts</artifactId> <version>1.0.0</version>

</dependency>

</dependencies>

You can use an exact version number, as is done in the example above, or 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 vaadin-archetype-application to create your project, it already includes the definition.

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

17.4.2.Compiling the Project Widget Set

If you have used the vaadin-archetype-application to create the project, the pom.xml includes all necessary declarations to compile the widget set. The widget set compilation occurs in standard Maven build phase, such as with package or install goal.

$ mvn package