Skip to content

Installation and Configuration 2.x

Jump to bottom
AlexanderLitus edited this page Aug 12, 2014 · 3 revisions

TOCSTART

TOCEND

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
    JDom jdom.jar Version 1.0. You can skip adding it if it's already available for the application.
    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.
    Commons FileUpload commons-fileupload.jar Version 1.2.2. You can skip adding it if it's already available for the application.
    Commons IO commons-io.jar Version 2.1. You can skip adding it if it's already available for the application.
  3. Register the OpenFaces filter in your WEB-INF/web.xml file as follows: 
    <!-- FILTER FOR PROCESSING INTERNAL OPENFACES RESOURCES -->
  <filter>
    <filter-name>ResourceFilter</filter-name>
    <filter-class>org.openfaces.util.ResourceFilter</filter-class>
  </filter>

    <!-- MAPPING FOR OPENFACES RESOURCE FILTER -->
<filter-mapping>
<filter-name>ResourceFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

    For more details, see the Resource Filter Optimization section.

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

            </div>
    </div>
</li>
<li>(For MyFaces 1.2 only) In order for the OpenFaces session expiration feature to work properly in MyFaces 1.2,
    add the following lines to the WEB-INF/web.xml file:
    <div class="code panel" style="border-width: 1px;">
        <div class="codeContent panelContent">

    <context-param>
    <param-name>org.apache.myfaces.ERROR_HANDLING</param-name>
    <param-value>false</param-value>
</context-param>

            </div>
    </div>
</li>

    Using with Maven

    The following repository 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>

    Here's a dependency for the OpenFaces library itself:

    <dependency>
  <groupId>org.openfaces</groupId>
  <artifactId>openfaces</artifactId>
  <version>2.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>
<dependency>
  <groupId>net.sourceforge.cssparser</groupId>
  <artifactId>cssparser</artifactId>
  <version>0.9.5</version>
</dependency>
<dependency>
  <groupId>org.w3c.css</groupId>
  <artifactId>sac</artifactId>
  <version>1.3</version>
</dependency>
<dependency>
  <groupId>commons-fileupload</groupId>
  <artifactId>commons-fileupload</artifactId>
  <version>1.2.2</version>
</dependency>
<dependency>
  <groupId>commons-io</groupId>
  <artifactId>commons-io</artifactId>
  <version>2.1</version>
</dependency>
    Downloading Nightly Builds with Maven

    You can also automatically build your Maven projects using the pre-production builds of OpenFaces which are prepared each night and contain the latest features and fixes. To do this, you just should change the version number of the appropriate <dependency> entry to 2.x-nightly, like this:
    Here's a dependency for the OpenFaces library itself:

    <dependency>
  <groupId>org.openfaces</groupId>
  <artifactId>openfaces</artifactId>
  <version>2.x-nightly</version>
  <scope>compile</scope>
</dependency>

    You can always see what's new in nightly builds relative to the latest production build in this document.

    Installation in JSR-168 Portlets Environment

    To use OpenFaces in Portlets environment, you should first make all necessary steps from the section Installation.

    To ensure that default styles of the OpenFaces components are correctly applied, the following CSS reference should be defined in the <head> tag of the HTML page:

    <link rel='stylesheet' type='text/css'
href='/<AppName>/META-INF/resources/openfaces/default.css'/>

    where <AppName> is a Portlet context path.
    Adding this CSS reference is portal server-specific. For more details, read related server documentation.

    JBoss Portal 2.4.1 comes with bundled MyFaces 1.1.1. The OpenFaces library requires MyFaces 1.1.4 in order for Ajax to work properly in JBoss Portal. You can fix this by replacing the myfaces-iml.jar and myfaces-api.jar files in the <PATH_TO_JBOSS_PORTAL_SERVER>\server\default\deploy\jbossweb-tomcat55.sar\jsf-libs folder.

    If you use OpenFaces in JBoss Portal Server, you should specify the following portlet class in the WEB-INF/portelt.xml file:

    <portlet-class>org.openfaces.portlet.OpenFacesPortlet</portlet-class>

    This portlet class should be specified for both JSF implemenetations: MyFaces and Sun reference implementation. Please note that org.openfaces.portlet.OpenFacesPortlet class should be used instead of org.apache.myfaces.portlet.MyFacesGenericPortlet or com.sun.faces.portlet.FacesPortlet class, not in addition to it. Please also note that if you use Sun Reference implementation, you still have to place JSF portlet bridge (jsf-portlet.jar) to your portlet.

    Third-Party Libraries

    The OpenFaces library uses software developed by the JDOM Project, JFreeChart library, JCommon class library, CSS Parser library, Apache Commons FileUpload library, Apache Commons IO 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, jdom.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.

    IGNORESTART

    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, jdom.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.
    • Include the following notice in your documentation:

    [Name of your software] uses the following third-party libraries:

    IGNOREEND

    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.

    Resource Filter Optimization

    To improve performance, you can reduce the scope of requests that are handled by OpenFaces Resource Filter. For example, you can use the following ResourceFilter mappings in your web.xml:

    <!-- MAPPING FOR OPENFACES COMPONENTS FILTER -->
  <filter-mapping>
    <filter-name>ResourceFilter</filter-name>
    <servlet-name>Faces Servlet</servlet-name>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>FORWARD</dispatcher>
  </filter-mapping>

    <filter-mapping>
