Example file

<?xml version="1.0"?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
  <!-- Enable debug output -->
  <debug-output>true</debug-output>

  <!-- Pick accessibility options based on a per-user managed bean -->
  <accessibility-mode>#{user.accessibilityMode}</accessibility-mode>

  <!-- A silly use of EL: English users get one appearance, -->
  <!-- others get another -->
  <skin-family>
    #{view.locale.language=='en' ?  'minimal' : 'customSkin'}
  </skin-family>
</trinidad-config>

Definition of subelements

All trinidad-config.xml files must begin with an <trinidad-config> element in the http://myfaces.apache.org/trinidad/config XML namespace. The order of elements inside of <trinidad-config> doesn't matter.

debug-output

The <debug-output> element controls whether output is enhanced for debugging. Apache Trinidad adds a variety of features to aid in debugging, including:

• Automatically indenting output
• Adding comments identifying which component was responsible for a block of HTML
• Detecting unbalanced elements, repeated use of the same attribute in a single element, or other malformed markup problems
• Detecting common HTML errors (like <form> tags inside other <form> tags, <tr> or <td> tags used in illegal locations, etc.)

client-validation

The <client-validation> element controls how client-side converters and validators are run. Three values are supported:

• "INLINE": validation is shown inline in a page (the default)
• "ALERT": validation is shown in an Javascript alert
• "DISABLED": validation is only handled on the server

client-validation-disabled

The <client-validation-disabled> element controls whether client side converters and validators are run. This element is deprecated - please use <client-validation>.

output-mode

The <output-mode> element configures what "Output Mode" Apache Trinidad is using. Accepted values include:

• "default" (or null): the default output mode
• "printable": an output mode suitable for printable pages
• "email": an output mode suitable for e-mailing a page's content

skin-family

The <skin-family> element configures the skin to be used. Accepted values include:

• "minimal": a more minimal skin

accessibility-mode

The <accessibility-mode> element defines the level of accessibility support to be used. Accepted values are:

• "default": Output supports accessibility features
• "inaccessible": Accessibility-specific constructs are stripped out to optimize output size
• "screenReader": Accessibility-specific constructs are added to improve behavior under a screen reader (but may affect other users negatively)

accessibility-profile

The <accessibility-profile> element defines finer-grained accessibility preferences than is possible to support with the acccessibility mode. Accepted values are:

• "high-contrast": Indicates that the end user prefers high contrast-friendly content.
• "large-fonts": Indicates that the end user prefers large fonts (larger fonts than the default font size provided by the skin).

Multiple values may be specified using whitespace to separate the values, eg:

  <!-- Enable both high-contrast and large-fonts content -->
  <accessibility-profile>high-contrast large-fonts</accessibility-profile>

Since accessibility preferences are user-specific, the accessibility-profile is typically bound, similar to the accessibility-mode. The preferences specified by the accessibility profile can be used at runtime to tune both styles/icons defined by the skin as well as the content produced by Renderers.

The typical use case for the "high-contrast" preference is to work around issues relating to CSS background images when platform/browser high contrast features are enabled. For example, when Windows High Contrast mode is enabled (Control Panel->Accessibility Options->Display->High Contrast->Use High Contrast), all background images are hidden. In cases where background images are used to convey information, this information is lost to high contrast users. The high-contrast accessibility profile option allows skin implementations to replace such background images with <img> element-based icons, thus avoiding the loss of information.

The typical use case for the "large-fonts" preference is to allow skins which specify small or non-scalable fonts (eg. px-based fonts on IE) to provide an alternate set of fonts for users who find the default fonts insufficient.

Note that at the moment, the Trinidad core renderers/skins do not yet take advantage of the accessibility profile preferences. These properties are primarily provided for skin authors who wish to design skins which provide styles/icons optimized for high contrast/large font users.

oracle-help-servlet-url

The <oracle-help-servlet-url> element defines an URL to an installation of Oracle Help for the Web (OHW). Apache Trinidad supports OHW Version 2.0 as well as earlier versions. Once this is configured, page content can be trivially attached to any JSF tag that accepts an URL by using the "requestContext" EL object. For example:

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

