The open source Liferay Portal has become a popular way of implementing enterprise websites. Providing an integrated platform for application development and deployment, Liferay has also become an environment for running business applications. For application development, Liferay Portal includes Vaadin as a pre-packaged framework for developing attractive, easy-to-use applications.

This Refcard gives a quick overview of the user interface development with Vaadin on Liferay. It covers topics like port let setup, configuration, inter-portlet communication (IPC), UI composition, and theming. To get a more general understanding of Liferay Portal and Vaadin framework, see Liferay Essentials and Vaadin: A Familiar Way to Build Web Apps With Java.

Strategies for Portal User Interface

Portlets are small web applications written in Java. They run in a piece of a web user interface within a portal. Portal manages the lifecycle and aggregation of port lets to a single visible web page. Here are some things to consider when choosing the tools for port let development:

UI granularity - How modular are your port lets? Are you building big application-like port lets, or small port lets that communicate with each other?

Security - Is the business logic running on the server side or on the browser

User experience - What kind of user experience is wanted in terms of graphics and transitions?

Programming language - What kind of development tools are available, and is a typed language preferred over scripting languages?

Available UI Frameworks

Liferay supports a number of server-side and client-side web frameworks for developmeport letortlet user interfaces. Which you should use depends on your background, as well as the strategy you choose for your application.

Difport letsortlets can use different frameworks to implement the user interface.

Vaadin is a server- and component-oriented user interface framework for Java web applications. Vaadin applications can be hosted as standalone web applications as wport letsortlets in portals like Liferay. Vaadin is a good choice for building applications that use Liferay as a platform.

Portlets created with Vaadin are essentially Ajax web applications that can be considered single-page applications.

• No page reloads - Once runninport letportlet page does not change when navigating inside a Vaadin application.
• Rich user experience - User interface relies on modern HTML5 and CSS3 web features like animations, transitions, and effects.
• Desktop-like development and UX - Applications are programmed and behave much like desktop applications, rather than web applications.
• Event-based XHR communication - User events are sent to server-side and UI changes are passed in response.
• Java-only development - Vaadin applications are meant to be built with Java.

Depending on your needs and requirements, there are two different ways to deploy a Vaadin application. The deployment setup also affect hoport letportlet is developed, so it is important to know the type of setup you are targeting.[h]

Since Liferay 6.x, there have been several tools to help you in deveport letsortlets with Vaadin. These tools are meant to simplify the creatport letsortlets and help portal administrators maintain the system.

Liferay IDE

Liferay IDE is an extension for the Eclipse IDE that adds support for the development of plug-in projects for the Liferay Portal platform. Since version 2.1, Liferay IDE has supported Vaadin 7 + Maven by offering wizards for crport letportlet plugin projects.

Creating a Project with Liferay IDE

Plugins for Liferay Portal must be created inside of a Liferay project. A Liferay project is essentially a root directory with a standardized structure containing the project’s (and each of its plugins’) necessary files. To create a new Liferay project within Liferay IDE, select File > New > Liferay Plugin Project and use the wizard to fill in project details, as shown below:

Vaadin applications deployed to Liferay can access the complete portal environment, including Liferay services, user context, and content that lives within Liferay. This section provides an overview of how Vaadin applications integrate with Liferay, along with best practices for deployment, initialization, and interaction with the Liferay environment.

Liferay/Vaadin Project Files

Vaadin applications built for Liferay are created as Portlet projects, which have several configuration files, such as portlet.xml. The project structure generated by Liferay IDE follows a Maven-style layout. For detailed information on all of these files, see the Liferay Developer Guide. Specific files with Vaadin-related content include:

Portlet Descriptor

To wire Vaadin to your port let, configure port let mapping in the portlet.xml. Here is an example of content of the file for Standalone Deployment setup:

   <portlet>
        <portlet-name>My simple Vaadin portlet</portlet-name>
        <display-name>My Vaadin portlet</display-name>


        <portlet-class>com.vaadin.server.VaadinPortlet</portlet-class>
        <init-param>
                <name>UI</name>
                <value>com.example.plugins.MyPortletUI</value>
        </init-param>
<init-param>
                <name>vaadin.resources.path</name>
                <value>PORTLET_CONTEXT</value>
        </init-param>
</portlet>

The port let class. The default is com.vaadin.server.VaadinPortlet. You can extend this class to add your own customizations to the port let.

When using Liferay IDE, this file is automatically generated by the Vaadin-Liferay Maven archetype. The parameters are explained below:

The port let class. The default is com.vaadin.server.VaadinPortlet. You can extend this class to add your own customizations to the port let.

 <init-param>
  <name>UI</name>
  <value>com.example.MyUI</value>

The class name of the application UI. This must extend com.vaadin.ui.UI

<init-param>
 <name>vaadin.resources.path</name>
 <value>PORTLET_CONTEXT</value>

