Creating and Publishing Vaadin Add-ons

Instructions for Add-on Authors

Who can be an add-on author?

Anyone can become an add-on author as long as you own the code for the add-on you are publishing. In Vaadin Directory individuals, teams and companies can publish their work. For publishing license options see chapter 8. Publishing Software in the Terms of Service. Keep in mind that only single person can publish an add-on to directory and is shown as author for those. This is important, if you are building the add-on together with someone else, or the add-on you are publishing is owned by a company. In this situations we recommend you to create a separate user account for the company or the team building the add-on. See 'Registering to vaadin.com' for details.

Registering to vaadin.com

Before you can publish anything in the Vaadin Directory you must register as vaadin.com user. Typically you create a personal account for yourself, but you can also create an account for teams and companies. You might consider these options if you are just publishing some work that is not completely authered or owned by you.

When registering fill out as complete information as you can. In minimum this means email, first and lastname and the contact information: email, phone and address.

You can access your information from the vaadin.com control panel.

Available Add-on Types

The add-ons are split into five different categories in Vaadin Directory.

UI Components (UI components with client and/or server-side implementation)
Data Components (e.g. data-source implementation)
Themes (CSS + images)
Tools (tools for making Vaadin development easier in some sense)
Miscellaneous (other add-ons that are supposed to help in Vaadin development)

Add-on Licenses

Vaadin Directory allows you to publish your work under different open-source
licenses. Supported licenses are listed in the Terms of Service, Chapter 8. Publishing.

Free Add-ons

To support as many users as possible an free distribution under an open-source license is recommended. The best option here is Apache License 2.0 as it is also used to license the Vaadin Framework.

Packaging Options

There are two options for packaging your add-on for distribution in Vaadin Directory.

Jar file: A package for a standalone component, tool or widget. This is meant to be dropped-in to WEB-INF/lib. Name implementation title in the Manifest file will be name of your add-on. The jar may also include a Maven pom.xml file.
Zip file: An add-on bundle package. Use this to package add-on, external dependency libraries and documentation into a single distribution package. Name implementation title in the Manifest file will be name of your add-on.

Read more: Vaadin Add-on Specification

Exporting using Eclipse plugin

The Vaadin Eclipse integration plugin includes an exporter for Vaadin Directory packages. Use the plugin to package add-on as jar file.

Steps to export a package:

Choose the Vaadin add-on project
In File menu (or context menu) choose Export
Select Vaadin Directory Package (type "vaadin" to filter field)
Choose the files to be included in the jar
- Plugin chooses all source code and classes by default. Exclude any unnecessary files.
- Remember that client-side GWT implementation need the source code in order to work.
Fill in the Manifest information and choose destination file and click Finnish.
- Implementation title: The unique official name of the add-on. This cannot be changed once uploaded to Vaadin Directory. (example: "RatingStars")
- Implementation version: Version of the add-on jar. This cannot be changed once uploaded to Vaadin Directory. (example: "0.4" or "0.4.2")
- Implementation vendor: Official name of the add-on vendor. You may use team name or several names here. (example: "Vaadin Ltd")
- License title: Official name of the add-on license (example: "Apache License 2.0")
- Widgetsets: Name of the add-on widgetset, if any (example: "org.vaadin.browsercookies.widgetset.BrowserCookiesApplicationWidgetset")

Make sure the export succeeds without compile warnings.

Using Maven to build add-ons

See Vaadin Maven integration wiki page for instructions on how to use vaadin-archetype-widget.

Creating add-on zip

Using zip package you can include documentation, use examples, compiled java-docs and other info bundled with the add-on package. Creating a zip instead of jar requires a bit more effort, but makes the add-on more complete and professional

Currently eclipse plugin does not support packaging directly to zip. In order to do so manually, you should