page-flow-scope-lifetime

The <page-flow-scope-lifetime> element controls the maximum number of pageFlowScope instances that will be kept active at any one time. The default is 15. Unlike other <trinidad-config> elements, <page-flow-scope> lifetime does not support EL expressions - it must be configured statically.

time-zone

The <time-zone> element defines the default time zone used for date processing and date display. Apache Trinidad will attempt to default the time zone to the time zone used by the client browser, but this property may be bound by an EL expression to a TimeZone object if needed. This value is used by org.apache.myfaces.trinidad.converter.DateTimeConverter while converting strings to Date.

two-digit-year-start

The <two-digit-year-start> element defines the 100-year span that should be used used by org.apache.myfaces.trinidad.converter.DateTimeConverter to parse strings containing 2 digit years. The parsed Date will be in the range startDate to startDate + 100 years. For example, when the string is "1/1/11" and the two-digit-year-start is set to 1900, the DateTimeConverter will parse it into the Date equivalent to 1st January 1911. If the property is not set, it is defaulted to year 1950. This property may be explicitly configured with an EL expression that returns Integer object or it can be directly harcoded to a integer value.This value should be specified as a Gregorian Calendar year.

right-to-left

The <right-to-left> element defines whether pages will be rendered in left-to-right mode (most languages) or right-to-left mode (Arabic and Hebrew, for example). While Apache Trinidad will automatically pick the reading direction for you (sufficient for the vast majority of developers), if you need a different default association of language to reading direction you can use an EL expression here that returns a Boolean object, or hardcode it to either "true" or "false".

number-grouping-separator

The <number-grouping-separator> element defines the separator used for groups of numbers. Apache Trinidad will automatically derive the separator from the current locale, but it may also be hardcoded or can be explicitly configured with an EL expression that returns a Character object. If set, this value is used by org.apache.myfaces.trinidad.converter.NumberConverter while parsing and formatting.

decimal-separator

The <decimal-separator> element defines the separator used for the decimal point. Apache Trinidad will automatically derive the separator from the current locale, but it may also be hardcoded or can be explicitly configured with an EL expression that returns a Character object. If set, this value is used by org.apache.myfaces.trinidad.converter.NumberConverter while parsing and formatting.

currency-code

The <currency-code> element defines the ISO 4217 currency code used by default for formatting currency fields when those fields do not specify an explicit currency field via their converter. If this value is not specified in the converter and is set here, then this value is used by org.apache.myfaces.trinidad.converter.NumberConverter while formatting. This value can be hardcoded or can be explicitly configured with an EL expression that returns a String object.

uploaded-file-processor

The <uploaded-file-processor> element must be the name of a class that implements the org.apache.myfaces.trinidad.webapp.UploadedFileProcessor interface. This API is responsible for processing each individual uploaded file as they come from the incoming request and making its contents available for the rest of the request. Most developers will find the default UploadedFileProcessor sufficient for their purposes, but applications that need to support uploading very large files may improve their performance by immediately storing files in their final destination, instead of requiring Apache Trinidad to handle temporary storage during the request.

uploaded-file-max-memory

The <uploaded-file-max-memory> element is used to set the maximum amount of memory used during the file upload process before the data will start writing out to disk. This setting directly overrides the web.xml setting org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY. This value can be hardcoded or can be explicitly configured with an EL expression that returns a Long object.

uploaded-file-max-disk-space

The <uploaded-file-max-disk-space> element is used to set the maximum amount of disk space allowed for an uploaded file before an EOFException is thrown. This setting directly overrides the web.xml setting org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE. This value can be hardcoded or can be explicitly configured with an EL expression that returns a Long object.

uploaded-file-temp-dir

The <uploaded-file-max-disk-space> element is used to change the default location uploaded files are stored. This setting directly overrides the web.xml setting org.apache.myfaces.trinidad.UPLOAD_TEMP_DIR. This value can be hardcoded or can be explicitly configured with an EL expression that returns a String object.

formatting-locale

The <formatting-locale> element is used by converters without an explicit locale to format values. Values for this follow the same format as locale values in faces-config.xml (ie en_US).

