icefaces 2 docs

Space DetailsKey: Name: Description: Creator (Creation Date): ICE ICEfacesThis is the Wiki home for the ICEfaces open-source project. See www.icefaces.org for details.

ken.fyten (Dec 15, 2009)

Last Modifier (Mod. Date): ken.fyten (Oct 29, 2010)

Available Pages ICEfaces 2 Overview ICEfaces 2.x Release Notes ICEfaces 2.0.2 Release Notes ICEfaces 2.0.1 Release Notes ICEfaces 2.0.0 Release Notes ICEfaces 2.0.0 RC2 Release Notes ICEfaces 2.0.0 RC1 Release Notes ICEfaces 2.0.0 Beta 2 Release Notes ICEfaces 2.0.0 Beta 1 Release Notes ICEfaces-2.0.0-Alpha3 Release Notes

ICEfaces-2.0.0-Alpha2 Release Notes ICEfaces 2 Documentation ICEfaces 2 Features Getting Started Downloading ICEfaces Supported Platforms Adding ICEfaces to Your Application Building and Running ICEfaces Examples with Maven

Building and Running ICEfaces with Ant Key Concepts Automatic Ajax Direct-to-DOM Rendering Single Submit Ajax Push - Overview Core Framework Ajax Push - APIs Core Tags Annotations JavaScript Client API Handling Exceptions Configuration ICEpush Configuration

JSF Configuration ComponentsPage 1

Document generated by Confluence on Jan 19, 2012 16:38

ICEfaces Components ICEfaces 2.0 Advanced Components Animation 2.0 CheckboxButton 2.0 DateTimeEntry 2.0 FileEntry 2.0 LinkButton 2.0 PushButton 2.0 SliderEntry 2.0

TabSet 2.0 ICEfaces Advanced Components Environment ACE ThemeRoller support ACE Source Artefacts and Generated Outputs ACE Meta Class ACE Component and Renderer Classes ACE Adding Resources to Meta Class ACE Skinning ACE Sprite Image Generation ACE CSS URL Mapping

ACE Disabled Styling Standard Portlet Development ICEfaces 1.x Compatibility

API Documentation Tutorials Introductory Tutorials Creating ICEfaces 2.1 Applications with Eclipse Getting Started with ICEfaces 2 Creating ICEfaces Applications with Eclipse Converting ICEfaces 1.8 Applications to ICEfaces 2

Converting ICEfaces 1.8 Components to ICEfaces 2 ICEfaces Feature Tutorial Easy Ajax Push Using Single Submit Using Window Scope ICEfaces Component Tutorials Auto-Complete Calendar Chart Columns Connection Status Data Table Drag & Drop EffectsPage 2


Menu Bar Panel Series Popup Progress Bar

Tree ICEfaces Advanced Component Tutorials Incremental Upload Processing Using FileEntryCallback General Tutorials Creating Your First Hibernate-Enabled Application Using ICEfaces with CDI Using ICEfaces with Spring Spring Web Flow 2 Spring Security Converters Creating a Composite Component Internationalization in ICEfaces Validators


Page 3

ICEfaces 2 OverviewThis page last changed on Mar 16, 2011 by feras.nasser.

A New StandardICEfaces 2 is an open-source Rich Internet Application (RIA) development framework based on the JavaServer Faces (JSF) 2 standard. Like its predecessor, ICEfaces 1.8, ICEfaces 2 extends JSF to simplify development and enhance the standard JSF feature set - simultaneously improving developer efficiency and expanding the spectrum of RIA capabilities that can be included in any JSF-based web application. Adhering closely to the standard JSF 2 extension points allows ICEfaces to work transparently with the stock JSF framework, simplifying integration and fostering 3rd party compatibility with other JSF 2compliant libraries.

Revolutionize RIA DevelopmentKey ICEfaces 2 framework extensions vastly simplify development, and expand the feature set of JSF 2. Automatic Ajax drastically simplifies JSF development by eliminating the need for JSF tags. Direct-to-DOM Rendering calculates the precise set of page changes from one request to the next, and Single Submit automatically submits individual components for processing. ICEfaces handles all of the Ajax underpinnings, allowing you to focus on application functionality. Ajax Push enables real-time, multi-user collaboration in your JSF applications. Any state change in the application can instantaneously trigger push updates to other users of the application that need to be informed. New Ajax Push APIs make it simpler than ever to add collaborative features to your application. A complete list of framework enhancements can be found here.

Rich ComponentsICEfaces 2 offers a vast array of rich components from with to craft your user interfaces. The ICEfaces Components include all components from ICEfaces 1.8 and use a compatibility layer that enables them to function with JSF 2.0, and ICEfaces 2. These components provide a smooth migration path from ICEfaces 1.8. The ICEfaces Advanced Components leverage all the features of the JSF 2.0 component architecture, and are based on the all-new Advanced Component Environment (ACE). The YUI JavaScript library provides rich, client-side web controls, but packaged as JSF components, so you don't need to know or use any JavaScript to include them in your application. Important features of the Advanced Components include flexible form definition, UI theming/skinning, and W3C ARIA accessibility. The ICEfaces Enterprise Components are derived from the ICEfaces 1.8 Composite Component, but ported to the new JSF 2.0 Facelet architecture. Originally created by the ICEfaces application development team, these components can greatly reduce development time for a host of common application use cases. These components are available only in ICEfaces 2 Enterprise Edition.

ToolsICEfaces 2 can be easily integrated into any Java EE development environment. In particular, IDE integration bundles are available for the open source IDEs Eclipse, and NetBeans.

Open Source and Enterprise GradeICEfaces 2 is an open source project licensed under Mozilla Public License, so you can develop and deploy with it, without any commercial licensing restrictions. You get all the advantages of a vibrant


Page 4

open source community, including a well-exercised code base, developer forums, and this wiki loaded with documentation and tutorials. ICEfaces is also enterprise grade software that is deployed in a wide range of Fortune 500 companies. If you need the assurances of professional support, you will get that and more from ICEfaces 2 Enterprise Edition (EE). With EE you get additional software, documentation, and deployment technologies like the Enterprise Push Server. You can learn more about the features and benefits of ICEfaces 2 EE here.


Page 5

ICEfaces 2.x Release NotesThis page last changed on Dec 22, 2011 by ken.fyten.

ICEfaces Release Notes

Latest Release

Version ICEfaces 3.0.0 RC2

Date 2011-12-22

Latest Stable Release

Version ICEfaces 2.0.2

Date 2011-05-13

Older Releases

Version ICEfaces 2.1.0 BETA 2 ICEfaces 2.1.0 BETA ICEfaces 2.0.1 ICEfaces 2.0.0

Date 2011-11-04 2011-10-04 2011-03-30 2010-12-21


Page 6

ICEfaces 2.0.2 Release NotesThis page last changed on May 13, 2011 by ken.fyten.

ICEfaces 2.0.2 Release NotesMay 13th, 2011 Cannot resolve external resource into attachment.

ContentsThese Release Notes include the following sections: About This Release Downloads Notable Changes Mojarra JSF 2.1.1-FCS Core Framework Changes Advanced Components Portlets Samples and Tutorials IDE Integrations Supported Platforms Known Issues Support

About This ReleaseICEfaces 2.0.2 is an official maintenance release featuring over 25 fixes and improvements.

DownloadsICEfaces 2.0.2 is available for download in the following formats: Binary and source-code bundles IDE Tool integration bundles Maven2 Public Repository (jars only) SVN repository checkout

Notable Changes in this Release

Mojarra JSF 2.1.1-FCS This release has been tested against Mojarra JSF 2.1.1-FCS, and includes the JSF 2.1.1-FCS libraries in the download bundles. Note that JSF 2.1.1-FCS is referred to as 2.1.1_b04 in the public Mojarra Maven repository.

Core Framework Delta-Submit


Page 7

Several issues that could cause problems when using Delta-Submit in specific circumstances have been resolved.

ICEfaces Advanced Components Support for Portlets The Advanced Components are now supported on Liferay 5.2. There remains a YUI-namespace collision issue that prevents the Advanced Components from being deployed to Liferay 6. See the Known Issues section for details. This issue is expected to be resolved with ICEfaces 2.1. Reduced JavaScript and CSS Static Footprint The Advanced Components now leverage compressed and combined JavaScript and CSS files which further reduces the number and size of the resource files that must loaded when initially visiting the page. The net result is that pages using the Advanced Components now load dramatically faster and overall response time when navigating between pages is substantially improved. A bug that prevented deploying ICEfaces applications that use ACE components to the ROOT context has been resolved. The focus indicator on the ace:sliderEntry component has been reduced in size. Previously it could grow to the width/height of the container in some browsers.

PortletFaces Bridge The included PortletFaces Bridge library has been updated to the 2.0.0 final release.

Samples & Tutorials Component Showcase Styling bugs in the panelTooltip and panelPositioned demos have been fixed.

