Vaadin Directory

Vaadin Directory is an online listing of packaged Vaadin add-ons that are free and open source. It is a channel for easily finding, promoting and distributing Vaadin add-ons. Registered Vaadin users can download and publish their own Vaadin add-ons.

Registering on vaadin.com

Before you can use or publish anything in Vaadin Directory, you must register as a vaadin.com user. Typically, you create a personal account for yourself, but you can also create an account for your team or company. You should consider these options if you are publishing work that is not completely authored or owned by you.

When registering, provide as much information as you can. At a minimum, this means your email, first and last name, and contact information: email, phone number and address.

You can modify your information in the profile area of your vaadin.com account at any time.

Using Vaadin Add-ons

Add-ons are intended to be "drop-in packages" for web projects that use the Vaadin framework.

There are two ways to install Vaadin add-ons:

  1. Maven dependency
  2. Java JAR or full ZIP download

Installing with Maven

Note: These instructions assume (and recommend) that you created your project using one of the Vaadin project templates at https://start.vaadin.com.

  1. Vaadin add-ons are served from their own Maven repository at http://maven.vaadin.com/vaadin-addons. Add the following repository to your project pom.xml:

    <repositories>
    <repository>
    <id>vaadin-addons</id>
    <url>http://maven.vaadin.com/vaadin-addons</url>
    </repository>
    </repositories>
  2. Copy the Maven dependency snippet from the add-on details page in Vaadin Directory and paste it to the dependencies section of your pom.xml.

  3. Recompile your project. During the build, the Vaadin Maven plugin will take care of the installation of:

You can then start using the add-on:

  • Themes: Add an@Theme("theme-name") annotation to your UI class.
  • Components and widgets: These are Java classes that you can use right away.
  • Tools: Follow the add-on documentation on how to install and run the tool.
The add-on page typically contains helpful information and links to samples and tutorials. Follow these to learn more about a specific add-on.

Creating Vaadin Add-ons

Maven coordinate policy has been updated! New add-ons have to prefix their Maven group ID with org.vaadin.addons. Otherwise the deployment to the add-on Maven repository will be denied. Existing add-ons are still allowed to publish new versions.

Individuals, teams and companies can publish their work in Vaadin Directory. For publishing license options, see the Vaadin Community Terms. If you have a personal account, keep in mind that any add-on published to the directory will display your name as the author. If you are building an add-on together with someone else, or the add-on you are publishing is owned by a company, we recommend that you create a separate user account for the collaboration or company.

Available add-on Types

Add-ons are divided into five categories in Vaadin Directory:

  • UI components (with client and/or server-side implementations).
  • Data components (for example, a data-source implementation).
  • Themes (CSS + images).
  • Tools (for Vaadin development).
  • Miscellaneous (other helpful Vaadin add-ons).

Add-on Licenses

Vaadin Directory allows you to publish your work under different open-source licenses. The supported licenses are listed in the Publishing Software section of Vaadin Community Terms.

Free add-ons

Vaadin Directory offers a choice of the following open-source licenses:

To support as many users as possible, we recommend you use the well-known open-source Apache License 2.0. Most add-ons use this as it is the same license that Vaadin uses.

Directory packaging

There are a couple of options for packaging your add-on for distribution in Vaadin Directory. Typically, you should create your add-on project with a recommended project template and the package will be created automatically for you.

Technically, an add-on bundle package is a standard ZIP file. Use this to package the add-on, external dependency libraries and documentation into a single distribution package. Name implementation title in your manifest file will be the name of your add-on.

Creating add-on projects from a project template for Vaadin 14+

For Vaadin 14+, the easiest way to create an add-on project is to use a template project. There are two alternatives, depending on the type of add-on:

You can create a new project by selecting Use this template in GitHub, naming your repository, and then selecting Create repository from template.

Note: You should check the Include all branches option to include support for all the Vaadin versions. If left unchecked, your template will only support the latest Vaadin version.
When developing, make sure you’re using the branch that matches your Vaadin version.

These projects contain a pom.xml file that is configured for packaging and publishing to Vaadin Directory.

Creating add-on projects with the Maven archetype for Vaadin 8

