ICEfaces 3.2.0 Release Notes

November 2nd, 2012

Contents

• About This Release
• Downloads
• What's New in 3.2
  • ACE Components
  • ICE Components
  • Core Framework
  • ICEpush
  • Samples & Tutorials
  • Documentation
  • IDE Integrations
  • JSF Runtimes
• Supported Platforms
• Known Issues
• 3rd Party Libraries
• Support

About This Release

---

ICEfaces 3.2 is an official ICEfaces feature release, featuring 13 new ACE components/sub-components, a new ordered-resource-loading capability, and over 160 issues resolved.

Downloads

---

ICEfaces is available for download in the following formats:

• Binary and source-code bundles
• IDE Tool integration bundles
• Maven Repository

What's New in 3.2?

---

ACE Components

New Components:

• ace:delegate
  • The Delegate is a container component that will receive the ace:tooltip functionality on behalf of some other inner component.
  • This is useful in cases where such inner components are prone to be completely replaced from the DOM during dynamic updates, where it could lose the ace:tooltip functionality.
  • Enables a single ace:tooltip component to be used for multiple ace:dataTable rows/cells (including dynamic update of the tooltip contents prior to display).
  • See the new ace:tooltip -> Delegate demo in the ICEfaces Showcase sample application.

• ace:gMap
  • All-new implementation based on Google Maps JavaScript API v3.
  • The ace:gMap component has a large number of helper subcomponents:
    • ace:gmapAutocomplete - An ACE component implementation of Google's Places autocomplete tool. The ace:gMapAutocomplete component will create a text box which will provide locations that match the currently typed string, then return information about the selected location such as the types Google has assigned to it, or the url to Google's information page on it.
    • ace:gMapControl - Modify the controls that appear on the map (overview, pan, rotate, scale, streetview, zoom).
    • ace:gMapInfoWindow - displays a pop-up window that can display either straight text information, or nested html code. If placed within a gMap, it will render at the locations given by its latitude and longitude attributes. If it is placed inside an ace:gMapMarker, it will bind to that marker and move to whatever location it occupies.
    • ace:gMapLayer - activates a layer on the parent gMap that's designed to provide an alternative visual, such as displaying bike paths, traffic, or third-party KML data.
    • ace:gMapMarker - places a marker upon the map in the desired coordinates to be used for designating points of interest or important locations.
    • ace:gMapOverlay - allows the user to create a shape of their choosing on the map.
    • ace:gMapServices - is an access point to the services portion of the api and will return information about the specified points, such as maximum zoom, or height. Directions are also specified through this subcomponent.
  • Requires that a valid Google Maps v3 API key be specified by setting the 'org.icefaces.ace.gmapKey' parameter in the web.xml.
  • See the new ace:gMap demos in the ICEfaces Showcase sample application.

• ace:tree
  • Includes the ace:node sub-component.
  • Supports Client (static) and Server (dynamic) modes, including lazy-loading w/ caching
  • Single/Multiple node selection
  • Drag & drop to reposition nodes
  • Ajax updates update node regions rather than entire component (improves scalability with large trees)
  • Tree & per node configuration of selection, expansion, reordering
  • Flexible sizing, layout will remain consistent no matter the size of node content
  • Ajax behaviours for (de)select / expand / contract / reorder
  • See the new ace:tree demos in the ICEfaces Showcase sample application.

• ace:submitMonitor
  • Monitors all submits to the server and indicates the status of the submits while in progress.
  • Can be made modal to block UI inputs during submits.
  • Optionally reports server and network connection errors, and session expiry.
  • Supports configurable text labels and image state indicators, or facets for a fully configurable UI.
  • Can be targeted to a complete page, or one or more containers or components within a page.
  • Multiple ace:submitMonitors can be used on the same page to customize behaviours for different component events or submit types.
  • See the new ace:submitMonitor demos in the ICEfaces Showcase sample application.

Updated and Enhanced Features and Components:

• New support for Mobile/Touchscreen devices
  • The ACE components now support direct interaction via touchscreen gestures on mobile devices, including resizing and moving dialogs, resizing dataTable columns, dragging the ace:sliderEntry slider,
    and general draggable/droppable/resizable functions.
  • See the ACE Components Mobile Device Support Wiki topic for details.

