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

Include the Necessary Libraries

ICEfaces provides the following libraries:

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

• icepush.jar - Provides Ajax Push functionality for ICEfaces. 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 ACE Components. You should include this library if you want to use latest ICEfaces components in your application. See the ACE Components topic for details.

• icefaces-compat.jar - This library contains the ICE Components (formerly known as the ICEfaces Component Suite in 1.x). You should include this library if you want to use the ICE Components in your application. See the ICE Components and ICEfaces 1.x Compatibility Features of ICEfaces 3 topics for more information. (ICEfaces 3.x only)

The ICE Components require additional 3rd party libraries. See the ICE 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 7 already have the JSF 2 libraries provided, but servlet-containers such as Tomcat do not.

http://www.icesoft.org/java/services/icefaces-professional-services.jsf

Configuration

The ICEfaces core framework (icefaces.jar), ICEpush (icepush.jar), and ACE 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>

ICE Components Configuration

The ICE Components require additional configuration steps before they can be used in your application. See the ICE Components topic for details. (ICEfaces 3.x only)

Optional Configuration

With ICEfaces 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 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.