Getting Started with ICEfaces 2

ICEfaces 2 is the new version of the ICEfaces framework that integrates with JavaServer Faces (JSF) 2. With ICEfaces 2, our goal is to deliver the highest value existing ICEfaces features, as well as important new enhancements, cleanly integrated into the JSF 2 platform. There are a number of ways to take advantage of ICEfaces 2 in your JSF 2 application:

First, add the icefaces.jar to your project. This immediately allows you to take advantage of Direct-to-DOM (D2D) rendering technology. D2D only sends browser DOM changes from the server to the browser, minimizing bandwidth consumption without the need to specify the new "f:ajax" component in your pages. Once the icefaces.jar is added to your project, you can also take advantage of ICEfaces Window Scope and Single Submit features.

After adding the icefaces.jar to your project, you can start adding components:

• The ACE Components are next-generation ICEfaces components. They are based on the all-new Advanced Component Environment (ACE) component development platform which implements a consistent approach to component authoring, meta-data management, and automates common component development tasks and optimizations.

• ICEfaces 2 provides a compatible component library based on the ICEfaces 1.x component suite. This set of components are referred to as ICE Components and immediately allow developers to build ICEfaces 2 applications with a mature AJAX component suite.

Finally, you may want to take advantage of asynchronous server-initiated updates using AJAX Push. Adding icepush.jar to your application enables Ajax Push, and allows you to add collaborative capabilities that will revolutionize your application.

Adding ICEfaces to a JSF 2 Project

Direct-to-DOM Rendering

This tutorial makes use of a JSF 2 application. The application consists of a page to add a new Job Applicant:

And a page that displays the applicants:

The clear button in job-applicant.xhtml consists of the following markup:

<h:commandButton id="clearButton" value="Clear">
    <f:ajax event="click" 
            render="@form" 
            listener="#{applicantController.clearForm}" 
            immediate="true" />
</h:commandButton>

Here we see the use of stock JSF tags including the new f:ajax tag. The render="@form" attribute on the f:ajax tag informs JSF that only the form should be rendered after the lifecycle is executed.

Pressing the "Clear" button under these circumstances will generate the following response, which includes the entire form:

<?xml version="1.0" encoding="utf-8"?>
<partial-response><changes><update id="form"><![CDATA[
<form id="form" name="form" method="post" action="/jobApplication/job-applicant.jsf"
      enctype="application/x-www-form-urlencoded">
<input type="hidden" name="form" value="form" />
<div class="header">
    <img src="/jobApplication/javax.faces.resource/icefaces.png.jsf?ln=images" alt="" /></div>
<div class="content">
<div class="menu">
    <input type="button" 
           onclick="window.location.href='/jobApplication/applicants.jsf'; return false;"
           value="Listing Page" />
</div>
<div class="contentBody">
    <div id="form:table" style="background-color:;">
        <table>
	    <tr>
	    	<td><label for="form:title">Title</label></td>
	        <td>
                    <table id="form:title">
	                <tr>
                            <td>
                                <input type="radio" name="form:title" id="form:title:0" value="1" />
                                <label for="form:title:0"> Dr.</label>
                            </td>
                            <td>
                                <input type="radio" name="form:title" id="form:title:1" value="2" />
                                <label for="form:title:1"> Ms.</label>
                            </td>
                            <td>
                                <input type="radio" name="form:title" id="form:title:2" value="3" />
                                <label for="form:title:2"> Mrs.</label>
                            </td>
                            <td>
                                <input type="radio" name="form:title" id="form:title:3" value="4" />
                                <label for="form:title:3"> Miss</label>
                            </td>
                            <td>
                                <input type="radio" name="form:title" id="form:title:4" value="5" />
                                <label for="form:title:4"> Mr.</label>
                            </td>
	                </tr>
                    </table>
	        </td>
	        <td></td>
	    </tr>
	    <tr>
	        <td>
                    <label for="form:firstName:input" style="float:left;">First Name</label>
                </td>
		<td>
                    <input id="form:firstName:input" 
                           type="text" 
                           name="form:firstName:input" 
                           value=""
                           style="float:left;" />
                </td>
		<td>
                    <span id="form:firstName:msg"></span>
                </td>
            </tr>
	    <tr>
	        <td>
                    <label for="form:lastName:input" style="float:left;">Last Name</label>
                </td>
		<td>
                    <input id="form:lastName:input" 
                           type="text" 
                           name="form:lastName:input" value=""
                           style="float:left;" />
                </td>
		<td>
                    <span id="form:lastName:msg"></span>
                </td>
	    </tr>
	    <tr>
	        <td>
                    <label for="form:email:input" style="float:left;">Email </label>
                </td>
		<td>
                    <input id="form:email:input" 
                           type="text" 
                           name="form:email:input" value=""
                           style="float:left;"
                           onblur="mojarra.ab(this,event,'blur',0,'form:email:msg')" />
                </td>
		<td>
                    <span id="form:email:msg"></span>
                </td>
	    </tr>
            <tr>
	        <td>
                    <input type="submit" name="form:j_idt50" value="Submit Applicant" />
	        </td>
	        <td>
                    <input id="form:clearButton" 
                           type="submit" 
                           name="form:clearButton" 
                           value="Clear"
                           onclick="mojarra.ab(this,event,'click',0,'@form');return false" />
	        </td>
	        <td>
                    <input id="form:cancelButton" 
                           type="submit" 
                           name="form:cancelButton" 
                           value="Cancel" />
	        </td>
	    </tr>
	</table>
    </div>
</div>
<div style="clear:both;"></div>
</div>
</form>]]></update>
<update id="javax.faces.ViewState">
<![CDATA[6613003036389132071:131205412038135456]]>
</update></changes></partial-response>