• Additional support for ARIA Accessibility Roles
  • The following ACE entry components now support ARIA accessibility roles:
    • ace:textEntry
    • ace:textAreaEntry
    • ace:maskedEntry
    • ace:autoCompleteEntry
    • ace:dateTimeEntry (partial)
  • ARIA support for additional ACE components is planned in future releases.

• ace:ajax
  • Now merges multiple Client Events when triggered by the same user-action into a single submit.
  • With the merging of ace:ajax requests, client side listeners for the same event are run in facelet order, and server side listeners are all called once on a single request.
  • Improvement over standard f:ajax behaviour of triggering multiple sequential submits, one for each client event triggered.

• ace:autoComplete
  • Added new "blur" client event.

• ace:chart
  • Added support for Bubble and Gauge chart types.
  • Updated the jqPlot library to v1.0.4.

• ace:dataExporter
  • New support for custom exporter implementations:
    • Includes the new OuterTableCSVExporter and InnerTableCSVExporter custom exporter types.
    • These custom exporters support exporting nested ace:dataTables in CSV format.
    • See the new ace:dataExporter -> Custom Exporter demo in the ICEfaces Showcase sample application.
  • Data can now optionally be exported with the column ordering established by the user in the client, or in the originally specified order.
  • Support for exporting data contained inside expandable rows, all rows will now be exported, whether or not they are currently "expanded".

• ace:dataTable
  • Optimized event initialization for improved performance with large tables.
  • Now cancels sort or filter operations when the form fails validation.
  • Added an new "all" option to the rowsPerPageTemplate attribute to specify that all rows should be displayed (resets previous pagination configurations).
  • Compatibility note: Previously, ace:dataTable headers were always styled with "position:relative". Starting with this release, the headers are only set to "position:relative" when resizable columns are enabled. This may effect existing applications that are expecting the "position:relative" styling to always be present.

• ace:maskedEntry
  • Added new "blur" client event.

• ace:rowEditor
  • Added optional per-component and global localizable title messages for ace:rowEditor icons.

• ace:sliderEntry
  • Added "showLabels" attribute to optionally render value-range labels for the slider bar.

• ace:tableConfigPanel
  • Added new 'in-col-left' and 'in-col-right' options for positioning the button/icon in the dataTable header.

• ace:tooltip
  • New "forDelegate" attribute - Specifies the id of the component that will receive the tooltip listeners on behalf of the component specified in the "for" attribute.
  • Useful when the tooltip component is outside a datatable or iterative container and references a component inside such container.
  • Improves performance by avoiding the creation of tooltip objects in each each row. It also guards against dynamic updates that could replace the component and make it lose its tooltip listeners.
  • This method allows retrieving row data by using the "fetch" and "store" attributes.
  • This approach is now recommended vs the previous "forContainer" one.
  • See the new ace:tooltip -> Delegate demo in the ICEfaces Showcase sample application.

• 3rd Party JavaScript Libraries
  • Added new jQuery UI Touch Punch 0.2.2 library.
  • Updated JQuery UI to 1.8.24.
  • Updated jqPlot to 1.0.4.
  • See the icefaces/lib/versions-licenses.html file in the release bundle for details on all included libraries.

ICE Components

• ice:panelCollapsible
  • New "toggleOnInput" attribute to determine if mouse-clicks that occur over input components inside the header should result in the panel collapsing/expanding, or simply be left to be handled by the input components themselves.

Core Framework

• New support for Ordered Resource Loading
  • Many times required resources need to be loaded in a specified order to support dependencies between the resources, or CSS styling overrides. Unfortunately JSF itself doesn't provide any mechanism for ordering the loading of resources on the page.
  • Resource dependencies can be specified via a new resource-dependency.xml configuration file that can be used to configure the resource dependencies in an application, thus ensuring that resources are always loaded in a determined sequence.
  • See the Resource Dependencies Wiki topic for more information.
  • The ICEfaces Showcase sample application now utilizes this feature. See the icefaces/samples/showcase/showcase/src/main/resources/META-INF/resource-dependency.xml file in the application source code for an example implementation.

• New WindowScopeBeanLocator API
  • Access WindowScope beans from other contexts.
  • WindowScopeBeanLocator.lookupBean(HttpServletRequest request, String name) can be used to lookup a bean by its name in the current window scope.

• Improved Logging
  • Improve logging when "Diff propagated to root but no ID set" warning occurs to provide more contextual information to ease debugging the root cause.
  • Added new check for improperly terminated components during rendering-phase to help catch potentially serious rendering errors ("Development" Project-Phase only).

