h1. Getting Started with ICEfaces 2
ICEfaces 2.0 is the new version of the ICEfaces framework that integrates with JavaServer Faces (JSF) 2.0. With ICEfaces 2.0, our goal is to deliver the highest value existing ICEfaces features, as well as important new enhancements, cleanly integrated into the JSF 2.0 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 "ICEfaces Advanced 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 "ICEfaces 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 ICEpush. ICEpush draws on years of expertise with Ajax Push in ICEfaces/JSF and gives applications the power of real-time, web-based collaboration.
----
\\
{panel}This tutorial will discuss the following topics related to ICEfaces 2:
* [Adding ICEfaces 2 to a JSF 2 Project|#adding]
* [Adding ICEfaces ACE Components|#ace]
* [Adding ICEfaces Components|#components]
* [Adding ICEpush|#icepush]
* [Tutorial Source Code Download|#download]
{panel}
\\
----
h3. {anchor:adding}Adding ICEfaces to a JSF 2 Project
\\
This tutorial makes use of a JSF 2 application. The application consists of a page to add a new Job Applicant:
!addapplicant.png!
And a page that displays the applicants:
!applicantlist.png!
The clear button in job-applicant.xhtml consists of the following markup:
{code:xml}
<h:commandButton id="clearButton" value="Clear">
<f:ajax event="click" render="@form" listener="#{applicantController.clearForm}" immediate="true" />
</h:commandButton>
{code}
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:
{code:xml}
<?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>
{code}
ICEfaces 2.0 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.0 library to an existing JSF 2.0 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 you will 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:
{code:xml}
<?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>
{code}
# A list of String data
# A list of arbitrarily complex child components
The following code sample shows an implementation using a list of String data:
{code:xml}
<ice:selectInputText rows="10" width="300" valueChangeListener="#{autoCompleteBean.updateList}">
<f:selectItems value="#{autoCompleteBean.list}"/>
</ice:selectInputText>
{code}
This will display a drop-down list of cities that match the text input. The 'rows' attribute defines how many results will be returned when text is entered. The 'width' attribute sets the width of the input text box and the drop-down list. The 'valueChangeListener' attribute binds to a backing bean method that determines the associated list when a value is changed.
Nested in the ice:selectInputText component tag is an f:selectItems JSF tag. The 'value' binding in this tag provides the list of available options. The screen shot below shows the component in action:
!autocomplete-action.png!
The following code sample shows an implementation with a list of arbitrarily complex child components:
{code:xml}
<ice:selectInputText rows="6"
width="300"
listVar="city"
valueChangeListener="#{autoCompleteBean.updateList}"
listValue="#{autoCompleteBean.list}">
<f:facet name="selectInputText">
<ice:panelGrid columns="3"
style="margin-bottom:-20px;"
columnClasses="cityCol,stateCol,zipCol">
<ice:outputText value="#{city.city}"/>
<ice:outputText value="#{city.state}"/>
<ice:outputText value="#{city.zip}"/>
</ice:panelGrid>
</f:facet>
</ice:selectInputText>
{code}
This will display values similar to the first way but adds more information to the drop down menu, such as state and zip, in addition to the city. The screen shot below shows this method in action:
!autocomplete-action2.png!
\\
\\
----
h3. {anchor:beans}Create the Backing Beans
\\
In the application we use three main backing beans:
* _AutoCompleteBean:_ Stores the values gathered from the AutoCompleteDictionary class. Also contains utility methods for updating the list and getting the matches from the dictionary list.
* _AutoCompleteDictionary:_ Gets the dictionary list from a file in the file system. Also sorts the dictionary appropriately.
* _City:_ Basic class used as an object in the dictionary list.
\\
\\
----
h3. {anchor:dictionary}Create the Dictionary
\\
The backing beans retrieve lists of viable options from AutoCompleteDictionary. Our dictionary is populated from an xml file as follows:
{code:xml}
<java version="1.6.0_21" class="java.beans.XMLDecoder">
<object class="java.util.ArrayList">
<void method="add">
<object class="com.icesoft.icefaces.tutorial.component.autocomplete.City">
<void property="areaCode">
<string>631</string>
</void>
<void property="city">
<string>Holtsville</string>
</void>
<void property="country">
<string>Suffolk</string>
</void>
<void property="state">
<string>New York</string>
</void>
<void property="stateCode">
<string>NY</string>
</void>
<void property="zip">
<string>00501</string>
</void>
</object>
</void>
</object>
</java>
{code}
In this case, we have encapsulated the options available to the user in a zipped xml file that is deployed with the applications. Options available to the user could also be retrieved from a database.
\\
\\
----
h3. {anchor:download}Tutorial Source Code Downloads
\\
|| Example || Source || Notes ||
| autocomplete-tutorial |[autocomplete-tutorial source code|^autocomplete-tutorial.zip|Download Source Code]| Simple example on how to use the Auto-Complete component.|
ICEfaces 2.0 is the new version of the ICEfaces framework that integrates with JavaServer Faces (JSF) 2.0. With ICEfaces 2.0, our goal is to deliver the highest value existing ICEfaces features, as well as important new enhancements, cleanly integrated into the JSF 2.0 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 "ICEfaces Advanced 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 "ICEfaces 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 ICEpush. ICEpush draws on years of expertise with Ajax Push in ICEfaces/JSF and gives applications the power of real-time, web-based collaboration.
----
\\
{panel}This tutorial will discuss the following topics related to ICEfaces 2:
* [Adding ICEfaces 2 to a JSF 2 Project|#adding]
* [Adding ICEfaces ACE Components|#ace]
* [Adding ICEfaces Components|#components]
* [Adding ICEpush|#icepush]
* [Tutorial Source Code Download|#download]
{panel}
\\
----
h3. {anchor:adding}Adding ICEfaces to a JSF 2 Project
\\
This tutorial makes use of a JSF 2 application. The application consists of a page to add a new Job Applicant:
!addapplicant.png!
And a page that displays the applicants:
!applicantlist.png!
The clear button in job-applicant.xhtml consists of the following markup:
{code:xml}
<h:commandButton id="clearButton" value="Clear">
<f:ajax event="click" render="@form" listener="#{applicantController.clearForm}" immediate="true" />
</h:commandButton>
{code}
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:
{code:xml}
<?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>
{code}
ICEfaces 2.0 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.0 library to an existing JSF 2.0 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 you will 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:
{code:xml}
<?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>
{code}
# A list of String data
# A list of arbitrarily complex child components
The following code sample shows an implementation using a list of String data:
{code:xml}
<ice:selectInputText rows="10" width="300" valueChangeListener="#{autoCompleteBean.updateList}">
<f:selectItems value="#{autoCompleteBean.list}"/>
</ice:selectInputText>
{code}
This will display a drop-down list of cities that match the text input. The 'rows' attribute defines how many results will be returned when text is entered. The 'width' attribute sets the width of the input text box and the drop-down list. The 'valueChangeListener' attribute binds to a backing bean method that determines the associated list when a value is changed.
Nested in the ice:selectInputText component tag is an f:selectItems JSF tag. The 'value' binding in this tag provides the list of available options. The screen shot below shows the component in action:
!autocomplete-action.png!
The following code sample shows an implementation with a list of arbitrarily complex child components:
{code:xml}
<ice:selectInputText rows="6"
width="300"
listVar="city"
valueChangeListener="#{autoCompleteBean.updateList}"
listValue="#{autoCompleteBean.list}">
<f:facet name="selectInputText">
<ice:panelGrid columns="3"
style="margin-bottom:-20px;"
columnClasses="cityCol,stateCol,zipCol">
<ice:outputText value="#{city.city}"/>
<ice:outputText value="#{city.state}"/>
<ice:outputText value="#{city.zip}"/>
</ice:panelGrid>
</f:facet>
</ice:selectInputText>
{code}
This will display values similar to the first way but adds more information to the drop down menu, such as state and zip, in addition to the city. The screen shot below shows this method in action:
!autocomplete-action2.png!
\\
\\
----
h3. {anchor:beans}Create the Backing Beans
\\
In the application we use three main backing beans:
* _AutoCompleteBean:_ Stores the values gathered from the AutoCompleteDictionary class. Also contains utility methods for updating the list and getting the matches from the dictionary list.
* _AutoCompleteDictionary:_ Gets the dictionary list from a file in the file system. Also sorts the dictionary appropriately.
* _City:_ Basic class used as an object in the dictionary list.
\\
\\
----
h3. {anchor:dictionary}Create the Dictionary
\\
The backing beans retrieve lists of viable options from AutoCompleteDictionary. Our dictionary is populated from an xml file as follows:
{code:xml}
<java version="1.6.0_21" class="java.beans.XMLDecoder">
<object class="java.util.ArrayList">
<void method="add">
<object class="com.icesoft.icefaces.tutorial.component.autocomplete.City">
<void property="areaCode">
<string>631</string>
</void>
<void property="city">
<string>Holtsville</string>
</void>
<void property="country">
<string>Suffolk</string>
</void>
<void property="state">
<string>New York</string>
</void>
<void property="stateCode">
<string>NY</string>
</void>
<void property="zip">
<string>00501</string>
</void>
</object>
</void>
</object>
</java>
{code}
In this case, we have encapsulated the options available to the user in a zipped xml file that is deployed with the applications. Options available to the user could also be retrieved from a database.
\\
\\
----
h3. {anchor:download}Tutorial Source Code Downloads
\\
|| Example || Source || Notes ||
| autocomplete-tutorial |[autocomplete-tutorial source code|^autocomplete-tutorial.zip|Download Source Code]| Simple example on how to use the Auto-Complete component.|