The easiest solution for packaging a Vaadin 8 project is to use Maven project packaging. When you use a proper Maven archetype, all the packaging details for add-on will be correct when you generate a new project for the add-on. This includes special manifest entries and ZIP packaging for directory distribution. The suggested archetype is available from GitHub.

To create a release:

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

Exporting using the Eclipse plugin for Vaadin 7 and 8

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

Steps to export a package:

  1. Choose the Vaadin add-on project.
  2. Go to File > Export and select Vaadin Directory Package (type "vaadin" to filter field).
  3. Choose the files to include in the JAR. Note:
    • The plugin chooses all source code and classes by default. Exclude any unnecessary files.
    • Remember that client-side GWT implementations need the source code in order to work.
  4. Fill in the manifest information, choose the destination file and select Finish:
    • Implementation title: The unique official name of the add-on (for example, "RatingStars"). This cannot be changed after upload to Vaadin Directory.
    • Implementation version: Version of the add-on JAR (for example, "0.4" or "0.4.2"). This cannot be changed after upload to Vaadin Directory.  
    • Implementation vendor: Official name of the add-on vendor (for example, "Vaadin Ltd"). You may use a team name or several names here. 
    • License title: Official name of the add-on license (for example, "Apache License 2.0")
    • Widgetsets: Name of the add-on widgetset, if any (for example,  "org.vaadin.browsercookies.widgetset.BrowserCookiesApplicationWidgetset")

Make sure the export succeeds without compile warnings.

Testing add-ons

Before publishing, you need to test your add-on thoroughly. Focus on the client-side code and browser issues, as well as validation of the API and dependencies. The general rule is that you cannot test your add-on too much. Here are some testing tips:

  • Testing the add-on in an empty Vaadin project:
    1. Create an add-on package.
    2. Create a new application project and import your add-on JAR into the project.
      1. Vaadin 14+ create project at start.vaadin.com 
      2. Vaadin 8: Use the Maven vaadin-archetype-application
    3. Write a small test view - this can also serve as a code sample later.
  • Browser compatibility testing: 
    1. Test with the browsers that are relevant to you and your users.
    2. Don't mark any specific browser as supported, unless you have tested it.
    3. Use a simple real-life test application.
    4. Test with other components as well.
  • Testing on different Vaadin versions:

    1. Change the Vaadin version JAR in your project to the oldest version you wish to support. Recompile both client and server-side code and test the add-on in an application.
      1. Vaadin 7 add-ons are typically compatible with version 7.2.0+.
      2. Vaadin 8 add-ons are typically compatible with 8.1+.
      3. Vaadin 14 add-ons will typically also work with the latest Vaadin version.
    2. Make sure you are using Java 8 to maximize 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 including the following documentation:

  • Javadoc: Make good use of Javadoc. Remember developers are your end-users and this is a 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 dependencies. Resolve typical misconfiguration issues in advance. You can also describe dependencies in a Maven pom.xml file.
    • Most important use cases and add-on APIs: 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. This depends on the component, but typically includes component APIs and CSS styles.
  • A feedback system. Use uservoice.com, for example. GitHub also 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 Vaadin Directory. Add a note in the add-on description.
  • An external JAR is needed: Package the add-on as a ZIP and include the external JAR. Link to the original download page.
  • Same classes are used in separate add-ons: Consider compiling a separate add-on from common classes.

Vaadin add-ons do not manage external dependencies and you need to take care of this. However, if you use 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.

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

Creating a Maven pom.xml for Vaadin add-on dependencies

Maven automates handling of add-on dependencies. This is through a pom.xml file, which should list all the dependencies. Vaadin add-ons are automatically published to 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.awesome</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 you use the Eclipse Plugin when exporting the add-on, please take care of the following:

  • The version number in the pom.xml must match the version given in the export wizard.
  • The pom.xml must be manually selected to be included in the add-on JAR.

 

Publishing Add-ons in Vaadin Directory

After you have successfully created an add-on package, go to vaadin.com/directory and log in to the system. Click Publish component (top-right corner). You can manage your previous  submissions by clicking My components. Choose the Vaadin version of the add-on you are uploading and choose the add-on ZIP package created in the Maven target folder.

