--- title: Creating Add-ons order: 11 layout: page --- [[gwt.addons]] = Creating Add-ons ((("add-ons", "creating", id="term.gwt.addons", range="startofrange"))) 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. [[gwt.addons.export]] == 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. . Select the project and then "File > Export" from the menu . In the export wizard that opens, select "Vaadin > Vaadin Add-on Package", and click [guibutton]#Next# . In the [guilabel]#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 [filename]#src# folder (at least for the client-side package), compiled server-side classes, themes in [filename]#WebContent/VAADIN/themes#. These are all included automatically. You probably want to leave out any demo or example code. + [[figure.gwt.addons.export]] .Exporting a Vaadin Add-on image::img/addon-export.png[] + If you are submitting the add-on to Vaadin Directory, the [guilabel]#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 [guilabel]#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 [guilabel]#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 [filename]#.gwt.xml# extension. + The [guilabel]#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 [filename]#myaddon-1.0.0.jar#. + Finally, click [guibutton]#Finish#. ifdef::web[] [[gwt.addons.ant]] == 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 [filename]#build# folder under the project. We begin the Ant script as follows: [subs="normal"] ---- <?xml version="1.0"?> <project xmlns:ivy="antlib:org.apache.ivy.ant" name="**My Own add-on**" basedir=".." 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. [[gwt.addons.ant.configuration]] === Configuration and Initialization In the example script, we organize most settings in a [literal]#++configure++# target and then initialize the build in [literal]#++init++# target. [subs="normal"] ---- //Update these settings for your project structure <target name="configure"> <!-- Where project source files are located --> <property name="src-location" value="**src**" /> <!-- Name of the widget set. --> <property name="widgetset" value="**com.example.myaddon.widgetset.MyAddonWidgetset**"/> <!-- Addon version --> <property name="version" value="**0.1.0**"/> <!-- Compilation result directory --> <property name="result-dir" value="build/result"/> <!-- The target name of the built add-on JAR --> <property name="target-jar" value="${result-dir}/**myaddon**-${version}.jar"/> </target> //Initialize build <target name="init" depends="configure"> <!-- Construct and check classpath --> <path id="compile.classpath"> <pathelement path="build/classes" /> <pathelement path="${src-location}" /> <fileset dir="${result-dir}/lib"> <include name="*.jar"/> </fileset> </path> <mkdir dir="${result-dir}"/> </target> ---- You will need to make some configuration also in the [literal]#++package-jar++# target in addition to the [literal]#++configure++# target. [[gwt.addons.ant.compiling]] === 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. ---- ---- The [literal]#++pattern++# attribute for the [literal]#++++# task specifies where the dependencies are stored, in the above case in the [filename]#build/result/lib# directory. Compiling the server-side classes is then straight-forward: ---- ---- [[gwt.addons.ant.javadoc]] === 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. [subs="normal"] ---- <!-- Compile JavaDoc --> <target name="compile-javadoc" depends="init"> <delete dir="${result-dir}/javadoc"/> <mkdir dir="${result-dir}/javadoc"/> <javadoc destdir="${result-dir}/javadoc"> <sourcefiles> <fileset dir="${src-location}" id="src"> <include name="**/*.java"/> <!-- Excluded stuff from the package --> <exclude name="**++*++++*++/client/++*++++*++/++*++**"/> <exclude name="**++*++++*++/demo/++*++++*++/++*++**"/> <exclude name="**++*++++*++/MyDemoUI.java**"/> </fileset> </sourcefiles> <classpath> <path refid="compile.classpath"/> </classpath> </javadoc> </target> ---- [[gwt.addons.ant.package]] === 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. ---- ---- 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. [subs="normal"] ---- <!-- Manifest required by Vaadin Directory --> <manifest> <attribute name="Vaadin-Package-Version" value="1" /> <attribute name="Vaadin-Widgetsets" value="${widgetset}" /> <attribute name="Implementation-Title" value="**My Own Addon**" /> <attribute name="Implementation-Version" value="${version}" /> <attribute name="Implementation-Vendor" value="**Me Myself**" /> <attribute name="Vaadin-License-Title" value="**Apache2**" /> <attribute name="Vaadin-License-File" value="**http://www.apache.org/licenses/LICENSE-2.0**" /> </manifest> ---- The rest of the [literal]#++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. [subs="normal"] ---- <!-- Include built server-side classes --> <fileset dir="build/result/classes"> <patternset> <include name="**com/example/myaddon/++*++++*++/++*++**"/> <exclude name="**++*++++*++/client/++*++++*++/++*++**"/> <exclude name="**++*++++*++/demo/++*++++*++/++*++**"/> <exclude name="**++*++++*++/test/++*++++*++/++*++**"/> <exclude name="**++*++++*++/MyDemoUI++*++**"/> </patternset> </fileset> <!-- Include widget set sources --> <fileset dir="src"> <patternset> <include name="**com/exaple/myaddon/++*++++*++/++*++**"/> </patternset> </fileset> <!-- Include JavaDoc in the JAR --> <fileset dir="${result-dir}/javadoc" includes="**/*"/> </jar> </target> ---- You should now be ready to run the build script with Ant. endif::web[] (((range="endofrange", startref="term.gwt.addons")))