Skip Headers
Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1)

Part Number B31973-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

A ADF Faces Configuration

This appendix describes how to configure JSF and ADF Faces features in various XML configuration files, and how to retrieve ADF Faces configuration values using the RequestContext API.

This chapter includes the following sections:

A.1 Introduction to Configuring ADF Faces

A JSF web application requires a specific set of configuration files, namely, web.xml and faces-config.xml. ADF applications also store configuration information in the adf-config.xml and adf-settings.xml files. Because ADF Faces shares the same code base with MyFaces Trinidad, a JSF application that uses ADF Faces components for the UI also must include a trinidad-config.xml file, and optionally a trinidad-skins.xml file. For more information about the relationship between Trinidad and ADF Faces, see Chapter 1, "Introduction to ADF Faces Rich Client".

A.2 Configuration in web.xml

Part of a JSF application's configuration is determined by the contents of its Java EE application deployment descriptor, web.xml. The web.xml file, which is located in the /WEB-INF directory, defines everything about your application that a server needs to know (except the root context path, which is automatically assigned for you in JDeveloper, or assigned by the system administrator when the application is deployed). Typical runtime settings in the web.xmlfile include initialization parameters, custom tag library location, and security settings.

The following is configured in the web.xmlfile for all applications that use ADF Faces:

Note:

JDeveloper automatically adds the necessary ADF Faces configurations to the web.xml file for you the first time you use an ADF Faces component in an application.

For more information about the required elements, see Section A.2.2, "What You May Need to Know About Required Elements in web.xml".

For information about optional configuration elements in web.xml related to ADF Faces, see Section A.2.3, "What You May Need to Know About ADF Faces Context Parameters in web.xml".

For information about configuring web.xml outside of ADF Faces, see Developing Web Applications, Servlets, and JSPs for WebLogic Server at http://download.oracle.com/docs/cd/E12839_01/wls/docs103/webapp/index.html

A.2.1 How to Configure for JSF and ADF Faces in web.xml

In JDeveloper, when you create a project that uses JSF technology, a starter web.xml file with default servlet and mapping elements is created for you in the /WEB-INF directory.

When you use ADF Faces components in a project (that is, a component tag is used on a page rather than just importing the library), in addition to default JSF configuration elements, JDeveloper also automatically adds the following to the web.xml file for you:

  • Configuration elements that are related to MyFaces Trinidad filter and MyFaces Trinidad resource servlet

  • Context parameter javax.faces.STATE_SAVING_METHOD with the value of client

When you elect to use JSP fragments in the application, JDeveloper automatically adds a JSP configuration element for recognizing and interpreting .jsff files in the application.

Example A-1 shows the web.xml file with the default elements that JDeveloper adds for you when you use JSF and ADF Faces and .jsff files.

For information about the web.xml configuration elements needed for working with JSF and ADF Faces, see Section A.2.2, "What You May Need to Know About Required Elements in web.xml".

Example A-1 Generated web.xml File

