Creating Add-ons

Add-ons are the most convenient way to reuse Vaadin code, either commercially or free. Vaadin Directory serves as the store for the add-ons. You can distribute add-ons both as JAR libraries and Zip packages.

Creating a typical add-on package involves the following tasks:

  • Compile server-side classes

  • Compile JavaDoc (optional)

  • Build the JAR

    • Include Vaadin add-on manifest

    • Include the compiled server-side classes

    • Include the compiled JavaDoc (optional)

    • Include sources of client-side classes for widget set compilation (optional)

    • Include any JavaScript dependency libraries (optional)

    • Exclude any test or demo code in the project

The exact contents depend on the add-on type. Component add-ons often include a widget set, but not always, such as JavaScript components or pure server-side components. You can also have data container and theme add-ons, as well as various tools.

It is common to distribute the JavaDoc in a separate JAR, but you can also include it in the same JAR.

Exporting Add-on in Eclipse

If you use the Vaadin Plugin for Eclipse for your add-on project, you can simply export the add-on from Eclipse.

  1. Select the project and then File › Export from the menu

  2. In the export wizard that opens, select Vaadin › Vaadin Add-on Package, and click Next

  3. In the Select the resources to export panel, select the content that should be included in the add-on package. In general, you should include sources in src folder (at least for the client-side package), compiled server-side classes, themes in WebContent/VAADIN/themes. These are all included automatically. You probably want to leave out any demo or example code.

    addon export

    Exporting a Vaadin Add-on

    If you are submitting the add-on to Vaadin Directory, the Implementation title should be exactly the name of the add-on in Directory. The name may contain spaces and most other letters. Notice that it is not possible to change the name later.

    The Implementation version is the version of your add-on. Typically experimental or beta releases start from 0.1.0, and stable releases from 1.0.0.

    The Widgetsets field should list the widget sets included in the add-on, separated by commas. The widget sets should be listed by their class name, that is, without the .gwt.xml extension.

    The JAR file is the file name of the exported JAR file. It should normally include the version number of the add-on. You should follow the Maven format for the name, such as myaddon-1.0.0.jar.

    Finally, click Finish.

Building Add-on with Ant

Building an add-on with Ant is similar to building Vaadin applications. Vaadin libraries and other dependencies are retrieved and included in the classpath using Apache Ivy.

In the following, we assume the same structure as in the Eclipse project example. Let us put the build script in the build folder under the project. We begin the Ant script as follows:

  1. <?xml version="1.0"?>
  3. <project xmlns:ivy="antlib:org.apache.ivy.ant"
  4.          name="My Own add-on"
  5.          basedir=".."
  6.          default="package-jar">

The namespace declaration is all you need to do to enable Ivy in Ant 1.6 and later. For earlier Ant versions, please see the Ivy documentation.

Configuration and Initialization

In the example script, we organize most settings in a configure target and then initialize the build in init target.

  1. //Update these settings for your project structure
  3. <target name="configure">
  4.     <!-- Where project source files are located -->
  5.     <property name="src-location" value="src" />
  7.     <!-- Name of the widget set. -->
  8.     <property name="widgetset" value="com.example.myaddon.widgetset.MyAddonWidgetset"/>
  10.     <!-- Addon version -->
  11.     <property name="version" value="0.1.0"/>
  13.     <!-- Compilation result directory -->
  14.     <property name="result-dir" value="build/result"/>
  16.     <!-- The target name of the built add-on JAR -->
  17.     <property name="target-jar"
  18.         value="${result-dir}/myaddon-${version}.jar"/>
  19. </target>
  21. //Initialize build
  23. <target name="init" depends="configure">
  24.     <!-- Construct and check classpath -->
  25.     <path id="compile.classpath">
  26.         <pathelement path="build/classes" />
  27.         <pathelement path="${src-location}" />
  28.         <fileset dir="${result-dir}/lib">
  29.             <include name="*.jar"/>
  30.         </fileset>
  31.     </path>
  33.     <mkdir dir="${result-dir}"/>
  34. </target>

You will need to make some configuration also in the package-jar target in addition to the configure target.

Compiling the Server-Side

Compiling the add-on requires the Vaadin libraries and any dependencies. We use Apache Ivy for resolving the dependencies and retrieving the library JARs.

  1. <!-- Retrieve dependencies with Ivy -->
  2. <target name="resolve" depends="init">
  3.     <ivy:retrieve
  4.         pattern="${result-dir}/lib/[artifact].[ext]"/>
  5. </target>

