> Markdown version of [Appendix A - Address Book Example Project Demonstration](https://vaadin.com/docs/v23/integrations/portlet/demo-address-book). Section index: [llms.txt](https://vaadin.com/docs/v23/integrations/llms.txt)

# Demonstration: Address Book

This demonstration brings together all the topics covered in the previous chapters. The focus of this chapter is on using inter-portlet communication between two Vaadin Portlets. Using this document along with the demonstration code, you’re able to understand the demonstration code and build similar applications yourself.

The learning goals are:

- Why events are needed

- How to send events from one Vaadin Portlet to another

- How to listen for events from other Vaadin Portlets

- How to update the portlet’s state based on the event

The source code with a complete project for this example is available in

- [Address Book for Liferay 7](https://github.com/vaadin/addressbook-portlet/tree/v23/)

## <a id="address-book-project-structure"></a>Address Book Project Structure

The address book demonstration shows how to build a simple address book application using Vaadin Portlets. The address book consists of two portlets. One portlet, *Contact List*, displays all the available contacts the user has. The other portlet, *Contact Form*, shows the information about the contact selected via the contact list. The Contact Form portlet also allows the user to edit the existing contact.

The project is structured as a multi-module project and has the following four modules:

- `addressbook-backend`\
  Holds the shared-data layer for both portlets.

- `addressbook-bundle`\
  Builds the front-end resource bundle for both portlets.

- `addressbook-form`\
  Contact information portlet.

- `addressbook-grid`\
  Contact list portlet.

- `portal`\
  Configuration for automatically setting up and running a Pluto portal using the Cargo plugin.

This chapter focuses on the portlet implementations. To get more familiar with setting up and maintaining a multi-module Vaadin Portlet project, take a look at the next chapter, [Creating a Multi-Module Portlet Project](https://vaadin.com/docs/v23/integrations/portlet/creating-multi-module-portlet-project.md).

### <a id="structure"></a>Structure

The address book consists of two portlets and their view components. The classes ending in `Portlet` are classes that extend `VaadinLiferayPortlet`, and classes ending in `View` are the view component classes for the portlets.

- Contact List: `ContactListPortlet` and `ContactListView` (in the `addressbook-grid` module)

  Responsible for displaying the available contacts in the address book. Allows the user to select a contact to be displayed in the Contact Form.

- Contact Form: `ContactFormPortlet` and `ContactFormView` (in the `addressbook-form` module)

  Responsible for displaying and modifying the contact information in the address book.

The other classes are there to provide business logic and mock implementations for data services.

### <a id="functionality-requirements-as-portlets"></a>Functionality Requirements as Portlets

#### <a id="contact-list"></a>Contact List

The portlet operates in only one portlet mode, `view`, and the user can’t change the mode. When the user selects a contact from the list, the contact’s details are displayed on the *Contact Form* portlet. When the contact’s information is changed in the *Contact Form* portlet, the relevant contact information is updated on the list. The list shows a limited number of contact attributes, including first name, last name, and phone number. When the portlet is maximized (its window state is changed to MAXIMIZED) more attributes are shown, including email and birthday.

To provide this functionality, the *Contact List*'s view class needs to be able to

- receive events

- send events

- react to window state changes

These requirements can be fulfilled by implementing the `PortletView` interface.

#### <a id="contact-form"></a>Contact Form

The portlet supports two portlet modes: `view` and `edit`. When the portlet is in `view` mode, the contact information is only displayed and can’t be changed. When user changes the portlet to `edit` mode, the information can be updated. After editing the information, the user can either save or discard the changes.

To provide this functionality, the *Contact List* view class needs to be able to

- react to portlet mode changes

- receive events

- send events

These requirements can be fulfilled by implementing the `PortletView` interface.

> **Note:** Use the `PortletView` interface in both view classes, as it provides a single entry point to the portlet state. You can both register event listeners and mutate the portlet’s state through the `PortletViewContext` object. However, if you are interested in only very particular types of updates and didn’t need to change the state, you could implement the `PortletModeHandler`, `WindowStateHandler`, or `EventHandler` interfaces

### <a id="implementation-details"></a>Implementation Details

This section looks at selected parts of the view classes `ListPortletView` and `FormPortletView`. The classes contain code that isn’t directly related to the portlet implementation and you skip those parts.

ListPortletView\.java

```java
public class ContactListView extends VerticalLayout implements PortletView {
    private ListDataProvider<Contact> dataProvider;

    private Grid<Contact> grid = new Grid<>(Contact.class);

    private PortletViewContext portletViewContext;

    @Override
    public void onPortletViewContextInit(PortletViewContext context) {
        // save context for sending events
        portletViewContext = context;

        // add event listeners for both "contact-updated" custom event
        // and window state change event
        context.addEventChangeListener("contact-updated",
                this::onContactUpdated);
        context.addWindowStateChangeListener(
                event -> handleWindowStateChanged(event.getWindowState()));
        init();
    }

    private void onContactUpdated(PortletEvent event) {
        int contactId = Integer
                .parseInt(event.getParameters().get("contactId")[0]);
        // retrieve the contact information from contact service
        Optional<Contact> contact = getService()
                .findById(contactId);
        // update grid's data provider with the updated contact
        contact.ifPresent(value -> dataProvider.refreshItem(value));
    }

    private ContactService getService() {
        // returns ContactService instance
    }

    private void handleWindowStateChanged(WindowState windowState) {
        if (WindowState.MAXIMIZED.equals(windowState)) {
            grid.setColumns("firstName", "lastName", "phoneNumber", "email",
                    "birthDate");
            grid.setMinWidth("700px");
            // ... rest of the configuration
        } else if (WindowState.NORMAL.equals(windowState)) {
            grid.setColumns("firstName", "lastName", "phoneNumber");
            grid.setMinWidth("450px");
            // ... rest of the configuration
        }
    }

    private void fireSelectionEvent(
            ItemClickEvent<Contact> contactItemClickEvent) {
        // get contact id
        Integer contactId = contactItemClickEvent.getItem().getId();

        // save the id into a string-to-string map
        Map<String, String> param = Collections.singletonMap(
                "contactId", contactId.toString());

        // send the event with name "contact-selected"
        portletViewContext.fireEvent("contact-selected", param);
    }

    private void init() {
        // ... grid initialization

        // add item click listener which fires our contact-selected event
        grid.addItemClickListener(this::fireSelectionEvent);

        // ... rest of the configuration
    }
}
```

The `ContactListView` view implements the `PortletView` interface. The `onPortletViewContextInit(PortletViewContext)` method in the `PortletView` interface provides the implementing class with a reference to a `PortletViewContext` object, which allows you to register listeners and change the portlet’s state. Besides `onPortletViewContextInit()`, the `ContactListView` has three important methods from the portlet perspective: `fireSelectionEvent()`, `handleWindowStateChanged()`, and `contactUpdated()`. Firing the selection event is triggered when user selects a contact in the list. The method creates a parameter map which contains the id of the selected contact. You then use the `portletViewContext` instance to send the event under the name `contact-selected`. Other Vaadin Portlet views that have registered listeners for this event name are notified about the event.

`handleWindowStateChanged()` is registered as a listener for the `WindowStateChange` event. It’s called when, for example, the portlet view is maximized or normalized. In this method, when the window state is changed to maximized, the minimum width of the grid is set to a higher value and more grid columns are shown.

The other method, `contactUpdated()`, is registered as an event listener for the `contact-updated` event via the `PortletViewContext` instance. The `contact-updated` event has the same parameters as the `contact-selected` event. You use the contact id to update the correct contact information on the list.

FormPortletView\.java

```java
public class ContactFormView extends VerticalLayout implements PortletView {
    private static final String ACTION_EDIT = "Edit";
    private static final String ACTION_CREATE = "Create new";
    private static final String ACTION_SAVE = "Save";

    private PortletViewContext portletViewContext;

    private Binder<Contact> binder;
    private Contact contact;

    private Button action;
    // ... other components

    @Override
    public void onPortletViewContextInit(PortletViewContext context) {
        // save context for sending events
        this.portletViewContext = context;
        // add event listeners for both "contact-selected" custom event
        // and portlet mode change event
        context.addEventChangeListener("contact-selected",
                this::onContactSelected);
        context.addPortletModeChangeListener(this::handlePortletModeChange);
        init();
    }

    // handles "contact-selected" event from PortletListView.
    // we check that the contact ID parameter is correct and that the contact exists.
    // then we display the contact information on the form.
    private void onContactSelected(PortletEvent event) {
        int contactId = Integer
                .parseInt(event.getParameters().get("contactId")[0]);
        Optional<Contact> contact = getService().findById(contactId);
        if (contact.isPresent()) {
            // ... set active contact
            this.contact = contact.get();
            // ... update the form
        } else {
            // ... empty the form
            clear();
        }
    }

    // called when the portlet mode changes
    // FormPortlet supports two modes: 'view' and 'edit'
    private void handlePortletModeChange(PortletModeEvent event) {
        // set fields to read-only mode when portlet mode is 'view'
        binder.setReadOnly(event.isViewMode());

        // set the button's text based on the portlet mode
        if (event.isViewMode()) {
            action.setText(ACTION_EDIT);
        } else {
            action.setText(ACTION_SAVE);
        }
    }

    private void fireUpdateEvent(Contact contact) {
        Map<String, String> param = Collections
                .singletonMap("contactId", contact.getId().toString());

        portletViewContext.fireEvent("contact-updated", param);
    }

    private PortletMode getPortletMode() {
        return portletViewContext.getPortletMode();
    }

    private void init() {
        // ... create the form layout
        setupButtons();

        // ... add components to form
    }

    private ContactService getService() {
        // returns ContactService instance
    }

    private void setupButtons() {
        action = new Button("action", event -> {
            if (PortletMode.EDIT.equals(getPortletMode())) {
                save();
            } else {
                portletViewContext.setPortletMode(PortletMode.EDIT);
            }
        });

        // ... setup rest of the buttons
    }

    private void clear() {
        // ... reset contact and clear form
    }

    private void save() {
        if (contact != null) {
            // ... save contact
        } else {
            // ... create new contact
        }
        // send custom portlet event
        fireUpdateEvent(contact);

        // ... update form

        // sent portlet mode back to view
        portletViewContext.setPortletMode(PortletMode.VIEW);
    }
}
```

`ContactFormView` uses the `PortletViewContext` received via the `onPortletViewContextInit(PortletViewContext)` method to register an event listener and portlet mode listener. The important methods for the portlet operation are `handlePortletMode()` and `onContactSelected()`. The `ContactFormView` supports two portlet modes, `view` and `edit`, which are declared in `portlet.xml`. In the `handlePortletMode()` method, depending on the portlet mode, we either enable or disable editing on the form fields. You also change the name of the `action` button to correspond to the correct mode.

`onContactSelected()` is called when the event `contact-selected` is sent by the *Contact List* portlet. When the event arrives, the contact id is used to display information for the selected `Contact`.

`A1514619-2CB3-4527-BF2E-93572ED9AA9A`