• Resolved an important issue with mandatory resources (as used by ACE components) that could result in the server-side component-tree growing with each render-cycle within a single View instances lifecycle, resulting in application slow-down until the view was discarded (page navigation or browser refresh/reload).

ICEpush

• New Support for PushRenderer cross-user group management
  • New APIs have been added that add the ability for one user to administer the membership of push groups (e.g. An admin-role in an application can add user-roles to specific push groups to receive updates).
  • PushRenderer now supports:
    • public static synchronized Set<String> getCurrentSessionPushIDSet()
    • public static synchronized String getCurrentViewPushID()
    • public static synchronized PushContext getPushContext()

Samples & Tutorials

• ICEfaces Showcase Sample Application
  • A large set of new demonstration panels have been added to illustrate key features of the new and improved ACE components.
  • Numerous bug fixes.

• All Samples
  • Added the "org.apache.myfaces.SERIALIZE_STATE_IN_SESSION=false" configuration parameter to all samples to avoid having MyFaces JSF serialize state between requests.
  • See ICE-8623 for more information.

• Tutorials
  • Added a new Master-Detail Tutorial featuring the ACE components.
  • Enhanced the ace:fileEntry Callback Tutorial to show custom failure types.
  • Updated the Easy Ajax Push tutorial for the current ICEfaces release.

Documentation

• The ICEfaces Wiki Documentation has been updated for all new features in this release.
• The ICEfaces 1.8-to-ICEfaces 3.x Migration Guide has been improved based on user feedback.

IDE Integrations

• Eclipse
  • The Eclipse integration has been enhanced to provide additional new project templates
    to quickly create a new ICEfaces project that matches your page layout needs.

JSF Runtimes

• The MyFaces JSF library included in this release has been updated to v2.1.9.

Supported Platforms

---

JSF Runtimes

• Oracle Mojarra JSF 2.1.3 - 2.1.6 (included).
• Apache MyFaces JSF 2.1.9 (included).

Browsers

• Chrome 22
• Firefox 10.02 - 16
• IE 6, IE 7, IE 8, IE 9, IE 10
• Safari 5, 6

Mobile Browsers

• Apple iOS Safari
• Google Android Chrome
• RIM BlackBerry OS6 WebKit Browser

Application Servers

• Apache Tomcat 6, 7
• Oracle Glassfish v3.0, 3.1
• RedHat JBoss AS 5, 6, 7

Portal Containers

• Apache Pluto 2.0.3
• Liferay Portal 5, 6

Apache Pluto Portlet deployments require the PortletFaces Bridge library. Note that the version of the PortletFaces Bridge that is currently shipped with ICEfaces includes fixes that aren't available with the generally released version. Ensure you use the copy of the library that ships with ICEfaces.

Liferay Portal 6.x Portlet deployments should use either the Liferay Faces Bridge 3.1 (available from Liferay).
Liferay Portal 5.x deployments must use the included PortletFaces Bridge library.

Known Issues

---

The following section describes the most commonly encountered known issues with this release:

General

• JSPs are not supported by ICEfaces 3 - use Facelets.
• It is required to specify "h:head" and "h:body" tags in your ICEfaces application pages.
• Applications must avoid the use of "javascript: void(0)" in browser DOM event handlers as this technique causes the "onBeforeOnload" event handler to be called in IE, which results in the ICEfaces bridges shutting down (thinking that the page is being navigated away from).

deltaSubmit

• Due to a none-standard rendering technique used by the h:selectOneMenu component, when using deltaSubmit=true mode, this component is not supported. Work-arounds are to use another component instead, such as ace:list, or ice:selectOneMenu.

ICEpush

• ICEpush (icepush.jar) asynchronous update support is limited to a single ICEfaces application per host-name/server.
  • Viewing multiple ICEfaces applications in the same browser from the same host server concurrently will result in only one of the applications having functional push capabilities.
  • Support for pushing asynchronous updates to multiple ICEfaces applications from the same server/host-name requires the use of the Enterprise Push Server (EPS), which is included in ICEfaces EE (Enterprise Edition).
  • This is necessary because the browser cannot support multiple concurrent push connections, so all push traffic must be multiplexed at a single point on the server.

1.8.x Compatibility

