ICEfaces 3.1.0 Release Notes

Table of Contents

ICEfaces 3.1 Release Notes

July 24th, 2012


About This Release

ICEfaces 3.1 is an official ICEfaces feature release, featuring 9 new ACE components, 4 new core components/tags, and over 220 issues resolved.


ICEfaces is available for download in the following formats:

What's New in 3.1?

ACE Components

New Components:

  • ace:autoCompleteEntry
    • Ability to display simple and compound content in the popup list (simple value string list or JSF facet content for each row).
    • Built-in and lazy-loaded suggestion list filtering.
    • Configurable filter case-sensitivity and match criteria (startsWith (default), endsWith, or match anywhere)
    • Features integrated label rendering (incl. Inplace/InField labels), and required/optional indicators and styling.
  • ace:chart
    • Provides interactive client-rendered dynamic charts without browser plugins
    • HTML5-based client rendering engine from jqPlot, w/ legacy support for IE 7+
    • Supported chart types: Line, Bar, Pie, Donut, OHLC, and Candlestick
    • Support for stacked and merged charts
    • Configurable axis and legends, including support for up to 2 X, and 9 Y-axes
    • Supports autoscale, animated plotting, and dynamic zooming
    • Cursor display, hover highlighting, and cursor tooltips (fully configurable)
    • Support for click, dragStart/dragStop, mouseIn/mouseOut, and showHighlighter/hideHighlighter client events.
  • ace:list
    • Populate via simple Strings or containers with arbitrary components for each list item.
    • Provides ordering/re-ordering via drag & drop
    • Supports single, multiple, and "none" selection modes.
  • ace:listControl
    • Provides column-item-ordering, dual-column list, or n-column list control-panels to one or more ace:list component.
  • ace:menuSeparator
    • Visually groups menuItems into logical sets.
  • ace:multiColumnMenu
    • Adds "mega-menu" style submenus to ace:menuBar and ace:contextMenu.
    • Supports defining multiple columns of menu items to be displayed in a menu "panel".
    • Optionally supports autoflow - creates multiple cols from a single large list of menuItems.
  • ace:richTextEntry
    • Leverages the industry-leading CKEditor rich text library.
    • Configurable toolbars (Basic, Advanced, Custom)
  • New Text Entry Component Features
    • Integrated label rendering, including Inplace/InField labels and left/right/top/bottom label positions.
    • Integrated required/optional label indicators and positioning (ex. render a "*" or "(Required)" string next to the component or component label).
    • Required/optional CSS style classes for style-based required or optional status indication (ex. change background colour for required input components).
    • Built-in support for Theme-Roller based style classes for components in Error/Invalid validation status (ex. highlight invalid components with red borders).
    • Supported by the ace:autoCompleteEntry, ace:dateTimeEntry, ace:maskedEntry, ace:textEntry, and ace:textAreaEntry components.
  • ace:textAreaEntry
    • Optionally user-resizable when running in HTML5 capable browsers.
    • Features integrated label rendering (incl. Inplace/InField labels), and required/optional indicators and styling.
  • ace:textEntry
    • AutoTab support - automatically tabs to the next component once the maxLength number of characters have been entered.
    • Features integrated label rendering (incl. Inplace/InField labels), and required/optional indicators and styling.

Updated and Enhanced Components:

  • 3rd Party JavaScript Libraries
    • Updated jQuery to v1.7.1, jQuery UI to v1.8.18, and Wijmo to v2.0.5
    • Optimized key-event listeners based on new jQuery 1.7 techniques for improved performance on older/slower browsers.
  • ace:notificationPanel
    • New "visible" attribute
    • New "onDisplay" event listener
  • ace:tooltip
    • Added capability to interact with the contents of the tooltip (tooltip will not close while mouse is hovered over it).
  • ace:dataTable
    • New "staticHeaders=true(default)/false" attribute to control whether or not the dataTable header should scroll with the data region, or remain static at the top and always visible when "scrollable=true".
    • New "toggleOnInvalidEdit=true/false(default)" property to control whether or not the rowEditor will be forced out of edit mode following an edit that fails due to validation failure.
    • New support for selecting a range of rows via shift(key)-click.
    • Added support for setting "maxHeight" on scrollable dataTable (to keep footer nested below last row)
    • Now indents the expansion toggle control in nested row expansion scenarios.
    • Added support for displaying unique styling for cases where row selector is hovered over a selected row
    • Now maintains the scrollable dataTable scrollbar position after an ajax-update occurs within the dataTable.
    • Improvements to column alignment accuracy when "scrollable=true".
    • Due to a large number of complex incompatibilities with core ace:dataTable features, the "liveScroll" attribute has been deprecated in this release and is not supported. This property will be removed in a future release.
  • ace:dateTimeEntry
    • New "size" attribute - optionally specify the number of characters to display when determining the width of the input field. Default is the maximum possible size of a date formatted by the date pattern.
    • New "tabindex" attribute.
    • Now features integrated label rendering (incl. Inplace/InField labels), and required/optional indicators and styling.
  • ace:maskedEntry
    • Now features integrated label rendering (incl. Inplace/InField labels), and required/optional indicators and styling.
  • ace:menuItem, ace:multiColMenu, ace:submenu
    • New 'disabled' attribute - when "disabled=true" menu components appear greyed out and are cannot be selected/actioned upon.
  • ace:tooltip
    • New "forContainer" attribute - specifies the id of the component that contains the component referenced by the "for" attribute. This is to be used in cases where the target component is inside an iterative container such as a data table and the tooltip component itself is outside.
  • Optimized animation effects
    • To improve application responsiveness the "slide" and "fade" animation effects now complete in a single animation step when running on IE7 / 8. These older browsers are unable to process dynamic layout changes effectively when DOM sizes are anything but trivial in size.
    • This change applies to the ace:animation and ace:dateTimeEntry components.
  • Improved TLD Documentation
    • The TLD documentation has been improved to provide the specific event and listener types that that application can use with the client behaviour events triggered via the ace:ajax component.