Some of the information is read from the manifest file of the add-on JAR and it cannot be modified in the web UI.

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, for example "MyComponent for Vaadin".
  • Add-on Version: The version of the add-on JAR. You can only submit several versions of the same add-on if they have different version numbers. The version is a string and the recommended way of versioning is to use two or three levels <major>.<minor>.<build>, for example, "3.2.1". Another rule of thumb is to use  major-version < 1 for experimental add-ons and >= 1 for others. Note that you cannot submit snapshot versions to Vaadin Directory

Read more: Vaadin Add-on Specification

General add-on information

This information is used in both Vaadin Directory search results and at the add-on details page. It is also indexed by external search engines. The purpose of this information is to help people find your component and understand what it provides and how it works.

    • Published: Is the add-on published or not. Note that you cannot turn this on unless at least one version of the add-on is available.
    • Icon: The icon is shown in the search results and details page. It should be rectangular (1:1 aspect ratio) and less than 100KB. Accepted formats: PNG, JPG, GIF. You can crop and optimize GIFs using online services, like https://ezgif.com
    • Summary: A one-liner describing the purpose of the add-on. This is what the user sees first when browsing the add-ons.
    • Description: A 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. You can use Markdown syntax for formatting.
  • Categories: Categories help people to find similar add-ons. You can choose as many as you like, but 3-5 is typically optimal. 
  • Samples:
    • Previews: Take a screenshot of your add-on if it is a widget or has a user interface. A good maximum size is 800x600 pixels.
    • Code samples: A piece of code that demonstrates at least the most typical use case.
    • YouTube video: A video to showcase the add-on or to provide a tutorial.
  • Related links:
    • Online demo: Provide a link to a live demo. The best way to showcase your widget or component is to let users play around with it.
    • Source code: Provide a link to the public source code of the add-on. You can use GitHub, Bitbucket.
    • Discussion forum: Link to an external discussion forum if you have one. Note that discussion is also possible in the directory itself.
    • Issue tracker: Link to an online issue tracker where the users can leave feature requests and bug reports.
  • You also might want list things like:
    • External add-on descriptions 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

You can publish and keep publishing several versions of your add-on. Typically, the same functionality is available for many Vaadin versions in a single add-on with just a different major version number.

  • Available: Turn this on to make the add-on JAR available for download. Note that you must make at least one version available before you can publish the add-on. All available versions show in the Component versions drop-down list in the details page.
  • Supported frameworks: List the supported Vaadin versions. Remember to take care of testing. Markdown is supported here.
  • Release notes: Include a short summary of what has changed and been added in this specific version. This will show up in the Release notes section on the details page.
  • Browser compatibility: Check all browsers that you have verified the add-on works with. For data components, check Browser independent. Note: Don't use the Browser independent option for UI widgets, rather test and verify the supported browsers.
  • Maturity: Check the applicable option. You can also request official certification for your add-on. Here are the guidelines:
    • Stable: The add-on is fully functional, the API is stable, all non-obvious limitations are documented and the documentation is complete. The publisher recommends the use of the add-on for production applications and is not aware of any major bugs.
    • Beta: The add-on is fully functional, the API is stable and major limitations are documented. Some documentation might still be lacking and the publisher expects there to be bugs.
    • Tested: The add-on is feature complete and has been tested to work as-is.
    • Experimental: The add-on is still incomplete and is not recommended for use by the publisher. The reason for including experimental add-ons is to provide feedback to the publisher and to make sharing as easy as possible.
    • Imported: The add-on was imported into Vaadin Directory, but it has not been tested yet.
    • Not maintained: This version is still available, but is not actively maintained. This is useful for supporting older Vaadin versions.
  • Licenses: Choose the license for your add-on. If unsure, use the Apache 2.0 as it is the same license that Vaadin uses. 

Removing Add-ons from Vaadin Directory

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

However, you can hide an add-on from public display by unpublishing it. If you made an error uploading an invalid package to the directory, you can delete the version and upload it again. To do this, go to vaadin.com/directory, login to your account, and click My components in the top right corner.