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
- SingleSubmit Alternatives
- Referencing ACE Component Client Objects (widgetVar)
- ACE Component Default Event Changes
- Configuring ace:dateTimeEntry's Locale
- Migrating from ICEmobile 1.3
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.
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 following typical icecore:singleSubmit syntax:...may be replaced with the following equivalent ace:ajax syntax:|
The ace:ajax and/or f:ajax tags can be used in place of the old icecore:singleSubmit tag.
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.
To illustrate this change, see the before and after code example below.
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.
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.
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.