Docs

You are viewing documentation for an older Vaadin version. View latest documentation

Docs

Inter-portlet Communication

How to enable Portlets to communicate with other Vaadin or non-Vaadin Portlets on the Portal page

Inter-portlet communication (IPC) is a collection of methods that 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 the Portlet 1.0 specification, portlets could pass information only via public request parameters; one portlet would create a request URL using request parameters to hold the data. When a request was made, the handling portlet would receive those parameters, with the data, via the request.

The 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 that have registered to handle events with certain names will process the dispatched event. This form of IPC happens entirely on the server side.

The 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 the 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 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 they are forwarded using PortletHub::dispatchClientEvent(). To handle the events dispatched by 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 on the client side.

Firing and Receiving Events in Java Code

Given two portlet views FiringPortletView and ReceivingPortletView, we set up 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 the PortletView interface, which allows it to get PortletViewContext when it is initialized. The button click listener then calls PortletViewContext::fireEvent(…​) method to fire our event. ReceivingPortletView.java also implements the 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 want 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 in the portlet.xml or defined using Portlet 3.0 specification annotations.

Note
 The 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 a JavaScript Event Handler

You may sometimes 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 with 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, which can be accessed in any portlet request handling context by calling VaadinPortletService.getCurrentResponse().getPortletResponse().

492C7336-9B36-4922-9F8F-57E220252F02