ICEfaces : Adding ICEfaces to Your Application

Configuring a JSF 2 Application to Use ICEfaces

If you're just starting to build a JSF 2 application, or you've already started building one and you'd like to add ICEfaces, it's simple to do:

Add <h:head> and <h:body> tags

JSF 2 includes head and body components that can be added to the page by using the <h:head> and <h:body> tags. ICEfaces 2 makes use of these components to automatically add certain scripts and other elements to the page, so the <h:head> and <h:body> tags are required on any pages of your application that use ICEfaces 2.

Include the Necessary Libraries

ICEfaces 2 provides the following libraries:

icefaces.jar - This is the ICEfaces 2 core framework and is required for all applications.

icepush.jar - Provides Ajax Push functionality for ICEfaces 2. This library is only required if Ajax Push functionality is required in the application. See the Ajax Push overview, and API for details.

icefaces-ace.jar - This library contain the ICEfaces Advanced Components (ACE) which are only compatible with ICEfaces 2. You should include this library if you want to use latest ICEfaces components in your application. See the ICEfaces Advanced Components topic for details.

icefaces-compat.jar - This library contains the ICEfaces Components (Known as the ICEfaces Component Suite in 1.x) that are compatible with ICEfaces 2. 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 Components and ICEfaces 1.x Compatibility topics for more information.
The ICEfaces Components require additional 3rd party libraries. See the ICEfaces Components topic for details.

jsf-api.jar and jsf-impl.jar - Must be included if the application server platform you plan to run on does not already supply them. For example, JEE6-compliant platforms such as Glassfish 3 and JBoss 6 already have the JSF 2 libraries provided, but servlet-containers such as Tomcat do not.

Configuration

The ICEfaces 2 core framework (icefaces.jar), ICEpush (icepush.jar), and ICEfaces Advanced Components (icefaces-ace.jar) do not require any additional configuration beyond what JSF 2 requires.

Simply ensure you have the FacesServlet is declared appropriately in your web.xml file:

    <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>*.jsf</url-pattern>
        <url-pattern>/icefaces/*</url-pattern>
    </servlet-mapping>

    <!-- More efficient, in an AJAX environment, to have server side state saving -->
    <context-param>
        <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
        <param-value>server</param-value>
    </context-param>

    <!-- HTML comments become components unless they're stripped -->
    <context-param>
        <param-name>javax.faces.FACELETS_SKIP_COMMENTS</param-name>
        <param-value>true</param-value>
    </context-param>

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

Required web.xml entries

    <!-- If you're using ice:gmap component, you'll need your own key here -->
    <context-param>
        <param-name>com.icesoft.faces.gmapKey</param-name>
        <param-value>ABQIAAAADlu0ZiSTam64EKaCQr9eTRTOTuQNzJNXRlYRLknj4cQ89tFfpxTEqxQnVWL4k55OPICgF5_SOZE06A
        </param-value>
    </context-param>

    <!-- Many of the ICEfaces Components make use of the Resource Servlet -->
    <servlet>
        <servlet-name>Resource Servlet</servlet-name>
        <servlet-class>com.icesoft.faces.webapp.CompatResourceServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <!-- These specific mappings are necessary for the Resource Servlet to function properly -->
    <servlet-mapping>
        <servlet-name>Resource Servlet</servlet-name>
        <url-pattern>/xmlhttp/*</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>/icefaces/*</url-pattern>
    </servlet-mapping>
</web-app>

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	?	?
krysalis-jCharts-1.0.0-alpha-1.jar	?	?

Optional Configuration

With 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:

<faces-config
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd"
    version="2.0"
    metadata-complete="false">
...
</<faces-config>

And if you are specifying your own components, use the new Facelets Taglib schema as well:

<facelet-taglib
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facelettaglibrary_2_0.xsd"
    version="2.0">
...
</facelet-taglib>

Advanced Configuration

ICEfaces 2.0 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. These parameters are fully documented in the Configuration section.