ICEfaces 2 to ICEfaces 3 Migration Guide

Added by Ken Fyten, last edited by Arturo Zambrano on Mar 08, 2012  (view change)
Table of Contents

This topic documents the changes that may impact backwards-compatibility when migrating an existing ICEfaces 2.x application to ICEfaces 3.

Open Source Software License Change

ICEfaces 3 is licensed under the Apache License, Version 2.0. Previous ICEfaces releases were licensed under the Mozilla Public License (MPL) 1.1.

ACE Components

The original ACE Components included in ICEfaces 2 have been substantially re-implemented for ICEfaces 3. Due the comprehensive nature of these changes, backwards compatibility could not be provided. However, efforts have been made to keep the ACE component tag APIs as similar as possible to the previous versions, thus, porting existing applications should be a straightforward process.

The following ICEfaces 2 ACE components are impacted:

  • ace:checkboxButton
  • ace:fileEntry
  • ace:linkButton
  • ace:pushButton
  • ace:sliderEntry
  • ace:tabSet / ace:tabPane / ace:tabSetProxy

ICEfaces 2 applications that use the above components will need to be revised to adapt to the following significant component changes:

ACE Repackaging

  • The entire Advanced Component Environment and all ACE Components have been repackaged to better isolate the ACE library from other ICEfaces framework libraries.
  • Java code formerly located under the "org.icefaces.component" and "org.icefaces.generator" packages is now located under the "org.icefaces.ace" package.
  • JavaScript functions formerly namespaced under the "ice.component" name-space are now under the "ice.ace" name-space.
  • NOTE: Applications will need to revise their Java import statements to reflect the new component packaging as required. In the unlikely event that an application has JavaScript that references the ACE JavaScript name-space, those references will also need to updated.

ThemeRoller Support

  • All ACE components now support the jQueryUI ThemeRoller theming system.
  • The ThemeRoller system provides an extensive collection of ready-to-use themes, as well as an intuitive web-application for creating custom themes easily without requiring extensive CSS knowledge.
  • The ThemeRoller-based CSS styles are injected into the ICEfaces page automatically.
  • The release bundle includes over 25 pre-defined themes ready for use.
  • Themes are no longer loaded via <link> tags at the bottom of the page and it is no longer necessary to specify the theme style class in the <body> tag. Themes are now loaded via a context parameter. This new theme-loading mechanism is explained in ace.theme in more detail. Instructions on how to use an existing theme or create a new one can be found at ACE ThemeRoller Support.
  • NOTE: Applications using custom styling with the ACE components will need to review and revise their styling to ensure it is applied as expected under the new ThemeRoller-based themes.

mandatoryResource Change

  • The default value for the "org.icefaces.mandatoryResourceConfiguration" configuration parameter has been changed to "none", which results in no component resources being pre-loaded. As a result, overall resource loading efficiency is greatly improved, but there is a risk that certain required resources for components that are dynamically added to the page after the initial page load will not be available, resulting in a component failure.
  • See the mandatoryResourceConfiguration Wiki topic for details on using mandatoryResource configuration techniques.
  • NOTE: Applications using the ICEfaces 2 ACE components may need to adopt the mandatoryResource configuration technique to ensure that require ACE component resources are available at runtime. It is reasonable to test the application without adding any mandatoryResource configuration (default = "none"), and then add specific components that fail to function normally as required by your application design. Setting the org.icefaces.mandatoryResourceConfiguration" configuration parameter to "all" in the web.xml is a good temporary workaround to mandatoryResource loading issues, but is not recommended for production use in most circumstances due to its heavy-weight approach to resource loading in the browser.

'singleSubmit' Attribute Removal

  • The 'singleSubmit' attribute has been removed from the ACE components in preference for using the new <ace:ajax> component. The <ace:ajax> approach provides a more flexible and standards compliant approach to ajax-submit, execution, and rendering configuration.
  • NOTE: Applications previously using the singleSubmit attribute will need to be updated to adopt the <ace:ajax event="xxx" execute="@this" render="@all"> equivalent.

ICE Components

ice:gMap & ice:inputRichText

  • Beginning with ICEfaces 3, the ice:gMap and ice:inputRichText components no longer automatically loads their required resources into the head of each page in the application. Instead, each component's resources will only be automatically loaded if the component is rendered on the page during the initial full page load. If the component is not rendered on the initial page load, and is subsequently added to the page via a dynamic page update (Ajax), it will not function correctly. In these cases, a mandatoryResourceConfiguration must be used to ensure that the component's resources are available when required, without incurring the expense unnecessary loading in cases when it is not in use.

ICEpush

PushRenderer API Change

  • The PushRenderer.getPortableRenderer(FacesContext) method has been removed.
  • The PushRenderer.getPortableRenderer() API must now be used.
  • The justification for this change is that serious errors could occur if the original method was invoked with a either a cached FacesContext on a non-JSF thread, or with a stale cached FacesContext on the JSF execution thread.

Samples

Compat Component Showcase Sample Application Removed

  • With the addition of the new ICEfaces Showcase sample application the compat/component-showcase application is now redundant and has been removed.
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

© Copyright 2021 ICEsoft Technologies Canada Corp.