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.
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 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>
<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>
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.
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.
<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">
...
<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.
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 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.
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: