Vaadin

Installing the widget set and themes to the portal is required for running two or more Vaadin portlets simultaneously in a single portal page. As this situation occurs quite easily, we recommend installing them in any case.

In addition to the Vaadin library, you will need to copy the portlet.jar to your project. It is included in the Vaadin installation package. Notice that you must not put the portlet.jar in the same WebContent/WEB-INF/lib directory as the Vaadin JAR or otherwise include it in the WAR to be deployed, because it would create a conflict with the internal portlet library of the portal.

How you actually deploy a WAR package depends on the portal. In Liferay, you simply drop it to the deploy subdirectory under the Liferay installation directory. The deployment depends on the application server under which Liferay runs; for example, if you use Liferay bundled with Tomcat, you will find the extracted package in the webapps directory under the Tomcat installation directory included in Liferay.

import com.vaadin.Application;
import com.vaadin.ui.*;
public class PortletExample extends Application {
    @Override 
    public void init() {
        Window mainWindow = new Window("Portlet Example");
        Label label = new Label("Hello Vaadin user");
        mainWindow.addComponent(label);
        setMainWindow(mainWindow);
    }
}

In these instructions, we assume that you use Liferay bundled with Apache Tomcat, although you can use many other application servers with Liferay just as well. The Tomcat installation is included in the Liferay installation package, under the tomcat-x.x.x directory.

The Vaadin JAR should be put in tomcat-x.x.x/webapps/ROOT/WEB-INF/lib/vaadin.jar. The Vaadin version number should normally be left out from the JAR.

The widget set needs to be located at /html/VAADIN/widgetsets/ and themes at /html/VAADIN/themes/ path under the portal context. You simply need to copy the contents from under your WebContent/VAADIN directory to the tomcat-x.x.x/webapps/ROOT/html/VAADIN directory under the Liferay installation directory. If you use a built-in widget set or theme included in Vaadin, such as the PortalDefaultWidgetSet, you should copy it from the Vaadin installation directory, from under WebContent/VAADIN/widgetsets. The default themes are located under WebContent/VAADIN/themes in the installation directory.

You need to define the widget set, the theme, and the JAR in the portal-ext.properties configuration file for Liferay, as described earlier. The file should normally be placed in the Liferay installation directory. See Liferay documentation for details on the configuration file.

Below is an example of a portal-ext.properties file:

# Path under which the VAADIN directory is located.
# (/html is the default so it is not needed.)
# vaadin.resources.path=/html
# Portal-wide widget set
vaadin.widgetset=com.vaadin.portal.gwt.PortalDefaultWidgetSet
# Theme to use
vaadin.theme=reindeer

The allowed parameters are:

You will need to restart Liferay after creating or modifying the portal-ext.properties file.

The only way a portal can interact with an application is to load it with a HTTP request; reloading does not reset the application. The Portlet 2.0 API supports four types of requests: render, action, resource, and event requests. The old Portlet 1.0 API supports only the render and action requests. Requests can be caused by user interaction with the portal controls or by clicking action URLs displayed by the portlet. You can handle portlet requests by implementing the PortletListener interface and the handler methods for each of the request types. You can use the request object passed to the handler to access certain portal data, such as user information, the portlet mode, etc.

The PortletListener interface is defined in the PortletApplicationContext2 for Portlet 2.0 API and com.vaadin.terminal.gwt.server.PortletApplicationContext class for the old Portlet 1.0 API. You can get the portlet application context with getContext() method of the application class.

You need to have the portlet.jar in your class path during development. However, you must not deploy the portlet.jar with the portlet, because it would create a conflict with the internal portlet library of the portal. You should put it in a directory that is not deployed with the portlet, for example, if you are using Eclipse, under the lib directory under the project root, not under WebContent/WEB-INF/lib, for example.

You can also define portal actions that you can handle in the handleActionRequest() method of the interface.

You add your portlet request listener to the application context of your application, which is a PortletApplicationContext when (and only when) the application is being run as a portlet.

// Check that we are running as a portlet.
if (getContext() instanceof PortletApplicationContext2) {
    PortletApplicationContext2 ctx =
            (PortletApplicationContext2) getContext();
    // Add a custom listener to handle action and
    // render requests.
    ctx.addPortletListener(this, new MyPortletListener());
} else {
    getMainWindow().showNotification(
            "Not initialized via Portal!",
            Notification.TYPE_ERROR_MESSAGE);
}

