Creating Faces portlets and projects

Faces portlet projects share common characteristics with standard portlet and Faces projects, although there are some differences that you should be aware of.

Faces portlet projects are created using the New Portlet Project wizard, or the New Portlet Project (JSR 168) wizard, depending on the portlet API that you want to base the project on. A default Faces portlet will be added in the process of creating the project. The wizard automatically generates Faces portlet configuration files, the directory structure that is required, and the necessary updates to the web.xml file.

The following types of resources defined by the Faces portlet APIs will be included in the project:
Resource type Files Target directory Notes
JARs All required Faces JAR files. WEB-INF/lib All Faces runtime JAR files are included in the portlet project WAR file.
Configuration files faces-config.xml WEB-INF Includes the following:
  • The portlet version of FacesContextFactory
  • The variable resolver for portlet API objects
Deployment descriptors
  • web.xml
  • portlet.xml
WEB-INF

The following modifications are made to the standard web.xml file:

  • The servlet com.ibm.faces.webapp.JSResourceServlet is added.
  • servlet and servlet-mapping tags have ID attributes with string values, suffixed with a unique ID to prevent conflicts with other portlets.
The following information is included in portlet.xml:
  • Portlet mode configuration is included.
  • Faces portlet-related config-param values are supplied.
The following sample configuration and deployment descriptor file snippets show representative tagging used within Faces portlet projects:
faces-config.xml
A lifecycle phase listener will be notified at the beginning and ending of processing for each standard phase of the request processing lifecycle. See the PhaseListener javadoc for more info. Also, see the PhaseId javadoc for a description of each phase. The following lifecycle section is added to Faces configuration files:
	<lifecycle>
		<phase-listener>com.ibm.faces.webapp.ValueResourcePhaseListener</phase-listener>
	</lifecycle>
The FactoryFinder API provides information about factories, as well as links to specific factories. The following factory finder section is added to Faces configuration files for an IBM® API portlet:
	<factory>
		<faces-context-factory>com.ibm.faces.context.WPPortletFacesContextFactoryImpl</faces-context-factory>
	</factory>
For a JSR 168 API portlet, the factory is defined as follows:
	<factory>
		<faces-context-factory>com.ibm.faces.context.PortletFacesContextFactoryImpl</faces-context-factory>
	</factory>
VariableResolver sections are also added for each of the API types:
<!-- variable/property resolver registration [IBM portlet API] -->
	<application>
		<variable-resolver>com.ibm.faces.databind.SelectItemsVarResolver</variable-resolver>
		<variable-resolver>
		com.ibm.faces.application.WPPortletVariableResolver</variable-resolver>
		<property-resolver>com.ibm.faces.databind.SelectItemsPropResolver</property-resolver>
	</application>
or
<!-- variable/property resolver registration [JSR 168 portlet API] -->
	<application>
		<variable-resolver>com.ibm.faces.databind.SelectItemsVarResolver</variable-resolver>
		<variable-resolver>
		com.ibm.faces.application.PortletVariableResolver</variable-resolver>
		<property-resolver>com.ibm.faces.databind.SelectItemsPropResolver</property-resolver>
	</application>
web.xml
This shows a sample Faces portlet servlet added to web.xml:
<servlet id="Faces_Unique_Servlet_Name">
		<servlet-name>faces_portlet.FacesPortletPortlet</servlet-name>
		<display-name>faces_portlet.FacesPortletPortlet</display-name>
		<servlet-class>com.ibm.faces.webapp.WPFacesGenericPortlet</servlet-class>
</servlet>
This is an example of servlet-mapping for a Faces portlet servlet.
<servlet-mapping>
      <servlet-name>faces_portlet.FacesPortletPortlet</servlet-name>
      <url-pattern>/faces_portlet.FacesPortletPortlet/*</url-pattern>
</servlet-mapping>
portlet.xml
This is an example of Faces portlet application defined in portlet.xml:
<portlet-app-def>
	<portlet-app uid="faces_portlet.FacesPortletPortlet.A_Unique_ID:1" major-version="1" minor-version="0">
		<portlet-app-name>Faces Portlet application</portlet-app-name>
		<portlet id="faces_portlet.FacesPortletPortlet" href="WEB-INF/web.xml#Servlet_A_Unique_ID:2" major-version="1" minor-version="0">
			<portlet-name>Faces Portlet portlet</portlet-name>
			<cache>
				<expires>0</expires>
				<shared>no</shared>
			</cache>
			<allows>
				<maximized />
				<minimized />
			</allows>
			<supports>
				<markup name="html">
					<view />
					<edit />
				</markup>
			</supports>
		</portlet>
	</portlet-app>
	<concrete-portlet-app uid="faces_portlet.FacesPortletPortlet.A_Unique_ID:3">
		<portlet-app-name>Faces Portlet application</portlet-app-name>
		<concrete-portlet href="#faces_portlet.FacesPortletPortlet">
			<portlet-name>Faces Portlet portlet</portlet-name>
			<default-locale>en</default-locale>
			<language locale="en">
				<title>Faces Portlet portlet</title>
				<title-short></title-short>
				<description></description>
				<keywords></keywords>
			</language>
			<config-param>
				<param-name>com.ibm.faces.portlet.page.view</param-name>
				<param-value>/FacesPortletView.jsp</param-value>
			</config-param>
			<config-param>
				<param-name>com.ibm.faces.portlet.page.edit</param-name>
				<param-value>/FacesPortletEdit.jsp</param-value>
			</config-param>
		</concrete-portlet>
	</concrete-portlet-app>
</portlet-app-def>  
Related concepts
Dynamic data using Faces components
JavaServer Faces portlet applications
Related tasks
Creating Faces portlet projects
Creating Faces portlets
Adding and updating Faces portlet modes for existing IBM portlets
Adding and updating Faces portlet modes for existing JSR 168 portlets
Creating Faces portlet JSP files
Creating Faces applications - overview
Related reference
Faces components reference
Attributes for Faces components
Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.