Create a jar-file first as explained before
Create myaddon-0.1 directory that contains the jar as well as any other contents you want to include. Consider including:
- readme.txt that explain that the add-on is an gives some pointers for getting more info
- docs directory with some documentation. Any documentation is better than none. Really.
  - docs/api might be a good place for javadocs
- license.txt could be places in the myaddon-0.1 directory or to docs directory
- src directory with sources
Add MANIFEST.MF to myaddon-0.1/../META-INF (yes, it must be side-by side with myaddon-0.1 directory)
You can create the manifest most of the info from the manifest inside jar, but you can add the following:
- Vaadin-Addon specifies the path to the jar containing the add-on implementation. for example this could be myaddon-0.1/myaddon-0.1.jar
- Vaadin-Dependency lists the dependencies - within the zip

For more complete documentation, see http://dev.vaadin.com/wiki/VaadinAddon

It is recommded that you create a build script that makes the above packaging process automatic.

Testing Add-ons

Before publishing, you need to test your add-on thoroughly. This is specially case with the client-side code and browsers, but also the API and dependencies should be validated. In general you cannot test your add-on too much. Here are some tips:

Test using the add on in a empty Eclipse project
- Create add-on package
- Create new project and import your add-on jar to the projec
- Write a small test application - this can also serve as a code sample
Browser compatibility testing
- Test with those brosers that are relevant to you and your users.
- Don't mark any specific browser as supported unless you have tested it.
- Use a simple real-life test application.
- Test together with some other components.
Testing with different Vaadin versions
- Change the Vaadin version jar in your project to the oldest version you wish to support. Recompile both client and server-side code and testdrive the add-on in an application.
- Typically most add-ons are compatible 6.2.0 and upwards.
- Make sure you are using Java 5 to maximize the backward compatibility.

Documenting an Add-on

Documentation is about quality and ease of use. The more documentation you provide the better your add-on is considered. Consider the following documentation:

Javadoc: Make good use of Javadoc. Remember developers are your end-users and this is major part of the user experience.
Tutorial: Write a tutorial (a wiki-page for example), that summarizes:
- Installation process. Remember not everyone uses Eclipse.
- External dependencies. What should be downloaded and where to put the. Resolve the typical misconfiguration issues beforehand. You can also describe dependencies in a Maven pom.xml file.
- Most important use case and add-on API. Break into code and explanation.

Also, depending your add-on you might consider:

Publicly available source code and VCS (like SVN, Git, CVS, ...)
Reference: Full reference documentation for the add-on. Depending on the component this includes component API, CSS styles.
A feedback system. Use for example uservoice.com offers a free feedback system for open source projects.

Vaadin Add-on Dependencies

There are basically three kinds of dependencies to handle:

Add-on requires another add-on to be installed: Link to the add-on in directory. Add note to add-on description.
An external jar is needed: Package the add-on as zip and include the external jar. Link to original download page.
Same classes is used in separate add-ons: Consider compiling a separate add-on from common classes.

Vaadin add-ons do not manage external dependencies and you have take care of them. However, if you are using Maven and package your pom.xml file inside the add-on jar, it will be used when the add-on is deployed into the vaadin-addons Maven repository. See Maven pom.xml for details.

Even if you include the pom.xml, you should still to provide instructions on how dependencies should be managed without Maven. This means pointing out the required libraries, providing download links and instructions where to install them.

Maven pom.xml

Maven automates handling of add-on dependencies. This is through pom.xml file which should list all the dependecies. Vaadin Add-ons are automatically published into a Maven repository and if there is a pom.xml file in the Add-on jar file it is used.

This does not mean you have to use Maven to create an add-on with dependencies. You can also include the pom.xml by hand by adding it to META-INF/maven/[groupId]/[artifactId]/pom.xml.

Here is an example pom.xml file with dependencies:

<?xml version="1.0" encoding="utf-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.vaadin.addons</groupId>
    <artifactId>youtubeplayer</artifactId>
    <version>1.0.1</version>
    <dependencies>
        <dependency>
            <groupId>org.vaadin.addons</groupId>
            <artifactId>swfobject</artifactId>
            <version>1.1.0</version>
        </dependency>
    </dependencies>
