Here is an example portlet.xml to configure a JSF2 portlet:
<portlet-class> javax.portlet.faces.GenericFacesPortlet </portlet-class> <init-param> <name>javax.portlet.faces.defaultViewId.view</name> <value>/welcome.xhtml</value> </init-param> <init-param> <name>javax.portlet.faces.defaultViewId.edit</name> <value>/jsf/edit.xhtml</value> </init-param> <init-param> <name>javax.portlet.faces.defaultViewId.help</name> <value>/jsf/help.xhtml</value> </init-param>
Only the javax.portlet.faces.defaultViewId.view init-param is mandatory. The edit and help init-param's are only required when your portlet requires the Edit and Help portlet modes.
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">
By default the 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>
Different JSF View Declaration Languages require different behavior from the Portlet Bridge when it comes to rendering views. Instructing the Bridge on which policy to use is done using the javax.portlet.faces.RENDER_POLICY context-param in web.xml.
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>
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>
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.
By default Portlet Bridge will add any JSF Resources for your portlet into the <head> section of the portal page the portlet is on, if the portlet container supports marking up the head of a page.
If you don't want any resources from your portlet being added to the <head> section of the portal page, simply add the following context param into web.xml of the portlet:
<context-param> <param-name>org.jboss.portletbridge.markupHead.enabled</param-name> <param-value>false</param-value> </context-param>
There may be occasions where you may want to prevent script tags being added to the <head> of the Portal page that are self-closing, ie. <script ... />.
The Portlet Bridge is now able to alter the default behavior to convert a self-closing script tag to something like <script .... > </script> by inserting a blank comment
into the XML Document for the script element to prevent a self-closing tag. Enabling it requires you to add the following context param into web.xml:
<context-param> <param-name>org.jboss.portletbridge.PREVENT_SELF_CLOSING_SCRIPT_TAG</param-name> <param-value>true</param-value> </context-param>
By default a Portlet Render Response will execute the full Faces Lifecycle before rendering the portlet content to be returned.
It's possible to disable this behavior by specifying the following context param in web.xml:
<context-param> <param-name>org.jboss.portletbridge.VIEW_PARAMETERS_DISABLED</param-name> <param-value>true</param-value> </context-param>
Disabling full execution of the Faces Lifecycle will break the functionality of some components, such as f:viewParam.
By default, the Bridge Request Scope will no longer be retained on completion of a Render Request. This change will bring us more into line with how we feel JSF 2 portlets are developed and intended to be used, such as focusing on Ajax requests and interactions over full page refreshes.
It is possible to return to the behavior of previous Portlet Bridge versions by setting the following initialization parameter in portlet.xml for a specific portlet:
<init-param> <name>org.jboss.portletbridge.BRIDGE_SCOPE_PRESERVED_POST_RENDER</name> <value>true</value> </init-param>
Or by setting it for all portlets present within an archive by setting the following context parameter in web.xml:
<context-param> <param-name>org.jboss.portletbridge.BRIDGE_SCOPE_PRESERVED_POST_RENDER</param-name> <param-value>true</param-value> </context-param>
The Portlet Bridge will no longer store updates to objects in the Bridge Request Scope that occurred during an Ajax request. This means that any JSF Managed Beans, or attributes set on the FacesContext, will no longer be updated after an Ajax request. Any subsequent re rendering of the portlet will show the values of these objects as they were before the Ajax request.
It is possible to revert to the previous behavior, of the data being stored in the Bridge Request Scope after an Ajax request, by setting the following context param in web.xml:
<context-param> <param-name>org.jboss.portletbridge.BRIDGE_SCOPE_ENABLED_ON_AJAX_REQUEST</param-name> <param-value>true</param-value> </context-param>
If the above parameter is set to true, such that data is saved in the Bridge Request Scope after an Ajax request, it is possible to disable the saving of Faces Messages with the following context param in web.xml:
<context-param> <param-name>org.jboss.portletbridge.FACES_MESSAGES_STORED_ON_AJAX_REQUEST</param-name> <param-value>false</param-value> </context-param>
Disabling the saving of Faces Messages after an Ajax request would be beneficial if your portlet has a mix of Ajax and Full Page requests, and you are not concerned with error messages resulting from an Ajax request disappearing if the portlet is refreshed.
To correctly generate portlet URLs when cookies are disabled by a browser, it is necessary to remove the Session ID parameter name from the URL to accurately determine which Faces view a URL should be directed at.
By default it assumes the parameter name is jsessionid, but this can be overridden by setting the following context param in web.xml:
<context-param> <param-name>org.jboss.portletbridge.SESSION_ID_PARAMETER_NAME</param-name> <param-value>mysessionparameter</param-value> </context-param>
By default, the Bridge will shorten the namespace that is added as a prefix to JSF Component Ids. This change will improve both the time that portlets take to be rendered by JSF, as the ids are now shorter, and the amount of data being passed between client and server.
It is possible to return to the behavior of previous Portlet Bridge versions by setting the following initialization parameter in portlet.xml for a specific portlet:
<init-param> <name>org.jboss.portletbridge.COMPONENT_NAMESPACE_SHORTENED</name> <value>false</value> </init-param>
Or by setting it for all portlets present within an archive by setting the following context parameter in web.xml:
<context-param> <param-name>org.jboss.portletbridge.COMPONENT_NAMESPACE_SHORTENED</param-name> <param-value>false</param-value> </context-param>