JBoss.orgCommunity Documentation
Migrating existing projects to RichFaces 4.0.0 (draft)
Copyright ©
Abstract
Read this book to take an existing RichFaces project and upgrade it for use with RichFaces 4. The book covers changes in component usage and behaviors, as well as new framework features which may affect existing RichFaces projects.
- 1. Introduction
- 2. Upgrading
- 3. Changes and new features
- 3.1. JSF 2 integration
- 3.2. Standardized attributes
- 3.3. Performance
- 3.4. Feature changes
- 3.4.1. Server-side process and render mechanisms
- 3.4.2. onbegin event attribute
- 3.4.3. <a4j:commandButton> and <a4j:commandLink>
- 3.4.4. <a4j:log>
- 3.4.5. <rich:message> and <rich:messages>
- 3.4.6. <a4j:outputPanel>
- 3.4.7. <a4j:push> and <a4j:poll>
- 3.4.8. <a4j:status>
- 3.4.9. <rich:popupPanel>
- 3.4.10. <rich:togglePanel>
- 3.5. Consolidated or renamed components
- 3.6. New components and behaviors
- 3.7. Deprecated components and behaviors
- 3.7.1. <a4j:page>
- 3.7.2. <rich:comboBox>
- 3.7.3. <rich:dataList>, <rich:dataDefinitionList>, and <rich:dataOrderedList>
- 3.7.4. <rich:dragSupport> and <rich:dropSupport>
- 3.7.5. <rich:modalPanel>
- 3.7.6. <rich:panelBar> and <rich:panelBarItem>
- 3.7.7. <rich:scrollableDataTable>
- 3.7.8. <rich:simpleTogglePanel>
- 3.7.9. <rich:suggestionBox>
- A. Revision History
RichFaces introduces many improvements and refinements to the RichFaces framework. Migrating your RichFaces projects to version brings several advantages to your applications, including:
complete integration with JavaServer Faces (JSF) 2.0, using new features and standardizing components;
performance improvements throughout the components and core features;
consistency throughout the framework, forming conventions and standards; and
simplification of project creation, build procedures, and application extension.
This book guides you through the process of migrating an existing project to RichFaces , and highlights important changes that have been made to the framework and how they may affect your projects and applications.
Upgrading an existing project to use the RichFaces framework only requires that the new libraries replace the old ones. For a complete installation guide for new projects, refer to the Developer Guide.
Ensure you make a back-up copy of any projects and settings before upgrading an existing RichFaces installation.
Check that the environment you are working in meets the RichFaces technical requirements listed in the Developer Guide.
Download RichFaces packages
If you have not already done so, download the RichFaces binaries from the RichFaces downloads page at http://www.jboss.org/richfaces/download.html.
Install libraries
Copy the following libraries from the RichFaces package to your application's
WEB-INF/liblibraries directory:richfaces-apirichfaces-implcore-ui
Set up Maven
For existing projects, you should already have a Maven installation set up for RichFaces. If not, refer to the Developer Guide for how to set up Maven.
Namespace and taglib declaration
The namespace and library inclusions are the same as those for previous versions of RichFaces.
The RichFaces namespaces need to be declared in the project's XHTML pages.
<ui:composition xmlns:a4j="http://richfaces.org/a4j" xmlns:rich="http://richfaces.org/rich"> ... </ui:composition>Note
With RichFaces , it is no longer necessary to modify the
web.xmlandfaces-config.xmlfiles of a project to use the framework.
- 3.1. JSF 2 integration
- 3.2. Standardized attributes
- 3.3. Performance
- 3.4. Feature changes
- 3.4.1. Server-side process and render mechanisms
- 3.4.2. onbegin event attribute
- 3.4.3. <a4j:commandButton> and <a4j:commandLink>
- 3.4.4. <a4j:log>
- 3.4.5. <rich:message> and <rich:messages>
- 3.4.6. <a4j:outputPanel>
- 3.4.7. <a4j:push> and <a4j:poll>
- 3.4.8. <a4j:status>
- 3.4.9. <rich:popupPanel>
- 3.4.10. <rich:togglePanel>
- 3.5. Consolidated or renamed components
- 3.6. New components and behaviors
- 3.7. Deprecated components and behaviors
- 3.7.1. <a4j:page>
- 3.7.2. <rich:comboBox>
- 3.7.3. <rich:dataList>, <rich:dataDefinitionList>, and <rich:dataOrderedList>
- 3.7.4. <rich:dragSupport> and <rich:dropSupport>
- 3.7.5. <rich:modalPanel>
- 3.7.6. <rich:panelBar> and <rich:panelBarItem>
- 3.7.7. <rich:scrollableDataTable>
- 3.7.8. <rich:simpleTogglePanel>
- 3.7.9. <rich:suggestionBox>
There have been several changes made to the RichFaces framework for version 4 that may affect migrated projects.
RichFaces 4 has full support for JavaServer Faces (JSF) 2. Due to limited support for JavaServer Pages (JSP) in JSF2, RichFaces no longer fully supports JSP either.
Several component and event attribute names have been changed from those used in previous versions of RichFaces. The names have been changed to be more consistent with attribute names used by JavaServer Faces 2, so as to provide standardized usage. Many of the name changes also provide more consistency and cleanliness within the framework itself. Other attributes have been deprecated in favor of consistent functionality.
processChanged to
executein 4.- Affected
a4jcomponents <a4j:support><a4j:form><a4j:push><a4j:commandButton><a4j:jsFunction><a4j:commandLink><a4j:poll>- Affected
richcomponents <rich:autocomplete><rich:menuItem><rich:toggleControl><rich:calendar><rich:panelMenuGroup><rich:togglePanel><rich:dataFilterSlider><rich:panelMenuItem><rich:togglePanelItem><rich:dataScroller><rich:progressBar><rich:tree><rich:dropSupport><rich:tab><rich:treeNode>
- Affected
reRenderChanged to
renderin 4.- Affected
a4jcomponents <a4j:support><a4j:form><a4j:push><a4j:commandButton><a4j:jsFunction><a4j:commandLink><a4j:poll>- Affected
richcomponents <rich:autocomplete><rich:dragSupport><rich:progressBar><rich:ajaxValidator><rich:dropSupport><rich:tab><rich:calendar><rich:extendedDataTable><rich:togglePanel><rich:dataFilterSlider><rich:menuItem><rich:tree><rich:dataScroller><rich:panelMenuGroup><rich:treeNode><rich:dataTable><rich:panelMenuItem>
- Affected
eventsQueueChanged to
queuein 4.- Affected
a4jcomponents <a4j:support><a4j:form><a4j:push><a4j:commandButton><a4j:jsFunction><a4j:commandLink><a4j:poll>- Affected
richcomponents <rich:ajaxValidator><rich:dropSupport><rich:toggleControl><rich:autocomplete><rich:menuItem><rich:togglePanel><rich:calendar><rich:panelMenuGroup><rich:togglePanelItem><rich:dataFilterSlider><rich:panelMenuItem><rich:tree><rich:dataScroller><rich:progressBar><rich:dragSupport><rich:tab>
- Affected
limitToListChanged to
limitRenderin 4.- Affected
a4jcomponents <a4j:support><a4j:form><a4j:push><a4j:commandButton><a4j:jsFunction><a4j:commandLink><a4j:poll>- Affected
richcomponents <rich:ajaxValidator><rich:dropSupport><rich:toggleControl><rich:autocomplete><rich:menuItem><rich:togglePanel><rich:calendar><rich:panelMenuGroup><rich:togglePanelItem><rich:dataFilterSlider><rich:panelMenuItem><rich:tree><rich:dataScroller><rich:progressBar><rich:treeNode><rich:dragSupport><rich:tab>
- Affected
onbeforedomupdateChanged to
onsuccessin 4.- Affected
a4jcomponents All components.
- Affected
richcomponents All components.
- Affected
ignoreDupResponsesDeprecated. Functionality moved to
queuein 4.- Affected
a4jcomponents <a4j:support><a4j:form><a4j:push><a4j:commandButton><a4j:jsFunction><a4j:queue><a4j:commandLink><a4j:poll>- Affected
richcomponents <rich:ajaxValidator><rich:dropSupport><rich:toggleControl><rich:autocomplete><rich:menuItem><rich:togglePanel><rich:calendar><rich:panelMenuGroup><rich:togglePanelItem><rich:dataFilterSlider><rich:panelMenuItem><rich:tree><rich:dataScroller><rich:progressBar><rich:treeNode><rich:dragSupport><rich:tab>
- Affected
requestDelayDeprecated. Functionality moved to
queuein 4.- Affected
a4jcomponents <a4j:support><a4j:commandLink><a4j:jsFunction><a4j:commandButton><a4j:form><a4j:queue>- Affected
richcomponents <rich:ajaxValidator><rich:dragSupport><rich:togglePanel><rich:autocomplete><rich:dropSupport><rich:tab><rich:calendar><rich:menuItem><rich:tree><rich:dataFilterSlider><rich:panelMenuGroup><rich:dataScroller><rich:panelMenuItem>
- Affected
ajaxSingleDeprecated. Use
execute="@this"in 4 instead.- Affected
a4jcomponents <a4j:support><a4j:form><a4j:push><a4j:commandButton><a4j:jsFunction><a4j:commandLink><a4j:poll>- Affected
richcomponents <rich:calendar><rich:panelMenuGroup><rich:togglePanel><rich:dataFilterSlider><rich:panelMenuItem><rich:togglePanelItem><rich:dataScroller><rich:progressBar><rich:toolTip><rich:dropSupport><rich:suggestionBox><rich:tree><rich:fileUpload><rich:tab><rich:treeNode><rich:menuItem><rich:toggleControl>
- Affected
The RichFaces framework has been extensively refined to provide better performance for applications. This includes improvements to bandwidth requirements for generated markup, size and number of required resources for Javascript and Cascading Style Sheets (CSS), and other general performance improvements.
Several considerations have been made to improve the use of bandwidth when generating markup.
XHTML markup has been simplified and streamlined using best practices, such as avoiding tables for layout.
Default attribute values are not rendered.
Javascript use has been simplified with shorter function names and only one proxy call per form.
The three Javascript libraries previously used by the RichFaces framework have been consolidated and standardized into a single library for better performance.
Usage of Cascading Style Sheets (CSS) has been simplified, trimming out duplicate or otherwise unnecessary entries and better utilizing the cascading approach for style values.
Features have been altered or added to existing components and behaviors in the RichFaces 4 framework. Refer to the Developer Guide for full details on how to make use of any new features.
Some of the mechanisms for server-side processing and rendering have been altered.
It is now possible to define zones for processing on the server-side without specifying execute definitions for every component. The execute="@region" property can be used to process regions defined on the server side.
Important
This approach is different to that in JSF 2, which uses default values of execute="@this" and render="@this" if no other value is defined.
The execute property has been extended to include the @region keyword, which facilitates the region rendering changes described in Section 3.4.1.1, “Regions”.
The onbegin attribute has been added to support JSF events with the type begin.
Both the <a4j:commandButton> and <a4j:commandLink> components use the onclick event attribute instead of the onbegin attribute.
The <a4j:log> component has had several features modified.
It is now possible to switch levels on the client side.
The log can now be displayed inline with page markup, in a new browser window, or in the browser console.
An application context parameter can now be defined to log all application pages.
Both the <rich:message> and <rich:messages> components can be automatically updated by any Ajax request, except those requests with limitRender = true. Attributes from previously-passed states are now cleared.
The <a4j:outputPanel> component has had several features modified.
The default value for the
layoutattribute is nowblock.The default value for the
ajaxRenderedattribute is nowfalse.If a child component is not to be rendered, a placeholder element will be included to preserve the layout.
Both the <a4j:push> and <a4j:poll> components now raise a client-side event. For <a4j:push>, this is the ondataavailable event, while for <a4j:poll> it is the ontimeevent.
The <a4j:status> component has had several features modified.
The
<a4j:status>component now has a representation in the Document Object Model (DOM) tree.The
<a4j:status>component no longer needs to be associated with a<a4j:region>.The
<a4j:status>component can now report request errors. An additionalerrorTextattribute anderrorfacet have been added to show if an error was raised when a request completed.The event attributes now include
onstart,onstop,onerror, andonsuccess.Multiple statuses can be presented for the same view or form, or a separate status attached to each component.
The <rich:popupPanel> component replaces the old <rich:modalPanel>. It allows the pop-up window to be presented as either a modal or non-modal window.
Several new components and behaviors have been added to RichFaces 4, some of which replace the functionality of deprecated elements. For full details on how to use these new components and behaviors, refer to the Component Reference.
The <rich:autocomplete> component replaces the old <rich:suggestionBox> component.
The <rich:accordion> component replaces the old <rich:panelBar> component. The <rich:accordionItem> component replaces the old <rich:panelBarItem> component.
The <rich:collapsiblePanel> component replaces the old <rich:simpleTogglePanel> component.
The <rich:dragBehavior> behavior replaces the old <rich:dragSupport> component. The <rich:dropBehavior> behavior replaces the old <rich:dropSupport> component.
The <rich:extendedDataTable> component now includes the functionality of the old <rich:scrollableDataTable> component.
The <rich:list> component now combines the functionality of the old <rich:dataList>, <rich:dataDefinitionList>, and <rich:dataOrderedList> components.
List styles
Previously, the bullet styles for the <rich:dataList> component and the numeration styles for the <rich:dataOrderedList> component were specified with the type attribute. The type attribute for the <rich:list> component is now used to specify the type of list, and the bullet and numeration styles are now handled in CSS. Refer to the <rich:list> component section in the RichFaces Component Reference for details.
The <rich:popupPanel> component replaces the old <rich:modalPanel> component.
Several new components and behaviors have been added to RichFaces 4, some of which replace the functionality of deprecated elements. For full details on how to use these new components and behaviors, refer to the Developer Guide.
The <rich:busyBehavior> component is used when heavy processing takes place to provide feedback to the user. It can be attached to a component's events to trigger appropriate messages.
The <rich:togglePanel> component now manages multiple <rich:togglePanelItem> components instead of using facets for the switchable panels. Refer to Section 3.5.9, “<rich:togglePanel> and <rich:togglePanelItem>” and the components' descriptions in the Component Reference for further details.
Some components and behaviors have been deprecated in RichFaces 4. For the most part these items have their functionality replicated by another component or behavior. Refer to Section 3.5, “Consolidated or renamed components” for further details on consolidated functionality.
RichFaces 4 drops support for the <a4j:page> component. The component was previously used for solving incompatibility in the JavaServer Pages (JSP) environment with Apache MyFaces in early Ajax4jsf versions.
The functionality of the old <rich:comboBox> component is now available through the <rich:select> component.
The functionality of the old <rich:dataList>, <rich:dataDefinitionList>, and <rich:dataOrderedList> components is now available through the <rich:list> component.
The functionality of the old <rich:dragSupport> component is now available through the <rich:dragBehavior> behavior. The functionality of the old <rich:dropSupport> component is now available through the <rich:dropBehavior> behavior.
The functionality of the old <rich:modalPanel> component is now available through the <rich:popupPanel> component.
The functionality of the old <rich:panelBar> component is now available through the <rich:accordion> component. The functionality of the old <rich:panelBarItem> component is now available through the <rich:accordionItem> component.
The functionality of the old <rich:scrollableDataTable> component is now available through the <rich:extendedDataTable> component.
The functionality of the old <rich:simpleTogglePanel> component is now available through the <rich:collapsiblePanel> component.