• In ICEfaces 2+, the "Request" scope is the "standard" JSF Request scope, and not the "Extended" Request scope that was the default in ICEfaces 1.x. This change may result in failures for ICEfaces 1.x applications that relied on the Extended Request Scope behavior that are being moved to ICEfaces 2.0. The workaround for this issue is to adopt one of "View", "Window", or "Session" scopes in JSF/ICEfaces 2+ instead.

Mojarra JSF

• This release includes the Mojarra JSF 2.1.6 runtime libraries.

  Note that Mojarra 2.1.4 introduced a dependency on Servlet 3.0 APIs, as a result, it should not be used on older JEE5 application servers. Instead, Mojarra 2.1.3, or Apache MyFaces 2.1, should be used on JEE5 servers.

• Note that the Mojarra JSF releases prior to 2.1.3 and greater than 2.1.6 have several serious issues that may impact your project and are not recommended. We are working with the Mojarra team to ensure future Mojarra releases (>2.1.13) will resolve these issues.
• When running a JSF application in JSF2 PROJECT_STAGE="Development" mode, you may see the follow warning appear at the bottom of the page: "Form component needs to have a UIForm in its ancestry.".
  • This issue is caused by a bug in Mojarra JSF, a suggested work-around is to set the JSF2 PROJECT_STAGE="Production" in the web.xml file.

MyFaces JSF

• Session State Serialization
  • There is a compatibility issue with MyFaces default behaviour of serializing the session state between requests. It is recommended that applications disable session-state serialization in MyFaces via the following configuration parameter:

     <context-param> 
            <param-name>org.apache.myfaces.SERIALIZE_STATE_IN_SESSION</param-name> 
            <param-value>false</param-value> 
        </context-param> 

  • See ICE-8623 for a detailed explanation.
• ace:dataTable w/ Row Expansion
  • An issue exists that prevents the use of the ace:dataTable with Row Expansion that contains editable components, on MyFaces only. At this time, Row Expansion can be used with none-editable components-only when running on MyFaces.

Browsers

• WebKit (Safari and Chrome)
  • The WebKit-based browsers (Google Chrome and Apple Safari) request content-type "application/xhtml+xml" by default, which is different from virtually all other browsers. In cases where the application page doesn't set the contentType explicitly this can result in these browsers defaulting to a strict XHTML rendering mode, which can cause some unexpected styling and layout issues. In order to have WebKit-based browsers render markup consistently with other browsers, you must specify the content-type in the view tag on each page:

    <f:view contentType="text/html">

  • See http://jira.icesoft.org/browse/ICE-6138 for more information.

Application Servers

• Tomcat 6.0
  • In some cases, when running Tomcat on Windows, undeploying an ICEfaces compatible application (i.e. that includes the icefaces-compat.jar) can cause an exception. See http://jira.icesoft.org/browse/ICE-5222 for additional information about this issue. To prevent this, include a context.xml file with your application that includes the following Context attributes to prevent jar and resource locking:

    <Context antiJarLocking="true" antiResourceLocking="true"/>

• Glassfish 3 / JBoss 6, 7 (JEE 6 Platforms)
  • It is required to have Mojarra JSF 2.1.3-2.1.6 installed. This may require updating the JSF Mojarra runtime libraries in Glassfish 3 or JBoss 6/7, depending on which JSF version is currently installed.

Portal Containers

• Liferay 5
  • Using the ACE Components with Liferay 5 can result in CSS styling conflicts between the Liferay themes and the ACE Component theme, as they both utilize the jQuery ThemeRoller styling scheme. It may be necessary to customize the themes to avoid conflicts when using the ACE components with Liferay 5. See the Custom ACE Styles for Liferay Portal Wiki topic for details.

Sample Applications

• ICEfaces Showcase Portlets
  • The ICEfaces Showcase Portlets are intended to be used with a single instance of each demo portlet on the same page at one time. Adding the same demo portlet to the page multiple times will result in component failures.
  • This issue is related to the id-usage and structure of the demo application itself, and is not an inherent limitation of ICEfaces or the components themselves.

3rd Party Libraries

---

The license and version information for all required/included 3rd Party libraries for this release is available here.

Support

---

Open source community support is available at http://www.icesoft.org.

The ICEfaces Community Forums are available for questions, comments, or general discussions regarding ICEfaces.

Commercial support agreements are also available.