ICEfaces 3.1.0.BETA2 Release Notes

Table of Contents

ICEfaces 3.1.0.BETA2 Release Notes

June 11th, 2012


About This Release

ICEfaces 3.1.0.BETA2 is a preview release of ICEfaces 3.1.0 and is not suitable for production use.


ICEfaces is available for download in the following formats:

What's New in 3.1.0.BETA2?

ACE Components

Updated & Enhanced Components:

  • The following component features first introduced with ace:textEntry have been added to the ace:autoCompleteEntry, ace:dateTimeEntry, and ace:maskedEntry components:
    • 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).
  • ace:autoCompleteEntry Enhancements
    • New "caseSensitive" attribute to configure case-sensitivity in matching suggestions with typed characters.
    • New "delay" attribute allows optional configuration of the number of milliseconds to wait for the next key press before processing and displaying the suggestion list popup (to improve scalability - avoids submitting while user is actively typing)
    • New "minChars" attribute to specify the minimum number of characters that must be entered before processing the suggestion list popup.
    • New "height" attribute - maximum height in pixels of the list of possible matches (if 0, then the size is automatically adjusted to show all possible matches). If more matches appear in the list than can be displayed within the specified height, a vertical scrollbar is displayed inside the list.
    • New "direction" attribute - specifies which direction to show the popup list of possible matches. Possible values are "up", "down", and "auto".
  • ace:column
    • The "groupBy" attribute will now automatically add the column to the front of the sort order without the need to also specify the "sortBy" attribute (columns with "groupBy" specified will always be included the front of the sort order).
    • Resetting the sort will clear any columns from the sort other than those with "groupBy" specified.
  • ace:dataTable
    • New "staticHeaders" attribute - specifies that the header and footer regions are displayed outside of the scrollable dataTable body region and that the headers and footers remain viewable at all times (default="true") (only active when "scrollable='true'").
      • This mode also enables the automatic column sizing behaviour that is required to keep the dataTable body and header/footer columns aligned.
      • When "staticHeaders='false'" (and "scrollable='true'"), the entire dataTable contents including the headers and footers are included inside the scrollable dataTable region. In this mode it is possible that the headers and footers may scroll out of view. Note that in this mode the automatic column sizing feature is not required which may result in improved responsiveness on older IE 7/8 browsers.
    • New "toggleOnInvalidEdit" attribute - adjusts the behaviour of any contained ace:cellEditor components when they contain a component that fails validation:
      • When "toggleOnInvalidEdit='false'" (default), the ace:cellEditor will remain in edit mode so long as any of its contents are invalid (fails validation).
      • When "toggleOnInvalidEdit='true'" the ace:cellEditor will leave edit mode regardless of the state of the contained components. This mode is consistent with the original 3.0.x behaviour and is included for compatibility with existing applications.
  • 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.
  • ace:list
    • New "selectionMode" attribute configure item selection behaviour. This attribute replaces the previous "select" attribute, which is no longer supported. Valid values are:
      • Undefined or "none" (default) - no item selection support.
      • "single" - a single item may be selected at one time.
      • "multiple" - multiple items may be selected. The multiple select behaviour is as follows:
        • Click now begins a new selection (clears any previously selected items).
        • CTRL (or Command) + Click adds to (or removes from) the selection set.
        • Shift + Click will add to the selection all unselected items between the previous selection (or deselection) and the clicked item, inclusive of the clicked item itself.
    • New "height" attribute - maximum height in pixels of the list (if 0, then the size is automatically adjusted to show all entries). If more items appear in the list than can be displayed within the specified height, a vertical scrollbar is displayed inside the list.
  • 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.


  • Liferay Faces Bridge
    • This release introduces preliminary 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.
  • ICEfaces Showcase Sample Application
    • Minor adjustments as required to adapt existing demos to use new ACE component attributes.

Samples & Tutorials

  • ICEfaces Showcase Sample Application
    • Minor adjustments as required to adapt existing demos to use new ACE component attributes.
  • 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-M7
    • This release provides an updated IDE integration for Eclipse 3.6/3.7/4.2-M7.
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 is included).
  • Apache MyFaces JSF 2.1.6 (included)


  • Chrome 19
  • Firefox 3.6 - 12
  • 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

(All 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 for all of your ICEfaces portlet deployments.)

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 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 releases prior to 2.1.3 have several serious issues that may impact your project and are not recommended.
  • 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.

MyFaces JSF

  • Portal Detection
    • MyFaces 2.1.6 has a defect that prevents proper detection of Portlet 2.0 spec. portal containers.
    • To work-around this issue, this release includes a patched MyFaces 2.1.6 library that resolves this issue (See details).
    • It is anticipated that this issue will be resolved in a future MyFaces JSF official release.
  • 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.


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.