<?xml version = '1.0' encoding = 'windows-1252'?><web-app 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-app_2_5.xsd" version="2.5"
         xmlns="http://java.sun.com/xml/ns/javaee">
  <description>Empty web.xml file for Web Application</description>
  <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>/faces/*</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>35</session-timeout>
  </session-config>
  <mime-mapping>
    <extension>html</extension>
    <mime-type>text/html</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>txt</extension>
    <mime-type>text/plain</mime-type>
  </mime-mapping>
</web-app>

Note:

When you use ADF data controls to build databound web pages, the ADF binding filter and a servlet context parameter for the application binding container are added to the web.xml file.

Configuration options for ADF Faces are set in the web.xml file using <context-param> elements.

To add ADF Faces configuration elements in web.xml:

  1. In the Application Navigator, double-click web.xml to open the file.

    By default, JDeveloper opens the web.xml file in the overview editor, as indicated by the active Overview tab at the bottom of the editor window.

    When you use the overview editor to add or edit entries declaratively, JDeveloper automatically updates the web.xml file for you.

  2. To edit the XML code directly in the web.xml file, click Source at the bottom of the editor window.

    When you edit elements in the XML editor, JDeveloper automatically reflects the changes in the Overview editor.

For a list of context parameters you can add, see Section A.2.3, "What You May Need to Know About ADF Faces Context Parameters in web.xml".

A.2.2 What You May Need to Know About Required Elements in web.xml

The required, application-wide configuration elements for JSF and ADF Faces in the web.xml file are:

  • Context parameter javax.faces.STATE_SAVING_METHOD: Specifies where to store the application's view state. By default this value is server, which stores the application's view state on the server. It is recommended that you set javax.faces.STATE_SAVING_METHOD to client when you use ADF Faces, to store the view state on the browser client. When set to client, ADF Faces then automatically uses token-based, client-side state saving. You can specify the number of tokens to use instead of using the default number of 15. For more information about state-saving context parameters, see Section A.2.3, "What You May Need to Know About ADF Faces Context Parameters in web.xml".

  • MyFaces Trinidad filter and mapping: Installs the MyFaces Trinidad filter org.apache.myfaces.trinidad.webapp.TrinidadFilter, which is a servlet filter that ensures ADF Faces is properly initialized in part by establishing a RequestContext object. TrinidadFilter also processes file uploads. The filter mapping maps the JSF servlet's symbolic name to the MyFaces Trinidad filter. The forward and request dispatchers are needed for any other filter that is forwarding to the MyFaces Trinidad filter.

    Tip:

    If you use multiple filters in your application, ensure that they are listed in the web.xml file in the order in which you want to run them. At runtime, the filters are called in the sequence listed in that file.
  • MyFaces Trinidad resource servlet and mapping: Installs the MyFaces Trinidad resource servlet org.apache.myfaces.trinidad.webapp.ResourceServlet, which serves up web application resources (images, style sheets, JavaScript libraries) by delegating to a resource loader. The servlet mapping maps the MyFaces Trinidad resource servlet's symbolic name to the URL pattern. By default, JDeveloper uses /adf/* for MyFaces Trinidad Core, and /afr/* for ADF Faces.

  • JSF servlet and mapping (added when creating a JSF JSP page or using a template with ADF Faces components): The JSF servlet servlet javax.faces.webapp.FacesServlet manages the request processing lifecycle for web applications that utilize JSF to construct the user interface. The mapping maps the JSF servlet's symbolic name to the URL pattern, which can use either a path prefix or an extension suffix pattern.

    By default JDeveloper uses the path prefix /faces/*, as shown in the following code:

    <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>/faces/*</url-pattern>
      </servlet-mapping>
    

    For example, if your web page is index.jspx, this means that when the URL http://localhost:8080/MyDemo/faces/index.jspx is issued, the URL activates the JSF servlet, which strips off the faces prefix and loads the file /MyDemo/index.jspx.

A.2.3 What You May Need to Know About ADF Faces Context Parameters in web.xml

ADF Faces configuration options are defined in the web.xml file using <context-param> elements. For example:

<context-param>
  <param-name>oracle.adf.view.rich.LOGGER_LEVEL</param-name>
  <param-value>ALL</param-value>
</context-param>

The following context parameters are supported for ADF Faces.

A.2.3.1 State Saving

You can specify the following state-saving context parameters:

  • org.apache.myfaces.trinidad.CLIENT_STATE_METHOD: Specifies the type of client-side state saving to use when client-side state saving is enabled by using javax.faces.STATE_SAVING_METHOD. The values for CLIENT_STATE_METHOD are:

    • token: (Default) Stores the page state in the session, but persists a token to the client. The simple token, which identifies a block of state stored back on the HttpSession object, is stored on the client. This enables ADF Faces to disambiguate the same page appearing multiple times. Failover is supported.

    • all: Stores all state information on the client in a (potentially large) hidden form field. It is useful for developers who do not want to use HttpSession.

    Performance Tip:

    Client-side state saving is recommended. However, because of the potential size of storing all state information, it is recommended that you set client-state saving to token.
  • org.apache.myfaces.trinidad.CLIENT_STATE_MAX_TOKENS: Specifies how many tokens should be stored at any one time per user, when token-based client-side state saving is enabled. The default is 15. When the number of tokens is exceeded, the state is lost for the least recently viewed pages, which affects users who actively use the Back button or who have multiple windows opened at the same time. If you are building HTML applications that rely heavily on frames, you would want to increase this value.

A.2.3.2 Debugging

You can specify the following debugging context parameters:

  • org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT: ADF Faces, by default, obfuscates the JavaScript it delivers to the client, stripping comments and whitespace at the same time. This dramatically reduces the size of the ADF Faces JavaScript download, but it also makes it tricky to debug the JavaScript. Set to true to turn off the obfuscation during application development. Set to false for application deployment.

  • org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION: By default this parameter is false. If it is set to true, ADF Faces will automatically check the modification date of your JSPs and CSS files, and discard the saved state when the files change.

    Performance Tip:

    When set to true, this parameter adds overhead that should be avoided when your application is deployed. Set to false when deploying your application to a runtime environment.
  • oracle.adf.view.rich.LOGGER_LEVEL: This parameter enables JavaScript logging when the default render kit is oracle.adf.rich. The default is OFF. If you wish to turn on JavaScript logging, use one of the following levels: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, and ALL. Set to INFO if you have enabled automated profiler instrumentation code (see oracle.adf.view.rich.profiler.ENABLED in Section A.2.3.7, "Profiling").

    Performance Tip:

    JavaScript logging will affect performance. You should set this value to OFF in a runtime environment.

A.2.3.3 File Uploading

You can specify the following file upload context parameters:

  • org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY: Specifies the maximum amount of memory that can be used in a single request to store uploaded files. The default is 100K.

  • org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE: Specifies the maximum amount of disk space that can be used in a single request to store uploaded files. The default is 2000K.

  • org.apache.myfaces.trinidad.UPLOAD_TEMP_DIR: Specifies the directory where temporary files are to be stored during file uploading. The default is the user's temporary directory.

Note:

The file upload initialization parameters are processed by the default UploadedFileProcessor only. If you replace the default processor with a custom UploadedFileProcessor implementation, the parameters are not processed.

A.2.3.4 Resource Debug Mode

You can specify the following:

  • org.apache.myfaces.trinidad.resource.DEBUG: Specifies whether or not resource debug mode is enabled. The default is false. Set to true if you want to enable resource debug mode. When enabled, ADF Faces sets HTTP response headers to let the browser know that resources (such as JavaScript libraries, images, and CSS) can be cached.

    Tip:

    After turning on resource debug mode, clear your browser cache to force the browser to load the latest versions of the resources.

    Performance Tip:

    In a production environment, this parameter should be removed or set to false.

A.2.3.5 Change Persistence

You set session change persistence by registering the appropriate ChangeManager class using the org.apache.myfaces.trinidad.CHANGE_PERSISTENCE context parameter. The valid value for storing changes to session scope is session.

Example A-2 shows a web.xml file configured to persist changes to the session.

Example A-2 Registering the Change Manager

<context-param>
  <param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
  <param-value>session</param-value>
</context-param>

For more information about enabling and using session change persistence, see Chapter 28, "Persisting Component Changes".

A.2.3.6 Assertions

You can specify whether or not assertions are used within ADF Faces using the oracle.adf.view.rich.ASSERT_ENABLED parameter. The default is false. Set to true to turn on assertions.

Performance Tip:

Assertions add overhead. Set this value to false in a runtime environment.

A.2.3.7 Profiling

You can specify the following JavaScript profiling context parameters:

  • oracle.adf.view.rich.profiler.ENABLED: Specifies whether or not to use the automated profiler instrumentation code provided with the JavaScript Profiler. The default is false. Set to true to enable the JavaScript profile. When the profiler is enabled, an extra round-trip is needed on each page to fetch the profiler data. By default, JDeveloper uses the /WEB-INF/profiler.xml configuration file. To override the location of the profiler.xml file, use the ROOT_FILE context parameter, as described next. You may also want to set DEBUG_JAVASCRIPT to true, to turn off JavaScript obfuscation. You also must set the LOGGER_LEVEL to at least INFO.

  • oracle.adf.view.rich.profiler.ROOT_FILE: Specifies the initial profiler.xml file to load, if automated profiler instrumentation code is turned on. By default, JDeveloper uses the /WEB-INF/profiler.xml file if ROOT_FILE is not specified.

A.2.3.8 Facelets Support

Specify the following if you intend to use Facelets with ADF Faces:

  • org.apache.myfaces.trinidad.ALTERNATE_VIEW_HANDLER: Install FaceletsViewHandler by setting the parameter value to com.sun.facelets.FaceletViewHandler.

  • javax.faces.DEFAULT_SUFFIX: Use .xhtml as the file extension for documents that use Facelets.

A.2.3.9 Dialog Prefix

To change the prefix for launching dialogs, set the org.apache.myfaces.trinidad.DIALOG_NAVIGATION_PREFIX parameter.

The default is dialog:, which is used in the beginning of the outcome of a JSF navigation rule that launches a dialog (for example, dialog:error).

A.2.3.10 Compression for CSS Class Names

You can set the org.apache.myfaces.trinidadinternal.DISABLE_CONTENT_COMPRESSION parameter to determine compression of the CSS class names for skinning keys.

The default is false. Set to true if you want to disable the compression.

Performance Tip:

In a production environment, set this parameter to false.

A.2.3.11 Test Automation

When you set the oracle.adf.view.rich.automation.ENABLED parameter to true and when the component ID attribute is null, the component testId attribute is used during automated testing to ensure the ID is not null. The testId is attribute only on the tag, it is not part of the Java component API.

A.2.3.12 UIViewRoot Caching

Use the org.apache.myfaces.trinidad.CACHE_VIEW_ROOT parameter to enable or disable UIViewRoot caching. When token client-side state saving is enabled, MyFaces Trinidad can apply an additional optimization by caching an entire UIViewRoot tree with each token. (Note that this does not affect thread safety or session failover.) This is a major optimization for AJAX-intensive systems, as postbacks can be processed far more rapidly without the need to reinstantiate the UIViewRoot tree.

You set the org.apache.myfaces.trinidad.CACHE_VIEW_ROOT parameter to true to enable caching. This is the default. Set the parameter to false to disable caching.

Note:

This type of caching is known to interfere with some other JSF technologies. In particular, the Apache MyFaces Tomahawk saveState component does not work, and template text in Facelets may appear in duplicate.

A.2.3.13 Themes and Tonal Styles

Use the oracle.adf.view.rich.tonalstyles.ENABLED parameter to turn the use of tonal styles off or on. While the tonal style classes, .AFDarkTone, .AFMediumTone, .AFLightTone and .AFDefaultTone style classes are still available for the purpose of backward compatibility, themes are provided as a replacement style. Themes are easier to author than tonal styles, rely on fewer selectors, and avoid CSS containment selectors; therefore, they are less prone to bugs. Due to the limitation on the number of selectors in one CSS file, both tonal styles and themes cannot be supported in the same application. Set to false to disable tonal styles.

A.2.3.14 Partial Page Navigation

Use the oracle.adf.view.rich.pprNavigation.OPTIONS parameter to turn partial page navigation on and off. By default, the value is off. Partial page navigation uses the same base page throughout the application, and simply replaces the body content of the page with each navigation. This results in better performance as JavaScript libraries and style sheets do not need to be reloaded with each new page. For more information, see Section 7.4, "Partial Page Navigation".

Valid values are:

  • on: PPR navigation is turned on for the application.

    Note:

    If you set the parameter to on, then you need to set the partialSubmit attribute to true for any command components involved in navigation. (for more information about partialSubmit, see Section 5.1.1, "Events and Partial Page Rendering")
  • off: PPR navigation is turned off for the application.

  • onWithForcePPR: When an action on a command component results in navigation, the action will always be delivered using PPR, as if the component had partialSubmit set to true (for more information about partialSubmit, see Section 5.1.1, "Events and Partial Page Rendering"). Therefore, if the component already has partialSubmit set to true, the framework does nothing. Otherwise, the entire document is refreshed to ensure that old page refresh behavior is preserved. The entire document is also refreshed if the action component does not contain navigation.

A.2.4 What You May Need to Know About Other Context Parameters in web.xml

Other optional, application-wide context parameters are:

  • javax.faces.CONFIG_FILE: Specifies paths to JSF application configuration resource files. Use a comma-separated list of application-context relative paths for the value, as shown in the following code. Set this parameter if you use more than one JSF configuration file in your application.

    <context-param>
      <param-name>javax.faces.CONFIG_FILES</param-name>
      <param-value>
       /WEB-INF/faces-config1.xml,/WEB-INF/faces-config2.xml
      </param-value>
    </context-param>
    
  • javax.faces.DEFAULT_SUFFIX: Specifies a file extension (suffix) for JSP pages that contain JSF components. The default value is .jsp.

    Note:

    This parameter value is ignored when you use prefix mapping for the JSF servlet (for example, /faces), which is done by default for you.
  • javax.faces.LIFECYCLE_ID: Specifies a lifecycle identifier other than the default set by the javax.faces.lifecycle.LifecycleFactory.DEFAULT_LIFECYCLE constant.

    Caution:

    Setting this to any other value will break ADF Faces.
  • org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION: Specifies whether JSP and CSS files require a restart in order to see changes at runtime. By default, set to false. Set to true if you want to be able to view changes without restarting the server.

A.3 Configuration in faces-config.xml

The JSF configuration file is where you register a JSF application's resources such as custom validators and managed beans, and define all the page-to-page navigation rules. While an application can have any JSF configuration file name, typically the file name is the faces-config.xml file. Small applications usually have one faces-config.xml file.

When you use ADF Faces components in your application, JDeveloper automatically adds for you the necessary configuration elements into faces-config.xml. For more information about the faces-config.xml file, see the Java EE 5 tutorial on Sun's web site (http://java.sun.com).

A.3.1 How to Configure for ADF Faces in faces-config.xml

In JDeveloper, when you create a project that uses JSF technology, an empty faces-config.xml file is created for you in the /WEB-INF directory. An empty faces-config.xml file is also automatically added for you when you create a new application workspace based on an application template that uses JSF technology (for example, the Java EE Web Application template. For more information, see Section 2.2, "Creating an Application Workspace".

When you use ADF Faces components in your application, the ADF default render kit ID must be set to oracle.adf.rich. When you insert an ADF Faces component into a JSF page for the first time, or when you add the first JSF page to an application workspace that was created using the Fusion template, JDeveloper automatically inserts the default render kit for ADF components into the faces-config.xml file, as shown in Example A-3.

Example A-3 ADF Default Render Kit Configuration in faces-config.xml

<?xml version="1.0" encoding="windows-1252"?>
<faces-config version="1.2" xmlns="http://java.sun.com/xml/ns/javaee">
  <application>
    <default-render-kit-id>oracle.adf.rich</default-render-kit-id>
  </application>
</faces-config>

Typically, you would configure the following in then faces-config.xml file:

  • Application resources such as message bundles and supported locales

  • Page-to-page navigation rules

  • Custom validators and converters

  • Managed beans for holding and processing data, handling UI events, and performing business logic

Note:

If your application uses the ADF Controller, these items are configured in the adfc-config.xml file. For more information, see the "Getting Started With Task Flows" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

In JDeveloper, you can use the declarative overview editor to modify the faces-config.xml file. If you are familiar with the JSF configuration elements, you can use the XML editor to edit the code directly.

To edit faces-config.xml in JDeveloper:

  1. In the Application Navigator, double-click faces-config.xml to open the file.

    By default, JDeveloper opens the faces-config.xml file in the overview editor, as indicated by the active Overview tab at the bottom of the editor window.

    When you use the overview editor to add for example, managed beans and validators declaratively, JDeveloper automatically updates the faces-config.xml file for you.

  2. To edit the XML code directly in the faces-config.xml file, click Source at the bottom of the editor window.

    When you edit elements in the XML editor, JDeveloper automatically reflects the changes in the Overview editor.

Tip:

JSF allows more than one <application> element in a single faces-config.xml file. The Overview mode of the JSF Configuration Editor allows you to edit only the first <application> instance in the file. For any other <application> elements, you will need to edit the file directly using the XML editor.

A.4 Configuration in adf-config.xml

The adf-config.xml file is used to configure application-wide features, like security, caching, and change persistence. Other Oracle components also configure properties in this file.

A.4.1 How to Configure ADF Faces in adf-config.xml

Before you can provide configuration for your application, you must first create the adf-config.xml file. Then you can add configuration for any application-wide ADF features that your application will use.

To create and edit adf-config.xml in JDeveloper:

  1. If not already created, create a META-INF directory for your project.

  2. Right-click the META-INF directory, and choose New from the context menu.

  3. In the Categories pane of the New Gallery, under the General node, select XML, and in the Items pane, select XML Document.

    Tip:

    If you don't see the General node, click the All Technologies tab at the top of the Gallery.
  4. Enter adf-config.xml as the file name and save it in the META-INF directory.

  5. In the source editor, replace the generated code with the code shown in Example A-4.

    Example A-4 XML for adf-config.xml File

    <?xml version="1.0" encoding="utf-8" ?>
    <adf-config xmlns="http://xmlns.oracle.com/adf/config"
                xmlns:ads="http://xmlns.oracle.com/adf/activedata/config">
     
    </adf-config>
    
  6. You can now add the elements needed for the configuration of features you wish to use.

A.5 Configuration in adf-settings.xml

The adf-settings.xml file holds project- and library-level settings such as ADF Faces help providers. The configuration settings for the adf-settings.xml files are fixed and cannot be changed during and after application deployment. There can be multiple adf-settings.xml files in an application. ADF settings file users are responsible for merging the contents of their configurations.

A.5.1 How to Configure for ADF Faces in adf-settings.xml

Before you can provide configuration for your application, you must first create the adf-settings.xml file. Then you can add the configuration for any project features that your application will use. For more information about configurations in this file, see Section A.5.2, "What You May Need to Know About Elements in adf-settings.xml".

To create and edit adf-settings.xml in JDeveloper:

  1. If not already created, create a META-INF directory for your project.

  2. Right-click the META-INF directory, and choose New from the context menu.

  3. In the Categories pane of the New Gallery, under the General node, select XML, and in the Items pane, select XML Document.

    Tip:

    If you don't see the General node, click the All Technologies tab at the top of the Gallery.
  4. In the source editor, replace the generated code with the code shown in Example A-5, with the correct settings for your web application root.

    Example A-5 XML for adf-settings.xml File

    <adf-settings xmlns="http://xmlns.oracle.com/adf/settings"
                  xmlns:wap="http://xmlns.oracle.com/adf/share/http/config" >
      <wap:adf-web-config xmlns="http://xmlns.oracle.com/adf/share/http/config">
        <web-app-root rootName="myroot" />
      </wap:adf-web-config>
    </adf-settings>
    
  5. You can now add the elements needed for the configuration of features you wish to use. For more information, see Section A.5.2, "What You May Need to Know About Elements in adf-settings.xml".

A.5.2 What You May Need to Know About Elements in adf-settings.xml

The following configuration elements are supported in the adf-settings.xml file.

A.5.2.1 Help System

You register the help provider used by your help system using the following elements:

  • <adf-faces-config>: A parent element that groups ADF Faces specific configurations.

  • <prefix-characters>: The provided prefix if the help provider is to supply help topics only for help topic IDs beginning with a certain prefix. This can be omitted if prefixes are not used.

  • <help-provider-class>: The help provider class.

  • <custom-property> and <property-value>: A property element that defines the parameters the help provider class accepts.

Example A-6 shows an example of a registered help provider. In this case, there is only one help provider for the application, so there is no need to include a prefix.

Example A-6 Help Provider Registration

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
  <help-provider prefix="MYAPP">
    <help-provider-class>
      oracle.adfdemo.view.webapp.MyHelpProvider
    </help-provider-class>
    <property>
      <property-name>myCustomProperty</property-name>
      <value>someValue</value>
    </property>
  </help-provider>
</adf-faces-config>
</adf-settings>

A.6 Configuration in trinidad-config.xml

When you create a JSF application using ADF Faces components, you configure ADF Faces features (such as skin family and level of page accessibility support) in the trinidad-config.xml file. Like faces-config.xml, the trinidad-config.xml file has a simple XML structure that enables you to define element properties using the JSF Expression Language (EL) or static values.

A.6.1 How to Configure ADF Faces Features in trinidad-config.xml

In JDeveloper, when you insert an ADF Faces component into a JSF page for the first time, a starter trinidad-config.xml file is automatically created for you in the /WEB-INF directory. Example A-7 shows a starter trinidad-config.xml file.

Example A-7 Starter trinidad-config.xml File Created by JDeveloper

<?xml version="1.0" encoding="windows-1252"?>
<trinidad-config xmlns="http://xmlns.oracle.com/trinidad/config">
 
  <skin-family>blafplus-rich</skin-family>
 
</trinidad-config>

By default, JDeveloper configures the blafplus-rich skin family for a JSF application that uses ADF Faces. You can change this to blafplus-medium, simple, or use a custom skin. If you wish to use a custom skin, create the trinidad-skins.xml configuration file, and modify trinidad-config.xml file to use the custom skin. For more information about creating custom skins, see Chapter 19, "Customizing the Appearance Using Styles and Skins".

Typically, you would configure the following in the trinidad-config.xml file:

  • Page animation

  • Level of page accessibility support

  • Time zone

  • Enhanced debugging output

  • Oracle Help for the Web (OHW) URL

You can also register a custom file upload processor for uploading files.

In JDeveloper, you can use the XML editor to modify the trinidad-config.xml file.

To edit trinidad-config.xml in JDeveloper:

  1. In the Application Navigator, double-click trinidad-config.xml to open the file in the XML editor.

  2. If you are familiar with the element names, enter them in the editor. Otherwise use the Structure window to help you insert them.

  3. In the Structure window:

    1. Right-click an element to choose from the Insert before or Insert after menu, and click the element you wish to insert.

    2. Double-click the newly inserted element in the Structure window to open it in the properties editor. Enter a value or select one from a dropdown list (if available).

      In most cases you can enter either a JSF EL expression (such as #{view.locale.language=='en' ? 'minimal' : 'blafplus-rich'}) or a static value (for example., <debug-output>true</debug-output>). EL expressions are dynamically reevaluated on each request, and must return an appropriate object (for example, a Boolean object).

For a list of the configuration elements you can use, see Section A.6.2, "What You May Need to Know About Elements in trinidad-config.xml".

Once you have configured the trinidad-config.xml file, you can retrieve the property values programmatically or by using JSF EL expressions. For more information, see Section A.8, "Using the RequestContext EL Implicit Object".

A.6.2 What You May Need to Know About Elements in trinidad-config.xml

All trinidad-config.xml files must begin with a <trinidad-config> element in the http://myfaces.apache.org/trinidad/config XML namespace. The order of elements inside of <trinidad-config> does not matter. You can include multiple instances of any element.

A.6.2.1 Animation Enabled

Certain ADF Faces components use animation when rendering. For example, trees and tree tables use animation when expanding and collapsing nodes. The following components use animation when rendering:

  • Table detail facet for disclosing and undisclosing the facet

  • Trees and tree table when expanding and collapsing nodes

  • Menus

  • Popup selectors

  • Dialogs

  • Note windows and message displays

The type and time of animation used is configured as part of the skin for the application. For more information, see Chapter 19, "Customizing the Appearance Using Styles and Skins".

You can set the animation-enabled element to either true or false, or you can use an EL expression that resolves to either true or false.

A.6.2.2 Skin Family

As described in Section A.6.1, "How to Configure ADF Faces Features in trinidad-config.xml", JDeveloper by default uses the blafplus-rich skin family for a JSF application that uses ADF Faces. You can change the <skin-family> value to blafplus-medium, simple, or use a custom skin. For information about creating and using custom skins, see Chapter 19, "Customizing the Appearance Using Styles and Skins".

You can use an EL expression for the skin family value, as shown in the following code:

<skin-family>#{prefs.proxy.skinFamily}</skin-family>

A.6.2.3 Time Zone and Year

To set the time zone used for processing and displaying dates, and the year offset that should be used for parsing years with only 2 digits, use the following elements:

  • <time-zone>: By default, ADF Faces uses the time zone used by the client browser. If needed, you can use an EL expression that evaluates to a TimeZone object. This value is used by org.apache.myfaces.trinidad.converter.DateTimeConverter while converting strings to Date.

  • <two-digit-year-start>: This defaults to the year 1950 if no value is set. If needed, you can use a static, integer value or an EL expression that evaluates to an Integer object. This value is used by org.apache.myfaces.trinidad.converter.DateTimeConverter to convert strings to Date.

A.6.2.4 Enhanced Debugging Output

By default, the <debug-output> element is false. ADF Faces enhances debugging output when you set <debug-output> to true. The following features are then added to debug output:

  • Automatic indenting

  • Comments identifying which component was responsible for a block of HTML

  • Detection of unbalanced elements, repeated use of the same attribute in a single element, or other malformed markup problems

  • Detection of common HTML errors (for example, <form> tags inside other <form> tags or <tr> or <td> tags used in invalid locations).

Performance Tip:

Set this parameter to false in a production environment.

A.6.2.5 Page Accessibility Level

Use <accessibility-mode> to define the level of accessibility support in an application. The supported values are:

  • default: Output supports accessibility features.

  • inaccessible: Accessibility-specific constructs are removed to optimize output size.

  • screenReader: Accessibility-specific constructs are added to improve behavior under a screen reader (but may have a negative effect on other users. For example, access keys are not displayed if the accessibility mode is set to screen reader mode).

Use <accessibility-profile> to configure the color contrast and font size used in the application. The supported values are:

  • high-contrast: Application displays using high-contrast instead of the default contrast.

  • large-fonts: Application displays using large fonts instead of the default size fonts.

To use more than one setting, separate the values with a space.

A.6.2.6 Language Reading Direction

By default, ADF Faces page rendering direction is based on the language being used by the browser. You can, however, explicitly set the default page rendering direction in the <right-to-left> element by using an EL expression that evaluates to a Boolean object, or by using true or false, as shown in the following code:

<!-- Render the page right-to-left for Arabic -->
<!-- and left-to-right for all other languages -->
<right-to-left>
 #{view.locale.language=='ar' ? 'true' : 'false'}
</right-to-left>

A.6.2.7 Currency Code and Separators for Number Groups and Decimal Points

To set the currency code to use for formatting currency fields, and define the separator to use for groups of numbers and the decimal point, use the following elements:

  • <currency-code>: Defines the default ISO 4217 currency code used by org.apache.myfaces.trinidad.converter.NumberConverter class to format currency fields that do not specify an explicit currency code in their own converter. Use a static value or an EL expression that evaluates to a String object. For example:

    <!-- Set the currency code to US dollars. -->
    <currency-code>USD</currency-code>
    
  • <number-grouping-separator>: Defines the separator used for groups of numbers (for example, a comma). ADF Faces automatically derives the separator from the current locale, but you can override this default by specifying a value in this element. You can use a static value or an EL expression that evaluates to a Character object. If set, this value is used by org.apache.myfaces.trinidad.converter.NumberConverter class while parsing and formatting.

    <!-- Set the number grouping separator to period for German -->
    <!-- and comma for all other languages -->
    <number-grouping-separator>
     #{view.locale.language=='de' ? '.' : ','}
    </number-grouping-separator>
    
  • <decimal-separator>: Defines the separator (for example., a period or a comma) used for the decimal point. ADF Faces automatically derives the separator from the current locale, but you can override this default by specifying a value in this element. You can use a static value or an EL expression that evaluates to a Character object. If set, this value is used by org.apache.mtfaces.trinidad.converter.NumberConverter class while parsing and formatting.

    <!-- Set the decimal separator to comma for German -->
    <!-- and period for all other languages -->
    <decimal-separator>
     #{view.locale.language=='de' ? ',' : '.'}
    </decimal-separator>
    

A.6.2.8 Formatting Dates and Numbers Locale

By default, ADF Faces and MyFaces Trinidad will format dates (including the first day of the week) and numbers in the same locale used for localized text (which by default is the locale of the browser). If, however, you want dates and numbers formatted in a different locale, you can use the <formatting-locale> element, which takes an IANA-formatted locale (for example, ja, fr-CA) as its value. The contents of this element can also be an EL expression pointing at an IANA string or a java.util.Locale object.

A.6.2.9 Output Mode

To change the output mode ADF Faces uses, set the <output-mode> element, using one of these values:

  • default: The default page output mode (usually display).

  • printable: An output mode suitable for printable pages.

  • email: An output mode suitable for emailing a page's content.

A.6.2.10 Number of Active PageFlowScope Instances

By default ADF Faces sets the maximum number of active PageFlowScope instances at any one time to 15. Use the <page-flow-scope-lifetime> element to change the number. Unlike other elements, you must use a static value; EL expressions are not supported.

A.6.2.11 Custom File Uploaded Processor

Most applications do not need to replace the default UploadedFileProcessor instance provided in ADF Faces, but if your application must support uploading of very large files, or if it relies heavily on file uploads, you may wish to replace the default processor with a custom UploadedFileProcessor implementation.

For example, you could improve performance by using an implementation that immediately stores files in their final destination, instead of requiring ADF Faces to handle temporary storage during the request. To replace the default processor, specify your custom implementation using the <uploaded-file-processor> element, as shown in the following code:

<uploaded-file-processor>
 com.mycompany.faces.myUploadedFileProcessor
</uploaded-file-processor>

A.6.2.12 Client-Side Validation and Conversion

ADF Faces validators and converters support client-side validation and conversion as well as server-side validation and conversion. ADF Faces client-side validators and converters work the same way as the server-side validators and converters, except that JavaScript is used on the client.

The JavaScript-enabled validators and converters run on the client when the form is submitted; thus errors can be caught without a server round-trip.

The <client-validation-disabled> configuration element is not supported in the rich client version of ADF Faces. This means you cannot turn off client-side validation and conversion in ADF Faces applications.

A.7 Configuration in trinidad-skins.xml

By default, JDeveloper uses the blafplus-rich skin family when you create JSF pages with ADF Faces components. The skin family is configured in the trinidad-config.xml file, as described in Section A.6.1, "How to Configure ADF Faces Features in trinidad-config.xml". If you wish to use a custom skin for your application, create a trinidad-skins.xml file, which is used to register custom skins in an application.

For detailed information about creating custom skins, see Chapter 19, "Customizing the Appearance Using Styles and Skins".

A.8 Using the RequestContext EL Implicit Object

In ADF Faces, you can use the EL implicit object requestContext to retrieve values from configuration properties defined in the trinidad-config.xml file. The requestContext implicit object, which is an instance of the org.apache.myfaces.trinidad.context.RequestContext class, exposes several properties of type java.util.Map, enabling you to use JSF EL expressions to retrieve context object property values.

For example, the EL expression #{requestContext} returns the RequestContext object itself, and the EL expression #{requestContext.skinFamily} returns the value of the <skin-family> element from the trinidad-config.xml file.

You can also use EL expressions to bind a component attribute value to a property of the requestContext implicit object. For example, in the EL expression that follows, the <currency-code> property is bound to the currencyCode attribute value of the JSF ConvertNumber component:

<af:outputText>
  <f:convertNumber currencyCode="#{requestContext.currencyCode}"/>
</af:outputText>

The requestContext implicit object properties you can use include the following:

For a complete list of properties, refer to the Javadoc for org.apache.myfaces.trinidad.context.RequestContext.

Note:

One instance of the org.apache.myfaces.trinidad.context.RequestContext class exists per request. The RequestContext class does not extend the JSF FacesContext class.

To retrieve a configuration property programmatically, first call the static getCurrentInstance() method to get an instance of the RequestContext object, then call the method that retrieves the desired property, as shown in the following code:

RequestContext context = RequestContext.getCurrentInstance();

// Get the time-zone property
TimeZone zone = context.getTimeZone();

// Get the right-to-left property
if (context.isRightToLeft())
{
  .
  .
  .
}