org.apache.myfaces.trinidad.security.FRAME_BUSTING

The parameter "org.apache.myfaces.trinidad.security.FRAME_BUSTING" controls the framebusting feature. Framebusting stops content from running inside frames (meaning a frame or iframe tag).

This context parameter is ignored when org.apache.myfaces.trinidad.util.ExternalContextUtils.isPortlet is true, and will behave as if the context parameter is set to 'never'.

Possible values are:

• differentOrigin - only bust frames if the an ancestor window origin and the frame origin are different. If the ancestor windows and frame have the same origin then allow the content to run in a frame. This is the default.
• always - always bust frames, meaning don't allow a page to be embedded in frames
• never - never bust frames, meaning always allow a page to be embedded in frames

org.apache.myfaces.trinidad.CACHE_VIEW_ROOT

Enables or disables UIViewRoot caching; defaults to true.

When "token" client-side state saving is enabled, Trinidad applies an additional optimization by caching an entire UIViewRoot tree with each token. (Care has been taken to ensure 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. However, it 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. This optimization can be disabled by setting this context parameter to false.

org.apache.myfaces.trinidad.CLIENT_STATE_METHOD

Chooses the type of client-side state saving used when client-side state saving is enabled (with the JSF standard javax.faces.STATE_SAVING_METHOD parameter). Two values are accepted:

• "token": the default, which stores page state in the session, but persists a token to the client that lets Apache Trinidad disambiguate the same page appearing multiple times. Failover is supported.
• "all": stores all state in the client in a (potentially large) hidden form field. This matches the default behavior of the JSF reference implementation, and can be useful for developers avoiding any use of HttpSession.

org.apache.myfaces.trinidad.CLIENT_STATE_MAX_TOKENS

In "token"-based client-side state saving, chooses how many tokens should be preserved at any one time. The default value is 15. When this is exceeded, state will have effectively been "forgotten" for the least recently viewed pages, which can impact users that actively use the Back button or that have multiple windows open simultaneously. Developers building HTML applications that rely heavily on frames will likely need to increase this value.

org.apache.myfaces.trinidad.CHANGE_PERSISTENCE

This configuration option allows to enable the change persistence feature. This feature is used to achieve customizations using ChangeManager APIs (in package org.apache.myfaces.trinidad.change). The valid values are:

• 'session'. This is a convenience token value to use org.apache.myfaces.trinidad.change.SessionChangeManager
• Package qualified class name of any custom implementation of org.apache.myfaces.trinidad.change.ChangeManager.

org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT

For applications that run in ProjectStage.Production, Apache Trinidad by default obfuscates the Javascript it delivers to the client, as well as stripping comments and whitespace. This dramatically reduces the size of our Javascript download, but also makes it tricky to debug the Javascript. In other stages the default value is TRUE. However, a user can override the ProjectStage behavior by using this flag.

org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION

For applications that run in ProjectStage.Production, Apache Trinidad by default compresses the style class names inside the css that is generated on the server. However, when developing custom Trinidad skins, it is much easier to work with the non-compressed style class names, which much more directly relate to those used in the skin css file. There for in all other stages (like Development) the compression is turned off. However, a user can override the ProjectStage behavior by using this flag.

org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION

If this parameter is enabled by setting to "true", Apache Trinidad will automatically check the modification date of your JSPs and skinning CSS files, and discard saved state when they change; this makes development easier, but adds overhead that should be avoided when your application is deployed. For applications that run in ProjectStage.Production, the value is "false" and all other stages use "true" as their default value. However, a user can override the ProjectStage behavior by using this flag.

org.apache.myfaces.trinidad.ENABLE_LIGHTWEIGHT_DIALOGS

Trinidad supports two dialog implementations. The default implementation pops a new browser window, but may be subject to popup blocking issues depending on the browser. The alternative lightweight implementation uses a skinnable modal iframe that hovers over the existing page. This flag can be set to turn on lightweight dialogs.

File upload configuration

For options affecting Apache Trinidad support of file uploads, please see the Configuration section of the "Processing file uploads" document.

#{requestContext}

The EL expression #{requestContext} returns the RequestContext object itself.

#{requestContext.helpTopic['foo']}

The EL expression #{requestContext.helpTopic['foo']} returns an URL to the help topic "foo". Before using this, you must configure the <oracle-help-servlet-url> element in trinidad-config.xml.

#{requestContext.helpSystem['frontPage']}

The EL expression #{requestContext.helpSystem['frontPage']} returns an URL to the front page of the help system. Before using this, you must configure the <oracle-help-servlet-url> element in trinidad-config.xml. (Other subproperties of "helpSystem" may be added in the future.)

#{requestContext.colorPalette}

The EL expression #{requestContext.colorPalette} returns a Map of color palettes, each of which is an array of java.awt.Color objects. Palette names include:

• "web216": the 216 web-safe colors
• "default49": a 49 color palette, including a fully transparent entry
• "opaque49": a 49 color palette, without a transparent entry
• "default80": an 80 color palette

#{requestContext.formatter}

The EL expression #{requestContext.formatter} returns an object that can be used for applying message formatting. For example, the following EL expression:

    <h:outputText value="#{requestContext.formatter['One{0}Three']['Two']}"/>

OneTwoThree

#{requestContext.agent}

The EL expression #{requestContext.agent} returns an object that describes the client agent that is making the request and is to display the rendered output. The agent object describes the following,

• agent type: Possible values "desktop", "pda", "phone" and "unknown"
• agent name and version: Agent names include "ie", "gecko" (for all gecko based browsers including Mozilla, Firefox, and Netscape 6+ versions), "webkit" (for all webkit based browsers including safari), "netfront", "blazer"
• platform name and version: Platform names include "windows", "linux", "mac", "palm", "solaris", "ppc"
• (mobile) device make and model when available, and
• capabilities : Capability names include
  • "dom" : dom level support (possible values are "none", "level1", "level2")
  • "tables" : table layout support (possible values "basic", "advanced")
  • "frames" : frames support (boolean value, "true" or "false"
  • "iframes" : iframes support (boolean value, "true" or "false"
  • "width" and "height" : screen resolution of the (mobile) device (integer value)

org.apache.myfaces.trinidad.CHECK_STATE_SERIALIZATION

For better High Availability Testing Support the org.apache.myfaces.trinidad.CHECK_STATE_SERIALIZATION System Property has been introduced. The behavior is controlled by passing a comma-delimited set of case-insensitive values on the system property:

• NONE no state serialization checks are performed (the default)
• ALL perform all available tests (unless NONE is also specified, in which case NONE takes precedence)
• SESSION Wrap the Session Map returned by the ExternalContext to test that only Serializable objects are placed in the Session Map, throwing a CastCastException if the Object is not Serializable
• BEANS The attributes of the session and application Maps should be checked for cases where the attribute was mutated but not dirtied for failover.
• TREE aggressively attempt to serialize the component state during state saving and throw an exception if serialization fails
• COMPONENT aggressively attempt to serialize each component subtree's state during state saving in order to identify the problem component (slow)
• PROPERTY aggessively attempt to serialize each property value during state saving in order to identify the problem property (slow)

org.apache.myfaces.trinidad.CLIENT_ID_CACHING

The org.apache.myfaces.trinidad.CLIENT_ID_CACHING system property controls the behavior of UIXComponentBase.getClientId(). By default, this method is optimized to reduce the amount of time spent building client id strings. The client id is computed and cached until the id is changed via a call to setId(). This matches the behavior of the standard UIComponentBase.getClientId() implementation.

Client id caching requires that iterating components reset the ids of any descendent components on each iteration. Failure to do this results in incorrect (the same) client ids being used across iterations. This system property is provided to help locate/debug such cases.

The following values may be specified:

• OFF Client id caching will not be performed. Instead, the client id will be recalculated on each call to UIXComponentBase.getClientId().
• DEBUG Client id caching will be performed and additional debugging diagnostics will be logged. This adds overhead to each call to UIXComponentBase.getClientId() and as such should only be used for testing/debugging purposes.
• ON Client id caching will be performed.

The system property defaults to ON, which is the correct value for production deployments.