JBoss.orgCommunity Documentation

Chapter 4. Developing Portlets with the Bridge

4.1. Excluding Attributes from the Bridge Request Scope
4.2. Supporting PortletMode Changes
4.3. Navigating to a mode's last viewId
4.4. General Error Handling
4.5. Custom Ajax Error Handling
4.6. Communication Between Your Portlets
4.6.1. Storing Components in PortletSession.APPLICATION_SCOPE
4.6.2. Using the PortletSession
4.7. Linking to Portlet/JSF Pages Using h:outputink
4.8. Redirecting to an External Page or Resource
4.9. Using Provided EL Variables
4.10. Remote Portlet Navigation Using Portlet Events

This chapter demonstrates common development tasks described by the 329 specification.

When your application uses request attributes on a per request basis and you do not want that particular attribute to be managed in the extended bridge request scope, you must use the following configuration in your faces-config.xml. Below you will see that any attribute namespaced as foo.bar or any attribute beginning with foo.baz(wildcard) will be excluded from the bridge request scope and only be used per that application's request.


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. Once processed it then removes this parameter from the query string. This means the following navigation rule causes one to render the \edit.jspx viewId in the portlet edit mode:


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 origin 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. E.g.


expression returns a viewId of the form


Without wildcarding, when a subsequent navigation occurs from this new view, the navigation rules wouldn't resolve because there wouldn't be an exact match. Likewise, the above edit.jspx


is wildcarded because there are navigation rules that target it that use a query string:

<to-view-id> /edit.jspx?javax.portlet.faces.PortletMode=edit </to-view-id>

Developers are encouraged to use such wildcarding to ensure they execute properly in the broadest set of bridge implementations.

Using Seam Page Actions

Since Seam page actions are called during RENDER_RESPONSE, there is no guarantee how many times your portlet will be rendered. So page actions should only be used for navigation related tasks and never perform operations with side effects, ie. all page actions must be idempotent. For code that should only be called once in this scenario, component based actions should be used instead. They are called at the INVOKE_APPLICATION phase which is performed in the portal ActionRequest (one time per submit).

The following configuration may be used to handle exceptions. This is also useful for handling session timeout and ViewExpiredExceptions.

Pay attention to the location element. It must contain the /faces/ mapping to work properly.


By default, error handling is sent to a standard servlet page for Ajax requests. To handle the error inside the portlet, use the following javascript:

         <script type="text/javascript">
           A4J.AJAX.onError = function(req,status,message){
             window.alert("Custom onError handler "+message);

           A4J.AJAX.onExpired = function(loc,expiredMsg){
             if(window.confirm("Custom onExpired handler "+expiredMsg+" for a location: "+loc)){
               return loc;
             } else {
               return false;

Also, add the following to web.xml. Read more about these settings here Request Errors and Session Expiration Handling


There are roughly 4 different ways to send messages, events, and parameters between portlets which are contained in different ears/wars or contained in the same war. The Portlet Container does not care if you have 2 portlets in the same war or if they are separated, because each portlet has a different HttpSession.

Of course, with the Portlet 2.0 spec, the recommended way to share a parameter or event payload between 2 or more portlets are the Section 3.4.2, “Public Render Parameters” and Section 3.4.1, “Sending and Receiving Events” mechanisms. This allows you to decouple your application from surgically managing objects in the PortletSession.APPLICATION_SCOPE.

But, if these do not meet your usecase or you have a different strategy, you can use one of the following methods.

For linking to any JSF/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

To link to a non JSF view (i.e. jboss.org) you can use the following parameter.

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

Then in your backing bean, you must call a redirect().


All EL variables found in the JSR-329 (Portlet 2.0) specification are available in the JBoss Portlet Bridge. For example, you can use the following to edit the portlet preferences on the UI.

           <h:inputText id="pref" required="true" value="#{mutablePortletPreferencesValues['userName'].value}" />
           <h:commandButton actionListener="#{myBean.savePref}" value="Save Preferences" />

Then in your backing bean, you must call the PortletPreferences.store() method.

      Object request = FacesContext.getCurrentInstance().getExternalContext().getRequest();
      PortletRequest portletRequest = (PortletRequest)request;
      if (request instanceof PortletRequest) {
         try {
            PortletPreferences portletPreferences = portletRequest.getPreferences();

When you send events using the method described here Section 3.4.1, “Sending and Receiving Events”, you can also leverage the EventNavigationResult and return a JSF navigation rule. For Example, by returning a

new EventNavigationResult("fromAction","Outcome"); 

the fromAction can be a catch all like "/*" or a nav rule defined in your faces-config.xml and outcome can be the from-outcome node defined in the faces-config.xml navigation rule.