ICE Components

  • ice:dataExporter
    • The ice:dataExporter component now supports PDF formatted exports.
      • This feature requires that the itext-2.1.7.jar be included in the application classpath (not provided in the ICEfaces bundle due to license restrictions).
  • ice:gmap
    • The ice:gmap component(s) have been updated to use the newer Google Maps v3 JavaScript API.
    • All previously supported component APIs, map-control types, etc. remain supported.
    • Compatibility Note: Applications will require new gmap keys to be provided in the web.xml file for use with the Google Maps v3.0 API, instead of the former v2.0 API. GMap keys used with previous ICEfaces releases will no longer function. The gmap key value is specified in the web.xml file via the "com.icesoft.faces.gmapKey" context parameter.

Core Framework

  • New icecore:refresh tag
    • Provides support for periodic page refreshes triggered from the client.
    • Leverages ICEfaces Ajax-Push architecture for optimal simplicity and performance.
    • See the Wiki Topic for details.
  • New icecore:setEventPhase component
    • Provides the ability to specify the JSF life-cycle phase that certain events will be broadcast in, for events originating from components in its child hierarchy.
    • See the setEventPhase Wiki Topic for details.
  • icecore:config configuration settings are now propagated into included xhtmls.
  • Improved Support for "window.onload" and "window.onunload" JavaScript Properties
    • Applications can now register their own listener callbacks directly with the "window.onload" and "window.onunload" JavaScript properties without causing adverse affects to ICEfaces.
    • Previously, applications had to use the "" and "" ICEfaces JavaScript APIs in order to avoid conflicting with the ICEfaces bridge event listeners on the native window object.
  • Configurable Minification/Compression of JavaScript Resources
    • All ICEfaces JavaScript resource files can now be provided in a none-minified/uncompressed format to the browser for easier analysis and debugging of JavaScript related issues in the browser.
    • ICEfaces JavaScript files are provided unminified/uncompressed when the JSF 2 "PROJECT_STAGE" configuration parameter is set to "Development".
    • Any other "PROJECT_STAGE" value will result in minified/compressed JavaScript files being provided, which is optimal from a performance and bandwidth perspective.
  • JavaScript and CSS Resource GZIP Compression Changes
    • ICEfaces no longer performs GZIP compression on CSS (.css) and JavaScript (.js) resource files by default. It is recommended that GZIP compression be configured and performed by the application server or web proxy server.
    • See the new Wiki Topic for details and server configuration resources.
  • blockUIOnSubmit - It is now possible to customize the blockUIOnSubmit overlay styling via the new "ice-blockui-overlay" CSS styleclass.
  • Default Status Dialogs - It is now possible to customize the standard ICEfaces status dialog overlay styling via the new "ice-status-indicator-overlay" CSS styleclass.


  • Liferay Faces Bridge
    • This release introduces support for using ICEfaces with the new Liferay Faces Bridge when running on Liferay Portal 5.2, 6.0, and 6.1.
    • Note that the Liferay Faces Bridge library must be downloaded from and is not included in the ICEfaces release bundle.
    • When using the Liferay Faces Bridge, the portletfaces-bridge-2.0.2-ice-7875.jar should not be included in the class path.

Improved Maven Support

  • ICEfaces Maven 2 Public Repository Improvements
    • Starting with this release, the ICEfaces Maven 2 Public Repository has been improved to include the complete set of binary, documentation, and source-code libraries and associated Maven artifacts. Previously only the binary libraries were available.
  • Build ICEfaces with Maven
    • Building the ICEfaces libraries themselves with Maven 2+ is now supported:
      • Within the ICEfaces source bundle (or SVN tag checkout) icefaces directory, type: "mvn deploy"
      • This will create a new "icefaces/local-test-repo" directory with the complete ICEfaces library set, including documentation and source-code jars, under your user directory.
  • Specify MyFaces JSF when building Sample Applications with Maven
    • All sample applications built using Maven can now optionally include the MyFaces JSF libraries, instead of the Mojarra JSF libs (default).
    • See the Building and Running ICEfaces with Maven Wiki topic for details.