The handler methods receive references to request and response objects, which are defined in the Java Servlet API. Please refer to the Servlet API documentation for further details.

The PortletDemo application included in the demo WAR package includes examples of processing mode and portlet window state changes in a portlet request listener.

You need to define which portlet modes are enabled in the portlet.xml deployment descriptor as follows.

<!-- Supported portlet modes and content types. -->
<supports>
    <mime-type>text/html</mime-type>
    <portlet-mode>view</portlet-mode>
    <portlet-mode>edit</portlet-mode>
    <portlet-mode>help</portlet-mode>
</supports>

Changes in the portlet mode are received as resource requests, which you can handle with a handleResourceRequest(), defined in the PortletListener interface. The current portlet mode can be acquired with getPortletMode() from the request object.

The following complete example (for Portlet 2.0) shows how to handle the three built-modes in a portlet application.

// Use Portlet 2.0 API
import com.vaadin.terminal.gwt.server.PortletApplicationContext2;
import com.vaadin.terminal.gwt.server.PortletApplicationContext2.PortletListener;
public class PortletModeExample extends Application
                                implements PortletListener {
    Window         mainWindow;
    ObjectProperty data; // Data to view and edit
    VerticalLayout viewContent   = new VerticalLayout();
    VerticalLayout editContent   = new VerticalLayout();
    VerticalLayout helpContent   = new VerticalLayout();
    
    @Override
    public void init() {
        mainWindow = new Window("Myportlet Application");
        setMainWindow(mainWindow);
        // Data model
        data = new ObjectProperty("<h1>Heading</h1>"+
                       "<p>Some example content</p>");
        // Prepare views for the three modes (view, edit, help)
        // Prepare View mode content
        Label viewText = new Label(data, Label.CONTENT_XHTML);
        viewContent.addComponent(viewText);
        // Prepare Edit mode content
        RichTextArea editText = new RichTextArea();
        editText.setCaption("Edit the value:");
        editText.setPropertyDataSource(data);
        editContent.addComponent(editText);
        // Prepare Help mode content
        Label helpText = new Label("<h1>Help</h1>" +
                                   "<p>This helps you!</p>",
                                   Label.CONTENT_XHTML);
        helpContent.addComponent(helpText);
        // Start in the view mode
        mainWindow.setContent(viewContent);
        // Check that we are running as a portlet.
        if (getContext() instanceof PortletApplicationContext2) {
            PortletApplicationContext2 ctx =
                (PortletApplicationContext2) getContext();
            // Add a custom listener to handle action and
            // render requests.
            ctx.addPortletListener(this, this);
        } else {
            mainWindow.showNotification("Not running in portal",
                               Notification.TYPE_ERROR_MESSAGE);
        }
    }
    // Dummy implementations for the irrelevant request types
    public void handleActionRequest(ActionRequest request,
                                    ActionResponse response,
                                    Window window) {
    }
    public void handleRenderRequest(RenderRequest request,
                                    RenderResponse response,
                                    Window window) {
    }
    public void handleEventRequest(EventRequest request,
                                   EventResponse response,
                                   Window window) {
    }
    public void handleResourceRequest(ResourceRequest request,
                                      ResourceResponse response,
                                      Window window) {
        // Switch the view according to the portlet mode
        if (request.getPortletMode() == PortletMode.EDIT)
            window.setContent(editContent);
        else if (request.getPortletMode() == PortletMode.VIEW)
            window.setContent(viewContent);
        else if (request.getPortletMode() == PortletMode.HELP)
            window.setContent(helpContent);
    }
}

Fully static modes that do not require the Vaadin server side application to be running can be implemented by subclassing the portlet class ApplicationPortlet2 (Portlet 2.0). The subclass can either create the HTML content directly or dispatch the request to e.g. a HTML or JSP page via the portal. When using this approach, any Vaadin portlet and portlet request listeners are not called.

Customizing the content for the standard modes (view, edit, and help) can be performed by overriding the methods doView, doEdit and doHelp, respectively. Custom modes can be handled by implementing similar methods with the @javax.portlet.RenderMode(name = "mymode") annotation.