13.7. Handling Portlet Mode Changes

Portals support three portlet modes defined in the Portlet API: view, edit, and help modes. The view mode is the default and the portal can have buttons to switch the portlet to the other modes. In addition to the three predefined modes, the Portlet API standards allow custom portlet modes, although portals may support custom modes to a varying degree.

You need to define which portlet modes are enabled in the portlet.xml deployment descriptor as follows.

<!-- Supported portlet modes and content types. -->
<supports>
    <mime-type>text/html</mime-type>
    <portlet-mode>view</portlet-mode>
    <portlet-mode>edit</portlet-mode>
    <portlet-mode>help</portlet-mode>
</supports>

Changes in the portlet mode are received as resource requests, which you can handle with a handleResourceRequest(), defined in the PortletListener interface. The current portlet mode can be acquired with getPortletMode() from the request object.

The following complete example (for Portlet 2.0) shows how to handle the three built-modes in a portlet application.

// Use Portlet 2.0 API
import com.vaadin.terminal.gwt.server.PortletApplicationContext2;
import com.vaadin.terminal.gwt.server.PortletApplicationContext2.PortletListener;

public class PortletModeExample extends Application
                                implements PortletListener {
    Window         mainWindow;
    ObjectProperty data; // Data to view and edit
    VerticalLayout viewContent   = new VerticalLayout();
    VerticalLayout editContent   = new VerticalLayout();
    VerticalLayout helpContent   = new VerticalLayout();
    
    @Override
    public void init() {
        mainWindow = new Window("Myportlet Application");
        setMainWindow(mainWindow);

        // Data model
        data = new ObjectProperty("<h1>Heading</h1>"+
                       "<p>Some example content</p>");

        // Prepare views for the three modes (view, edit, help)
        // Prepare View mode content
        Label viewText = new Label(data, Label.CONTENT_XHTML);
        viewContent.addComponent(viewText);

        // Prepare Edit mode content
        RichTextArea editText = new RichTextArea();
        editText.setCaption("Edit the value:");
        editText.setPropertyDataSource(data);
        editContent.addComponent(editText);

        // Prepare Help mode content
        Label helpText = new Label("<h1>Help</h1>" +
                                   "<p>This helps you!</p>",
                                   Label.CONTENT_XHTML);
        helpContent.addComponent(helpText);

        // Start in the view mode
        mainWindow.setContent(viewContent);

        // Check that we are running as a portlet.
        if (getContext() instanceof PortletApplicationContext2) {
            PortletApplicationContext2 ctx =
                (PortletApplicationContext2) getContext();

            // Add a custom listener to handle action and
            // render requests.
            ctx.addPortletListener(this, this);
        } else {
            mainWindow.showNotification("Not running in portal",
                               Notification.TYPE_ERROR_MESSAGE);
        }
    }

    // Dummy implementations for the irrelevant request types
    public void handleActionRequest(ActionRequest request,
                                    ActionResponse response,
                                    Window window) {
    }
    public void handleRenderRequest(RenderRequest request,
                                    RenderResponse response,
                                    Window window) {
    }
    public void handleEventRequest(EventRequest request,
                                   EventResponse response,
                                   Window window) {
    }

    public void handleResourceRequest(ResourceRequest request,
                                      ResourceResponse response,
                                      Window window) {
        // Switch the view according to the portlet mode
        if (request.getPortletMode() == PortletMode.EDIT)
            window.setContent(editContent);
        else if (request.getPortletMode() == PortletMode.VIEW)
            window.setContent(viewContent);
        else if (request.getPortletMode() == PortletMode.HELP)
            window.setContent(helpContent);
    }
}