Docs

Documentation versions (currently viewingVaadin 14)

Inter-portlet Communication

Inter-portlet communication (IPC) is a collection of methods which allow portlets to pass information from one to another. This allows the separate portlets to work in a cohort to provide a cohesive whole.

In Portlet 1.0 specification, portlet could only pass information via public request parameters; one portlet would create a request URL with request parameters that held the data. When the request was made, the handling portlet would receive those parameters and thus the data via the request.

Portlet 2.0 specification introduced events; an event is defined in the portlet.xml with the associated parameter types. A portlet may dispatch an event, and portlets which have registered to handle events with certain names will process the dispatched event. This form of IPC happens entirely on the server-side.

Portlet 3.0 specification brings PortletHub - a client-side API for portlets to use for various tasks. One aspect of this is firing client-side events and creating action requests to the server-side portlets.

Vaadin Portlets allows the developer to leverage the latest Portlet 3.0 style IPC and provides helper APIs for common use-cases.

Vaadin Portlet IPC with 3.0 Specification

When Vaadin Portlets run on a portal supporting Portlet 3.0 specification, Vaadin Portlet automatically adds PortletHub support on the client-side. The standard IPC for Vaadin Portlets leverages PortletHub to provide the developer with seamless integration of the client-side and server-side events.

You can use PortletViewContext to send events from your portlet’s view class. These events are then delivered to the client-side, where the events are delivered forward using PortletHub::dispatchClientEvent(). To handle the events dispatched by the PortletHub you can either register your portlet’s view class to handle certain events based on the event names, or register a JavaScript event handler onto the client-side.

Firing and Receiving Events in Java Code

Given two portlet views FiringPortletView and ReceivingPortletView we setup our Vaadin Portlet IPC as follows:

public class FiringPortletView extends Div implements PortletView {

    private PortletViewContext portletContext;

    @Override
    public void onPortletViewContextInit(PortletViewContext context) {
        portletContext = context;

        Button button = new Button("Fire event", event -> portletContext
                .fireEvent("my-ipc-event", Collections.emptyMap()));
    }
}
public class ReceivingPortletView extends Div
        implements PortletView {

    @Override
    public void onPortletViewContextInit(PortletViewContext context) {
        context.addEventChangeListener("my-ipc-event", event -> Notification
                .show("Received '" + event.getEventName() + "' event!"));
    }
}

FiringPortletView.java implements PortletView interface which allows it to get PortletViewContext when it is initialized. Then the button click listener calls PortletViewContext::fireEvent(…​) method to fire our event. ReceivingPortletView.java also implements PortletView interface, which allows it to add event listeners via PortletViewContext::addEventChangeListener when it is initialized. When adding an event listener, we can specify the event name for which we’d like to receive updates.

Events are fired using the PortletHub delivery method. Using PortletHub for IPC has the following benefits over the older Portlet 2.0 event mechanism:

  • Non-Vaadin portlets may receive these events on the client-side just as easily.

  • Firing these events does not require the code to be executed inside a portlet request.

  • These events do not need to be registered into the portlet.xml or defined using the 3.0 specification annotations.

Note
Vaadin Portlet IPC API does not support Portlet 2.0 style event handling. The basic Portlet API can of course still be used if desired.

Registering JavaScript Event Handler

Occasionally, you may want to receive a portlet event on the client side, without a server round-trip. A client-side event listener handling events of type EVENT can be registered directly to the portlet hub:

const hub = window.Vaadin.Flow.Portlets[PORTLET_NS].hub();
hub.addEventListener(EVENT, function (type, state) { /* event handling code */ })

The portlet hub registrations for all Vaadin Portlets are stored in the window.Vaadin.Flow.Portlets object. To access the registration belonging to a specific portlet you need the namespace PORTLET_NS of your portlet. On the server side, this can be obtained by calling the method PortletResponse::getNamespace of the current portlet response. The latter can be accessed in any portlet request handling context by calling VaadinPortletService.getCurrentResponse().getPortletResponse().