A.11 adf-faces-config.xml

When you create a JSF application using ADF Faces components, besides configuring elements in faces-config.xml you can configure ADF Faces-specific features in the adf-faces-config.xml file. The adf-faces-config.xml file has a simple XML structure that enables you to define element properties using the JSF expression language (EL) or static values.

In JDeveloper when you insert an ADF Faces component into a JSF page for the first time, a starter adf-faces-config.xml file is automatically created for you in the /WEB-INF directory of your ViewController project. Example A-28 shows the starter adf-faces-config.xml file.

Typically you would want to configure the following in adf-faces-config.xml:

Page accessibility levels
Skin family
Time zone
Enhanced debugging
Oracle Help for the Web (OHW) URL

Example A-28 Starter adf-faces-config.xml Created by JDeveloper

<?xml version="1.0" encoding="windows-1252"?>
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/view/faces/config">

  <skin-family>oracle</skin-family>

</adf-faces-config>

A.11.1 Tasks Supported by adf-faces-config.xml

The following JSF tasks are supported by the adf-faces-config.xml file.

A.11.1.1 Configuring Accessibility Levels

To define the level of accessibility support in an application, use <accessibility-mode>. 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 affect on other users. For example access keys are not displayed if the accessibility mode is set to screen reader mode).

Example A-29 Configuring an Accessibility Level

<!-- Set the accessibility mode to screenReader -->
<accessibility-mode>screenReader</accessibility-mode>

A.11.1.2 Configuring Currency Code and Separators for Number Groups and Decimals

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 oracle.adf.view.faces.converter.NumberConverter to format currency fields that do not specify a currency code in their own converter.
<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. If set, this value is used by oracle.adf.view.faces.converter.NumberConverter while parsing and formatting.
<decimal-separator>—Defines the separator (e.g., 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. If set, this value is used by oracle.adf.view.faces.converter.NumberConverter while parsing and formatting.

Example A-30 Configuring Currency Code and Separators For Numbers and Decimal Point

<!-- Set the currency code to US dollars. -->
<currency-code>USD</currency-code>

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

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

A.11.1.3 Configuring For Enhanced Debugging Output

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 illegal locations).

Example A-31 Enabling Enhanced Debugging

<!-- Activate the ADF Faces enhanced debugging features -->
<debug-output>true</debug-output>

A.11.1.4 Configuring for 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. ADF Faces JavaScript-enabled validators and converters run on the client when the form is submitted; thus errors can be caught without a server round trip. You can, however, turn off client-side conversion and validation in your ADF Faces application by setting <client-validation-disabled> to "true".

Example A-32 Turning Off Client-Side Validation and Conversion

<!-- Disable client validation -->
<client-validation-disabled>true</client-validation-disabled>

A.11.1.5 Configuring the Language Reading Direction

By default, ADF Faces page rendering direction is based on the language being used by the browser. However, you can explicitly set the default page rendering direction in the <right-to-left> element by using "true" or "false".

Example A-33 Configuring For Right-to-Left Page Rendering

<!-- 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.11.1.6 Configuring the Skin Family

By default, ADF Faces uses the Oracle <skin-family> for all pages. You can change this to specify a custom <skin-family>. See also Section A.12.1, "Tasks Supported by adf-faces-skins.xml".

For information about creating custom skins, see Section 14.3, "Using Skins to Change the Look and Feel".

Example A-34 Configuring a Skin to be Used For All Pages

<!-- Specify custom skin instead of Oracle skin -->
<skin-family>srdemo<skin-family>

A.11.1.7 Configuring the 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 e-mailing a page's content.

Example A-35 Configuring an Output Mode

<!-- Set the output mode to printable -->
<output-mode>printable</output-mode>

A.11.1.8 Configuring the Number of Active ProcessScope Instances

By default ADF Faces sets the maximum number of active processScope instances at 15. Use the <process-scope-lifetime> element to change the number. A static value must be used.

Example A-36 Configuring the Number of Active ProcessScope Instances

<!-- Set the maximum number of processScope instances to 10 -->
<process-scope-lifetime>10</process-scope-lifetime>

A.11.1.9 Configuring the Time Zone and Year Offset

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

<time-zone>—ADF Faces defaults to the time zone used by the client browser. This value is used by oracle.adf.view.faces.converter.DateTimeConverter while converting strings to Date.
<two-digit-year-start>—Defaults to the year 1950 if no value is set. This value is used by oracle.adf.view.faces.converter.DateTimeConverter to convert strings to Date.

Example A-37 Configuring the Time Zone and Year Offset

<!-- Set the time zone to Pacific Daylight Savings Time -->
<time-zone>PDT</time-zone>

<!-- Set the year offset to 2000 -->
<two-digit-year-start>2000</two-digit-year-start>

A.11.1.10 Configuring a Custom Uploaded File Processor

Most applications don't need to replace the default UploadedFileProcessor instance provided by ADF Faces, but if your application needs to support uploading of very large files or rely 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 a custom implementation using the <uploaded-file-processor> element.

Example A-38 Configuring a Custom Uploaded File Processor

<!-- Use my UploadFileProcessor class -->
<uploaded-file-processor>
 com.mycompany.faces.myUploadedFileProcessor
</uploaded-file-processor>

A.11.1.11 Configuring the Help Site URL

If you use Oracle Help for the Web (OHW) to provide help in your application, you can attach help content to any JSF tag that accepts a URL. Before you can do this, you must configure your help site URL by using the <oracle-help-servlet-url> element. ADF Faces supports OHW Version 2.0 as well as earlier versions

Use the adfFacesContext.helpTopic EL object to attach help content to the JSF tag. For example:

<h:outputLink value="#{adfFacesContext.helpTopic.someTopicID}">
   <h:outputText value="Help!"/>
</h:outputLink>

Example A-39 Configuring the Help Site URL

<!-- Set the help site URL -->
<oracle-help-servlet-url>mywebsite.com/project_one/help</oracle-help-servlet-url>

A.11.1.12 Retrieving Configuration Property Values From adf-faces-config.xml

Once you have configured elements in the adf-faces-config.xml file, you can retrieve property values using one of the following approaches:

Programmatically using the AdfFacesContext class.

The AdfFacesContext class is a context class for all per-request and per-webapp information required by ADF Faces. One instance of the AdfFacesContext class exists per request. Although it is similar to the JSF FacesContext class, the AdfFacesContext class does not extend FacesContext.

To retrieve an ADF Faces configuration property programmatically, first call the static getCurrentInstance() method to get an instance of the AdfFacesContext object, then call the method that retrieves the desired property, as shown in the following example:
```
// Get an instance of the AdfFacesContext object
AdfFacesContext context = AdfFacesContext.getCurrentInstance();

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

// Get the right-to-left property
if (context.isRightToLeft())
{
  ...
}
```
For the list of methods to retrieve ADF Faces configuration properties, refer to the Javadoc for oracle.adf.view.faces.context.AdfFacesContext.
Using a JSF EL expression to bind a component attribute value to one of the properties of the ADF Faces implicit object (adfFacesContext).

The AdfFacesContext class contains an EL implicit variable, called adfFacesContext, that exposes the context object properties for use in JSF EL expressions. Using a JSF EL expression, you can bind a component attribute value to one of the properties of the adfFacesContext object. For example in the EL expression below, the <currency-code> property is bound to the currencyCode attribute value of the JSF ConvertNumber component:
```
<af:outputText>
  <f:convertNumber currencyCode="#{adfFacesContext.currencyCode}"/>
</af:outputText>
```