IDE Integrations NetBeans 7 This release provides a new IDE integration for NetBeans 7. Eclipse 3.6 Eclipse 3.6 is also supported. MyEclipse 9.0.1 MyEclipse 9.0.1 will include an ICEfaces 2.0.2 integration (when released by Genuitec). Change Log For a complete list of all changes in this release, see the related JIRA Change Log.

Supported PlatformsThis release has been tested on the following: JSF Runtimes Mojarra JSF 2.1.1-FCS / JSF 2.1.1-b04 This version is included in the release bundles Browsers Google Chrome 10


Page 8

Mozilla Firefox 3.6, 4.0 Microsoft IE 8, IE 9 Apple Safari 5 Application Servers Tomcat 6, 7 Glassfish 3.1 JBoss 6.0 Portal Containers Liferay Portal 5.2.3, 6.0.6 Using PortletFaces Bridge v2.0.0

Known IssuesThe following section describes the most commonly encountered known issues with this release: General JSPs are not supported by ICEfaces 2.0 - use Facelets. It is required to specify "h:head" and "h:body" tags in your ICEfaces application pages. The Delta-Submit function does not support cases where an Ajax DOM update in the browser dynamically introduces new form elements into the DOM that were not part of the form when the page was originally loaded. In order to use Delta-Submit successfully all form elements / components must be present on the page at the time the page is loaded. Due to an apparent bug in the Sun Mojarra JSF 2 runtime library, component binding is not reliable when used within a View scope. The recommended workaround is to use the ICEfaces "Window" or JSF "Session" scopes instead if component-binding is required. Alternatively, applications can be modified to avoid the requirement for using component-binding in View scope by using techniques similar to that used in the Data Paginator demo section of Compatible Component Showcase application. For details, see ICE-5226. ICEfaces Components ice:inputRichText The inputRichText component is not currently supported on IE9. This issue will be resolved in a future release. Advanced Components ace:fileEntry - occasionally the JavaScript error "Failed to load resource: javax.faces.resource/ listen.icepush.jsf" will appear in the JavaScript console after a successful file upload. This error can be ignored as it has no functional impact. Liferay Portal 6 The Advanced Components are not currently supported on Liferay Portal 6, with the exception of the fileEntry component (Liferay 5.2 is supported). Using the fileEntry component on Liferay 6 requires that the mandatoryResourceConfiguration configuration parameter be set in the web.xml as follows:

org.icefaces.mandatoryResourceConfiguration


Page 9

javax.faces.FACELETS_SKIP_COMMENTS true

If you are using the ICEfaces Components (icefaces-compat.jar) in your application, the following additional configuration steps are required: Required web.xml entries

