diff options
Diffstat (limited to 'documentation/addons/addons-maven.asciidoc')
| -rw-r--r-- | documentation/addons/addons-maven.asciidoc | 170 |
1 files changed, 170 insertions, 0 deletions
diff --git a/documentation/addons/addons-maven.asciidoc b/documentation/addons/addons-maven.asciidoc new file mode 100644 index 0000000000..9c5ca8c25c --- /dev/null +++ b/documentation/addons/addons-maven.asciidoc @@ -0,0 +1,170 @@ +--- +title: Using Add-ons in a Maven Project +order: 4 +layout: page +--- + +[[addons.maven]] += Using Add-ons in a Maven Project + +((("Maven", "using add-ons", id="term.addons.maven", range="startofrange"))) + + +To use add-ons in a Maven project, you simply have to add them as dependencies +in the project POM. Most add-ons include a widget set, which are compiled to the +project widget set. + +Creating, compiling, and packaging a Vaadin project with Maven was described in +<<dummy/../../../framework/getting-started/getting-started-maven#getting-started.maven,"Using +Vaadin with Maven">>. + +[[addons.maven.dependency]] +== Adding a Dependency + +Vaadin Directory provides a Maven repository for all the add-ons in the +Directory. + +. Open the add-on page in Vaadin Directory. + +. Select the version. The latest is shown by default, but you can choose another +the version from the dropdown menu in the header of the add-on details page. + +. Click the [guilabel]#Maven/Ivy# to display the Maven dependency declaration, as +illustrated in Figure <<figure.addons.maven.pombutton>>. If the add-on is +available with multiple licenses, you will be prompted to select a license for +the dependency. + ++ +[[figure.addons.maven.pombutton]] +.Maven POM Definitions +image::img/directory-maven-pom.png[] + +. Copy the [literal]#++dependency++# declaration to the [filename]#pom.xml# file +in your project, under the [literal]#++dependencies++# element. + + ++ +[subs="normal"] +---- + ... + <dependencies> + ... + <dependency> + <groupId>**com.vaadin.addon**</groupId> + <artifactId>**vaadin-charts**</artifactId> + <version>**1.0.0**</version> + </dependency> + </dependencies> +---- ++ +You can use an exact version number, as is done in the example above, or +[literal]#++LATEST++# to always use the latest version of the add-on. + ++ +The POM excerpt given in Directory includes also a repository definition, but if +you have used the [literal]#++vaadin-archetype-application++# to create your +project, it already includes the definition. + +. Compile the widget set as described in the following section. + + + +[[addons.maven.compiling]] +== Compiling the Project Widget Set + +If you have used the [literal]#++vaadin-archetype-application++# to create the +project, the [filename]#pom.xml# includes all necessary declarations to compile +the widget set. The widget set compilation occurs in standard Maven build phase, +such as with [parameter]#package# or [parameter]#install# goal. + +[subs="normal"] +---- +[prompt]#$# [command]#mvn# [parameter]#package# +---- +Then, just deploy the WAR to your application server. + +[[addons.maven.compiling.recompiling]] +=== Recompiling the Widget Set + +The Vaadin plugin for Maven tries to avoid recompiling the widget set unless +necessary, which sometimes means that it is not compiled even when it should. +Running the [literal]#++clean++# goal usually helps, but causes a full +recompilation. You can compile the widget set manually by running the +[parameter]#vaadin:compile# goal. + +[subs="normal"] +---- +[prompt]#$# [command]#mvn# [parameter]#vaadin:compile# +---- +Note that this does not update the project widget set by searching new widget +sets from the class path. It must be updated if you add or remove add-ons, for +example. You can do that by running the [literal]#++vaadin:update-widgetset++# +goal in the project directory. + +[subs="normal"] +---- +[prompt]#$# [command]#mvn# [parameter]#vaadin:update-widgetset# +... +[INFO] auto discovered modules [your.company.gwt.ProjectNameWidgetSet] +[INFO] Updating widgetset your.company.gwt.ProjectNameWidgetSet +[ERROR] 27.10.2011 19:22:34 com.vaadin.terminal.gwt.widgetsetutils.ClassPathExplorer getAvailableWidgetSets +[ERROR] INFO: Widgetsets found from classpath: +... + +---- +Do not mind the "ERROR" labels, they are just an issue with the Vaadin Plugin +for Maven. + +After running the update, you need to run the [literal]#++vaadin:compile++# goal +to actually compile the widget set. + + + +[[addons.maven.widgetset]] +== Enabling Widget Set Compilation + +If you are not using a POM created with the proper Vaadin archetype, you may +need to enable widget set compilation manually. The simplest way to do that is +to copy the definitions from a POM created with the archetype. Specifically, you +need to copy the [literal]#++plugin++# definitions. You also need the Vaadin +dependencies. + +You need to create an empty widget set definition file, which the widget set +compilation will populate with widget sets found from the class path. Create a +[filename]#src/main/java/com/example/AppWidgetSet.gwt.xml# file (in the project +package) with an empty [literal]#++<module>++# element as follows: + + +---- +<module> +</module> +---- + +[[addons.maven.widgetset.web]] +=== Enabling the Widget Set in the UI + +If you have previously used the default widget set in the project, you need to +enable the project widget set in the [filename]#web.xml# deployment descriptor. +Edit the [filename]#src/main/webapp/WEB-INF/web.xml# file and add or modify the +[literal]#++widgetset++# parameter for the servlet as follows. + +[subs="normal"] +---- +<servlet> + ... + <init-param> + <description>Widget Set to Use</description> + <param-name>widgetset</param-name> + <param-value>**com.example.AppWidgetSet**</param-value> + </init-param> +</servlet> +---- +The parameter is the class name of the widget set, that is, without the +[filename]#.gwt.xml# extension and with the Java dot notation for class names +that include the package name. + + + +(((range="endofrange", startref="term.addons.maven"))) + + |