The pattern attribute for the <retrieve> task specifies where the dependencies are stored, in the above case in the build/result/lib directory.

Compiling the server-side classes is then straight-forward:

  1. <!-- Compile server-side -->
  2. <target name="compile-server-side"
  3.         depends="init, resolve">
  4.     <delete dir="${result-dir}/classes"/>
  5.     <mkdir dir="${result-dir}/classes"/>
  7.     <javac srcdir="${src-location}"
  8.            destdir="${result-dir}/classes">
  9.         <classpath>
  10.             <path refid="compile.classpath"/>
  11.         </classpath>
  12.     </javac>
  13. </target>

Compiling the JavaDoc

You may want to include API documentation for the add-on in the same or in a different JAR file. You can do it as follows, using the configuration we defined earlier. You may want to exclude the client-side classes and any test and demo classes from the JavaDoc, as is done in this example, if they are in the same source tree.

  1. <!-- Compile JavaDoc -->
  2. <target name="compile-javadoc" depends="init">
  3.     <delete dir="${result-dir}/javadoc"/>
  4.     <mkdir dir="${result-dir}/javadoc"/>
  6.     <javadoc destdir="${result-dir}/javadoc">
  7.         <sourcefiles>
  8.             <fileset dir="${src-location}" id="src">
  9.                 <include name="/.java"/>
  11.                 <!-- Excluded stuff from the package -->
  12.                 <exclude name="**/client/**/*"/>
  13.                 <exclude name="**/demo/**/*"/>
  14.                 <exclude name="**/MyDemoUI.java*"/>
  15.             </fileset>
  16.         </sourcefiles>
  17.         <classpath>
  18.             <path refid="compile.classpath"/>
  19.         </classpath>
  20.     </javadoc>
  21. </target>

Packaging the JAR

An add-on JAR typically includes the following:

  • Vaadin add-on manifest

  • The compiled server-side classes

  • The compiled JavaDoc (optional)

  • Sources of client-side classes (optional)

  • Any JavaScript dependency libraries (optional)

Let us begin crafting the target. The JAR requires the compiled server-side classes and the optional API documentation.

  1. <!-- Build the JAR -->
  2. <target name="package-jar"
  3.         depends="compile-server-side, compile-javadoc">
  4.     <jar jarfile="${target-jar}" compress="true">

First, you need to include a manifest that defines basic information about the add-on. The implementation title must be the exact title of the add-on, as shown in the Vaadin Directory title. The vendor is you. The manifest also includes the license title and file reference for the add-on.

  1. <!-- Manifest required by Vaadin Directory -->
  2. <manifest>
  3.     <attribute name="Vaadin-Package-Version"
  4.                value="1" />
  5.     <attribute name="Vaadin-Widgetsets"
  6.                value="${widgetset}" />
  7.     <attribute name="Implementation-Title"
  8.                value="My Own Addon" />
  9.     <attribute name="Implementation-Version"
  10.                value="${version}" />
  11.     <attribute name="Implementation-Vendor"
  12.                value="Me Myself" />
  13.     <attribute name="Vaadin-License-Title"
  14.                value="Apache2" />
  15.     <attribute name="Vaadin-License-File"
  16.         value="http://www.apache.org/licenses/LICENSE-2.0" />
  17. </manifest>

The rest of the package-jar target goes as follows. As was done in the JavaDoc compilation, you also need to exclude any test or demo code in the project here. You need to modify at least the emphasized parts for your project.

  1.         <!-- Include built server-side classes -->
  2.         <fileset dir="build/result/classes">
  3.             <patternset>
  4.                 <include name="com/example/myaddon/**/*"/>
  5.                 <exclude name="**/client/**/*"/>
  6.                 <exclude name="**/demo/**/*"/>
  7.                 <exclude name="**/test/**/*"/>
  8.                 <exclude name="**/MyDemoUI*"/>
  9.             </patternset>
  10.         </fileset>
  12.         <!-- Include widget set sources -->
  13.         <fileset dir="src">
  14.             <patternset>
  15.                 <include name="com/exaple/myaddon/**/*"/>
  16.             </patternset>
  17.         </fileset>
  19.         <!-- Include JavaDoc in the JAR -->
  20.         <fileset dir="${result-dir}/javadoc"
  21.                  includes="*/"/>
  22.     </jar>
  23. </target>

You should now be ready to run the build script with Ant.