Trinidad
Foundation
Modules
Project Documentation

Converting From Standard JSF Tags to Apache Trinidad Tags

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)
Some of the enhanced features of Apache Trinidad tags are described below.

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 - use accessKey
  • readonly - use readOnly
  • alt and/or title - use shortDesc
  • style - use inlineStyle
  • dir, lang, tabindex - n/a
The following table shows the standard JSF tags and how they map to Apache Trinidad tags.
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>
enctype="multipart/form-data", use usesUpload="true"
target - use targetFrame
accept, acceptcharset, endtype onreset - n/a.
<h:graphicImage> <tr:objectImage>
value or url - use source
ismap - use imageMapType="server"
longdesc - use longDescURL
usemap - n/a.
<h:inputHidden> <tr:inputHidden>
required - n/a
<h:inputSecret> <tr:inputText>
set tr:inputText's "secret" attribute to true
maxlength - use maximumLength
size - use columns
redisplay - n/a.
<h:inputText> <tr:inputText>
maxlength - use maximumLength
size - use columns
<h:inputTextarea> <tr:inputText>
set the tr:inputText's "rows" attribute to the desired number of rows > 1
cols - use columns
<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>
onblur, onfocus - n/a.
<h:outputLink> <tr:goLink>
value - use destination
use text for the link's text
target - use targetFrame
converter, charset, coords,hrefrel, rev, shape, type - n/a.
<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>
This makes it easier to write JavaScript (and results in smaller, more concise HTML) - especially in cases where you may not know the ID of the form - and enables the use of some CSS features on these fields. On the other hand, this means that pages using multiple forms cannot reuse IDs among forms. You can use the <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
For more information, see Using Apache Trinidad Tables in Development Guidelines for Apache MyFaces Trinidad Applications.

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="&quot;{0}&quot; in &quot;{1}&quot;
                                  is not a valid date. Example: &quot;{4}&quot;"/>
                                      
   </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".