ICEfaces 2 renders component markup to a server-side DOM (Document Object Model) that reflects the current client view. Each time the JSF lifecycle runs a DOM comparison is done and, if there are any changes, a concise set of page updates are sent back to the client to be applied to the page. We call this Direct-to-DOM or D2D rendering.

Adding the ICEfaces 2 library to an existing JSF 2 application will provide dynamic partial-page-updates for all compliant components, without the need to specify the "f:ajax" component in your pages.

Simply add the icefaces.jar to the application and we have Direct-to-Dom (D2D) rendering applied to the page. Now, when we press the "Clear" button, we get the following response which only updates two hidden fields:

<?xml version="1.0" encoding="utf-8"?>
<partial-response><changes><update id="v3wbj72"><![CDATA[
<form action="/jobApplication/job-applicant.jsf" id="v3wbj72" method="post" name="v3wbj72">
    <input name="v3wbj72" type="hidden" value="v3wbj72" />
    <input autocomplete="off" id="javax.faces.ViewState" name="javax.faces.ViewState" type="hidden"
           value="-6647367167940831220:-1927413051417630450" />
</form>]]>
</update>
<update id="javax.faces.ViewState">
<![CDATA[-6647367167940831220:-1927413051417630450]]>
</update><eval><![CDATA[ice.applyFocus('form:clearButton');]]></eval></changes></partial-response>

With Direct-to-DOM rendering, we no longer need the f:ajax tag nested in our "Clear" button:

<h:commandButton id="clearButton"
                 value="Clear"
                 actionListener="#{applicantController.clearForm}"
                 immediate="true" />

Notice the difference in the amount of markup sent back in the response - and this is for a small form with only four fields. Direct-to-DOM rendering is powerful stuff. The beauty is that from a developer point of view, it takes place automatically under the covers. This is what we call Automatic Ajax. The AJAX is built in to the framework and you do not have to concern yourself with how updates are applied, Direct-to-DOM rendering takes care of it for you.

Single Submit

The Single Submit feature is basically the ability to specify that only one component will execute in the JSF lifecycle. ICEfaces 2 Single Submit is similar in intent to ICEfaces Partial Submit, but is an improvement which leverages JSF 2 expanded capabilities.

The <icecore:singleSubmit> tag is a convenient and easy way to Single Submit enable standard h: components, without having to litter the page with <f:ajax> tags. It allows an entire page region to be enabled at once.

Simply add the namespace to your page. In job-applicant.xhtml add the following:

xmlns:icecore="http://www.icefaces.org/icefaces/core"

And then nest the tag in your form:

<icecore:singleSubmit />

All the form fields will now behave as if they have a nested f:ajax tag with the execute="@this" attribute. As the user tabs through fields in the form, the individual fields are executed in the JSF lifecycle and immediate feedback is provided, enhancing the user experience:

In this case, we have tabbed through the first three fields and those components have been executed on the server. They all have the required="true" attribute and because nothing was input in the field, a FacesMessage was automatically generated and output in the page via the h:message tag. We have arrived at the email field without performing a full form submit, but have been able to generate feedback on fields we have already visited.

Window Scope

ICEfaces 2 also introduces a new custom scope called "Window" scope. This custom scope is designed to fill in a gap in the existing scopes available for JSF 2, as it exists for the life of a browser window or tab including surviving reloads and refreshes.