<filter-name>ResourceFilter</filter-name>
<url-pattern>/openFacesResources/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>

    Running Application in WebSphere Application Server

    WebSphere 8.0

    WebSphere v8.0 automatically includes one of its built in versions of JSF into the class path of your application. The version included by default is MyFaces 2.0. In order for your JSF 1.2 based application to work on WebSphere 8, you have to change the default JSF implementation to Sun reference implementation version 1.2 (aka Mojarra) in the WebSphere settings.

    You can do this in the WebSphere administration panel. In the "JSP and JSF options" page (Applications -> Application Types -> WebSphere enterprise applications -> <your application> -> JSP and JSF options) please change JSF implementation option to "SunRI1.2".

    IMPORTANT: Make sure to restart the WebSphere application server after you have changed this setting, for the changes to take effect.
    WebSphere 6.1

    To run the application with OpenFaces in WebSphere 6.1, update WebSphere to version 6.1.0.7. Also, make sure that the com.ibm.ws.webcontainer.invokefilterscompatibility property is set to "true". You can do this in the Custom Properties form (Application Servers -> <server> -> Web Container Settings -> Web Container -> Custom Properties). Once set, you should not change this custom property even if you upgrade the WebSphere Application Server.

    Then, follow these steps to run your OpenFaces application:

    1. Move ss_css2.jar from the WAR file to WebSphere libraries folder (only for MyFaces JSF implementation).
    2. Deploy the application to WebSphere.
    3. Specify a class loader for the application and module as "Application class loader first".
    4. Start the application.
    WebSphere 6.0

    To run the application with OpenFaces in WebSphere 6.0, update WebSphere to version 6.0.2.17. Then, follow these steps:

    1. Move ss_css2.jar from the WAR file to WebSphere libraries folder (only for MyFaces JSF implementation).
    2. Deploy the application to WebSphere.
    3. Specify a class loader for the application and module as "Parent last".
    4. Specify a class loader for the server as "Parent last" (only for MyFaces JSF implementation).
    5. Start the application.

    Running JSP Applications in WebLogic Application Server

    JSP applications running on WebLogic require a special version of OpenFaces jar to be used, so you should use the openfaces-weblogic-jsp.jar file, that can be found in the distribution package, instead of openfaces.jar, when adding OpenFaces to your application. These two files are identical except a minor change in META-INF/openfaces.tld file that is required because of WebLogic's specifics of handling namespace URLs.

    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 JSF RI 1.2 (aka Mojarra 1.2). OpenFaces demo can run on Tomcat 6.0 application server without any changes. Running on other servers might require a different set of libraries and appropriate changes in web.xml (this mostly concerns the cases when other JSF implementation is bundled with a particular server).

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

    1. Unzip OpenFaces-<version> demo-facelets.zip or OpenFaces<version>-demo-jsp.zip for a Facelets or JSP version of the demo respectively.
    2. Copy openfaces-demo-facelets.war (or openfaces-demo-jsp.war for a JSP version) to the webapps folder of the Tomcat 6.0.x server.
    3. Run the Tomcat server.
    4. In your browser, open http://ServerName:PortNumber/openfaces-demo-facelets/ (or ...openfaces-demo-jsp for a JSP version of the demo).
Clone this wiki locally