Use PORTLET_CONTEXT for standalone deployments, or use /html for “shared” deployments.

Liferay Portlet Descriptor

Liferay also requires a liferay-portlet.xml descriptor file that defines Liferay-specific parameters. In particular, Vaadin port lets must be defined as “instance able,” but not as “ajaxable”:

<liferay-portlet-app> 
  <portlet>
    <portlet-name>Portlet Example portlet</portlet-name>
    <instanceable>true</instanceable>
    <ajaxable>false</ajaxable> 
  </portlet>
</liferay-portlet-app>

This is because Vaadin port lets handle the Ajax requests internally without Liferay’s Ajax mechanisms.

Liferay Portlet Display Descriptor

The liferay-display.xml file defines the port let category under which port lets are located in the Add Application window in Liferay. Without this definition, port lets will be organized under the “Undefined” category.

The following puts the application in a new category called “Vaadin”:

<liferay-portlet-app> 
  <display>
  <category name=”Vaadin”>
    portlet id= ”MyVaadinExamplePortlet”/
  </category>
</display>

For more information on these and other optional descriptors, see Chapter 11.8 of the Book of Vaadin and the Liferay Developer Guide.

With Vaadin, the user interface is built from user interface components. They are server-side Java classes that implement a single UI control such as a button, select, or layout. With layout components, you can compose larger components that hierarchically build up the application UI.

Vaadin Application

A Vaadin application is defined in a class that extends com.vaadin.ui.UI. This is the class that you should define as the UI initialization parameter in portlet.xml as described in earlier sections.

A new instance of this class is created when a new user comes to portal view where the port let resides.

Example minimal working Vaadin application using the “Valo” theme:

@Title(“My Vaadin Portlet UI”)
@Theme(“valo”)
public class HelloPortlet extends com.vaadin.UI {

  @Override
  protected void init(VaadinRequest request) {

    // Create the content root layout for the UI
    VerticalLayout content = new VerticalLayout(); 
    setContent(content);


    // Display the greeting
    content.addComponent(new Label(“Hello Portlet!”)); 
  }
}

Vaadin UI Components

Vaadin Framework includes nearly 100 stock components, and you can find hundreds of open-source add-on components in the Vaadin Add-on Directory.

You can also extend Vaadin by creating new UI components with the Google Web Toolkit (GWT) or JavaScript. GWT is an open-source Java-to-JavaScript compiler that allows you to build client-side features without JavaScript.

You can find all the core components in the com.vaadin.ui.* Java package. Add-ons may use their own package naming, but it is typical that they start with org.vaadin.*.

User Interface Layout

Start by creating a main Window for your application and putting the initial content in there. The user interface structure is a hierarchy of nested layouts and components. Here is an example of a simple user interface hierarchy:

VerticalLayout (form)

• TextField (name)
• TextField (email)
• Button (subscribeBtn)

The above UI could be created in Java as follows:

setTitle(“Subscribe Newsletter”); 
VerticalLayout form = new VerticalLayout();
form.setSpacing(true); 
TextField name = new TextField(“Name”); 
TextField email = new TextField(“Email”); 
Button subscribeBtn = new Button(“Subscribe”);
form.addComponent(name); 
form.addComponent(email);
form.addComponent(subscribeBtn);

The result will look like.

User Interface Events

Vaadin is an event-based framework. You can receive user-triggered events in your application by registering a listener for it. Here is an example for Button.ClickEvent:

subscribeBtn.addListener(new Button.ClickListener() { 
  @Override
  public void buttonClick(ClickEvent event) { 
  // …
  } 
});

Event listeners are executed in the server side synchronously. You can fetch data and update the user interface by adding and removing components.

Theming Vaadin Applications

Vaadin is designed to support the parallel work of application developers and graphic designers by strongly separating the graphical elements from the functionality.

All Vaadin applications have an associated theme. Themes are essentially a collection of SCSS files, images, fonts, and other assets that define the look and feel of Vaadin’s user interface components. The following Vaadin themes are included in Liferay by default:

Structure of a Vaadin Theme

Vaadin themes are located in the themes folder of the portal. They are a collection of CSS and images that give the Vaadin components their look and feel. The theme folder must contain a styles.css stylesheet, and custom layouts must be placed in the layouts/ sub-folder. Other contents may be named freely.

An example Vaadin theme structure extending “Valo”:

To inherit a Vaadin Valo-theme, insert it in the main level styles.scss file:

@import “../valo/valo”;

You should put your SCSS customization rules into the separate mytheme.scss file and import those rules into styles.scss. To activate the theme in your port let, add the following to the init() method of your application:

public void init(VaadinRequest request) { 
  setTheme(“my theme”); // ...
}

SCSS Class Names in Vaadin

To maximize the use of theme inheritance and to help customize components, the CSS class selectors in Vaadin are defined using the scheme .v-<component|item>. All style names are lowercase.

