View Source

h1. ICEfaces 3.0 Release Notes

*_February 3rd, 2012_*


h2. Contents

* [About This Release|#about]
* [Downloads|#downloads]
* [What's New in 3.0|#notablechanges]
** [ACE Components|#acechanges]
** [ICE Components|#icechanges]
** [Core Framework|#frameworkchanges]
** [ICEpush|#icepushchanges]
** [Samples & Tutorials|#samplechanges]
** [JSF Support|#jsfchanges]
** [Documentation|#docchanges]
** [IDE Integrations|#idechanges]
* [Migration Guide|#migrationguide]
* [Supported Platforms|#supportedplatforms]
* [Known Issues|#knownissues]
* [Support|#support]

h2. 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 3 is licensed under the [Apache License, Version 2.0|]. Previous ICEfaces releases were licensed under the [Mozilla Public License (MPL) 1.1|].

h2. Downloads
ICEfaces is available for download in the following formats:

* Binary and source-code [bundles|]
* IDE Tool [integration bundles|,NetBeans]
* [Maven Repository|] (jars only)

h2. What's New in 3.0?

h4. [ACE Components]

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!

*All-new ace:dataTable*
* 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.
* Data-filtering.
* 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.

*New Components:*
* ace:accordion, ace:accordionPane
* ace:confirmationDialog
* 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:dialog
* ace:draggable, ace:droppable, ace:resizable
* ace:maskedEntry
* ace:notificationPanel
* ace:panel
* ace:printer
* ace:progressBar
* ace:tooltip

*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|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.
* Most components can now emit client-events which can optionally be handled via the {{ace:ajax}} tag to be routed to a client-side JavaScript event handlers.

*ThemeRoller Support*
* 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|ACE ThemeRoller Support] ready for use.

*mandatoryResource Change*
* 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 ACE Components resource files (JavaScript and CSS files) have been optimized to minimize the number and size of the resource files that are required to be loaded by the browser. This includes both combining individual ACE component resources together into fewer files, and minification of the content of those files to reduce files sizes.

*ACE Repackaging*
* 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.
* JavaScript functions formerly namespaced under the "{{ice.component}}" name-space are now under the "{{ice.ace}}" name-space.

h4. [ICE Components]

* ice:dataExporter
** 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.

* ice:gMap
** The Google Maps Javascript libraries required by the ice:gmap component are no longer automatically preloaded with every initial page render. Instead, the [mandatoryResourceConfiguration] may be used to specify if the ice:gmap resources should be preloaded on the page. This provides increased efficiency to page loading in cases where the ice:inputRichText is not used on a page.

* ice:inputRichText
** The CKeditor Javascript libraries required by the ice:inputRichText component are no longer automatically preloaded with every initial page render. Instead, the [mandatoryResourceConfiguration] may be used to specify if the ice:inputRichText resources should be preloaded on the page. This provides increased efficiency to page loading in cases where the ice:inputRichText is not used on a page.

* ice:panelGroup
** Improved support for auto-scrolling when dragging an ice:panelGroup inside a scrollable <DIV>.

* ice:selectInputText
** Added "partialSubmit" attribute to the ice:selectInputText component.

* ice:menuPopup
** 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.

* ice:panelPositioned
** A new "beforeChangeListener" attribute has been added to support the ability to cancel a drop event, thus preventing the item from being re-positioned.

* ice:panelTooltip
** 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.

h4. Core Framework

* Delta Submit Improvements
** The [Delta Submit|deltaSubmit] implementation has been refactored to improve efficiency and robustness.

* New @AllWindowsClosed Annotation
** A new [@AllWindowsClosed|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|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|messagePersistence] 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.
*** Example: {code}<icecore:config mandatoryResource="tabSet tabPane fileEntry"/>{code}
** 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.

* Optimizations
** Several aspects of the core framework have been optimized to reduce execution time and/or Java heap consumption.

h4. ICEpush

* New <icecore:push group="chat"> Tag
** A new {{<icecore:push group="">}} [tag|push] 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.

h4. 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.

h4. JSF Support

* 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.

h4. Documentation

* 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.

h4. IDE Integrations

* 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.

{tip:title=Change Log}For a complete list of all changes in this release, see the related JIRA [Change Log|].{tip}

h2. Migration Guide

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.

* [ICEfaces 2 to ICEfaces 3 Migration Guide]

h2. Supported Platforms

This release has been tested on the following:

h4. JSF Runtimes
* Mojarra JSF 2.1.3, 2.1.4
* Apache MyFaces JSF 2.1.5

h4. Browsers
* Google Chrome 15
* Mozilla Firefox 3.6, 10
* Microsoft IE 8, IE 9
* Apple Safari 5

h4. Application Servers
* Tomcat 6, 7
* Glassfish 3.1
* JBoss 6, 7

h4. Portal Containers
* PortletFaces Bridge 2.0.2
* Liferay Portal 5.5, 6

h2. Known Issues

The following section describes the most commonly encountered known issues with this release:

h4. General

* 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.
* Applications must avoid the use of "javascript: void(0)" in browser DOM event handlers as this technique causes the "onBeforeOnload" event handler to be called in IE, which results in the ICEfaces bridges shutting down (thinking that the page is being navigated away from).

h4. ICEpush
* 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.

h4. MyFaces JSF

* 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.

h4. Mojarra JSF

* 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.

h4. Browsers

* 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:
{code}<f:view contentType="text/html">{code}
** See for more information.

h4. Application Servers

* 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 [|] 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: {code:xml}<Context antiJarLocking="true" antiResourceLocking="true"/>{code}

* 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.

h4. Portal Containers

* 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.

h2. Support

Open source community support is available at

The [ICEfaces Community Forums|] are available for questions, comments, or general discussions regarding ICEfaces.