ICEfaces™ Community Edition v1.0 Release Notes May 12th, 2006

Overview

• Understanding ICEfaces Community Edition (CE)
  
• Notable changes in this release
• Supported browsers, application servers, and tools
• Known issues with this release
• Getting support for ICEfaces
• License information

Understanding ICEfaces Community Edition (CE)

ICEfaces delivers extensions to Java ServerFaces (JSF) that provide an AJAX-enabled rich presentation environment for JSF applications. ICEfaces brings value to any J2EE development project that needs to provide superior presentation capabilities to the web application user. In particular, ICEfaces provides the following features:

• Smooth, incremental page updates that do not require a full page refresh to achieve presentation changes in the application.
• Server-initiated asynchronous presentation updates for dynamic near-real-time data push.
• The ICEfaces Component Suite, a complete rich JSF component suite that fully leverages ICEfaces capabilities.
  
• Intelligent form processing that facilitates fine-grained interactions with the user as they manipulate a form.
• API support for rapid development of group-aware and collaborative applications, such as Chat, Webcast, social apps., etc.)
• JSP or Facelets based development.
• Tool integrations for leading Java IDEs.
  

Learn More

This ICEfaces release comes with extensive documentation that will help you understand the product thoroughly. Documentation for this release is located in your installation directory at .../install_dir/docs/. The following documents are provided in PDF format:

1. ICEfaces Getting Started Guide: This guide takes you through product installation, environment configuration, demo app installation, and a basic 5-stage tutorial. This guide also contain information related to support for different application server environments and development tools.
2. ICEfaces Developer's Guide: This guide contains information relevant to developing applications with ICEfaces. It describes the ICEfaces architecture, and explains key concepts that the ICEfaces developer should be aware of. It also provides a complete reference guide that covers APIs, configuration, components (including the ICEfaces Component Suite), and TLDs. The guide also covers advanced topics like writing Direct-to-DOM renderers for custom components.

Additionally, all ICEfaces documentation is also available on-line at http://www.icesoft.com/support/icefaces_docs.html.

Notable Changes in This Release

The following notable changes have been made in this release:

General

• Exception logging has been improved to make it easier to quickly determine the root cause of any exceptions.

• A new API has been added that supports asynchronously redirecting and navigating the browser to a new URL from the server.

• ICEfaces now detects if JavaScript is disabled on the browser and will report an error on the server and optionally redirect the browser to another URL in this event.

• A dependency in the ICEfaces AJAX bridge on cookie support in the browser has been removed.

• ICEfaces resource files can now be optionally compressed for deployments with limited connection bandwidth.
  

• Numerous improvements in general software quality, consistency, and robustness.

ICEfaces Component Suite

• The "z-icefaces-components.jar" has been renamed "icefaces-comps.jar".

• The CSS class names used by many of the components were changed between the beta and final v1.0 release. The purpose of the change was to implement an "ice" prefix to provide a measure of name-space protection between the CSS classes used by the ICEfaces components and other elements that may exist on the page. Additional changes were also made to shorten some classnames. A detailed summary of the changes including the before and after class names is available here.

• In previous releases many components provided individual attributes for each CSS class name that they supported as a mechanism to support customization of the look of the components. These individual CSS class name attributes have been removed from all components in this release in favor of a more lightweight approach. All components now support the "style" and "styleClass" attributes for making style adjustments to the default styles provided by the current CSS "theme" being used. To customize the default theme styles for all component instances the theme CSS file must be customized or replaced.

• The attributes of the tree component have been rationalized:
• The "cssImageDirectory" attribute has been renamed to "imageDir".
  
• The individual image attributes has been removed (e.g. navCloseTop, navOpenTop, navOpenTopNoSiblings, etc.). Images are now located in the location specified in the "imageDir" attribute using predefined image names.
• The "actionListener" attribute has been removed (not required).
• The "styleClass" attribute has been added (applies to the topmost DIV).

• The images attributes of the selectInputDate component have been rationalized:
• "cssImageDirectory" attribute renamed to "imageDir"
• The individual image attributes has been removed. Images are now located in the location specified in the "imageDir" attribute using predefined image names.
• Removed unimplemented attributes (addResources, popupButtonString, popupGotoString, popupTodayString, popupWeekString, popupScrollLeftMessage, popupScrollRightMessage, popupSelectMonthMessage, popupSelectYearMessage, popupSelectDateMessage).

