Creating Add-ons

    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.

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

    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.

      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:

    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.

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

    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 -->
    15.     <!-- The target name of the built add-on JAR -->
    16.     <property name="target-jar"
    17.         value="${result-dir}/myaddon-${version}.jar"/>
    18. </target>
    20. //Initialize build
    22. <target name="init" depends="configure">
    23.     <!-- Construct and check classpath -->
    25.         <pathelement path="build/classes" />
    26.         <pathelement path="${src-location}" />
    27.         <fileset dir="${result-dir}/lib">
    28.             <include name="*.jar"/>
    29.         </fileset>
    30.     </path>
    32.     <mkdir dir="${result-dir}"/>
    33. </target>

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

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

    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.

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

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