Installation and Configuration

Installation

Provided that you already have a JSF application, the following steps will allow you to use OpenFaces components in your application:

  1. Add openfaces.jar to the application libraries.
  2. Add the following libraries found in the distribution under the lib folder to the application:
    Library Distribution file name Notes
    CSS Parser cssparser.jar Version 0.9.5. You can skip adding it if it's already available for the application.
    SAC: The Simple API for CSS sac.jar Version 1.3. You can skip adding it if it's already available for the application.
    JCommon jcommon.jar Version 1.0.16. You can skip adding it if it's already available for the application.
    JFreeChart jfreechart.jar Version 1.0.13. You can skip adding it if it's already available for the application.
    Commons-Collections commons-collections.jar Version 3.1. You can skip adding it if it's already available for the application.
  1. (Optional) If you want to turn on automatic client-side validation for all pages, add the following lines to the WEB-INF/web.xml file (see Validation Framework documentation for more information):
    <context-param>
        <param-name>org.openfaces.validation.clientValidation</param-name>
        <param-value>onSubmit</param-value>
      </context-param>

Using with Maven

The following repositories should be added to the <repositories> tag in your pom.xml file to make OpenFaces itself and its dependencies (such as JFreeChart) to be available:

<repository>
  <id>org.openfaces</id>
  <url>http://repository.openfaces.org/repository</url>
</repository>
<repository>
  <id>jfree</id>
  <url>http://www.ibiblio.org/maven/jfree/</url>
</repository>

Here's a dependency for the OpenFaces library itself:

<dependency>
      <groupId>org.openfaces</groupId>
      <artifactId>openfaces</artifactId>
      <version>3.0</version>
      <scope>compile</scope>
    </dependency>

And here are the dependencies required for OpenFaces at runtime:

<dependency>
  <groupId>commons-collections</groupId>
  <artifactId>commons-collections</artifactId>
  <version>3.1</version>
</dependency>
<dependency>
  <groupId>jfree</groupId>
  <artifactId>jcommon</artifactId>
  <version>1.0.16</version>
</dependency>
<dependency>
  <groupId>jfree</groupId>
  <artifactId>jfreechart</artifactId>
  <version>1.0.13</version>
</dependency>

Third-Party Libraries

The OpenFaces library uses software developed by the JFreeChart library, JCommon class library, CSS Parser library and parts of code from Apache MyFaces Project, Apache Commons codec and JSON software.

Redistribution

When distributing your application, please make sure to:

  • Include the following libraries to your project:
    • openfaces.jar (OpenFaces library)
    • Third-party libraries used by the OpenFaces library: jcommon.jar, jfreechart.jar, ss_css2.jar (for more details, see the section Third-Party Libraries)
  • Include a copy of the LGPL license.
  • Include a copy of the Apache License.

Using OpenFaces Library

To use components of the OpenFaces library, you should declare "http://openfaces.org/" namespace with "o" prefix. To do it, add the following piece of code to the JSP application:

<%@taglib uri="http://openfaces.org/" prefix="o" %>

Or add the following parameter to the <HTML> tag to the Facelets application:

xmlns:o="http://openfaces.org/"

Application Context Parameters

All application context parameters are summarized in the following table:

Parameter Description
org.openfaces.ajax.sessionExpiration The application-wide setting that specifies the way session expiration is handled. Property has two possible values "default" (default value) and "silent". For more details see Ajax Framework documentation.
org.openfaces.validation.clientValidation The application-wide settings of the OpenFaces validation framework. For more details see Validation Framework documentation.
torg.openfaces.validation.disabled The flag that indicates whether or not the OpenFaces validation for all application is disabled. Default is "false". If org.openfaces.validation.disabled property is set to "true" all OpenFaces validation features are turned off. This property can be used for debugging purposes.
org.openfaces.validation.useDefaultClientPresentation The flag that indicates whether or not validatable components use the default presentation if no validation or conversion error presentation is set for these components. This property is relevant when client-side validation is turned on for the application. For more details see Validation Framework documentation.
org.openfaces.validation.useDefaultServerPresentation The flag that indicates whether or not validatable components use the default presentation if no validation or conversion error presentation is set for these components. This property is relevant when client-side validation is turned off for the application. For more details see Validation Framework documentation.
org.openfaces.validation.defaultPresentationClass The full class name of the component that will be used as a default validation presentation component. The component should extend the UIMessage class. If this parameter is omitted, the FloatingIconMessage component is used as a default validation presentation component. Parameters for the validation presentation component are specified as application-scope context parameters in the web.xml file, with the name that contains preceding validation presentation component's class name without package specification, following dot "." and component's attribute name. For more details see Validation Framework documentation.
org.openfaces.ajaxMessageHTML Specifies the message that appears when any Ajax request is in progress. This parameter should be specified as portion of HTML that will be shown in the upper-right corner upon an Ajax request. For more details see Ajax Framework section in the OpenFaces Developers Guide.
org.openfaces.autoSaveFocus The flag that indicates whether or not focus is saved between form submissions for all application pages. For more details see Focus Component documentation.
org.openfaces.autoSaveScrollPos The flag that indicates whether or not the scroll position is tracked for all application pages. For more details see Scroll Position Component documentation.

Setting Up a Local Copy of OpenFaces Demo Application

The binary and source distribution of OpenFaces demo application can be found in the OpenFaces downloads page. There are two versions of the demo, both having the same functionality but based on different view technologies: the Facelets-based, and the JSP-based one. The demo package is bundled with Mojarra 2.0. OpenFaces demo can run on Tomcat 6.0 and GlassFish v3 application servers without any changes. Running on other servers might require a different set of libraries and appropriate changes in web.xml.

To run OpenFaces demo on the local machine, follow these steps:

  1. Unzip OpenFaces-<version>-demo-facelets.zip package.
  2. Copy openfaces-demo-facelets.war to the webapps directory of the Tomcat 6.0.x server (or autodeploy direcotry of Glassifsh v3 server).
  3. Run the server.
  4. In your browser, open http://ServerName:PortNumber/openfaces-facelets-demo/ .
OpenFaces