• A bug in the selectInputDate and dataPaginator components that could cause failures when used within an <f:subview> tag has been corrected.

• Label alignment issues on the outputProgress component have been corrected.

• A new Drag & Drop mode was added, "DragGhost". When configured via the "dragOptions" attribute the draggable will create a partially transparent copy of the original component (a "ghost") to be dragged, leaving the original draggable component in place. When dropped, the draggable ghost will disappear.

Facelets

• The icefaces-facelets.jar is now based on Facelets v10.0.14.

• The icefaces-facelets.jar includes a backported fix from Facelets v1.1 that resolves an issue that could cause large EL expressions to be fragmented.

• Corrected issues with several components that prevented them from working well when using Facelets.

• Fixed a bug that prevented the use of abitrary attributes with ICEfaces components when using Facelets.

• Fixed a bug that prevented using an EL expression to set the page <title>.

Example Applications

• A new ICEfaces WebMail example application is provided in source-code form in this release. This example can be used as a reference for ICEfaces developers. The WebMail application is implemented entirerly using the ICEfaces Component Suite components and illustrates rich web application capabilities such as incremental UI updates for all components, asynchronous server-initiated updates for events such as new mail arriving, and drag-and-drop support for sorting mail messages in to folders.

• Minor tweaks and bug fixes to the Component Showcase and Address examples.

Tools

• Sun Java Studio Creator 2 (Early Access)
  
• An Early Access version of ICEfaces integration for Sun Java Studio Creator 2 is included in this release.
• Provides an IDE  extension for creating new ICEfaces JSF projects and working with ICEfaces Sample applications.
• Includes a Studio Creator complib for the ICEfaces Component Suite that supports design-time drag-and-drop visual design in Studio Creator using the ICEfaces components.

• NetBeans v5.x
  
• A ICEfaces integration bundle for NetBeans 5.x will be available shortly after the release of ICEfaces Community Edition v1.0 on the ICEfaces Knowledge Base section for Tools, located here. It was not available in time to be included in the ICEfaces Community Edition v1.0 release.
  

Supported Browsers, Application Servers, & Tools

Browsers

J2EE Application Servers

J2EE Integrated Development Environments (IDEs)

Known Issues

The following are known issues with this release:

JSP Markup

• UIComponentBodyTag processing supports only a single call to doAfterBody(). The full JSP lifecycle for iterative body processing is not supported.

• The first-generation children of the DataTable's table-header and column-header facets must be standard JSF components. For example, plain markup cannot be contained on its own within these facets, it must be wrapped in a panelGrid and the panelGrid, in turn, can be contained within the facet.

• JSP Page to Document conversion escapes &nbsp, but &nbsp in JSP Documents must be manually escaped by the developer as &amp;nbsp. Similarily, & characters must be escaped as &amp;.

