Portlet 2.0 Schema

To have access to the latest Portlet 2.0 spec features, such as Events and Public Render Parameters, it's important to ensure that your portlet.xml contains the following schema definition:

<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
  version="2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd">

Preserving Request Parameters outside ActionRequest

By default the JBoss Portlet Bridge does not retain any Request Parameters that were received as part of an ActionRequest from the Portal. To ensure that Request Parameters from an ActionRequest are retained in the Bridge Request Scope until a RenderRequest, add the following init-param to portlet.xml:

<init-param>
  <name>javax.portlet.faces.preserveActionParams</name>
  <value>true</value>
</init-param>

If you're using Facelets:

Include the following in web.xml:

<context-param>
  <param-name>
    javax.portlet.faces.RENDER_POLICY
  </param-name>
  <param-value>
    ALWAYS_DELEGATE
  </param-value>
</context-param>

If you're using JSP:

Include the following in web.xml:

<context-param>
  <param-name>
    javax.portlet.faces.RENDER_POLICY
  </param-name>
  <param-value>
    NEVER_DELEGATE
  </param-value>
</context-param>

Supported Render Policies in JBoss Portlet Bridge:

• ALWAYS_DELEGATE: Indicates the Bridge should not render the view itself but rather always delegate the rendering.

• NEVER_DELEGATE: Indicates the Bridge should always render the view itself and never delegate.

• DEFAULT: Directs the Bridge to first delegate the render and if and only if an Exception is thrown then render the view based on its own logic. If the configuration parameter is not present or has an invalid value the Bridge renders using default behavior. I.e. as if DEFAULT is set.

Events

<init-param>
  <name>javax.portlet.faces.autoDispatchEvents</name>
  <value>true</value>
</init-param>

<supported-publishing-event>
  <qname xmlns:jbp="urn:jboss:portal:samples:event">jbp:BookingEvent</qname>
</supported-publishing-event>

<event-definition>
  <qname xmlns:jbp="urn:jboss:portal:samples:event">jbp:BookingEvent</qname>
  <value-type>org.jboss.example.booking.BookingEvent</value-type>
</event-definition>

@XmlRootElement
public class BookingEvent implements Serializable {

  private String id;
  public static final QName QNAME = new QName("urn:jboss:portal:samples:event", "BookingEvent");

  public BookingEvent(String id) {
      this.id = id;
  }

  public String getId() {
    return id;
  }
}

Object response = FacesContext.getCurrentInstance().getExternalContext().getResponse();
  if (response instanceof StateAwareResponse) {
    String id = "an id";
    StateAwareResponse stateResponse = (StateAwareResponse) response;
    stateResponse.setEvent(BookingEvent.QNAME, new BookingEvent(id));
  }

<init-param>
  <name>javax.portlet.faces.bridgeEventHandler</name>
  <value>org.jboss.example.booking.BookingEventHandler</value>
</init-param>

<supported-processing-event>
  <qname xmlns:jbp="urn:jboss:portal:samples:event">jbp:BookingEvent</qname>
</supported-processing-event>

public class BookingEventHandler implements BridgeEventHandler {
  public EventNavigationResult handleEvent(FacesContext context, Event event) {
    // Process event payload as appropriate
  }
}

Public Render Parameters

Public Render Parameters (or PRPs) are one of the most powerful and simple Portlet 2.0 features. Several portlets (JSF or not) can share the same render parameters. This feature can be use to present a cohesive UI to the user across all portlets on the page (i.e. using an employee ID to display relative data).

<portlet>
  ...
  <supported-public-render-parameter>hotelName</supported-public-render-parameter>
</portlet>

<public-render-parameter>
  <identifier>hotelName</identifier>
  <qname xmlns:j="http://jboss.org/params">j:hotelName</qname>
</public-render-parameter>

<init-param>
  <name>javax.portlet.faces.bridgePublicRenderParameterHandler</name>
  <value>org.jboss.example.booking.BookingPRPHandler</value>
</init-param>

Object response = FacesContext.getCurrentInstance().getExternalContext().getResponse();
if (response instanceof StateAwareResponse) {
  StateAwareResponse stateResponse = (StateAwareResponse) response;
  stateResponse.setRenderParameter("hotelName", "Name of Hotel");
}