com.icesoft.faces.gmapKey ABQIAAAADlu0ZiSTam64EKaCQr9eTRTOTuQNzJNXRlYRLknj4cQ89tFfpxTEqxQnVWL4k55OPICgF5_SOZE06A Resource Servlet com.icesoft.faces.webapp.CompatResourceServlet 1 Resource Servlet /xmlhttp/* Faces Servlet /icefaces/*

3rd Party Dependencies If you are using the ICEfaces Components you will also require additional 3rd party libraries. Libraries servlet-profile : Tomcat web-profile : JBoss 6, Glassfish 3 ? ?

commons-beanutils.jar commons-logging.jar jsf-api.jar jsf-impl.jar jxl.jar

? ? ? ? ?

?


Page 46

krysalis-jCharts-1.0.0alpha-1.jar

?

?

Optional ConfigurationWith ICEfaces 2 there is no need for a faces-config.xml file, but if you are using one in your application or for your own components, remember to use the new schema for JSF 2:

... New Project. Select Maven then Maven Project, Click Next. Click Add and enter in the following values: 1. 2. 3. 4. 5. 6. Group ID: org.icefaces Artifact ID: icefaces-compat-webapp-archetype Version: 2.0.0 Repository: http://anonsvn.icefaces.org/repo/maven2/snapshots/ Click OK, then Next. Enter in Project Name and other information.

Click Finish.


Page 51

Building and Running ICEfaces with AntThis page last changed on Dec 15, 2010 by jack.van.ooststroom.

Building ICEfacesIf you have downloaded the Source distribution bundle of ICEfaces 2, you will need to compile and build the ICEfaces libraries before using them. The ICEfaces 2 Binary distribution bundle comes with prebuilt ICEfaces libraries so building is not necessary. To build ICEfaces, open a console or shell and navigate to the "icefaces" directory where you unzipped the ICEfaces distribution. Then, in the console, type the following and press Enter:

ant allclean world

This builds all of the ICEfaces libraries and sample applications suitable for deployment to any JEE 6 Servlet Profile platform, such as Tomcat 6/7 and Jetty 7. If you'd like to build specific pieces of the distribution, type:

ant -p

to get a list of the available targets (e.g. ant core). It's recommended that you build everything the first time to ensure all the required libraries are created.

Running the ExamplesThe ICEfaces 2.0 distribution comes with example applications that illustrate the key features of ICEfaces 2 as well as providing source code and guidance about configuration and library dependencies. The default build target, "ant ", is mapped to the "servlet-profile" build target, which builds a version of the sample application suitable for deployment to any Servlet Profile platform, such as Tomcat 6/7 and Jetty 7, and includes both the icefaces.jar and the icepush.jar for Ajax Push support. The default build behavior can be modified using either the convenience targets in the build file or the properties as follows:

ant servlet-profile

This includes jsf-*.jar files, icefaces.jar and icepush.jar.

ant web-profile

This includes icefaces.jar and icepush.jar. Properties can also be used with the ant command to exclude the related .jar files from the .war file:


Page 52

ant -Dno-icefaces='' -Dno-icepush=''

The "no-icefaces" property excludes all ICEfaces and ICEpush related .jar files where the "no-icepush" property only excludes the ICEpush related .jar file. JSF 2 Examples The examples under [icefaces2.install.dir]/icefaces/samples/core do not use the ICEfaces Component Suite. These applications use only standard JSF 2 components enhanced with the core ICEfaces framework. As such, they require far fewer library dependencies. The main example is Auction - a version of the original ICEfaces 1.8 Auction Monitor application ported to run on ICEfaces 2 but modified to use only JSF standard components and ICEpush. To run any of the pure JSF 2 examples, open a console or shell and navigate to the directory (e.g. [icefaces2.install.dir]/ icefaces/samples/core/auction), type:

ant -p

And press Enter. This displays a list of build targets for various platforms.Component Suite Example

The examples under the [icefaces2.install.dir]/icefaces/samples/compat directory use the ICEfaces Component Suite for ICEfaces 2. The main example is the Component Showcase - a version of the original ICEfaces 1.8 Component Showcase ported to run on ICEfaces 2. To run any of the compatibility examples, open a console or shell and navigate to the directory (e.g. [icefaces2.install.dir]/icefaces/samples/compat/component-showcase), and type:

ant -p

And press Enter. This displays a list of build targets for various platforms. The resulting .war files of the Compat samples includes the icefaces-compat.jar as an ICEfaces related .jar file. Using the "no-icefaces" property additionally excludes the icefaces-compat.jar.Advanced Component Example

There is a showcase example of the Advanced Components available under:

icefaces/samples/ace/showcase

To see a list of the available build targets, navigate to the directory in your shell or console and type:

ant -p

then press Enter. This displays a list of build targets for various platforms.


Page 53

The resulting .war files of the ACE samples includes the icefaces-ace.jar as an ICEfaces related .jar file. Using the "no-icefaces" property additionally excludes the icefaces-ace.jar.


Page 54

Key ConceptsThis page last changed on Oct 29, 2010 by ken.fyten.

ICEfaces Key Concepts Automatic Ajax Direct-to-DOM Rendering Single Submit Ajax Push - Overview


Page 55

Automatic AjaxThis page last changed on Jan 18, 2012 by ted.goddard.

DefinitionAutomatic Ajax is a mechanism in the ICEfaces framework that calculates precise/minimal page updates from one JSF lifecyle to the next, eliminating the need for standard JSF tags in the page.

Comparing Automatic Ajax with Standard JSF AjaxJSF TagJSF 2 includes Ajax capabilities with the tag. adds client-side behavior to its parent component, enabling it to perform an Ajax submission, cause execution of the JSF lifecycle, and ultimately render new view content to be inserted in the page. The page designer controls what type of event causes the submit to occur, and defines what components participate in the execute phase and what components must render as a result of the execute phase. The following page snippet illustrates an input field causing an output field to update when the user modifies and tabs out of the input field.

The sequence of events resulting in a page update based on this markup is illustrated below.

1. 2. 3. 4.

User interacts with the input field and tabs out of it. onBlur event causes tag to execute. Ajax Request is generated back to application. JSF lifecycle executes on the inputText component only, updating the model.


Page 56

5. JSF render phase runs on outputText component only. 6. Response is generated with page update containing markup associated with outputText. 7. DOM update is applied to the outputText text field in the DOM. The application of is simple in a trivial use case such as this, but as page complexity increases so does the complexity of defining appropriate tags, and if you get it wrong, your application can become ill behaved.

In the final analysis, it proves unreasonable to wire tags into a complex page to achieve optimal/minimal page updates. It becomes necessary to wire together broader regions of a page that may need updating based on some event, resulting in larger page updates than actually required.

Automatic Ajax with ICEfacesICEfaces Automatic Ajax feature guarantees minimal page updates under any condition, and does not require the page developer to consider how, when or why page updates occur. The key to Automatic Ajax is the use of Direct-to-DOM (D2D) rendering in the ICEfaces framework. D2D does just what it says, and writes the output of the JSF rendering phase into a server-side DOM that represents exactly what the client DOM needs be. Using a cached version of the DOM, the framework calculates precisely the set of DOM updates required to affect the changes in the page at the completion of any JSF lifecycle. While D2D handles the page updating aspect, it is still necessary to initiate the whole process through some UI event. ICEfaces provides the Single Submit features, which causes a component to submit itself automatically when the user interacts with it. It act much like a

but does not update the entire page, as the D2D mechanism intercepts the page update and calculates the precise, minimal set of updates required. In the ICEfaces Advanced Components, Single Submit is controlled through the singleSubmit attribute. For other components, the tag can wrap any number of components and enable them for single submission. Returning now to our trivial example, the JSF markup in an ICEfaces page would look like:


Page 57

The sequence of events resulting in a page update based on this markup is illustrated below.

1. 2. 3. 4. 5. 6. 7.

User interacts with the input field and tabs out of it. onBlur event cause singleSubmit to occur on inputText. Ajax Request is generated from singleSubmit. JSF lifecycle executes on the inputText component only, and model is updated. JSF render phase runs on entire component tree producing a server-side DOM. DOM differences are calculated and page update to outputText is generated in the response. DOM update is applied to the outputText text field in the DOM.

The beauty of this solution is that regardless of how complex the page becomes, minimal additional markup is required to ensure it behaves properly. You only needs to define what components are enabled with singleSubmit, and the ICEfaces framework does the rest.

Optimizing Automatic AjaxAutomatic Ajax optimizes development time, but there is a trade off at run time as it is necessary to render the entire page to produce the DOM for comparison. It is possible to optimize this rendering with tags that override the render="@all" behavior used to singleSubmit on a given component. Attaching a tag as a child of any component will override the singleSubmit behavior of that component and allow the developer to specify a subset of the component tree that should render. The ICEfaces framework detects this partial rendering and performs D2D only on that specific subset of the component tree. Returning to our trivial example, the following markup will ensure that only the outputText is rendered.


Page 58

Of course, this sort of optimization is unnecessary in such a trivial example, but could prove useful in more complex pages. Most importantly, it is an optimization, not a necessity. Optimizations can be applied near the end of the development cycle, when the characteristics of the application are well understood, and proper behavior has been well established.


Page 59

Direct-to-DOM RenderingThis page last changed on Feb 16, 2011 by steve.maryka.

DefinitionDirect-to-DOM (D2D) rendering is a mechanism that renders a JSF component tree into a W3C standard DOM. When the rendered DOM is cached between JSF lifecyles, it can be used to compute the difference between 2 successive page views, to determine a precise set of DOM changes required to update the page from one view to the next. D2D rendering is core to the Automatic Ajax feature of the ICEfaces 2.0 framework.

D2D FundamentalsRenderingD2D rending does just what it says, it renders a JSF component tree directly into a DOM, as illustrated in the following diagram:


Page 60

When the ICEfaces 2.0 Jar is added to a JSF application, the standard RenderKit is overridden with the ICEfaces RenderKit, and specifically, the ICEfaces RenderKit provides a DomResponseWriter instead of the standard JSF ResponseWriter. The DomResponseWriter diverts the output of any component renderer into a server-side DOM data structure.

DOM DifferencingA newly produced DOM from the D2D rendering process represents the page that will be replicated in the client browser DOM. The cached previous DOM is a replica of the DOM currently in the client browser, so the difference between the two DOMs defines the page updates that need to occur at the client browser. The differencing mechanism performs the basic task of calculating the set of updates to transform one DOM into the next, but the implementation in ICEfaces 2.0 has been highly optimized.

Page UpdatingGiven the set of page updates from the differencing algorithm, the standard JSF Ajax mechanism is used to deliver and insert those updates into the client DOM, thus completing the JSF lifecyle with D2D rendering. The whole process is illustrated below:


Page 61

1. 2. 3. 4.

User interacts with some browser control in the page. Ajax Event generated for singleSubmit. Ajax Request sent to the application. The JSF lifecycle executes on a single component in the component tree, updating the model appropriately. 5. Render phase traverses entire component tree, and D2D calculates necessary page updates. 6. Page updates are returned in the Ajax Response. 7. Standard JSF mechanism updates the client-side DOM with page updates.


Page 62

Single SubmitThis page last changed on Jan 18, 2012 by ted.goddard.

DefinitionSingle Submit provides the ability to submit one component to execute in the JSF lifecycle, and is integral to the Automatic Ajax mechanism in ICEfaces 2. This means that only the specified component will decode, validate, update its bean model state, and trigger events, but a full render phase will occur. Direct-to-DOM Rendering is then used to determine the set of incremental page updates that must occur in the client browser DOM.

Comparison with Partial SubmitSingle Submit is similar in intent to ICEfaces 1.8.x Partial Submit, but is an improvement which leverages JSF 2's expanded capabilities. With Partial Submit, every component in the submitted form still executes, but the other components' required properties are temporarily disabled, which allows them to pass required validation, but does not stop their validators from running, which can cause FacesMessages to be created for components which the user had not yet interacted with. Single Submit will not cause the errant FacesMessages, as it will not execute any undesired validation. So, if the input for the submitted component are valid, then the bean model's state is guaranteed to be updated, which could not be guaranteed with Partial Submit, as another component in the form could have a validator, and cause the UpdateModel phase to not execute. Also, Single Submit is more performant, as it skips executing the undesired components, and does not manipulate required attributes on other components.

singleSubmit AttributeOn each of the ICEfaces Advanced Components, the feature is controlled via a singleSubmit attribute. In general, components can be classified by three categories: input, command, and container. Complex components may have aspects of functionality from more than one category. For the singleSubmit attribute, it has two distinct meanings, one if the component is primarily an input component, and one if it is primarily a command component. What is similar between the two, is that when singleSubmit="true", the component deviates from its default behavior such that only that component will submit and execute. The default value is false. Input components usually have javax.faces.component.UIInput as a superclass. Examples of input components are: h:inputText, h:selectOneMenu and ice:checkboxButton. With an input component, when singleSubmit="true", changing the value of this component will submit and execute this component only. This is equivalent to having set inside the standard h: components. When singleSubmit="false", no submit occurs. Command components usually have javax.faces.component.UICommand as a superclass. Examples of input components are: h:commandButon, h:commandLink and ice:pushButton. With a command component, when singleSubmit="true", triggering an action on this component will submit and execute this component only. This is equivalent to having set inside the standard h: components. When singleSubmit="false", triggering an action on this component will submit and execute the full form that this component is contained within.

TagThe tag is a convenient and easy way to Single Submit enable standard h: components without having to litter the page with tags. It allows an entire page region to be enabled at once. The behavior can be configured via the attribute submitOnBlur="true", such as to cause form submission to occur on "blur" events as well as "change" events. (For example, this is necessary if "required" validation is expected to run each time a user visits a field.)


Page 63

With Cancel ButtonsWhen making a cancel button, or any other button whose goal is to skip any form validation, avoid the UpdateModel phase, and potentially navigate to another page, the best practice has changed. In the past, it was best to have immediate="true" and partialSubmit="true" on the cancel button, to achieve those goals. Now, it's possible, to instead use one of the above single submit mechanisms. This is better because using single submit to only execute the cancel button means that no other component will be validated or do their UpdateModel phase, since they won't be executed at all. Single submit is more efficient, and safer, as it has no edge cases, like if an input component itself has immediate="true" and uses a custom validator.

FacesMessage CachingWhen JSF completes a lifecycle, it discards all of the FacesMessage objects that have been added to the FacesContext. This means that next lifecycle, any pertinent FacesMessage objects have to be recreated and re-added to the FacesContext, for h:message components to be able to display them. When doing full form submits, where every component in the form is executed, this is not a problem, as every component will get its chance to add whatever FacesMessage objects are appropriate. When doing partial executes, either because of Single Submit, or because of tags, then certain portions of the view will not execute, and any FacesMessage objects they had previously added to the FacesContext will be lost. This might mislead the user to thinking that the fields they had previously interacted with, and misentered data in, are now valid. ICEfaces 2 carries forward these FacesMessages, until either a full form submit and execute occurs, or until those specific components are executed again.


Page 64

Ajax Push - OverviewThis page last changed on Dec 13, 2010 by robert.lepack.

DefinitionAjax Push allows the application to incrementally update any part of the page at any time, for any group of clients. This is a small change in terms of the technical capabilities of Ajax applications, but it is a revolutionary change in terms of what applications can actually provide to users. Ajax Push is the key to building collaborative multi-user applications for the web.

Under the HoodThe intricacies of the Ajax Push implementation are completely transparent to the ICEfaces developer, as you work with a straightforward set of APIs. It is, however, useful to understand the basic mechanics. Ajax Push in ICEfaces 2.0 leverages an asynchronous notification mechanism call ICEpush. Simply put, ICEpush uses long polling to provide asynchronous notification over standard HTTP, using only standard browser capabilities. The sequence of events involved in Ajax Push is illustrated below.

1. 2. 3. 4.

Some state change in the application triggers an Ajax Push event. ICEpush notification is delivered to the browser client over a dedicated ICEpush connection. Notification at client browser causes a JSF Ajax request with an empty execute phase. Render phase captures new state of client, and Direct to DOM Rendering delivers incremental page updates to client.

The diagram shows a single client recipient of a push, but the mechanism supports named groups of clients that all receive notifications. ICEpush handles all aspects of the asynchronous blocking connections involved, including connection management/sharing, heartbeating, and ARP integration.

Programming ModelAjax Push can be added to an application with just two lines of code. The org.icefaces.application.PushRenderer pushes page updates to groups of pages. To cause all pages in "someGroup" to be updated with the current server state, call


Page 65

PushRenderer.render("someGroup");

The easiest way to assemble push groups is to push updates to all pages in a user's session using

PushRenderer.addCurrentSession("someGroup");

To distinguish between individual pages in a session, use

PushRenderer.addCurrentView("someGroup");

It really is as simple as that to add real-time collaboration to your JSF application. Checkout the full API for more details.

DeploymentBecause of the underlying asynchronous blocking connections used by the ICEpush notifications, there are a couple of deployment considerations for Ajax Push-enabled applications.

ARPICEpush relies on Servlet 3.0 standard ARP APIs. If they are not present in the deployment environment, normal thread blocking connections are used.

Enterprise Push ServerFor clustered and high-availability deployments of Ajax Push-enabled applications the Enterprise Push Server (EPS) is required. It manages asynchronous blocking connections across the cluster and performs seamless fail over for mission-critical, high-availability deployments. EPS is available in ICEfaces Enterprise Edition.


Page 66

Core FrameworkThis page last changed on Dec 09, 2010 by steve.maryka.

ICEfaces 2 Core Framework Features Ajax Push - APIs Core Tags Annotations JavaScript Client API Handling Exceptions Configuration ICEpush Configuration JSF Configuration


Page 67

Ajax Push - APIsThis page last changed on Nov 25, 2011 by ken.fyten.

OverviewAjax Push enables real-time collaborative applications, based on a mechanism call ICEpush. Check out the Ajax Push overview before delving into the API.

ICEpush Library - icepush.jarTo enable Ajax Push with ICEfaces 2, you simply include the icepush.jar library with your application.

APIPushRendererICEfaces 2 provides a new API for using Ajax Push from within your application. The main class of relevance is org.icefaces.application.PushRenderer, which contains the methods to support Ajax Push in your application. The PushRenderer API is similar to the SessionRenderer API from ICEfaces 1.8.x, and revolves around establishing named groups of pages, and asking them to update themselves in response to an Ajax Push trigger.

Group ManagementGroup naming is performed in some application-specific manner using the following APIs: Add a session and all associated pages (views) to a group using,

PushRenderer.addCurrentSession(String groupName);

Add only a particular page to a group using,

PushRenderer.addCurrentView(String groupName);

You can also remove sessions or views from a group.

PushRenderer.removeCurrentView(String groupName); PushRenderer.removeCurrentSession(String groupName);

The PushRenderer automatically manages the removal of unused group members, so programmatic removal is not strictly necessary.

Push RenderingWhen something of note changes in the application, you can push to a group using,


Page 68

PushRenderer.render(groupName);

Pushing from outside the JSF contextAll APIs described so far must be called from inside a JSF context. This is typical in collaborative interactions, as Ajax Push is triggered by a user of the application, and thus from inside the JSF context for that user. Other trigger points could come from outside the JSF context, such as a web service, messaging services, or a database. A portable handle to the PushContext is made available using,

PortableRenderer PushRenderer.getPortableRenderer();

And elsewhere in the non-contextual code, trigger a push using,

PortableRenderer.render(String groupName);

PortingAPI changesIn ICEfaces 1.8.x, there were two distinct APIs available for using Ajax Push.

SessionRendererThere is a compatible version of the com.icesoft.faces.async.render.SessionRenderer based on the org.icefaces.application.PushRenderer. The SessionRenderer exposes an API that is compatible with ICEfaces 1.8.x, so applications that used the SessionRenderer API in ICEfaces 1.8.x should be transparently mapped to use the new PushRenderer.

RenderManager and RenderableThe RenderManager API is not supported in ICEfaces 2. Specifically, this means that the following classes are not available in ICEfaces 2.0: com.icesoft.faces.async.render.RenderManager com.icesoft.faces.async.render.Renderable com.icesoft.faces.async.render.OnDemandRenderer com.icesoft.faces.async.render.IntervalRenderer com.icesoft.faces.webapp.xmlhttp.PersistentFacesState The recommendation for porting existing applications is to change the code to use the PushRenderer API. For IntervalRenderer-equivalent functionality based on PushRenderer and java.util.Timer, see the ClockBean of the Auction demo. The Auction example can be found under [icefaces2.install.dir]/samples/ auction.


Page 69

ICEpush ConfigurationThe ICEpush library supports specific configuration parameters that can be used to optimize performance and reliability as required. Details on ICEpush configuration can be found in the ICEpush Configuration Parameters topic in the ICEpush product Wiki.


Page 70

Core TagsThis page last changed on Dec 04, 2011 by mark.collette.

Core TagsTo use any of the core tags, first declare the core namespace:

The ICEfaces 2 core framework supports the following tags in your Facelets markup:

The tag is designed to allow submission from just the component generating the event and then update the page with any changes from all components. It's used in the following way:

...

More detailed information can be found in the Single Submit section.

You can use the ICEfaces configuration tag to adjust behaviour on a per-page basis. These settings take precedence over corresponding application global settings specified via context-param entries in the web.xml. To do so, add the tag to the page and then set one or more of the following attributes:ariaEnabled

Allows control of DOM rendering on a per-page basis. By default, when ICEfaces is available, ARIA support is enabled. By using this setting in in conjunction with the application-scoped org.icefaces.aria.enabled context parameter, you can control whether or not ARIA support is active on an individual page.mandatoryResource

[As of ICEfaces 3.0]

A space-delimited list of components that will have their requisite resources pre-loaded on this page. The pre-loading allows the components to function correctly even if they are later added to the page dynamically. The values "none" (which is the default) and "all" are also valid. The value of this attribute on a page takes precedence over the values specified by the context parameter org.icefaces.mandatoryResourceConfiguration. See Configuration#mandatoryResourceConfiguration for additional details.


Page 71

messagePersistence

[As of ICEfaces 3.0]

Allows control of message persistence on a per-page basis. By default, when ICEfaces is available, FacesMessages are persisted across different partial submits from the same page. This setting can be used to disable this behavior on a per-page basis.render

Allows control of DOM rendering on a per-page basis. By default, when ICEfaces is available, DOM rendering and partial page updates are enabled for stock JSF components. By using this setting in in conjunction with the application-scoped org.icefaces.render.auto context parameter, you can control whether or not ICEfaces is active on an individual page. See Configuration for additional details.

[As of ICEfaces 3.0] You can use the ICEfaces push tag to configure push behavior on a per-view basis. To do so, add the tag to the page and then set one or more attributes. A view can be added to one or more push groups by adding one or more occurrences of this tag.group

Allows control of the current view being added to a push group. This is a mandatory attribute specifying the group the view must be added to.


Page 72

AnnotationsThis page last changed on Mar 03, 2011 by deryk.sinotte.

[email protected] postback navigation, where the result of a navigation event returns the same view id, the default behaviour for JavaServer Faces is to create a new view instance. This also means a new map of viewscoped beans where all the previous view-scoped beans are disposed and new instances created. By adding the @ViewRetained annotation to a bean in View scope, that bean instance is propagated across the navigation to the new view map. This only occurs during postback, where the id of the original view and the new view are the same. The benefit is that view-scoped beans can have consistent state during postback, and not appear to reset themselves. To use the annotation, simply import it and add it to the class of the view-scoped bean that you'd like to retain:

package org.icefaces.demo; import javax.faces.bean.ManagedBean; import javax.faces.bean.ViewScoped; import java.io.Serializable; import org.icefaces.bean.ViewRetained; @ManagedBean(name = "myViewScopedBean") @ViewScoped @ViewRetained public class MyViewScopedBean implements Serializable { ...

@org.icefaces.bean.WindowDisposedA view-scoped bean annotated with @WindowDisposed is removed from the View map when the browser window associated with that view is closed. With stock JavaServer Faces, view-scoped beans are disposed when the session expires. By using ICEfaces and the @WindowDisposed annotation, view-scoped beans can be disposed in a more timely fashion resulting in more efficient use of resources.

package org.icefaces.demo; import javax.faces.bean.ManagedBean; import javax.faces.bean.ViewScoped; import java.io.Serializable; import org.icefaces.bean.WindowDisposed; @ManagedBean(name = "myViewScopedBean") @ViewScoped @WindowDisposed public class MyViewScopedBean implements Serializable { ...


Page 73

JavaScript Client APIThis page last changed on Sep 19, 2011 by mircea.toma.

JavaScript Client APIICEfaces 2 provides a client-side JavaScript API that allows developers access to various features like form submission, event callbacks, and Ajax Push connection monitoring.

NamespaceThe namespace used for the ICEfaces client API is 'ice'. It is defined in the bridge.js file, a link to which is automatically rendered out to each page that uses ICEfaces.

Form Submission APIThe functions here allow developers access to the specialized types of form submission (e.g. partial, full, single) provided by ICEfaces. ice.submit(event, element) or ice.s(event, element) This is the full submit function that behaves much like a traditional form submission where all form items are posted to the request. Usage:

ice.submit(myEvent, theSubmittingElement);

Parameters: event The event captured by the event handler. element The element owning the event handler. ice.se(event, element) and ice.ser(event, element) These functions submit a single element rather than all the elements of the form. This kind of submission reduces the elements serialization overhead and also increases the communication efficiency with the server. Usage: ice.se sends javax.faces.partial.execute=@this and javax.faces.partial.render=@all along with the serialized element and event.

ice.se(myEvent, theSubmittingElement);

ice.ser sends javax.faces.partial.execute=@this and javax.faces.partial.render=@this along with the serialized element and event.


Page 74

ice.ser(myEvent, theSubmittingElement);

Parameters: event The event captured by the event handler. element The element owning the event handler.

Event Callback APIThe functions here allow developers access to the main events that occur in the ICEfaces client-side bridge. This API complements the existing API that's available in JSF 2 that allows the developer to register callbacks for general event and error handling. The ICEfaces API is designed in much the same way as the JSF API. Callback functions are registered that allow the developer to tap into several types of client events that are specific to ICEfaces. ice.onAfterUpdate(callback) Accepts a reference to a callback function. The callback function will be invoked after the updates are applied to the DOM. Usage:

ice.onAfterUpdate(postUpdateHandler); ... var postUpdateHandler = function(updates) { ... };

Parameters: updates A set of elements as defined in the JSF 2.0 JavaScript API documentation (see jsf.ajax.response in http://java.sun.com/javaee/javaserverfaces/2.0/docs/js-api/symbols/ jsf.ajax.html). ice.onBeforeUpdate(callback) Accepts a reference to a callback function. The callback function will be invoked before the updates are applied to the DOM. Usage:

ice.onBeforeUpdate(preUpdateHandler); ... var preUpdateHandler = function(updates) { ... };

Parameters:


Page 75

updates A set of elements as defined in the JSF 2.0 JavaScript API documentation (see jsf.ajax.response in http://java.sun.com/javaee/javaserverfaces/2.0/docs/js-api/symbols/ jsf.ajax.html). ice.onServerError(callback) Accepts a reference to a callback function. The callback function will be invoked when a server error is received by the browser from a JSF form submit. Usage:

ice.onServerError(serverErrorHandler); ... var serverErrorHandler = function(statusCode, responseText, responseDOM) { ... };

Parameters: statusCode The HTTP status code. responseText The body of the HTTP response in text format. responseDOM The parsed body of the HTTP response as XML. This parameter is present only when response is in XML/HTML format. ice.onSessionExpiry(callback) Accepts a reference to a callback function. The callback function will be invoked when the HTTP session has been invalidated or expired. Usage:

ice.onSessionExpiry(sessionExpiryHandler); ... var sessionExpiryHandler = function() { ... };

ice.onNetworkError(callback) Accepts a reference to a callback function. The callback function will be invoked when a network error is detected by the browser during a request-response. Usage:

ice.onNetworkError(networkErrorHandler); ... var networkErrorHandler = function(statusCode, errorDescription) { ...


Page 76

};

Parameters: statusCode The HTTP status code. errorDescription The description of the network error. ice.onBeforeSubmit(callback) Accepts a reference to a callback function. The callback function will be invoked just before the form submit request is issued. Usage:

ice.onBeforeSubmit(paramHandler); ... var paramHandler = function(source) { ... };

Parameters: source The element that triggered the form submission. ice.onElementRemove(elementID, callback) Accepts the ID of the element to be monitored for removal and a reference to a callback function. The callback function will be invoked when the element with the specified ID is removed from the document. Usage:

ice.onElementRemove(elementID, callback) ... var callback = function() { ... };

Parameters: elementID The ID of the element to be monitored for removal. callback The callback function invoked when the identified element is removed. ice.onLoad(callback) Accepts a reference to a callback function. The callback function will be invoked when the DOM document finished loading. This registration function allows the registration of multiple callbacks without the danger of callback overwriting (unlike the native windown.onload property).


Page 77

ICEfaces inserts the JS resource defining the ice.onLoad function right before the 'head' ending tag to make sure the scripts are loaded in a deterministic order. Any inline or referenced Javascript code that uses this function needs to be loaded later, preferably right after the 'body' starting tag. Usage:

ice.onLoad(callback) ... var callback = function() { ... };

Parameters: callback The callback function invoked when the document has been loaded. ice.onUnload(callback) Accepts a reference to a callback function. The callback function will be invoked when the DOM document is unloaded. This registration function allows the registration of multiple callbacks without the danger of callback overwriting (unlike the native windown.onunload property). ICEfaces inserts the JS resource defining the ice.onUnload function right before the 'head' ending tag to make sure the scripts are loaded in a deterministic order. Any inline or referenced Javascript code that uses this function needs to be loaded later, preferably right after the 'body' starting tag. Usage:

ice.onUnload(callback) ... var callback = function() { ... };

Parameters: callback The callback function invoked when the document has been unloaded.

Focus Retention APIThe functions here allow developers access to ICEfaces' focus retention mechanism. ice.setFocus(id) or ice.sf(id) Accepts an element ID. By calling this function the client will send the ID to the server next time a form submit is invoked. The focus is not moved on the specified element. Usage:


Page 78

ice.setFocus(id);

Parameters: id The ID of the element. ice.applyFocus(id) or ice.af(id) Accepts an element ID. By calling this function the client will move the focus on the specified element and also call ice.setFocus so that the server will be informed about the focus change. Usage:

ice.applyFocus(id);

Parameters: id The ID of the element.

Push Specific APIThe following functions are available and valid only when ICEpush is enabled for the application. ice.onBlockingConnectionUnstable(callback) Accepts a reference to a callback function. The callback function will be invoked when the client bridge's hearbeat detects that the server isn't responding in a timely fashion. Usage:

ice.onBlockingConnectionUnstable(connectionUnstableHandler); ... var connectionUnstableHandler = function() { ... };

Parameters: none ice.onBlockingConnectionLost(callback) Accepts a reference to a callback function. The callback function will be invoked when the blocking connection to the server has been lost and is considered unrecoverable. Usage:

ice.onBlockingConnectionLost(connectionLostHandler); ...


Page 79

var connectionLostHandler = function(reconnectionAttempts) { ... };

Parameters: reconnectionAttempts The number of reconnect attempts made by the bridge to re-establish the connection before considering the connection unrecoverable. ice.onBlockingConnectionServerError(callback) Accepts a reference to a callback function. The callback function will be invoked when a server error is received by the browser on the blocking connection. Usage:

ice.onBlockingConnectionServerError(serverErrorHandler); ... var serverErrorHandler = function(statusCode, responseText, responseDOM) { ... };

Parameters: statusCode The HTTP status code. responseText The body of the HTTP response in text format. responseDOM The parsed body of the HTTP response as XML. This parameter is present only when response is in XML/HTML format.

Configuration APIThe following parameters are used to configure certain functional parts of the client. ice.disableDefaultErrorPopups This parameter can be used to disable the popups rendered by default when a network error, session expiry or server error occurs. The parameter is usually set when an application or component developer wants to have rendered only the defined custom indicators. Usage:

ice.disableDefaultErrorPopups = true;


Page 80

Logging APIice.log.debug(logger, message, exception) Logs a DEBUG level message to the console or log window. ice.log.info(logger, message, exception) Logs a INFO level message to the console or log window. ice.log.warn(logger, message, exception) Logs a WARN level message to the console or log window. ice.log.error(logger, message, exception) Logs a ERROR level message to the console or log window. Usage:

ice.log.debug(ice.log, 'Debug message'); ice.log.info(ice.log, 'Info message'); ice.log.warn(ice.log, 'Warning message'); try { ... } catch (e) { ice.log.error(ice.log, 'Error occurred', e); }

Parameters: logger The logger. message The message to be logged. responseDOM The captured exception. This is an optional parameter. ice.log.childLogger(parentLogger, categoryName) Creates an new child logger that logs its messages into the defined category. Usage:

var a = ice.log.childLogger(ice.log, 'A'); ice.log.debug(a, 'message in category A'); //outputs -- [window.A] debug: message in category A var aa = ice.log.childLogger(a, 'AA'); ice.log.warn(aa, 'message in category AA');


Page 81

//outputs -- [window.A.AA] warning: message in category AA

Parameters: logger The parent logger. categoryName The name of the category.


Page 82

Handling ExceptionsThis page last changed on Mar 04, 2011 by ken.fyten.

Handling ExceptionsThe standard Servlet mechanism for handling exceptions that occur on the server is to specify an error-page entry in the deployment descriptor (web.xml file) and allow the container to redirect to the configured resource. For example:

javax.faces.application.ViewExpiredException /faces/viewExpired.xhtml

This mechanism works fine as long as the exception makes it up to the servlet container. If the exception is handled in some other way and doesn't bubble up to the container, it renders the error-page strategy ineffective. With JSF 2 and ICEfaces 2, you can decide how you want to handle exceptions both on the server and the client. Server-side - ExceptionHandlers With JSF 2, there is now a facility for hooking into the lifecycle and customizing how exceptions are handled. This is done using an ExceptionHandlerFactory and one or more custom ExceptionHandlers. By default, Mojarra provides implementations of both a standard ExceptionHandler for normal requests as well as an Ajax implementation for Ajax requests Exceptions for non-Ajax requests can be handled using the error-page facility. If no error page is specified then a default page is created JSF and sent back to the client. Exceptions for Ajax requests are contained within Ajax responses and do not trickle up to the container so the error-page strategy is not used. If you'd like to change this behavior in some way, you can write your own ExceptionHandler and deal with the exceptions on the server as you see fit. It's relatively simple to do. ICEfaces currently uses the technique described here to emit SessionExpired exceptions instead of ViewExpiredExceptions when appropriate. Ed Burns has a blog about this specifically.1) Create one or more implementations of ExceptionHandlers

ExceptionHandlers are request-scoped resources - that is, there is a new one for each request. Exceptions that occur during a JSF lifecycle are generally queued to be handled by one or more of the ExceptionHandlers. Normally, you'd create an ExceptionHandler that extends ExceptionHandlerWrapper. The interesting work of finding the exceptions you're interested in and then processing those might look like this:

public class MyExceptionHandler extends ExceptionHandlerWrapper { private ExceptionHandler wrapped; public MyExceptionHandler(ExceptionHandler wrapped) { this.wrapped = wrapped; } public javax.faces.context.ExceptionHandler getWrapped() { return wrapped;


Page 83

} public void handle() throws FacesException { Iterator events = getUnhandledExceptionQueuedEvents().iterator(); //Iterate through the queued exceptions while (events.hasNext()) { ExceptionQueuedEvent event = (ExceptionQueuedEvent) events.next(); ExceptionQueuedEventContext context = (ExceptionQueuedEventContext) event.getSource(); Throwable t = context.getException(); //See if it's an exception I'm interested in if (t instanceof MyCustomException) { try { //do something exciting with the exception } finally { //remove it if you processed it events.remove(); } } //Let the next ExceptionHandler(s) deal with the others getWrapped().handle(); } } }

2) Create an implementation of ExceptionHandlerFactory

ExceptionHandlers are created by ExceptionHandlerFactories. The basic mechanism is to create an ExceptionHandlerFactory that links into the chain of existing ExceptionHandlerFactories. Your factory is used to create the appropriate ExceptionHandler for the request. Because it's a wrapper, we can chain them together by passing in the delegate when we create the instance. For example:

public class MyExceptionHandlerFactory extends ExceptionHandlerFactory { ExceptionHandlerFactory delegateFactory; public MyExceptionHandlerFactory(ExceptionHandlerFactory delegateFactory) { this.delegateFactory = delegateFactory; } public ExceptionHandler getExceptionHandler() { return new MyExceptionHandler(delegateFactory.getExceptionHandler()); } }

3) Then you need to register your factory with JSF. You can add an entry into the faces-config.xml of the .war that includes your custom ExceptionHandler(s):

org.company.faces.context.MyExceptionHandlerFactory


Page 84

4) Then, in your application, exceptions of interest can be done like this:

FacesContext fc = FacesContext.getCurrentInstance(); ExceptionQueuedEventContext ctxt = new ExceptionQueuedEventContext(fc, new MyCustomException("my bad") ); Application app = fc.getApplication(); app.publishEvent(fc, ExceptionQueuedEvent.class, ctxt);

Client-side - JavaScript Callbacks When an exception does occur during an Ajax request, JSF will process those exceptions and send them back as Ajax responses. With stock JSF, you can register a callback and handle these errors as you see fit. This is done using the JavaScript API provided by JSF:

//Assign your error handling function to a variable var jsfErrorCallback = function handleError(error) { //Handle all errors by simply redirecting to an error page window.location.href = "./generalError.xhtml"; } //Register your error handler as a callback jsf.ajax.addOnError(jsfErrorCallback);

ICEfaces uses this same technique. By default, when ICEfaces is active on the page and an error comes back as an Ajax response, a small popop is displayed with a short description of the error. For example, if a session times out and you attempt to interact with the page it will cause a ViewExpiredException when JSF attempts to restore the view:

If you would like to do something else with these errors, you can use much the same technique as described above:

//Assign your error handling function to a variable var iceErrorCallback = function iceHandleError(statusCode, responseTxt, responseDOM) {


Page 85

//Handle all errors by simply redirecting to an error page window.location.href = "./generalError.xhtml"; } //Safely check if ICEfaces is available if (ice) { //Turn off the popups as we plan to handle this ourselves ice.configuration.disableDefaultIndicators = true; //Register your error handler as a callback ice.onServerError(iceErrorCallback); }


Page 86

ConfigurationThis page last changed on Dec 04, 2011 by mark.collette.

ConfigurationICEfaces 2 provides a number of configuration parameters that need not be adjusted for typical applications, but may be useful for diagnostic purposes or in special cases. Context Parameters The following parameters are set as context parameters in the web.xml file of your application. Several of them may be overridden on a page by page basis via the icecore:config tag.aria.enabled

default is true Setting aria.enabled to true indicates that all views in the the application are ARIA (Accessible Rich Internet Applications) enabled. This context parameter is application-wide and works together with the ariaEnabled attribute of the ICEfaces tag so that ARIA support can be turned on and off selectively on a per page basis.

org.icefaces.aria.enabled false

autoid

default is true Setting autoid to true causes the majority of standard JSF components to write their IDs to the page. This allows ICEfaces to apply page updates at a fine granularity. With this parameter set to false, page updates can only be applied for components that have manually specified IDs. This parameter is provided for fallback to completely standard behavior; it is not generally intended to be set to false for application use.

org.icefaces.autoid false

compressDOM

default is false Setting compressDOM to true indicates to the ICEfaces core framework that the server-side DOM representation of the current view should be serialized and compressed between requests. The default value of false leaves the DOM representation intact between requests.

org.icefaces.compressDOM true


Page 87

compressResources

default is true By default, ICEfaces will gzip compress most static resource responses. Setting compressedResources to false instructs ICEfaces not to compress any resource responses.

org.icefaces.compressResources false

deltaSubmit

default is false Setting deltaSubmit to true tells ICEfaces that form submission should be handled in a special way to minimize what is sent across the wire. The parameters of a form post are compared to the previous submission and only those that have changed are sent to the server. The rest of the form parameters are reconstructed on the server from the cached DOM and then processed normally.

org.icefaces.deltaSubmit true

Known Issue The Delta-submit function does not support cases where an Ajax DOM update in the browser dynamically introduces new form elements into the DOM that were not part of the form when the page was originally loaded. In order to use Delta-Submit successfully all form elements / components must be present on the page at the time the page is loaded.lazyPush

default is true By default, when using Ajax Push, the feature is activated in a lazy fashion. This means that the blocking connection used for doing Ajax Push is not activated until the first push is requested. Setting lazyPush to false tells ICEfaces to automatically activate ICEpush for each session and each page. This context parameter is application-wide and works together with the lazyPush attribute of the ICEfaces configuration tag so that ICEpush can be set to activate lazily on a per-page basis.

org.icefaces.lazyPush false

To apply lazy push activation to select pages only, set this parameter to false and add:


Page 88

lazyWindowScope

default is true By default, when using the window scoped beans, the window management is activated in a lazy fashion. This means that if the window scope map doesn't contain any window scoped beans no dispose-window request is sent upon window closure. Setting lazyWindowScope to false tells ICEfaces to always send a dispose-window request upon window closure regardless of the window scope map being empty or not. This context parameter is application-wide. Please note that if the view scope map contains any view scoped beans, lazyWindowScope is not enabled by default.

org.icefaces.lazyWindowScope false

mandatoryResourceConfiguration

default is 'all' in ICEfaces 2.0, and 'none' in ICEfaces 3.0+ The mandatoryResouceConfiguration may be set to one of three values: none, all, or a space delimited list of components. When none is specified, then only when a component is actually on the page will its Javascript and CSS resources be rendered into the head of the page. This can cause problems when a component is initially not in the page, but then on a postback it is dynamically added to the page. In that case, it's necessary to have pre-loaded the resources into the head, for the eventuality of the component being later dynamically added to the view. A simple yet blunt method of accomplishing this is to set it to all, so that every componnt which participates in the MandatoryResourceComponent mechanism may have their resources pre-loaded into the head. There is a performance cost to pre-loading every component's resources, especially when this might apply to components that your application may not even use at all. For this reason, applications may specifically list the components by name, space delimited, that they wish to pre-load. [ICEfaces 2.0] The component's full class name must be specified. For example, to specify sliderEntry, org.icefaces.component.sliderentry.SliderEntry would be given. [ICEfaces 3.0+] The component's tag name may be specified, or for backwards compatibility, the component class name may still be specified. For example, to specify sliderEntry, either of sliderEntry or the longer org.icefaces.component.sliderentry.SliderEntry may be given. For instance, to pre-load resources for sliderEntry and dateTimeEntry:

org.icefaces.mandatoryResourceConfiguration sliderEntry dateTimeEntry

To apply resource configuration to select pages only, use:

render.auto

default is true


Page 89

Setting render.auto to true causes ICEfaces to automatically apply DOM rendering to each page. If this is set to false, then DOM rendering and updating is turned off for the entire application.

org.icefaces.render.auto false

This context parameter is application-wide and works together with the render attribute of the ICEfaces tag so that ICEfaces rendering can be turned on and off selectively on a per page basis. To apply ICEfaces DOM rendering to select pages only, set this parameter to false and add:

to just those pages that should be rendered via ICEfaces.standardFormSerialization

default is false By default, ICEfaces does optimized serialization and submission of form elements based on the element that triggered the submission. Setting standardFormSerialization to true indicates that ICEfaces should do a normal, standard, full form submission.

org.icefaces.standardFormSerialization true

strictSessionTimeout

default is false The default value of false for strictSessionTimeout indicates that ICEfaces should not interfere with container-managed control of session timeout. In this case, each user request and each Ajax Push request will extend the session. Setting strictSessionTimeout to true indicates that ICEfaces should attempt to enforce the configured session timeout by ignoring any Ajax Push activity so that only usertriggered requests will extend the session.

org.icefaces.strictSessionTimeout true

subtreeDiff

[As of ICEfaces 3.0] default is true By default, when using ICEfaces, Ajax-specified subtree diffing is always done. Setting subtreeDiff to false indicates that ICEfaces will not perform a DOM diff on the rendered subtrees. Instead the rendered output of subtrees is sent directly to the browser, thus not updating the server-side DOM.


Page 90

org.icefaces.subtreeDiff false

uniqueResourceURLs

default is true The default value of "true" will cause ICEfaces to append random numbers to certain resource URLs, thereby preventing caching. This is useful for development, but can interfere with Portlet URL generation.

org.icefaces.uniqueResourceURLs false

windowScopeExpiration

default is 1000 A value, in milliseconds, indicating how long window-scoped values should remain valid in the session after a reload or redirect occurs. This allows for postbacks that might occur quickly after a reload or redirect to successfully retrieve the relevant window-scoped values.

org.icefaces.windowScopeExpiration 1500

disableDefaultErrorPopups default is false This parameter can be used to disable the popups rendered by default when a network error, session expiry or server error occurs. The parameter is usually set when an application or component developer wants to have rendered only the defined custom indicators. Usage:

org.icefaces.disableDefaultErrorPopups true

replayNavigationOnReload [As of ICEfaces 3.0] default is false


Page 91

This parameter can be used to replay the navigation rules when the page is reloaded. The parameter is usually set in applications where it is desirable to avoid the content being reset to the first page (before non-redirect navigation was triggered) when reloading. Usage:

org.icefaces.replayNavigationOnReload true

Compatible Context Parameters The following parameters are set as context parameters in the web.xml file of your application, but only apply if you are using the compatibility component suite:blockUIOnSubmit

default is false Setting blockUIOnSubmit to true tells ICEfaces that the user interface (UI) should block any subsequent requests until the current request has been processed. This is provided to help prevent double-submits in applications that require this feature.

org.icefaces.blockUIOnSubmit true

connectionLostRedirectURI

default is "null" Setting connectionLostRedirectURI to a valid URI tells ICEfaces that when the Ajax Push connection is lost, that the client is to be redirected to the specified page.

org.icefaces.connectionLostRedirectURI /myPath/theConnectionLostPage.jsf

sessionExpiredRedirectURI

default is "null" Setting sessionExpiredRedirectURI to a valid URI tells ICEfaces that when the user session expires, that the client is to be redirected to the specified page.

org.icefaces.sessionExpiredRedirectURI /myPath/theSessionExpiredPage.jsf


Page 92

ICEpush ConfigurationThis page last changed on Nov 25, 2011 by ken.fyten.

ICEpush ConfigurationThe ICEpush library supports specific configuration parameters that can be used to optimize performance and reliability as required. Details on ICEpush configuration can be found in the ICEpush Configuration Parameters topic in the ICEpush product Wiki.


Page 93

JSF ConfigurationThis page last changed on Jun 07, 2011 by mark.collette.

JSF ConfigurationJSF has it's own configuration context parameters, which may optionally be specified, to further tune or configure applications. These context parameters are set in the web.xml file of your application. Various JSF implementations, such as Mojarra, also have their own configuration context parameters. Caching Context Parameters These context parameters affect how resources will be cached. JSF pages use components which themselves register resources either programmatically or statically via @ResourceDependency annotations. These resources typically consist of Javascript and CSS files, but can be any other files that the page contains.javax.faces.PROJECT_STAGE

Default is Production When the PROJECT_STAGE is set to Production, and a resource is within its cached duration, then the web browser can avoid going to the server at all for the resource. If it's beyond the duration, or the user has pressed the Refresh button, then the browser may request if the resource has been updated, which can either return an HTTP 304 code saying that the resource is still valid in the browser's cache, or it will return an HTTP 200 code and serve out the resource, if it has been updated. When the PROJECT_STAGE is set to Development, the cache duration is ignored, so the browser will always request if the resource has been updated, and use the HTTP 304 and 200 accordingly. So, caching is not completely disabled, as it can still avoid downloading the resource, but it will still communicate with the server.

javax.faces.PROJECT_STAGE Production

com.sun.faces.defaultResourceMaxAge

Default is 604800 This parameter is specific to Mojarra's JSF implementation. The default is about 10 minutes, which is not really that long. It's recommended that production applications specify a longer caching duration, for example 2 weeks. Again, this only applies when the PRJECT_STAGE has been set to Production, and allows the browser to avoid any communication with the server, in regards to cached resources. There is no means for setting different cache durations for different resources, this globally applies to all resources.

com.sun.faces.defaultResourceMaxAge 604800


Page 94

ComponentsThis page last changed on Nov 04, 2010 by ken.fyten.

ICEfaces Components ICEfaces 2.0 Advanced Components Animation 2.0 CheckboxButton 2.0 DateTimeEntry 2.0 FileEntry 2.0 LinkButton 2.0 PushButton 2.0 SliderEntry 2.0 TabSet 2.0 ICEfaces Advanced Components Accordion AccordionPane Ajax Animation CellEditor CheckboxButton ConfirmationDialog ContextMenu Column ColumnGroup DataTable - Data Model Lifecycle DataExporter DateTimeEntry Dialog Draggable Droppable ExcludeFromExport FileEntry LinkButton MaskedEntry Menu and Menubar MenuButton MenuItem NotificationPanel Panel Printer ProgressBar PushButton Row RowEditor RowExpander RowPanelExpander SliderEntry Submenu TabSet Tooltip ICEfaces Advanced Components Environment ACE ThemeRoller support ACE Source Artefacts and Generated Outputs ACE Meta Class ACE Component and Renderer Classes ACE Adding Resources to Meta Class ACE Skinning - ACE Sprite Image Generation - ACE CSS URL Mapping ACE Disabled Styling Standard


Page 95

ICEfaces ComponentsThis page last changed on Oct 20, 2011 by robert.lepack.

ICEfaces (ICE) ComponentsThe ICEfaces Components are an ICEfaces 2-compatible version of the ICEfaces 1.x ICEfaces Component Suite. You should include this library if you want to use the ICEfaces Component Suite components in your application or if you are porting an existing ICEfaces 1.8.x application to ICEfaces 2. See the ICEfaces 1.x Compatibility section for more information on porting an existing ICEfaces 1.x application to ICEfaces 2. View the API Documentation. View the TLD Documentation.

Configurations Details Required web.xml entries

javax.faces.STATE_SAVING_METHOD server javax.faces.FACELETS_SKIP_COMMENTS true com.icesoft.faces.gmapKey ABQIAAAADlu0ZiSTam64EKaCQr9eTRTOTuQNzJNXRlYRLknj4cQ89tFfpxTEqxQnVWL4k55OPICgF5_SOZE06A Faces Servlet javax.faces.webapp.FacesServlet Resource Servlet com.icesoft.faces.webapp.CompatResourceServlet 1


Page 96

Faces Servlet *.jsf Resource Servlet /xmlhttp/* Faces Servlet /icefaces/*

Add icefaces-compat.jar to your application project

[icefaces2.dir]/icefaces/lib/icefaces-compat.jar

3rd Party Dependencies If you are using the ICEfaces Components you will also require additional 3rd party libraries. Libraries servlet-profile : Tomcat web-profile : JBoss 6, Glassfish 3 Y Y

commons-beanutils.jar commons-logging.jar jsf-api.jar jsf-impl.jar jxl.jar krysalis-jCharts-1.0.0alpha-1.jar

Y Y Y Y Y Y

Y Y

Component List

checkbox

checkbox for a selectManyCheckbox component when its layout is "spread" single column of data within a parent UIData component used to create multiple dataTable headers or footers with allowable colspan and rowspan used to render multiple table columns

column

columnGroup

columns


Page 97

commandButton commandLink

submit or reset button HTML "a" anchor element that acts like a form submit button when clicked clickable column header allowing user to toggle the sort order of data in table export the data contents of an table component into a variety of formats used to render a set of page navigation controls for a table HTML table tied to underlying data model add effects to parent component HTML form width added features Google map adds control to the gMap direction from point A to point B supports the KML and GeoRSS data formats for displaying geographic information wrapper for google map's GLatLng API list of gMapLatLng components uses google map's GMarker API to display points on the map HTML "img" element header row for a table HTML "input" element of "type" "hidden" JSF based rich text component HTML "input" element of "type" "password" HTML "input" element of "type" "text" HTML "textarea" element used to capture javascript events and optionally send a notification to server and fire an action event similar to f:loadBundle but allows change to messages dynamically provides a robust menu system menu items contained by a menuBar dynamic heirarchy of menu items

commandSortHeader

dataExporter

dataPaginator

dataTable effect form gMap gMapControl gMapDirection gMapGeoXml

gMapLatLng gMapLatLngs gMapMarker

graphicImage headerRow inputHidden inputRichText inputSecret inputText inputTextarea jsEventListener

loadBundle

menuBar menuItem menuItems


Page 98

menuItemSeparator menuPopup

separates groups of menu items context sensitive popup menu providing popup nested child menus single message for a specific component all the messages for a specific component charts of various types displays information about the status of the network connection renders parameterized text HTML "label" element HTML "a" anchor element plays a media object report progress to users in cases where a long running server-side task is necessary expose resources for opening or downloading link desired ICEfaces theme CSS stylesheets span element for displaying text. container component with five regions: north, south, east, west, and center clickable header to hide or show contents popup confirmation dialog splitable panel HTML "table" element container for a group of child components placement of components in absolute or relative position modal or non-modal popups series of repeating child-components which can be dragged and repositioned dynamically generates a series of repeating childcomponents within a panel multiple panel groups with one group visible at a time a tab within a tab set a set of tabs with one table active at a time tooltip popup

message messages outputChart outputConnectionStatus

outputFormat outputLabel outputLink outputMedia outputProgress

outputResource outputStyle outputText panelBorder

panelCollapsible panelConfirmation panelDivider panelGrid panelGroup panelLayout

panelPopup panelPositioned

panelSeries

panelStack

panelTab panelTabSet panelTooltip


Page 99

portlet radio

container for a portlet in a portal radio button for a selectOneRadio component when its layout is "spread" mechanism for dynamically generating a series of repeating child-components enables single and multiple row selection for a data table HTML "input" element of type "checkbox" input field, inline calendar or popup calendar for entering date and time input text component enhanced with autocomplete functionality a list of checkboxes list box allowing multiple selections list box with only one item visible at a time allowing multiple selections list box with single selection list box with only one item visible at a time allowing single selection set of radio buttons specifies the phase that certain events will be broadcast in sets listener class for tab change in tabset displays hierarchical data as a tree of branches and leaf nodes a node in a tree

repeat

rowSelector

selectBooleanCheckbox selectInputDate

selectInputText

selectManyCheckbox selectManyListbox selectManyMenu

selectOneListbox selectOneMenu

selectOneRadio setEventPhase

tabChangeListener tree

treeNode

Examples

Compat Components Showcase The Compat Components Showcase example provides a high-level demonstration of the ICEfaces Compat Components and is located in:

[icefaces2.dir]/icefaces/samples/compat/component-showcase

From that directory, you can use ant to build the Component Showcase. The strategy is to build a .war file for the platform you are running on. All of the content-related files are located in:


Page 100

[icefaces2.dir]/icefaces/samples/compat/component-showcase/src

So to build a component-showcase.war file for Tomcat 6.0 or 7.0 (non-JEE6 container), you would run the following ant command from the component-showcase directory:

component-showcase > ant clean servlet-profile

Alternatively, to build a component-showcase.war file for a JEE6 container, which includes the JSF libraries, you would run the following ant command from the component-showcase directory:

component-showcase > ant clean web-profile

The resulting component-showcase.war is located in:

[icefaces2.dir]/icefaces/samples/dist/component-showcase.war

This .war file can be deployed to the Tomcat "webapps" directory.

Compat Auction Monitor The Auction Monitor simulates the tracking of live auctions and illustrates the following dynamic web application features; ticking clocks, real-time bid updates, dynamically rendered buttons, the ability to hide and show table rows on demand, and an integrated chat section. It is located in:

[icefaces2.dir]/icefaces/samples/compat/auctionMonitor

From that directory, you can use ant to build the Auction Monitor. The strategy is to build a .war file for the platform you are running on. All of the content-related files are located in:

[icefaces2.dir]/icefaces/samples/compat/auctionMonitor/src

So to build an auctionMonitor.war file for Tomcat 6.0 or 7.0 (non-JEE6 container), you would run the following ant command from the auctionMonitor directory:

auctionMonitor > ant clean servlet-profile

Alternatively, to build an auctionMonitor.war file for a JEE6 container, which includes the JSF libraries, you would run the following ant command from the auctionMonitor directory:


Page 101

auctionMonitor > ant clean web-profile

The resulting auctionMonitor.war is located in:

[icefaces2.dir]/icefaces/samples/dist/auctionMonitor.war



Page 102

ICEfaces 2.0 Advanced ComponentsThis page last changed on Nov 04, 2011 by ken.fyten.

ICEfaces 2.0 Advanced (ACE) ComponentsThe ICEfaces Advanced Components are next-generation ICEfaces components, based on the all-new Advanced Component Evironment (ACE) component development platform. ICEfaces 2.0 Only This section is for the ICEfaces 2.0 Advanced Components only, and is not applicable to later releases (2.1+). For the latest ICEfaces Advanced Components documentation, see the ICEfaces Advanced Components topic. Key features of the Advanced Components include: Provide the abilty to leverage powerful JavaScript components while shielding ICEfaces application developers from having to learn/use JavaScript directly. Support client-side functionality to improve component richness, responsiveness, and scalability. Support complete flexibilty in how forms are used with respect to container components, such as TabSet. TabSet allows the use of multiple forms as required, with no limitation that all tabPanes be included in the same form as the tabSet itself. Provide a flexible and consistent approach to UI theming/skinning across all components. The Advanced Components are authored using the ICEfaces Advanced Component Evironment, which implements a consistent approach to component authoring, meta-data management, and automates common component development tasks and optimizations. View the API Documentation. View the TLD Documentation.

ComponentsThe following Advanced Components are included in the ICEfaces 2 distribution: Animation 2.0 CheckboxButton 2.0 DateTimeEntry 2.0 FileEntry 2.0 LinkButton 2.0 PushButton 2.0 SliderEntry 2.0 TabSet 2.0

ExamplesThe following example is included in the ICEfaces 2 distribution:

Advanced Components Showcase (ace-showcase) The Advanced Components Showcase example provides a high-level demonstration of the ICEfaces Advanced Components and is located in:

[icefaces2.dir]/icefaces/samples/ace/showcase/

From that directory, you can use ant to build the Component Showcase. The strategy is to build a .war file for the platform you are running on. All of the content-related files are located in:


Page 103

[icefaces2.dir]/icefaces/samples/ace/showcase/src

So to build an ace-showcase.war file for Tomcat 6.0 or 7.0 (non-JEE6 container), you would run the following ant command from the showcase directory:

showcase > ant clean servlet-profile

Alternatively, to build an ace-showcase.war file for a JEE6 container, which includes the JSF libraries, you would run the following ant command from the showcase directory:

showcase > ant clean web-profile

The resulting ace-showcase.war is located in:

[icefaces2.dir]/icefaces/samples/dist/ace-showcase.war


Using Advanced ComponentsTo add ACE components to an application, follow these steps: 1. Follow the steps in Get

icefaces 2 docs

Documents

class acecomponentbuildexplodedorgicefacescomponent

java acecomponentsrcorgicefacescomponent

acecomponentbuildexplodedorgicefacescomponent

js acecomponentresourcesorg

acecomponentresourcesorg

wysiwig editing

java reserved

support complete