As an example, the following SCSS rules extend the Valo theme and change the color of all captions and add borders to all TextFields in the mytheme.scss file:

.mytheme {

  // include valo theme rules
  @include valo; 


  .v-texfield {
          border: 1px solid red;
  }

  .v-caption {
    color: red;
  }
}

The relevant CSS class names are:

.mytheme {
  /* … other SCSS rules … */
  .v-textfield { 
    .v-caption {color: green; }
  }
}

Extending Valo-theme

The Valo theme was introduced in Vaadin 7.3. Unlike other themes, Valo is meant to be configured using variables instead of using CSS rules. Variables define a feature of a theme, and they can affect many CSS rules at the same time. For example, changing background color luminance also configures the highlight color. Variable names start with v- and can be used like this:

$v-background-color: rgb(123,123,123);

Full reference documentation is available at https://vaadin.com/api/valo.

Accessing Liferay APIs from Vaadin: Best Practices

Vaadin applications typically begin by constructing the UI using Vaadin APIs, and then allowing the application to respond to user events such as button clicks. In many cases, UI construction or event handling requires some data from the Liferay environment. Here are two example methods demonstrating how to access Liferay services from Vaadin UI code:

private String getPortletContextName(VaadinRequest request) {

  WrappedPortletSession wps = (WrappedPortletSession)
      request.getWrappedSession();

  PortletSession ps = wps.getPortletSession();
  PortletContext ctx = ps.getPortletContext();
  return ctx.getPortletContextName();
}

private Integer getPortalCountOfRegisteredUsers() {
  Integer result = null;

  try {
    result = UserLocalServiceUtil.getUsersCount();
  } catch (SystemException e) {
    log.error(e);
  }

  return result;
}

The above examples use several APIs explained below:

These can be used throughout a Vaadin application, including init(), and within listeners and other Vaadin-specific code.

Accessing Liferay Services

In the above code, there is a method call to UserLocalServiceUtil.getUsersCount() - this is a Liferay service that returns the number of users registered in Liferay. The Liferay Developer Guide contains descriptions of many other Liferay services, but here are a few to get you started (and which can be used throughout Vaadin applications).

Inter-portlet Communication (IPC)

Liferay offers different IPC mechanisms to allow portlets to communicate with each other. The following table summarizes the different IPC methods in Liferay:

IPC in Vaadin Portlets

Vaadin applications deployed to Liferay can easily communicate with each other through the above IPC mechanisms. The easiest approach is to use the Vaadin IPC Add-on for Liferay. To use this add-on in your project, simply declare the dependency within your pom.xml:

<dependency>
  <groupId>org.vaadin.addons</groupId>
  <artifactId>vaadin-ipc-for-liferay</artifactId>
  <version>2.0.0</version>
</dependency>

Or, if you are using Ivy:

<dependency org=”org.vaadin.addons”
            name=”vaadin-ipc-for-liferay”
            rev=”2.0.0” />

Once declared, your Vaadin applications can communicate using the LiferayIPC APIs, as shown here:

Sending a Message to Another Vaadin Application

/* class member declaration */
private LiferayIPC ipc;

@Override
protected void init(VaadinRequest request) {
  /* UI Initialization */ilcipc =  new LiferayIPC();
  ipc.extend(this);
}

some_button.addClickListener(new ClickListener() {
  @Override
  public void buttonClick(ClickEvent event) {
    /* Send message on button click */ 
    ipc.sendEvent(“MyIPCMessageName”, “The Payload”);
  }
});

Receiving the event in another Vaadin application:

ipc.addLiferayIPCEventListener(“MyIPCMessageName”,
  new LiferayIPCEventListener() {

  @Override
  public void eventReceived(LiferayIPCEvent event) {
    Notification.show(“Got the payload: “ + event.getData());
  }
});

Receiving an Eevent from a Vaadin Application/Portlet Using JavaScript

<script type=”text/javascript”>
  Liferay.on(“uniqueEventId”,
    function(event) {
        alert(event);
    }
  );
</script>

Sending an Event from Another Portlet Using JavaScript

<script>
  Liferay.fire(“uniqueEventId”, “someData”);
</script>

This method is not suitable for sending a lot of data, but rather notifying the portlet that something has updated. The actual data should be shared using the portal session, the database, files, or some external storage. For example, to use the portal session to store and retrieve large objects:

WrappedPortletSession wrappedPortletSession = (WrappedPortletSession) request.getWrappedSession();

PortletSession portletSession = wrappedPortletSession.getPortletSession();

// save data to session
portletSession.setAttribute(“data-key”, data, PortletSession.APPLICATION_SCOPE);

// retrieve data from session

SomeType data = (SomeType)portletSession.getAttribute(“data-key”, PortletSession.APPLICATION_SCOPE);