</project>

Note:If using Eclipse Plugin when exporting the add-on please take care of the following:

Version number in pom.xml matches the version given in export wizard.
pom.xml must be manually selected to be included in the add-on jar.

Publishing an Add-on in the Vaadin Directory

After you have successfully created an add-on package go to vaadin.com/directory and log in to system. Follow the link Authoring in the left menu to manage your submissions. Click on New Add-on to submit a new add-on or choose existing one from the list.

Some of the information is read from the manifest file of the add-on jar and it cannot be modified from the web interface.

Add-on jar manifest information:

Name: The official name of the add-on. This cannot be changed later. You can use Vaadin as part of the name like: "MyComponent for Vaadin".
Add-on Version: The version of the add-on jar. You cansubmit several versions of the same add-on only if they have different version number. The version is a string, but a good way of versioning is to use two or three level of versions like <major>.<minor>.<build> ("3.2.1"). Anothor rule of thumb is to use use major-version < 1 for experimental add-ons and >= 1 for others.

Value Added Tax

Prices in the directory do not contain value added tax (VAT). VAT is added to the price by the
following rules:

If Buyer's country is outside EU, no VAT is added to the price
If Buyer's country is in EU and Buyer gives correct VAT number, no VAT is added to the
price. Finnish Tax officials require that the validity of VAT numbers has been checked.
VAT number is checked using http://ec.europa.eu/taxation_customs/vies/lang.do?
fromWhichPage=vieshome&selectedLanguage=EN

For others, Finnish VAT is added to the price The right to use add-on is given at the moment payment arrives to Vaadin's bank account. Thus the transaction will be recorded to accounting on with that date. Any purchases with no valid payment is excluded from accounting. VAT numbers and VAT is reported to tax officials according to the above mentioned transaction date. EUR sum for VAT is always calculated and included on the invoice regardless of the currency used.

Certification Process

Publisher can request certification for any add-on he has published and marked stable. Certification request is sent by email to [directory@vaadin.com]. Certification costs 250 USD for any previously uncertified add-on and 150 USD for new versions of previously certified add-ons. Invoice for certification is sent to the requesting Publisher. PayPal and bank transfers are accepted form of payment.

Certification is done by one person from Vaadin Ltd within one week from the confirmed payment of the certification fee. It is expected that one person can certify 2 add-ons per day on average.

Certification process will contains the following steps:

Ensuring that the add-on description is complete and gives clear picture of what add-on is and why one should consider downloading it.
Any online demos are tested and ensured that they correspond to the description add-on is downloaded and package contents are studied to ensure that all necessary technical parts are there and documentation seems to be complete
Package is studied to ensure that it doesn't contain libraries or modules with conflicting licenses from what have been said in the description. If additional downloads are needed, their licenses are also studied.
Add-on is tested for 1-2 hours to see if it works in practice. This study include the
following tests:
- Creation of a test application that uses the add-on
- Cross-browser testing with all browsers supported by Vaadin
- Memory profiling to ensure that the add-on does not leak badly on server-side

If the add-on version passes all the above tests, add-on version is marked to be certified in Directory and Publisher is notified about this by email. If add-on fails any of the tests, certification process the interrupted and the problem is reported to Publisher. Publisher can upload another version and ask the certifier to continue the certification. The certification will allways start from the beginning. After three failed certification attempts the certification process is terminated. If the Publisher still wants to certify the add-on, he must buy another round of certifications.

Removing Add-on from the Vaadin Directory

It is not possible to completely remove an add-on from Directory. Otherwise someone might use the same add-on name with different content, which gets confusing to the users.

However, you can hide an add-on from the public by unpublishing it. Also, if you made an error uploading a invalid package to Directory you can delete the version and upload it again.

Vaadin