• Non-JSF JSP tags (<jsp:xxx/>, etc.) embedded in JSP Pages and Documents are ignored by the ICEfaces parser with the exception of the inclusion mechanism (see Markup Reference in Developer's Guide for details).

• Java code (<% ...%>, etc.) embedded in JSP Pages and Documents is ignored by the ICEfaces parser with the exception of the inclusion mechanism (see Markup Reference in Developer's Guide for details).

• Input documents must be well-formed XML.

• Deprecated HTML elements, specifically the FONT element, do not respond properly to DOM manipulation functions in the ICEfaces client-side JavaScript bridge. (see HTML 4.01 Specification for details on deprected HTML Elements).

• Pages must contain a <HEAD> tag so that ICEfaces can properly add a link to its own custom JavaScript library.

• If the JSF tag <f:loadBundle> is used in a parent page and a child page included via <jsp:include /> references the loadBundle's properties, an exception is thrown.

• Any ICEfaces page included from a JSP via <jsp:include/> must contain a <body> tag as the content of the <body> tag is precisely the content inserted into the including page.

• Tiles tags are not supported within ICEfaces pages, but ICEfaces pages may be included via Tiles.

• If multiple ICEfaces inclusions are performed by the same parent JSP, each ICEfaces form must have a manually applied unique ID.

• JSP Pages are dynamically converted to JSP Documents for processing by the ICEfaces parser, so it is important not to mix JSP Page and JSP document types when performing static inclusion.

General

• If the JSF templates for an application are nested within directories the ICEfaces AJAX bridge will not work properly. The workaround is to create additional mapping entries in web.xml descriptor for each directory.
  

• There are conditions in which the asynchronous communication between the server and browser stops (such as the user pressing the browser "stop" button or allowing their machine to sleep). In this situation, the application server console will show the following exception (including stack trace) with no functional impact: java.lang.RuntimeException: IncrementalNodeWriter Queue limit exceeded:51. The user may need to refresh the page to continue using the application.

• If at any time the asynchronous connection between the browser and the server is lost due to a network interuption, reloading the page will generally restore normal operation.

• ICEfaces pages included via <jsp:include> or <tiles:insert> have distinct PersistentFacesContext objects even if they are included by the same parent page. For this reason, application-initiated renders will apply only to the inclusion associated with the particular PersistentFacesContext.

• Inclusion of ICEfaces content from JSP is not compatible with MyFaces.

• Integration of HTML renderers with the ICEfaces Direct-to-DOM renderers is generally possible but idiosyncrasies have been noted with a small number of custom renderers. In these cases, enclosing the custom tag with a standard JSF panelGrid tag in the source document can help to correct the problem.

ICEfaces Component Suite

• menuBar
  • Menu items' hover behaviour is such that hovering over a menu item should result in highlighting of the entire item. There is an issue in that hovering over the image or its padding area will not result in highlighting of the menu item. Instead the user should hover over the menu item text.
  • When a menu is expanded and the user clicks on one of the menu items, and then the same menu is expanded again, the last-clicked menu item will appear with a dashed outline. This is only an issue in the Firefox or Mozilla browser.

• Effects
• In Internet Explorer the Fade, Appear, and Pulsate effects will not transition when used with select elements.
  
• In Safari the Highlight effect will does not work on buttons and lists.

• Drag & Drop
• In Internet Explorer dragging and holding an image will cause the cursor to change to the not symbol. Operation returns to normal with a second left mouse button click.

• inputFile
  
• The file upload component, <ice:inputFile>, directly writes a containing form in the web page and must not be placed within an <ice:form> or <h:form>.
• When using Firefox / Mozilla and ICEfaces Community Edition with the inputFile component ICEfaces may erroneously report that the connection has been lost while the file upoad is in progress.  To reduce the visual impact of the Connection Lost message, we recommend the use of the outputConnectionStatus component, which will still report a connection problem, but in a much more subtle manner. This is may also be avoided by using the ICEfaces Enterprise Edition.

• panelTabSet
• On Safari browsers only, the layout of the tabs is incorrect, with horizontal spacing between the tabs.
• On Safari browsers only, the tab panel resizes when tabs are selected.

Facelets

• When using Facelets you must use the redirect tag to move from one page to another if you are using navigation rules in your
  faces-config.xml file.

Application Servers

• BEA Weblogic Server 9
• In order to run ICEfaces on the BEA Weblogic Server 9, the html and core tld files located in jsf-impl.jar should be extracted from the jar file and placed into the WEB-INF folder of any application you want to deploy.

• Websphere Application Server 6.0.0.1
• A bug in the application server prevents the Timezone Step 3+ tutorials from running correctly. A Webshpere patch is available from IBM that resolves this issue: APAR numberPQ99195, http://www-1.ibm.com/support/docview.wss?rs=180&uid=swg1PQ99195.
  
• Component effects are not currently supported when hosted on Websphere.

Support

For help with this release please refer to http://support.icesoft.com where you will find the ICEsoft knowledge base including articles, slideshows, and other resources. In addition refer to the ICEfaces Community Edition support forums where you can monitor and participate in discussions on ICEfaces technology, tips, and techniques.  If desired, commercial support options are also available from ICEsoft.

License Notice

License agreements can be found in the .../install_dir/docs/license directory.

© Copyright 2005-2006. ICEsoft Technologies, Inc.