Publishing Vaadin add-ons

Who can be an add-on author?

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. If you are building the add-on together with someone else, or the add-on you are publishing is owned by a company, 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 modify your information in the vaadin.com account page.

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 well-known open-source license is recommended. In Vaadin directory you can choose from the following open-source licenses:

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. Typically you should create your add-on project with a good project template (see below) and the packages are created automatically for you.

  • 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

Suggested solution: Creating add-on projects with Maven archetypes

The easiest solution for packaging is using the Maven project packaging. You'll get all the details for add-on packaging right, if you generate a new project for the add-on using a proper Maven archetype. This includes special manifest entries and zip packaging for Directory distribution. The currently suggested archetype is available from github, or you can use the official vaadin-archetype-widget archetype.

To create a release:

  1. Set the version information for the release to pom.xml, or use Maven release plugin to do a release for you. You cannot upload snapshot packages to the Vaadin Direcory.
  2. If you didn't use Maven release plugin, use the command mvn package create a compatible zip file.
  3. Upload the zip file to the directory.

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

Manually 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 7.2.0 and upwards.
    • Make sure you are using Java 6 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: Documentation for the add-on. Depending on the component this includes component API, CSS styles.
  • A feedback system. Use for example uservoice.com and GitHub offer 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.

Manually creating a 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.

Read more: Vaadin Add-on Specification

General Add-on Information:

  • Published: Is the Add-on published or not. Note, that you cannot turn this on unless at least one version of add-on is available.
  • Summary: A one-liner describing the purpose add-on. Remember that this is what the user sees first when browsing the add on.
  • Description: More detailed description of the add-on. Explain the purpose of your add-on and give a sample use case. This is indexed for the search.
  • Highlights:
    • Screenshot: Take a screenshot of your add-on if it is a widget or has user interface. Good maximum size is 800x600.
    • Code Example: A piece of code that demonstrates the at least the most common use case.
    • YouTube Video: Video that showcase the add-on or video tutorial.
  • Related Links:
    • Online Demo: Provide a link to a online demo. The best thing to showcase your widget or component is to let users play around with it a bit.
    • Discussion Forum: If you have a discussion forum where users can discuss about the
    • Issue Tracker: Linkt to online issue tracker where the users can leave feature requests and bug reports.
    • Source Code: If you publish the source code in a public VCS, provide a link to online repository

      You might also want list things like:
    • External add-on description and/or project hosting
    • Download links for dependencies. Sometimes it makes more sense to make the dependency download available from the original site.
    • Links to other relevant developer information, like specifications.

Version-specific information:

This information is bound to the specific jar-file.

  • Available: Turn this on to make add-on jar available for download. Note that you must make at least one version available before you can publish the add-on. All versions made available show in a drop-down list in the add-on information page header.
  • Supported Vaadin Versions: List the supported Vaadin versions. Remember to take care of the testing.
  • Release Notes: Short summary of what has been changed and added in this specific version. This will show up in the comment timeline at the add-on on information page.
  • Browser Compatibility: Check all browsers that you have verified to work. For data components you should check the "Browser independent". Note: don't use "Browser independent" option for the UI widgets, but rather test and verify the supported browsers.
  • Code Maturity: Check either Experimental, Beta or Stable. You can also request official certification for your add-on.
    The maturity level describes what level the add-on author thinks the add-on is. Here are some guidelines for
    maturity levels:
    • Experimental - add-on is still incomplete and is not recommended to be used by the Publisher. The reason for showing experimental add-ons is to give feedback to Publisher and to make sharing as easy as possible.
    • Beta - add-on is fully functional, API is stable and major limitations are documented. Documentation might be still lacking and Publisher expects there to be bugs.
    • Stable - add-on is fully functional, API is stable, all non-obvious limitations are documented and documentation is complete. Publisher recommends the use of add-on for production applications and is not avare of any major bugs.
    • Certified - A stable add-on where Vaadin personnel has ensured that the add-on description written by the author is truthful and accurate. Vaadin personnel has also briefly tested the add-on demos and examples and has not bumped into any major bugs in those tests. Certification is done for each version of the add-on. It should be noted that Vaadin will take no responsibility if add-on contains malicious code, licensing problems or bugs. See 'Certification Process' for details
  • Licenses: Choose the license to your add-on. You can choose multiple licenses. 

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.

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 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.