Table of Contents
ICEfaces 3.0 Release Notes
February 3rd, 2012
About This Release
ICEfaces 3.0 is an official ICEfaces major release, featuring over 40 new and improved ACE Components, new support for MyFaces JSF, and over 400 other enhancements, improvements, and bug fixes.
ICEfaces is available for download in the following formats:
What's New in 3.0?
The ACE Components now include over 40 components, including an industry-leading new ace:dataTable, support for jQueryUI ThemeRoller themes, and a flexible new ace:ajax tag and client-event support!
- Integrated pagination, scrolling, and lazy-data-loading.
- Column re-ordering via drag-and-drop.
- Single and multi-row and cell selection.
- Single and multi-column sorting.
- Expandable rows and panels, column stacking, and n-level dataTable nesting.
- Find API for locating and navigating to matching data.
- Configuration panel for user-specified column visibility, ordering, and sort-criteria.
- Optimized rendering and data-transport for efficiently viewing large data-sets.
- ace:accordion, ace:accordionPane
- ace:contextMenu, ace:menu, ace:menuBar, ace:menuButton, ace:menuItem, ace:submenu
- ace:dataExporter, ace:excludeFromExport
- ace:dataTable, ace:cellEditor, ace:column, ace:columnGroup, ace:expansionToggler, ace:panelExpansion, ace:row, ace:rowEditor, ace:rowExpansion, ace:tableConfigPanel
- ace:draggable, ace:droppable, ace:resizable
Updated & Enhanced Components:
- ace:animation - re-implemented to use jQuery effects.
- ace:checkboxButton, ace:linkButton, ace:pushButton, ace:fileEntry, ace:tabSet
- Now support ThemeRoller themes.
- ace:pushButton - now supports wrapping arbitrary markup.
- ace:dateTimeEntry - now based on the jQuery calendar and has the following additional enhancements:
- Supports ThemeRoller themes.
- Optionally display multiple-months in popup calendar.
- Initialize multi-month popup calendar to display Last/This/Next, This/Next/TheOneAfterThat, or any starting month desired.
- Optionally display Year / Month drop-down menus in popup calendar.
- Optionally include a "Today" button to navigate to the current date.
- ace:sliderEntry - re-implemented using the jQuery slider control.
- ace:tabPane - new "cache" attribute to support advanced client-caching behavior flexibility.
- A new ace:ajax tag has been added for use in conjunction with the ACE components to configure the ajax-submit, execution, and rendering behaviour for the new client-events emitted by each component.
- All ACE components now support the jQueryUI ThemeRoller theming system.
- The ThemeRoller system provides an extensive collection of ready-to-use themes, as well as an intuitive web-application for creating custom themes easily without requiring extensive CSS knowledge.
- The ThemeRoller-based CSS styles are injected into the ICEfaces page automatically.
- The release bundle includes over 25 pre-defined themes ready for use.
- The default value for the "org.icefaces.mandatoryResourceConfiguration" configuration parameter has been changed to "none", which results in no component resources being pre-loaded. As a result, overall resource loading efficiency is greatly improved, but there is a risk that certain required resources for components that are dynamically added to the page after the initial page load will not be available, resulting in a component failure.
- See the mandatoryResourceConfiguration Wiki topic for details on using mandatoryResource configuration techniques.
- Optimized Resource Loading
- The entire Advanced Component Environment and all ACE Components have been repackaged to better isolate the ACE library from other ICEfaces framework libraries.
- Java code formerly located under the "org.icefaces.component" and "org.icefaces.generator" packages is now located under the "org.icefaces.ace" package.
- The ice:dataExporter component has been re-implemented to resolve the following issues:
- Now possible to reset the dataExporter after an export to ensure that the current dataTable data will be used upon subsequent exports.
- No longer requires multiple clicks from the user to proceed with a download in none-IE browsers.
- No longer creates an empty export file in the constructor of the base OutputTypeHandler which avoids the possibilty of collecting numerous empty files during the user-session.
- The ice:dataExporter now uses converters when exporting data.
- Improved support for auto-scrolling when dragging an ice:panelGroup inside a scrollable <DIV>.
- Added "partialSubmit" attribute to the ice:selectInputText component.
- A new "blockMenuOnInput" attribute has been added that can be used to prevent the popup menu from being triggered when the context-menu button is clicked over an input component.
- A new "beforeChangeListener" attribute has been added to support the ability to cancel a drop event, thus preventing the item from being re-positioned.
- Improved auto-positioning when used in scrollable containers.
- Added "escape" attribute to ice:message and ice:messages.
- Added "tabIndex" attribute to ice:dataPaginator, ice:rowSelector/ice:dataTable, and ice:panelCollapsible.
- Delta Submit Improvements
- The Delta Submit implementation has been refactored to improve efficiency and robustness.
- New @AllWindowsClosed Annotation
- A new @AllWindowsClosed method annotation has been added that can be used by session-scoped beans that need to be notified when all browser windows for that session are closed. This is useful in cases where the application wants to actively cleanup a user-session upon window close.
- Window Scope
- Support for @PostConstruct and @PreDestroy annotations has been added to the ICEfaces custom Window scope.
- New messagePersistence Configuration
- A new configuration parameter and icecore:config attribute have been added to support configuration of ICEfaces "intelligent message caching" feature. See the Message Persistence Wiki topic for details.
- Custom Update Support
- The ICEfaces Direct-to-DOM rendering engine has been enhanced to support partial component tree rendering that may consist of regular DOM-diffed regions combined with new sub-component custom update regions that are excluded from DOM differencing. This feature enables richer ACE component interactions and efficiencies for specific use-cases.
- mandatoryResource Configuration
- It is now possible to configure the mandatoryResourceConfiguration by specifying the ACE or ICE component tag name.
<icecore:config mandatoryResource="tabSet tabPane fileEntry"/>
- Configuration is also still supported via the fully-qualified component class-name, as in previous releases, but the new tag-name based approach is far simplier to use for most developers.
- The new keyword "all" can be used with the mandatoryResourceConfiguration context-parameter. Specifying mandatoryResource="all" indicates that all available (on the classpath) component resources should be preloaded during the initial page load.
- The mandatoryResource loading system has been improved to prevent possible multiple load requests for the same resource on the same page, and to improve resource caching behavior by marking each resource URL with a unique identifier that lasts the life of the application scope, thus negating the need to check if the resource has changed on the server.
- Several aspects of the core framework have been optimized to reduce execution time and/or Java heap consumption.
- New <icecore:push group="chat"> Tag
- A new <icecore:push group=""> tag has been added to make push group registration easier.
- Multiple occurrences of this component within a view can be used to add the current view to different groups.
- Automated ICEpush Setup/Teardown
- By default, ICEpush will now automatically setup and teardown it's blocking connection on a per-page basis, depending on whether or not any ICEPush groups are active on the page.
- Previously, ICEpush was lazily initialized, but not actively torn down if a once active push group became inactive on the page.
- New lazyPush Configurability
- A new configuration parameter has been added to disable the automated lazy initialization and teardown of ICEpush, forcing ICEpush to keep its blocking connection active at all times. See the lazyPush Wiki topic for details.
Samples & Tutorials
- New ICEfaces Showcase Sample Application
- Features extensive component demonstrations for the ACE Components and ICE Components.
- Includes source-code viewing in the application, and direct linking from each demo to related component documentation.
- A portlet version of the showcase sample is also provided.
- Replaces the "ace-showcase" and "compat/component-showcase" sample applications from ICEfaces 2.0.
- For more information see the Samples & Tutorials Wiki topic.
- Oracle Mojarra JSF
- This release has been tested with Mojarra JSF 2.1.3 and 2.1.4, and includes the JSF 2.1.4 library in the download bundles.
- Note that as of Mojarra JSF 2.1.4 the Mojarra libraries require a Servlet 3.0 spec. server to run on. For older servers use Mojarra JSF 2.1.3, or MyFaces JSF.
- Apache MyFaces JSF
- This release adds support for ICEfaces on Apache MyFaces JSF (2.1.5+).
- The MyFaces JSF library included with this release is a specially patched version of the MyFaces JSF 2.1.5 release, called "JSF 2.1.5-ice-7517.jar". The patch increases the maxiumum URL length from the MyFaces standard 256 characters to 1024 characters. This was necessary to prevent resource loading issues when using MyFaces in portal containers. This patch will be included in the forthcoming MyFaces JSF 2.1.6 release official release. You may also use the official MyFaces JSF 2.1.5 libraries if you are not deploying into a portlet environment.
- ICEfaces Wiki
- The ICEfaces Wiki documentation has been significantly overhauled for this release.
- Each ACE component now has a topic of its own which contains everything needed to use the component, as well as find other resources that demonstrate the component, etc.
- The Core Configuration topic has been refactored such that each configuration has a topic page of its own, providing more details and a standard structure for each topic, as well as improving searchability indexing of the configuration items.
- NetBeans 7.0, 7.1
- This release provides an updated IDE integrations for NetBeans 7.0, and 7.1
- Note: It is critical that users update their NetBeans 7 installation with the latest module versions prior to installing the ICEfaces NetBeans integration. See the NetBeans Integration Release Notes for details.
- Eclipse 3.6, 3.7
- This release provides an updated IDE integration for Eclipse 3.6/3.7.
- Features improved design-time renderers for the ACE Components.
For a complete list of all changes in this release, see the related JIRA Change Log.
An ICEfaces 2 to ICEfaces 3 Migration Guide is available for those wishing to migrate their existing ICEaces 2.x applications to ICEfaces 3.0.
This release has been tested on the following:
- Mojarra JSF 2.1.3, 2.1.4
- Apache MyFaces JSF 2.1.5
- Google Chrome 15
- Mozilla Firefox 3.6, 10
- Microsoft IE 8, IE 9
- Apple Safari 5
- Tomcat 6, 7
- Glassfish 3.1
- JBoss 6, 7
- PortletFaces Bridge 2.0.2
- Liferay Portal 5.5, 6
The following section describes the most commonly encountered known issues with this release:
- JSPs are not supported by ICEfaces 3 - use Facelets.
- It is required to specify "h:head" and "h:body" tags in your ICEfaces application pages.
- ICEpush (icepush.jar) asynchronous update support is limited to a single ICEfaces application per host-name/server.
- Viewing multiple ICEfaces applications in the same browser from the same host server concurrently will result in only one of the applications having functional push capabilities.
- Support for pushing asynchronous updates to multiple ICEfaces applications from the same server/host-name requires the use of the Enterprise Push Server (EPS), which is included in ICEfaces EE (Enterprise Edition).
- This is necessary because the browser cannot support multiple concurrent push connections, so all push traffic must be multiplexed at a single point on the server.
- URL Length Limit
- MyFaces 2.1.5 enforces a maximum URL length limit of 256 characters. This limit causes problems with some ACE resource URLs when used inside a portlet environment.
- To work-around this issue, this release includes a patched MyFaces 2.1.5 library that extends the length limit to 1024 characters.
- It is anticipated that this issue will be resolved in the upcoming MyFaces JSF 2.1.6 official release.
- This release includes the Mojarra JSF 2.1.4 runtime libraries.
- Mojarra 2.1.4 introduces a hard depedency on Servlet 3.0 APIs, as a result, it cannot be used on older JEE5 application servers. Mojarra 2.1.3, or Apache MyFaces 2.1.6 should be used in on older JEE5 servers instead.
- Note that the Mojarra JSF 2.1.0-2.1.2 releases have several serious issues that may impact your project:
- A bug that prevents it from supporting bean-annotation on non-Glassfish 3.1 application servers and servlet containers.
- Several bugs that prevent the IE9 browser from working properly with JSF-ajax operations.
- Partial State Saving bugs that might prevent the use of Partial State Saving in your application.
- This release of ICEfaces includes the Mojarra JSF 2.1.4 release libraries which resolves the known issues noted above.
- When running a JSF application in JSF2 PROJECT_STAGE="Development" mode (which is the default setting for all ICEfaces sample applications), you may see the follow warning appear at the bottom of the page: "Form component needs to have a UIForm in its ancestry.".
- This issue is caused by a bug in Mojarra JSF, a suggested work-around is to set the JSF2 PROJECT_STAGE="Production" in the web.xml file.
- WebKit (Safari and Chrome)
- The WebKit-based browsers (Google Chrome and Apple Safari) request content-type "application/xhtml+xml" by default, which is different from virtually all other browsers. In cases where the application page doesn't set the contentType explicitly this can result in these browsers defaulting to a strict XHTML rendering mode, which can cause some unexpected styling and layout issues. In order to have WebKit-based browsers render markup consistently with other browsers, you must specify the content-type in the view tag on each page:
- See http://jira.icefaces.org/browse/ICE-6138 for more information.
- Tomcat 6.0
- In some cases, when running Tomcat on Windows, undeploying an ICEfaces compatible application (i.e. that includes the icefaces-compat.jar) can cause an exception. See http://jira.icefaces.org/browse/ICE-5222 for additional information about this issue. To prevent this, include a context.xml file with your application that includes the following Context attributes to prevent jar and resource locking:
<Context antiJarLocking="true" antiResourceLocking="true"/>
- Glassfish 3 / JBoss 6, 7 (JEE 6 Platforms)
- It is recommended to have Mojarra JSF 2.1.4 installed. This may require updating the JSF Mojarra runtime libraries in Glassfish 3 or JBoss 6/7, depending on which JSF version is currently installed.
- Liferay 5
- Using the ACE Components with Liferay 5 results in a jQuery library conflict that will disable the Liferay portal interface elements. Thus, using ACE Components with Liferay 5 is not recommended in this release.
- There is no issue using the ICE Components with Liferay 5.
- Liferay 6 is fully supported.
Open source community support is available at http://www.icesoft.org.
The ICEfaces Community Forums are available for questions, comments, or general discussions regarding ICEfaces.