Vaadin Editors Developers Guide

This page contains all information related to developing the Vaadin based editors and UIs.
See also the VaadinNotes for general information on Vaadin.

Development Environment Setup


  1. Eclipse IDE: This guide assumes that you are using the Eclipse IDE. For installing and setting up eclipse, please see EclipsePreferencesforTeams
  2. Maven 3: Install maven either via your packagemanegment or download it from Maven
  3. Install the Eclipse Jetty Integration plugin (current version 3.9.0). Using the outdated run-jetty-run plugin ( is not recommended. If you need to use the RunJettyRun plugin for some reasonm make sure you are using version 9.0.0+ which is available via the nightly update site - The reason for the specific version of Jetty is due to the dependency on Servlet 3.0+ API which is used in the project.
  4. Vaadin Plugin for Eclipse: For details on this plugin see section 2.4.2 from the Book of Vaadin. This plugin provides tools for compiling widgetsets, creating Vaadin specific objects and designing components using the included Vaadin Visual Designer.


Get the cdm-vaadin project source code with

git clone

and build the project with

mvn clean install

A. If you have the m2e eclipse plugin installed: Import the project via File->Import->Maven/Existing Maven Projects ...
B. Otherwise you need to run mvn eclipse:eclipse and import the project into Eclipse as File->Import->General/Existing Projects into Workspace ...

Now you need to create the configuration files for the data sources:

  1. In {home}/.cdmlibrary folder create a file (if not yet exists) with an entry to a datasource e.g. cdm.datasource=testDataSource
  2. In the same folder copy/create a datasources.xml with the according datasource (testDataSource) in it:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns=""
  xmlns:xsi="" xmlns:context=""

   <bean id="testDataSource"  lazy-init="true" class="com.mchange.v2.c3p0.ComboPooledDataSource">
        <property name="driverClass" value="com.mysql.jdbc.Driver"/>
        <property name="user" value="user"/>
        <property name="password" value="password"/>
        <property name="jdbcUrl" value="jdbc:mysql://localhost/testDataSource?autoReconnect=true&amp;autoReconnectForPools=true&amp;"/>

Enabling Vaadin applications.

Since #6628 vaadin applications need to be enabled explicitly!

A vaadin application is represented by the context of a Vaadin UI. A mechanism to enable vaadin UIs on a per cdm-webapp instances is provieded which work in the cdm-server and also in development environments. To enable a vaadin UI for a specific cdm-vaadin or cdm-webapp instance you need to create a per instance java properties file:


The content of the properties file to enable all UIs which are currently implemented:


For details on the reasons why explicit enablement of vaadin UIs is important, please refer to #6628.

Starting the Vaadin web app

There are various ways to start the Vaadin web app from the development environment.

Independently from the way you choose the application will run at http://localhost:8080. After launching check if http://localhost:8080/app-test/navi is available.

Further GUIs are available from the following endpoints:

SuperDev Mode

The Book of Vaadin describes the SuperDev mode in chapter 14.6.1. The wiki page Using SuperDevMode is also an valuable source of information.

The SuperDev mode is per default disabled in src/main/java/eu/etaxonomy/cdm/vaadin/AppWidgetSet.gwt.xml`:

     SuperDev mode is enabled default starting with GWT 2.6.0

     For more information and instructions see: 
    <set-configuration-property name="devModeRedirectEnabled" value="false" />

    <inherits name="org.vaadin.peter.contextmenu.ContextmenuWidgetset" />

Once it is enabled the vaadin application requires also the Vaadin code server to run which listens per default at port 9876

You may need to add the following dependencies to your pom.xml


Launch via Eclipse launchers

If the vaadin project is correctly set up a launcher configuration should be available which is named cdm-vaadin - run. If it is missing try to fix the Resource configuration in the project setting.
Please refer to EclipseLauncherConfigurations for further required preparation steps for using these launchers.

As last resort you can also import the cdm-vaadin jetty launch configuration in Eclipse by selecting File->Import->Launch Configurations and choosing the cdm-vaadin.launch file in the ide/eclipse directory (not recommended!).

Setting details of the launch configuration

  • Tab Webapp
    • Name: cdm-vaadin - run
    • Project: vaadin project
    • WebApp folder: src/main/webapp
    • HTTP/HTTPS port: 8080
  • Tab Dependencies (only the following check boxes are active)
    • Compile Scope [x]
    • Runtime Scope [x]
    • Test Scope [x]

Auto Login

The LoginPresenter class offers a auto login feature for developers. To activate the auto login you need to provide the user name and password using the environment variables cdm-vaadin.login.usr and cdm-vaadin.login.pwd, e.g.:

 -Dcdm-vaadin.login.usr=admin -Dcdm-vaadin.login.pwd=00000

SuperDev Mode

No prepared launcher available TODO

Launch via the Maven Jetty plugin

Start the Vaadin application:

mvn jetty:run

SuperDev Mode

Start the code server for the SuperDev mode

mvn vaadin:run-codeserver

The command

mvn vaadin:run

also starts the code server. As of the documentation mvn vaadin:help this should start the widget in Hosted Mode but only the Code Server seems to be running.


[ERROR] {gitpath}/vaadin/src/main/webapp/VAADIN/themes/valo/styles.scss could not be read!

If mvn clean install or mvn eclipse:eclipse fails with this message you have to delete the folder vaadin/src/main/webapp/VAADIN/themes/valo. It is not used anyway but it seems like the IDE sometimes creates it as a default theme


cdmlib-vaadin applications can be started in debug mode. The debug mode can be enabled by activating the spring profile debug:

Once activated this profile enabled the following debugging tools are available:


Start the EntityCacheDebugger by the key combination Space + Ctrl


This tool adds buttons to the UI by which the user gain gain permissions for cdm entities. These Buttons must be programatically added to the UI:

PermissionDebugUtils.addGainPerEntityPermissionButton(AbstractComponentContainer toContainer, Class<? extends CdmBase> cdmType, UUID entitiyUuid, EnumSet<CRUD> crud, String property)

Updated by Andreas Müller 8 months ago · 31 revisions