diff options
Diffstat (limited to 'documentation/gwt/gwt-addons.asciidoc')
| -rw-r--r-- | documentation/gwt/gwt-addons.asciidoc | 318 |
1 files changed, 0 insertions, 318 deletions
diff --git a/documentation/gwt/gwt-addons.asciidoc b/documentation/gwt/gwt-addons.asciidoc deleted file mode 100644 index df2e2f268f..0000000000 --- a/documentation/gwt/gwt-addons.asciidoc +++ /dev/null @@ -1,318 +0,0 @@ ---- -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"))) - - |