> Markdown version of [Inter-portlet Communication](https://vaadin.com/docs/v14/flow/integrations/portlet/inter-portlet-communication). Section index: [llms.txt](https://vaadin.com/docs/v14/flow/llms.txt)

# Inter-portlet Communication

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.

## <a id="vaadin-portlet-ipc-with-3-0-specification"></a>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.

### <a id="firing-and-receiving-events-in-java-code"></a>Firing and Receiving Events in Java Code

Given two portlet views `FiringPortletView` and `ReceivingPortletView`, we set up our Vaadin Portlet IPC as follows:

FiringPortletView\.java

```java
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()));
    }
}
```

ReceivingPortletView\.java

```java
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.

### <a id="registering-a-javascript-event-handler"></a>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:

```js
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`