ICEfaces 3 to 4 Migration Guide

Overview

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 following typical icecore:singleSubmit syntax:

<h:form>
    <icecore:singleSubmit/>
    ...
</h:form>

...may be replaced with the following equivalent ace:ajax syntax:

<h:form>
    <ace:ajax execute="@this" "render="@all" >
       ...
    </ace:ajax>
</h:form>

Nesting within a Single Component

 <ace:sliderEntry id="widthEntry"
                                clickableRail = "true"
                                min="0"
                                max="15"
                                stepPercent="1"
                                value="#{chartBarBean.barWidth}">
                           <ace:ajax event="slideEnd" execute="@this" render="@all" listener="#{chartBarBean.updateChart}"/>
                       </ace:sliderEntry>

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="sampleDialog.show();" type="button"/>

<ace:dialog id="myDialog"
            header="A sample dialog overview example"
            widgetVar="sampleDialog"
            width="400">
...

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"
            width="400">
...

The new ice.ace.instance approach for showing dialogs requires the full id of the dialog to be specified, such as "j_idt77:qrDialog" instead of just "qrDialog". To reduce the complexity of working with complete IDs for showing/hiding dialogs it may be preferable in some cases to locate dialogs inside of forms with <h:form prependId="false" > specified.

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',
        ...etc...
 };

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.

Migrating from ICEmobile 1.3

If you are migrating an existing ICEmobile 1.3 / ICEfaces 3.3 application to ICEfaces 4 there are a number of significant differences that must be accommodated in the application:

The ICEmobile libraries are no longer required/supported with ICEfaces 4. Instead, the MOBI mobile JSF components have been integrated directly into ICEfaces 4 in a single release package, simplifying the management and configuration of the libraries required to develop mobile applications with ICEfaces.

A significant number of ICEmobile MOBI components have not been brought forward into ICEfaces 4 in order to reduce the amount of overlap that existed between the MOBI and ACE libraries previously. Generally, any ICEmobile MOBI component not included in ICEfaces 4 can be replaced with an equivalent ACE component.
- See the ICEMobile 1.3 to ICEfaces 4 Component Migration Guide topic for more information.

The ICEfaces 4 MOBI components now support the same jQuery ThemeRoller themes as the ACE components. Consolidating all the components on a single theming scheme (jQuery ThemeRoller) simplifies theme selection and customization and better supports consistent theming when ACE and MOBI components are used on the same page. As a result, however, the ICEmobile 1.3 themes, including device-specific themes, are not supported by the ICEfaces 4 MOBI components.
- For more information on using the jQuery ThemeRoller themes with the ACE & MOBI components, see the ACE ThemeRoller Support topic.