In some cases, it can be useful to implement certain modes of a portlet as pure HTML or JSP pages instead of running the full Vaadin application user interface in them. Common reasons for this are static pages (for example, a simple help mode), integrating legacy content to a portlet (for example, a JSP configuration interface), and providing an ultra-lightweight initial view for a portlet (for users behind slow connections).

Fully static modes that do not require the Vaadin server side application to be running can be implemented by subclassing the portlet class ApplicationPortlet2 (Portlet 2.0). The subclass can either create the HTML content directly or dispatch the request to, for example, a HTML or JSP page via the portal. When using this approach, any Vaadin portlet and portlet request listeners are not called.

Customizing the content for the standard modes (view, edit, and help) can be performed by overriding the methods doView, doEdit and doHelp, respectively. Custom modes can be handled by implementing similar methods with the @javax.portlet.RenderMode(name = "mymode") annotation.

You need to define which portlet modes are enabled in the portlet.xml deployment descriptor as described in Section 13.7, “Handling Portlet Mode Changes”. Also, the portlet class in portlet.xml should point to the customized subclass of ApplicationPortlet2.

The following example (for Portlet 2.0) shows how to create a static help page for the portlet.

portlet.xml:

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

HtmlHelpPortlet.java::

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

public class HtmlHelpPortlet extends ApplicationPortlet2 {
    // Override the help mode, let the Vaadin
    // application handle the view mode
    @Override
    protected void doHelp(RenderRequest request,
                          RenderResponse response)
            throws PortletException, IOException {
        // Bypass the Vaadin application entirely
        response.setContentType("text/html");
        response.getWriter().println(
                "This is the help text as plain HTML.");

        // Alternatively, you could use the dispatcher for,
        // for example, JSP help pages as follows:
        // PortletRequestDispatcher dispatcher = getPortletContext()
        // .getRequestDispatcher("/html/myhelp.jsp");
        // dispatcher.include(request, response);
    }
}

To produce pure HTML portlet content from a running Vaadin application instead of statically outside an application, the ApplicationPortlet2 method writeAjaxPage should be overridden. This approach allows using the application state in HTML content generation, and all relevant Vaadin portlet request and portlet listeners are called around the portlet content generation. However, the client side engine (widgetset) is not loaded by the browser, which can shorten the initial page display time.

<portlet-class>com.vaadin.demo.portlet.HtmlModePortlet</portlet-class>
<supports>
    <mime-type>text/html</mime-type>
    <portlet-mode>view</portlet-mode>
    <portlet-mode>help</portlet-mode>
</supports>
public class CountApplication extends Application {
    private int count = 0;
    
    public void init() {
        Window w = new Window("Portlet mode example");
        w.addComponent(new Label("This is the Vaadin app."));
        w.addComponent(new Label("Try opening the help mode."));
        setMainWindow(w);
    }
        
    public int incrementCount() {
        return ++count;
    }
}
// Use Portlet 2.0 API
public class HtmlModePortlet extends AbstractApplicationPortlet {

    @Override
    protected void writeAjaxPage(RenderRequest request,
            RenderResponse response, Window window,
            Application app)
                throws PortletException, IOException {
        if (PortletMode.HELP.equals(request.getPortletMode())) {
            CountApplication capp = (CountApplication) app;
            response.setContentType("text/html");
            response.getWriter().println(
                "This is the HTML help, shown "
                + capp.incrementCount() + " times so far.");
        } else {
            super.writeAjaxPage(request, response, window, app);
        }
    }
    
    @Override
    protected Class<? extends Application> getApplicationClass(){
        return CountApplication.class;
    }
}

The user can freely move between Vaadin and non-Vaadin portlet modes with the user interface provided by the portal (for standard modes) or the portlet (for example, action links). Once the server side application has been started, it continues to run as long as the session is alive. If necessary, specific portlet mode transitions can be disallowed in portlet.xml.

In the case of Portlet 1.0, both a portlet and a servlet are involved. A render request is received by ApplicationPortlet when the portlet mode is changed, and serving pure HTML in some modes can be achieved by overriding the method render and handling the modes of interest separately while calling super.render() for other modes. As always, when extending the portlet, the reference to the portlet class in portlet.xml needs to be updated.

To serve HTML-only content in the Portlet 1.0 case after starting the server side application and calling the relevant listeners, the servlet class ApplicationServlet should be subclassed instead of the portlet. The method writeAjaxPage can be overridden to produce custom HTML content for certain modes. However, it should be noted that some HTML content (for example, loading the portal-wide Vaadin theme) is created by the portlet and not the servlet.