Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

Inter-Portlet Communication

Describes how to enable Portlets to communicate with other Portlets (Vaadin or non-Vaadin) on the Portal page

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 the Portlet 1.0 specification, a 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.

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 which have registered to handle events with certain names 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 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 on the client side.

Firing and Receiving Events in Java Code

Given two portlet views, FiringPortletView and ReceivingPortletView, you can set up your 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’s initialized. The button-click listener then calls the PortletViewContext::fireEvent(…​) method to fire an event. ReceivingPortletView.java also implements the PortletView interface, which allows it to add event listeners via PortletViewContext::addEventChangeListener() when it’s initialized. When adding an event listener, you can specify the event name for which you 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 as well.

  • Firing these events doesn’t require the code to be executed inside a portlet request.

  • These events don’t need to be registered into the portlet.xml or defined using the 3.0 specification annotations.

Note
 The Vaadin Portlet IPC API doesn’t support Portlet 2.0-style event handling. The basic Portlet API can of course still be used if desired.

Registering a 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, you can get this 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().

9E8357EA-F22C-4243-BFFC-A8CD5B316331