ICEfaces 3 to 4 Migration Guide

You are viewing an old version (v. 10) of this page.
The latest version is v. 18, last edited on Dec 09, 2014 (view differences | )
<< View previous version | view page history | view next version >>


The purpose of this guide is to provide information regarding changes made in ICEfaces 4 that may impact the behaviour of existing ICEfaces 3 applications, or may represent changes to previously established best-practices for ICEfaces application development.


ICE (Compat) Component Alternatives

The legacy ICEfaces ICE (Compat) Components are not supported in ICEfaces 4. Existing applications will need to replace the "ice:" component references with suitable ACE or MOBI alternatives.

See the ICE to ACE Component Migration Guide topic for more information.

SingleSubmit Alternatives

The "icecore:singleSubmit" tag and related "singleSubmit" attributes on various ACE and MOBI components have been removed in ICEfaces 4 in favour of the more JSF-compliant "ace:ajax" tag mechanism for triggering ajax submits with partial page processing and or rendering.

The ace:ajax tag must be used in conjunction with ACE and MOBI components, and the f:ajax tag must be used with any JSF standard "h:" components. It is possible and safe to wrap a form or set of components on the page with both an f:ajax and ace:ajax tag if you are using mixed "h:" and "ace:" or "mobi:" components.

The ace:ajax tag provides a large set of configurability in terms of the scope of execution and rendering for ajax submits, as well as which client-events should trigger the submits, and a mechanism for intercepting the submit with a custom client-side JavaScript callback, checking the submit status, etc. See the ace:ajax Wiki topic for more information.

The "icecore:singleSubmit" tag may be replaced with the equivalent:
<ace:ajax execute="@this" "render="@all"/>
Nesting within a Single Component
 <ace:sliderEntry id="widthEntry"
                                clickableRail = "true"
                           <ace:ajax event="slideEnd" execute="@this" render="@all" listener="#{chartBarBean.updateChart}"/>
Wrapping a Form or Multiple Components

The ace:ajax and/or f:ajax tags can be used in place of the old icecore:singleSubmit tag.

mandatoryResourceConfiguration No Longer Required

The use of mandatoryResourceConfiguration for dynamically added components is no longer necessary, so long as "org.icefaces.generateHeadUpdate='true'" (default). Note that it may still be desirable to specify mandatoryResource for certain components in order to force their resources to be loaded at page-load time instead of dynamically when they are first rendered.

Referencing ACE Component Client Objects (widgetVar)

The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use.

widget = ice.ace.instance('frm:myDialog');

To illustrate this change, see the before and after code example below.

Before (ICEfaces 3 API)
<h:commandButton id="show" value="Show Dialog" onclick=";" type="button"/>

<ace:dialog id="myDialog"
            header="A sample dialog overview example"
After (ICEfaces 4 API)
<h:commandButton id="show" value="Show Dialog" onclick="ice.ace.instance('myDialog').show();" type="button"/>
<ace:dialog id="myDialog"
            header="A sample dialog overview example"

Notable Behavior Changes

ACE Component Default Event Changes

To better align with standard JSF 2.2 f:ajax and client event behaviors, the following changes have been made to the ace:ajax component:

  • The default "execute" value has been changed to "@this", instead of "@all".
  • Changed the default client event to "valueChange" for the following Input components: ace:autoCompleteEntry, ace:richTextEntry, ace:textAreaEntry, ace:textEntry.
  • The default ajax event for the following Action components has been changed to 'action' (instead of 'activate'). The "activate" event will continue to function as an alias to the new "action" event for backwards compatibility: ace:checkboxButton, ace:dataExporter, ace:linkButton, ace:menuItem, ace:printer, ace:pushButton, ace:radioButton.
  • Changed the default execute scope to "@this" instead of "@all" for the following components/events: ace:linkButton/action, ace:maskedEntry/valueChange, ace:menuItem/action, ace:printer/action, ace:pushButton/action, ace:radioButton/action, ace:autoCompleteEntry, ace:richTextEntry, ace:menuItem.
  • The ACE Component TLD documentation now includes the default execution and rendering scope for each client event, as well as the default client event for each component.

Configuring ace:dateTimeEntry's Locale

The mechanism used to set the locale in the ace:dateTimeEntry component has changed in 4.0. In previous releases the ace:dateTimeEntry -component's localization was set via JavaScript:

ice.ace.locales['fi'] = {
         closeText: 'Sulje',

Starting with 4.0, the locale is now set via a value-binding to the new "locale" attribute on the ace:dateTimeEntry component.

A demonstration of the required technique is available in the ICEfaces 4 Showcase sample application, under ace:dateTimeEntry->Locale.

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

© Copyright 2017 ICEsoft Technologies Canada Corp.