Samples & Tutorials

  • ICEfaces Showcase Sample Application
    • A large set of new demonstration panels have been added to illustrate key features of the new and improved ACE components.
    • Numerous bug fixes.
  • Auction Sample Application
    • The core/auction sample application has been updated to use the new icecore:refresh tag for interval updates of the auction page. Previously asynchronous ICEfaces push was used in this sample.
  • Portlet Samples
    • A new ant build configuration has been added to all portlet samples for the Liferay Faces Bridge: "ant -Dliferayfaces="true" clean servlet-profile"

IDE Integrations

  • NetBeans 7.1
    • This release provides an updated IDE integration for NetBeans 7.1
  • Eclipse 3.6, 3.7, 4.2
    • This release provides an updated IDE integration for Eclipse 3.6/3.7/4.2.
    • Design-time support has been added for the new and enhanced ACE components in this release.
    • The ICEfaces Showcase sample application is now included as a reference project plugin for Eclipse integration users.
Change Log
For a complete list of all changes in this release, see the related JIRA Change Log.

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.

Supported Platforms

JSF Runtimes

  • Oracle Mojarra JSF 2.1.3 - 2.1.6 (included).
  • Apache MyFaces JSF 2.1.8-ICE-8229 (included).
Myfaces 2.1.8-ICE-8229 is a specially patched MyFaces 2.1.8 library for use with this release. See for details on the nature of the patch.


  • Chrome 20
  • Firefox 10.02 - 14
  • IE 6, IE 7, IE 8, IE 9
  • Safari 5

Mobile Browsers

  • Apple iOS Safari
  • Google Android Chrome
  • RIM BlackBerry OS6 WebKit Browser
A subset of component functionality, such as those requiring mouse-drag operations, are not currently supported on mobile devices with touch-screen interfaces.

Application Servers

  • Apache Tomcat 6, 7
  • Oracle Glassfish v3.0, 3.1
  • RedHat JBoss AS 5, 6, 7

Portal Containers

  • Apache Pluto 2.0.3
  • Liferay Portal 5, 6

Apache Pluto Portlet deployments require the PortletFaces Bridge library. Note that the version of the PortletFaces Bridge that is currently shipped with ICEfaces includes fixes that aren't available with the generally released version. Ensure you use the copy of the library that ships with ICEfaces.

Liferay Portal Portlet deployments may use either the Liferay Faces Bridge 3.1.RC2 (available from Liferay), or the included PortletFaces Bridge library.

When using the Liferay Faces Bridge, the portletfaces-bridge-2.0.2-ice-7875.jar should not be included in the class path.

Known Issues

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.
  • 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).


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

1.8.x Compatibility

  • In ICEfaces 2+, the "Request" scope is the "standard" JSF Request scope, and not the "Extended" Request scope that was the default in ICEfaces 1.x. This change may result in failures for ICEfaces 1.x applications that relied on the Extended Request Scope behavior that are being moved to ICEfaces 2.0. The workaround for this issue is to adopt one of "View", "Window", or "Session" scopes in JSF/ICEfaces 2+ instead.

Mojarra JSF

  • This release includes the Mojarra JSF 2.1.6 runtime libraries.
    Note that Mojarra 2.1.4 introduced a dependency on Servlet 3.0 APIs, as a result, it should not be used on older JEE5 application servers. Instead, Mojarra 2.1.3, or Apache MyFaces 2.1, should be used on JEE5 servers.
  • Note that the Mojarra JSF releases prior to 2.1.3 and greater than 2.1.6 have several serious issues that may impact your project and are not recommended. We are working with the Mojarra team to ensure future Mojarra releases (>2.1.10) will resolve these issues.
  • When running a JSF application in JSF2 PROJECT_STAGE="Development" mode, 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.

MyFaces JSF

  • ace:dataTable w/ Row Expansion
    • An issue exists that prevents the use of the ace:dataTable with Row Expansion that contains editable components, on MyFaces only. At this time, Row Expansion can be used with none-editable components-only when running on MyFaces.


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

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:
      <Context antiJarLocking="true" antiResourceLocking="true"/>
  • Glassfish 3 / JBoss 6, 7 (JEE 6 Platforms)
    • It is required to have Mojarra JSF 2.1.3+ 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.

Portal Containers

  • Liferay 5
    • Using the ACE Components with Liferay 5 can result in CSS styling conflicts between the Liferay themes and the ACE Component theme, as they both utilize the jQuery ThemeRoller styling scheme. It may be necessary to customize the themes to avoid conflicts when using the ACE components with Liferay 5. See the Custom ACE Styles for Liferay Portal Wiki topic for details.

Sample Applications

  • ICEfaces Showcase Portlets
    • The ICEfaces Showcase Portlets are intended to be used with a single instance of each demo portlet on the same page at one time. Adding the same demo portlet to the page multiple times will result in component failures.
    • This issue is related to the id-usage and structure of the demo application itself, and is not an inherent limitation of ICEfaces or the components themselves.


Open source community support is available at

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

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

© Copyright 2021 ICEsoft Technologies Canada Corp.