Portal Integration

4.Put the libraries in tomcat-x.x.x/webapps/ROOT/WEB-INF/lib/

5.Extract the VAADIN folders from vaadin-server.jar, vaadin-themes.jar, and vaadin-client-compiled.jar and copy their contents to tomcat-x.x.x/webapps/ROOT/html/VAADIN

You need to define the widget set, the theme, and the JAR in the portal-ext.properties configuration file for Liferay, as described earlier. The file should normally be placed in the Liferay installation directory. See Liferay documentation for details on the configuration file.

Below is an example of a portal-ext.properties file:

#Path under which the VAADIN directory is located.

#(/html is the default so it is not needed.)

#vaadin.resources.path=/html

#Portal-wide widget set vaadin.widgetset=com.vaadin.portal.gwt.PortalDefaultWidgetSet

#Theme to use

vaadin.theme=reindeer

The allowed parameters are:

vaadin.resources.path

Specifies the resource root path under the portal context. This is /html by default. Its actual location depends on the portal and the application server; in Liferay with Tomcat it would be located at webapps/ROOT/html under the Tomcat installation directory.

vaadin.widgetset

The widget set class to use. Give the full path to the class name in the dot notation. If the parameter is not given, the default widget set is used.

vaadin.theme

Name of the theme to use. If the parameter is not given, the default theme is used, which is reindeer in Vaadin 6.

You will need to restart Liferay after creating or modifying the portal-ext.properties file.

12.6. Handling Portlet Requests

Portals such as Liferay are not AJAX applications, but reload the page every time a user interaction requires data from the server. They consider a Vaadin UI to be a regular web application that works by HTTP requests. All the AJAX communications required by the Vaadin UI are done by the Vaadin Client-Side Engine (the widget set) past the portal, so that the portal is unaware of the communications.

The only way a portal can interact with a UI is to load it with a HTTP request; reloading does not reset the UI. The Portlet 2.0 API supports four types of requests: render, action, resource, and event requests. The old Portlet 1.0 API supports only the render and action requests. Requests can be caused by user interaction with the portal controls or by clicking action URLs displayed by the portlet. You can handle portlet requests by implementing the PortletListener interface and the handler methods for each of the request types. You can use the request object passed to the handler to access certain portal data, such as user information, the portlet mode, etc.

The PortletListener interface is defined in the PortletApplicationContext2 for Portlet 2.0 API and com.vaadin.terminal.gwt.server.PortletApplicationContext class for the old Portlet 1.0

Handling Portlet Requests

329

Portal Integration

API. You can get the portlet application context with getContext() method of the application class.

You need to have the portlet.jar in your class path during development. However, you must not deploy the portlet.jar with the portlet, because it would create a conflict with the internal portlet library of the portal. You should put it in a directory that is not deployed with the portlet, for example, if you are using Eclipse, under the lib directory under the project root, not under

WebContent/WEB-INF/lib, for example.

You can also define portal actions that you can handle in the handleActionRequest() method of the interface.

You add your portlet request listener to the application context of your application, which is a PortletApplicationContext when (and only when) the application is being run as a portlet.

// 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, new MyPortletListener()); } else {

Notification.show("Not initialized via Portal!", Notification.TYPE_ERROR_MESSAGE);

}

The handler methods receive references to request and response objects, which are defined in the Java Servlet API. Please refer to the Servlet API documentation for further details.

The PortletDemo application included in the demo WAR package includes examples of processing mode and portlet window state changes in a portlet request listener.

12.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.

330	Handling Portlet Mode Changes

Portal Integration

// 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 {

Notification.show("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) {

Handling Portlet Mode Changes

331

Portal Integration

}

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);

}

}

Figure 12.4, “Portlet Modes in Action” shows the resulting portlet in the three modes: view, edit, and help. In Liferay, the edit mode is shown in the popup menu as a Preferences item.

Figure 12.4. Portlet Modes in Action

12.8. Non-Vaadin Portlet Modes

This section is not yet updated for Vaadin 7.

332	Non-Vaadin Portlet Modes

Portal Integration

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 VaadinPortlet. 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 12.7, “Handling Portlet Mode Changes”. Also, the portlet class in portlet.xml should point to the customized subclass of VaadinPortlet.

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.server.VaadinPortlet;

public class HtmlHelpPortlet extends VaadinPortlet {

//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 writeAjaxPage() method VaadinPortlet 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.

Non-Vaadin Portlet Modes

333

Portal Integration

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 CountUI extends UI { 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 AbstractVaadinPortlet {

@Override

protected void writeAjaxPage(RenderRequest request, RenderResponse response, Window window,

UI 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

334	Non-Vaadin Portlet Modes