Adding ICEfaces ACE Components

The ICEfaces Advanced Components are next-generation ICEfaces components, based on the all-new Advanced Component Evironment (ACE) component development platform.

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.
• Provide support for W3C ARIA accessibility features in all applicable components, including keyboard navigation.

The following Advanced Components are included in the ICEfaces 2 distribution:

• Animation
• CheckboxButton
• DateTimeEntry
• FileEntry
• LinkButton
• PushButton
• SliderEntry
• TabSet

To use the components, add the icefaces-ace.jar to your application.

Adding ICEfaces Components

The 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.0.

The following ICEfaces Components are included in the ICEfaces 2 distribution:

• checkbox
• column
• columnGroup
• columns
• commandButton
• commandLink
• commandSortHeader
• dataExporter
• dataPaginator
• dataTable
• effect
• form
• gMap
• gMapControl
• gMapDirection
• gMapGeoXml
• gMapLatLng
• gMapLatLngs
• gMapMarker
• graphicImage
• headerRow
• inputFile
• inputHidden
• inputRichText
• inputSecret
• inputText
• inputTextarea
• loadBundle
• menuBar
• menuItem
• menuItems
• menuItemSeparator
• menuPopup
• message
• messages
• outputBody
• outputChart
• outputConnectionStatus
• outputDeclaration
• outputFormat
• outputHead
• outputHtml
• outputLabel
• outputLink
• outputMedia
• outputProgress
• outputResource
• outputStyle
• outputText
• panelBorder
• panelCollapsible
• panelConfirmation
• panelDivider
• panelGrid
• panelGroup
• panelLayout
• panelPopup
• panelPositioned
• panelSeries
• panelStack
• panelTab
• panelTabSet
• panelTooltip
• portlet
• radio
• rowSelector
• selectBooleanCheckbox
• selectInputDate
• selectInputText
• selectManyCheckbox
• selectManyListbox
• selectManyMenu
• selectOneListbox
• selectOneMenu
• selectOneRadio
• setEventPhase
• tabChangeListener
• tree
• treeNode

To use the components, add the icefaces-compat.jar to your application.

NOTE: If you are using the ICEfaces Components you will also require additional 3rd party libraries. See Appendix A - ICEfaces Library/App. Server Dependencies in the ICEfaces 1.8 Developer's Guide for details.

Adding AJAX Push

To enable Ajax Push with ICEfaces 2, you simply add the icepush.jar library to your application.

ICEfaces 2 provides a new [API] for using Ajax Push from within your application. As a developer, the class you need to be aware of is org.icefaces.application.PushRenderer. The PushRenderer contains the methods to support using Ajax Push in your application. The new API is very similar to the SessionRenderer API from ICEfaces 1.8.x. The basic API revolves around adding sessions to groups:

PushRenderer.addCurrentSession(String groupName);

When something of note changes in the application, you can request the client get a notification to get the updates by calling:

PushRenderer.render(groupName);

In our tutorial application, we can take advantage of AJAX Push by updating the applicants list after a new job applicant has been added. First, we will add a PushManager class:

@ManagedBean
@ViewScoped
public class PushManager implements Serializable {
    private static final String GROUP = "applicants";

    public PushManager() {
	PushRenderer.addCurrentSession(GROUP);
    }

    public void push() {
	PushRenderer.render(GROUP);
    }

    public String getGroup() {
	return GROUP;
    }
}

In our applicants.xhtml page, we add the following facet to the dataTable:

<f:facet name="footer">
    Push Group Name: <i>#{pushManager.group}</i>
</f:facet>

Any user viewing this page will have a view scope instance of PushManager in scope.

The next step is to push an update out to everyone once a new job applicant has been added. In our ApplicantController.java class we add the following to the addApplicant() method:

PushManager pushManager =
    (PushManager)FacesUtils.getManagedBean("pushManager");
pushManager.push();

If we open a browser window in Internet Explorer and one in FireFox we will have two separate sessions running in our tutorial application. In FireFox, we have already added a job applicant to our applicants list:

In Internet Explorer, we now add a new job applicant:

After the "Submit Applicant" button has been pressed, the Firefox window immediately receives an update via AJAX push:

With AJAX Push added to the application, users receive real-time updates from the server without needing to initiate a request to the server.

Adding icefaces.jar, icefaces-ace.jar and icepush.jar to your JSF 2 applications will equip you with all the tools necessary to create AJAX enabled Rich Internet Applications.

Tutorial Source Code Downloads