public class BookingPRP {
  private String hotelName;

  public String getHotelName() {
    return hotelName;
  }

  public void setHotelName(String hotelName) {
    this.hotelName = hotelName;
  }
}

<application>
  <application-extension>
    <bridge:public-parameter-mappings>
      <bridge:public-parameter-mapping>
        <parameter>bookingMapPortlet:hotelName</parameter>
        <model-el>#{bookingPRP.hotelName}</model-el>
      </bridge:public-parameter-mapping>
    </bridge:public-parameter-mappings>
  </application-extension>
</application>

public class BookingPRPHandler implements BridgePublicRenderParameterHandler {
  public void processUpdates(FacesContext context) {
    ELContext elContext = context.getELContext();
    BookingPRPBean bean = (BookingPRPBean) elContext.getELResolver().getValue(elContext, null, "bookingPRP");

    if(null != bean) {
      System.out.println("******processUpdates from BookingPRPHandler: " + bean.getHotelName());
    }
  }
}

Portlet Session

It's possible to share data with other portlets, within the same portlet application, using name/value pairs within the PortletSession. Use the following code to set the name/value data:

Object objSession = FacesContext.getCurrentInstance().getExternalContext().getSession(false);
  try {
    if (objSession instanceof PortletSession) {
      PortletSession portalSession = (PortletSession)objSession;
      portalSession.setAttribute("your parameter name", "parameter value", PortletSession.APPLICATION_SCOPE);
    }
  }

Then in your JSP or Facelets page you can retrieve the value using:

#{httpSessionScope['your parameter name']}

Switching Portlet Modes

A PortletMode represents a distinct render path within an application. There are three standard modes: view, edit, and help. The Bridge's ExternalContext.encodeActionURL() recognizes the query string parameter javax.portlet.faces.PortletMode and uses this parameter's value to set the portlet mode on the underlying portlet actionURL or response, but once processed it then removes this parameter from the query string.

The following navigation rule causes one to render the \edit.xhtml viewId in the portlet edit mode:

<navigation-rule>
  <from-view-id>/register.xhtml</from-view-id>
  <navigation-case>
    <from-outcome>edit</from-outcome>
    <to-view-id>/edit.xhtml?javax.portlet.faces.PortletMode=edit</to-view-id>
  </navigation-case>
</navigation-rule>

Portlet Mode's last viewId

By default a mode change will start in the mode's default view without any (prior) existing state. One common portlet pattern when returning to the mode one left after entering another mode (e.g.. view -> edit -> view) is to return to the last view (and state) of this original mode. The Bridge will explicitly encode the necessary information so that when returning to a prior mode it can target the appropriate view and restore the appropriate state. The session attributes maintained by the Bridge are intended to be used by developers to navigate back from a mode to the last location and state of a prior mode, as such a developer needs to describe a dynamic navigation: "from view X return to the last view of mode y". This is most easily expressed via an EL expression, for example:

<navigation-rule>
  <from-view-id>/edit.xhtml*</from-view-id>
  <navigation-case>
    <from-outcome>view</from-outcome>
    <to-view-id>#{sessionScope['javax.portlet.faces.viewIdHistory.view']}</to-view-id>
  </navigation-case>
</navigation-rule>

Linking to Facelets page within same Portlet

When linking to any Facelets page within your portlet web application, you may use the following:

<h:outputLink value="#{facesContext.externalContext.requestContextPath}/home.xhtml">
  <f:param name="javax.portlet.faces.ViewLink" value="true"/>
    navigate to the test page
  </h:outputLink>

Redirect to External Page or Resource

To link to a non JSF View (such as jboss.org), you may use the following:

<h:commandLink actionListener="#{yourBean.yourListener}">
  <f:param name="javax.portlet.faces.DirectLink" value="true"/>
    navigate to the test page
</h:commandLink>

With a backing Bean that has the following:

public class YourBean {
  public void yourListener() {
    FacesContext.getCurrentInstance().getExternalContext().redirect("http://www.jboss.org");
  }
}