View Source

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

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

h3. 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|Ajax Push - Overview], and [API|Ajax Push - APIs] 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)

{note}The ICE Components require additional 3rd party libraries. See the [ICE Components] topic for details.{note}

* *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][!icefaces-services-wiki.png|align=center!|http://www.icesoft.org/java/services/icefaces-professional-services.jsf]

h3. 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:
{code:xml} <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>

{code}
h3. 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)


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

{code:xml}<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>
{code}
And if you are specifying your own components, use the new Facelets Taglib schema as well:

{code:xml}<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>{code}
h3. 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.