123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318 |
- ---
- 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.
-
-
- ----
- <!-- Retrieve dependencies with Ivy -->
- <target name="resolve" depends="init">
- <ivy:retrieve
- pattern="${result-dir}/lib/[artifact].[ext]"/>
- </target>
- ----
-
- The [literal]#++pattern++# attribute for the [literal]#++<retrieve>++# 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:
-
-
- ----
- <!-- Compile server-side -->
- <target name="compile-server-side"
- depends="init, resolve">
- <delete dir="${result-dir}/classes"/>
- <mkdir dir="${result-dir}/classes"/>
-
- <javac srcdir="${src-location}"
- destdir="${result-dir}/classes">
- <classpath>
- <path refid="compile.classpath"/>
- </classpath>
- </javac>
- </target>
- ----
-
-
- [[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.
-
-
- ----
- <!-- Build the JAR -->
- <target name="package-jar"
- depends="compile-server-side, compile-javadoc">
- <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.
-
- [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")))
-
|