Overview
Apache Trinidad includes replacements for many of the tags in the JavaServer Faces (JSF) specification. It is important to emphasize that there is no requirement whatsoever that you convert from standard JSF tags to Apache Trinidad tags. Standard JSF tags and Apache Trinidad tags can be mixed freely within a single page. In general, the Apache Trinidad tags are more powerful, because they:
- Often offer more features than the standard tags
- Can be used inside of the
<tr:forEach>
tag (it is, unfortunately, not possible to support standard tags inside<tr:forEach>
) - Provide more efficient implementations of client-side state saving (reduced per-component size)
Getting Started
If you're using Apache Trinidad for the first time, and you're adding ADF Faces tags into existing JSF pages, you'll need to know a few tips to get everything working correctly.
First, Apache Trinidad needs its stylesheet in each page to look correct. You should replace <HTML>, <HEAD>, and <BODY> tag with our <tr:document> tag which creates these standard root elements as well as includes our stylesheet in the page.
Second, if you call the Javascript form.submit()
function, you'll bypass the Apache Trinidad support for client-side
validation. Use the "autoSubmit" property on our input components or use the
command components.
Differences
Unless noted, the Apache Trinidad tag name is the same as the standard JSF tag with the exception of the prefix. Apache Trinidad tags use the prefix 'tr'. For example, <h:commandButton>
is <tr:commandButton>
in Apache Trinidad.
The following list shows some of the common h: attributes and how they map to tr: attributes:
accesskey
- useaccessKey
readonly
- usereadOnly
alt
and/ortitle
- useshortDesc
style
- useinlineStyle
dir
,lang
,tabindex
- n/a
Standard JSF tag | Apache Trinidad tag | Attribute Mapping/Notes |
---|---|---|
<h:column> |
<tr:column> |
The tr:column must be the immediate child of tr:table . See the
Table features
section below.
|
<h:commandButton> |
<tr:commandButton> or <tr:resetButton> or <tr:objectImage> |
value - use text
type = "reset", use <tr:resetButton> tag image - use <tr:objectImage> tag onblur, onchange, onfocus, readonly - n/a. |
<h:commandLink> |
<tr:commandLink> |
value - use text
charset, coords, hrefrel, rev, shape - n/a. |
<h:dataTable> |
<tr:table> |
see the Table features
section below.
|
<h:form> |
<tr:form> |
|
<h:graphicImage> |
<tr:objectImage> |
|
<h:inputHidden> |
<tr:inputHidden> |
|
<h:inputSecret> |
<tr:inputText> |
|
<h:inputText> |
<tr:inputText> |
|
<h:inputTextarea> |
<tr:inputText> |
|
<h:message> |
<tr:message> |
showDetail, showSummary, xyzClass, xyzStyle, tooltip - n/a
|
<h:messages> |
<tr:messages> |
globalOnly, showDetail, showSummary, xyzClass, xyzStyle, layout, tooltip - n/a
|
<h:outputFormat> |
no tr: equivalent
|
|
<h:outputLabel> |
<tr:outputLabel> |
|
<h:outputLink> |
<tr:goLink> |
|
<h:outputText> |
<tr:outputText> |
|
<h:panelGrid> |
no tr: equivalent
|
|
<h:panelGroup> |
<tr:panelGroup> |
|
<h:selectBooleanCheckbox> |
<tr:selectBooleanCheckbox> |
|
<h:selectManyCheckbox> |
<tr:selectManyCheckbox> |
layout - "vertical" and "horizontal" instead of "pageDirection" and "lineDirection"; also, the default is vertical, not horizontal
|
<h:selectManyListbox> |
<tr:selectManyListbox> |
|
<h:selectManyMenu> |
<tr:selectManyListbox> |
|
<h:selectOneListbox> |
<tr:selectOneListbox> |
|
<h:selectOneMenu> |
<tr:selectOneChoice> |
|
<h:selectOneRadio> |
<tr:selectOneRadio> |
border, disabledClass, enabledClass, layout - n/a. |
The ADF <tr:form>
component does not implement the JSF NamingContainer
API.
When you use the <tr:form>
tag, the ID in the generated HTML does not
include the form's ID as a prefix. For example:
<h:form id="foo"> <!-- This inputText will have an id of "foo:bar" --> <tr:inputText id="bar"/> </h:form> <tr:form id="foo2"> <!-- This inputText will have an id of just "bar2" --> <tr:inputText id="bar2"/> </tr:form>
<f:subview>
tag around
an <tr:form>
if you need to reuse ID values, or you can just
continue using <h:form>
.
Additional features
As mentioned earlier, the Apache Trinidad tags offer some general features
that are not available with the standard JSF tags - such as <tr:forEach>
support
and more efficient (smaller) client-side state saving. There are
many other features supported by the Apache Trinidad tags and components that are
not supported by the standard JSF tags. It'd take too much
space to discuss all of these features, but a couple of the more important
ones are discussed here.
Label and message support
Apache Trinidad input components make it much easier to support the standard label-and-message pattern for laying out forms. Typically, a JSF page might contain content like:
<h:panelGrid columns="2"> <!-- Use outputLabel; outputText doesn't support accessibility --> <h:outputLabel for="nameInput" value="Name: "> <h:panelGroup> <h:inputText id="nameInput" value="Enter a name"/> <f:verbatim><br></f:verbatim> <h:message for="nameInput"/> </h:panelGroup> </h:panelGrid>
All the Apache Trinidad input components automate this pattern; the single entry of:
<tr:inputText label="Name:" value="Enter a name"/>
...gives you all the layout of the JSF example above - automatic
label and message layout and accessibility support.
When you use a series of Apache Trinidad input components, you'll
need to line up the labels and fields. For this purpose, Apache Trinidad
provides the <tr:panelForm>
layout panel that will stack
Apache Trinidad input components.
<tr:panelForm> <tr:inputText label="First name:" value="/> <tr:inputText label="Last name:" value="/> </tr:panelForm>
If you want to use an Apache Trinidad input component, but do not want any of these features (because you require a more flexible layout strategy, for example, or are already providing messaging), set the "simple" attribute to "true":
<!-- No label or messaging --> <tr:inputText simple="true" value="Enter a name"/>
Table features
The Apache Trinidad <tr:table>
component (a replacement for <h:dataTable>
)
adds many features, including:
- Built-in support for paging through data sets
- Support for identifying rows by key instead of by index
- No-code support for partial-page rendering (re-rendering only the table, not the entire page)
- Support for sorting
- "Single" and "multiple" selection columns
Message customization
In Apache Trinidad, for error messages that are reported for cases of invalid input for editable components, during conversion and validation can be customized for every converter or validator. This also applies to "required" validation on all input components.
<tr:selectInputDate id="mdf6" value="2004/09/06" label="Date of birth" tip="1/20/1972 or 1972/20/2"> <tr:convertDateTime secondaryPattern="d/M/yyyy" pattern="yyyy/M/d" convertDateMessageDetail=""{0}" in "{1}" is not a valid date. Example: "{4}""/> </tr:selectInputDate>
For a invalid input value say 2004/15/1 - It would result in error message:
"2004/15/1" in "Date of birth" is not a valid date. Example: "2005/11/29".