Bridge Configuration The 329 specification is aimed at making the developers life as easy as possible with JSF+Portlet development. You will see below that there are minimal settings to getting any JSF web application up and running in the Portal environment. If you are starting from scratch, we highly recommend you use the .
Core Setup and Configuration
portlet.xml The basic JSR-329 portlet configuration. yourPortletName javax.portlet.faces.GenericFacesPortlet javax.portlet.faces.defaultViewId.view /welcome.xhtml javax.portlet.faces.defaultViewId.edit /jsf/edit.xhtml javax.portlet.faces.defaultViewId.help /jsf/help.xhtml ]]> When preserveActionParams is set to TRUE, the bridge must maintain any request parameters assigned during the portlet's action request. The request parameters are maintained in the"bridge request scope". When this attribute isn't present or is FALSE the action's request parameters are only maintained for the duration of the portlet request scope. javax.portlet.faces.preserveActionParams true ]]>
faces-config.xml The PortletViewHandler ensures that each JSF portlet instance is properly namespaced. org.jboss.portletbridge.application.PortletViewHandler org.jboss.portletbridge.application.PortletStateManager ...]]>
Facelets Configuration The following web.xml setting is only for Facelets based applications
web.xml ... org.ajax4jsf.VIEW_HANDLERS org.jboss.portletbridge.application.FaceletPortletViewHandler ]]> javax.portlet.faces.RENDER_POLICY ALWAYS_DELEGATE ... ]]> RenderPolicy Options 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.
JSP Only Configuration The following web.xml setting is only for JSP based applications. Download the demo application here.
web.xml javax.portlet.faces.renderPolicy NEVER_DELEGATE ... ]]>
JSR-329 The Jboss Portlet Bridge can be used with a any compatible implementation ( for example, MyFaces implementation). Simply put the following into web.xml : javax.portlet.faces.BridgeImplClass org.apache.myfaces.portlet.faces.bridge.BridgeImpl ]]>
RichFaces Setup and Configuration Options
web.xml The following configuration is designated for portlets using the RichFaces library. These settings will vary based on your individual needs. See this section of the RichFaces documentation for more details. Sometimes it is better to use the "ALL" load strategy in portlets so you do not need to worry about loading the "framework.pack.js" and "ui.pack.js" files manually in your portlet header. org.richfaces.LoadStyleStrategy ALL org.richfaces.LoadScriptStrategy ALL ]]> If you use the "NONE" strategy, you must include the following scripts in your portlet or portal page header. If you are using JBoss Portal, you can add this to the jboss-portlet.xml file. The org.ajax4jsf.RESOURCE_URI_PREFIX configuration cross references the path to your scripts below. These settings are required for RichFaces using the "NONE" strategy. ]]> Seam automatically configures your Ajax4JSF Filter, so if you are running a Seam portlet, you do not need the following Filter config. (But you do need the RESOURCE_URI_PREFIX no matter what) org.ajax4jsf.RESOURCE_URI_PREFIX rfRes Ajax4jsf Filter ajax4jsf org.ajax4jsf.Filter ajax4jsf FacesServlet FORWARD REQUEST INCLUDE ... ]]>
Seam Setup and Configuration Options
Configuration The ExceptionHandler is used to clean Seam contexts and transactions after errors. org.jboss.portletbridge.ExceptionHandler org.jboss.portletbridge.SeamExceptionHandlerImpl ]]> If you are using this bridge packaged from 2.0.0.BETA onward, you must define the following web.xml parameter to use the JBoss Portlet Bridge provided Seam Phase Listener. javax.faces.LIFECYCLE_ID SEAM_PORTLET ]]>
Portlet 2.0 Coordination One very important thing to note before using either of the following mechanisms, is that you must have the proper 2.0 schema and xsd definition at the top of your portlet.xml. ]]>
Sending and Receiving Events
Configuration Just like with any portlet 2.0 event consumer and receiver, you must define them in the portlet.xml. To see a working example, checkout the Seam Booking Demo portlet. You must also define the following init params in your portlet.xml. javax.portlet.faces.autoDispatchEvents true javax.portlet.faces.bridgeEventHandler org.foo.eventhandler ]]> For now, you must dipatch the event in the JSF or Seam backing bean. Future versions on the 2.0 bridge will automate the dispatching and consuming of events. Then you must also create the event handler class by implementing the BridgeEventHandler interface to process the event payload.
Public Render Parmaeters
Configuration 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). The bridge maps a render parameter to a backing bean using settings in your faces-config.xml and portlet.xml. A clear and working example can be found in the Seam Booking Demo portlet. You must define the following init params in your portlet.xml. javax.portlet.faces.bridgePublicRenderParameterHandler org.foo.PRPHandler ... myCoolPRP ]]> Create a managed bean and public-parameter-mappings in your faces-config.xml. This should be a basic bean that you can bind the passed parameter to a string with getter and setter. bookingPRP your.class.Name session "the name of your portlet":hotelName #{bookingPRP.hotelName} ]]> You must set the parameter in the JSF or Seam backing bean, if you are providing one from your portlet. Then you must also implement the BridgePublicRenderParameterHandler interface to process any updates from the received parameter.
Serving Your JSF Resources in a Portlet
Configuration We have setup a few examples to show you how to use EL and a simple bean that will allow you to use the portlet resource serving mechanism within a JSF portlet. In ResourceBean.java, you can see a very simple implementations of a Map object that uses the bridge to get and encode a resource url served from the portlets web application. So, when you have the normal "/images", "/styles" and other resource folders in your web app, you can use the following EL expression to serve them in your JSF application. Just copy the ResourceBean.java code above, and add an entry to you faces-config.xml for the bean: resource org.richfaces.demo.common.ResourceBean application ]]>