Apache MyFaces Trinidad 1.2
A Practical Guide
David Thomas
Chapter No. 3
"Most Wanted Tags and Tag Attributes"
In this package, you will find:
A Biography of the author of the book
A preview chapter from the book, Chapter NO.3 "Most Wanted Tags and Tag Attributes"
A synopsis of the book’s content
Information on where to buy this book
About the Author
David Thomas is a developer and technical project manager of Java-based web
applications, and has well over 10 years of experience in various web technologies.
He began writing applications based on the Common Gateway Interface (CGI), HTML
and Javascript, with a short Java Applets interlude.
The main occupation with Java began when Java took charge of the server. A series of
Java Servlet applications were developed using an early, self-built Model-2 controller
architecture.
Java Server Pages (JSP) took hold for a rather long time and a couple of major,
increasingly complex, web applications were developed in combination with Struts. This
also included the development of major portal applications in the finance and banking
sector.
Shortly after Java Server Faces 1.2 (JSF) emerged, began the development of a major JSF
web application including the development of a high-level framework based on Apache
My Faces Trinidad, Facelets and JBOSS Seam in the area of controlling. This project
spawned a couple of sub projects, so development continues up to the present day.
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
This is the author's first book which is highly influenced by the accumulated years of his
experience in web technology.
Apart from his work and the writing of this book, David Thomas likes to write music,
sing his own songs, and accompany them on piano and guitar. Other hobbies of his are
going on holidays, reading books, walking, swimming, making tea, and taking trains.
Furthermore, he is a firm believer in vegetarianism and the responsibility of each human
being for her or his well-being and surroundings—in short, of acting locally while
thinking globally.
Regarding this book he hopes it will be of great value to many people to enjoy an
effective and efficient use of Trinidad.
I would like to thank my wife for her patience during the writing of
this book.
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Apache MyFaces Trinidad 1.2
A Practical Guide
In this book, you will learn how Facelets and Seam are used to get the most out of JSF.
You start out by learning where Trinidad comes from and what its aims are. Additionally,
you will also learn the often occurring tag attributes and, in particular, Trinidad's Ajax
technology. You will implement login, authorization, navigation, internationalization,
polling and browser issues with the help of these technologies. You will then use Seamgen for deployment.
As you move through the book, you will develop a web application example where a
series of selected Trinidad components are applied and their capabilities explored.
Finally, you will master the Trinidad dialog framework, a Trinidad key technology that
allows the application of dialogs.
What This Book Covers
Chapter 1, Introducing Trinidad, introduces you to the Trinidad component library. We
give a general idea of this component library, the areas covered by its components, and
compare it to other libraries. Finally, the integration of Trinidad and Seam is discussed.
Chapter 2, Structuring and Building Pages with Facelets, explains Facelets as a basic
means to structure and build pages using Facelet page composition, Facelet composition
components, and JSTL.
Chapter 3, Most Wanted Tags and Tag Attributes, discusses the Trinidad tags and their
attributes in a structured approach. You will gain an insight into the design of Trinidad
allowing you to draw an efficient mental map of the library and make an effective
selection and application of tags.
Chapter 4, Rendering Pages Partially, introduces you to the Trinidad's Ajax technology
called PPR (Partial Page Rendering). PPR is inspected from two points of view—the pure
tag-based partial rendering and the pure Java-side partial rendering techniques.
Chapter 5, Web Application Groundwork, teaches you how to develop the basic parts of
the web application that serves as our Trinidad example. We present using Seam-gen to
rapidly deploy after each change of any fi le.
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Chapter 6, Building a Panel-based Content, deals with Trinidad's panelAccordion and
showDetailItem components to show how they can be combined to build panel-based,
panel-wise collapsible content.
Chapter 7, Building a Form, discusses the combinination of Trinidad's tags to Facelet
composition components to build highly flexible and well-formatted forms, including
messaging support.
Chapter 8, Growing a Tree, deals with Trinidad's tree components and models and
exemplify their application. We present an effective shortcut that makes Trinidad's tree
support an easy, and yet powerful, technology.
Chapter 9, The table and treeTable Components, gives an insight to Trinidad's table and
treeTable components and exemplifies their application. We apply the components in an
increasingly refined way, revealing most of their features one at a time.
Chapter 10, The Chart Component, deals with Trinidad's chart component and shows its
application. You will learn to competently set up representation parameters, effectively
achieving the intended representation focus and thus graphically materializing hidden
information in an appropriate way.
Chapter 11, Building a Wizard, deals with Trinidad's components to implement a wizard
and show their application. We present a solution to avoid an existing Facelet problem.
Chapter 12, Dialogs—Pop Up Your Web Application, discusses Trinidad's pop-up
window techniques. We revisit Seam conversations to address the specific necessities for
pop-up dialogs in Trinidad and Seam. We enhance the web application with a couple of
pop-up windows including wizard pop-up support.
Appendix, References, provides us with useful references and links related to Apache
MyFaces Trinidad.
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Most Wanted Tags and
Tag Attributes
This chapter discusses the Trinidad tags and their attributes in a structured
approach. The reader will gain an insight into the design of Trinidad allowing
them to draw an efficient mental map of the library and an effective selection and
application of tags. More concretely, the following topics are covered:
•
An overview of the XHTML-focused Trinidad namespace trh
•
An overview of the central Trinidad namespace tr
•
An orientation and classification on the attributes supported by Trinidad
Component library structure
Trinidad's approach to web technology is comprehensive: Aimed at full control
of all the bits and pieces that make up a web application, little should be left that
needs to be added. So based on such a closed world, Trinidad presents itself with
a wealth of components and tags that even include very basic XHTML tags as
replacements for the real XHTML originals. This is no radical replacement
approach, rather it enables Trinidad to remain in full control of mechanisms
such as partial-page rendering (PPR, also generally known as Ajax) that otherwise
would need to deal with potentially incompatible libraries externally (refer to
Chapter 1, Introducing Trinidad, for further discussion).
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Most Wanted Tags and Tag Attributes
The following image provides an outline of Trinidad's structural package design:
org.apache.myfaces.trinidad.component
org.apache.myfaces.trinidad.util
<<Call>>
<<Access, Derive>>
<<Call>>
<<Access, Derive>>
<<Call>>
org.apache.myfaces.trinidad.component.core
<<Call>>
<<Access, Derive>>
org.apache.myfaces.trinidad.component.core.input
<<Access, Derive>>
<<Import, Access, Instantiate, Derive, Call>>
org.apache.myfaces.trinidad.component.core.nav
org.apache.myfaces.trinidad.component.core.data
<<Call>>
org.apache.myfaces.trinidad.component.core.output
<<Call>>
org.apache.myfaces.trinidad.component.core.layout
<<Import, Instantiate, Call>>
org.apache.myfaces.trinidad.event
Trinidad is divided into the following two namespaces:
•
tr: It is the usual tag library id that references Trinidad's core library tags. It's
a large library of over 100 components ranging from layout components and
navigational components, to special viewer components that all implicitly
support skinning, partial-page rendering, popup dialogs, error or info
messaging, and so on.
•
trh: It is the usual tag library id that references Trinidad's XHTML support
library tags, a small companion that offers alternatives for those XHTML
tags that are usually applied to build XHTML structures, for example,
XHTML tables.
Let us take a closer look at both namespaces. The upcoming image shows the
core API's hierarchical structure. The tags are backed by two types of Trinidad
classes—UIX* classes that deal with the JSF component requirements to implement
specific JSF lifecycle processing methods, and Core* classes that deal with the
specific properties (getters or setters).
[ 52 ]
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Chapter 3
Trinidad’s XHTML tag library namespace (trh)
Two groups can be distinguished from the trh namespace. The first one deals
with the definition of an XHTML page and provides the developer with the
following tags:
•
<trh:html>: It is used to define the whole XHTML page, analogous
to <html>
•
<trh:head>: It is used to define the header, analogous to <head>
•
<trh:body>: It is used to define the main contents, analogous to <body>
•
<trh:script>: It is used to define a JavaScript to be executed, analogous
to <script>
[ 53 ]
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Most Wanted Tags and Tag Attributes
The second group deals with the layout of an XHTML table:
•
<trh:tableLayout>: It is used to define an XHTML table.
•
<trh:rowLayout>: It is used to define an XHTML table line, analogous to
<tr>; note that it can also be used to display an arbitrary line, particularly
when elements need to be kept in one and the same line. Alternatively,
it is particularly interesting to look at the tr namespace as it provides
some less heavy structures free from table constructions, for instance
panelGroupLayout with a layout set to vertical or a panelBorderLayout,
both generating div structures instead.
•
<trh:cellFormat>: It is used to define an XHTML table cell as part of an
XHTML table.
The attributes of each tag are defined in a most consistent, and thus
recognizable, way that will be seen in detail later in this book. By
the way, there are also tags for the construction of framesets such as
trh:frame in case anyone still wants to make use of framesets
However, before we deal with the attributes let us conclude this structural overview
by a look at the organization of the functionality of the core tag library.
Trinidad’s core tag library namespace (tr)
The following groups can be functionally distinguished which is also reflected in
the packages structure of Trinidad's API (all beginning with org.apache.myfaces.
trinidad.component; which has been left out here to avoid repetition). Note that,
for completeness, we will also include information on the pure Java side as well as
information on the few components that stem from the trh namespace:
•
Basic document composition tags from the core API: document,
stylesheet, form, subform. poll also appears here although it
is not a composition tag.
•
Form input and display tags, components from the core.input API:
inputText, inputDate, inputListOfValues, and so on.
•
Command or navigation tags from core.nav that includes two tag types:
°
°
One that is focused on command tags that assumes a given
form, presupposing the use of form and display tags from the
foregoing group—commandButton, commandLink, goButton,
goLink, and so on.
The other deals exclusively with navigation:
navigationTree, navigationPane, breadCrumbs, and so on.
[ 54 ]
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Chapter 3
•
Large input and output component tags from core.data, for example,
table, tree, and treeTable components.
•
Layout component tags from core.layout, for example, all the swinglike panel tags, such as panelBorderLayout, panelHorizontalLayout,
panelAccordion, showDetail, showDetailItem, and so on.
•
Basic output components from core.output that are almost always used in a
web application, for example, messages, outputText, outputLabel, spacer,
statusIndicator, and so on.
•
Model objects from core.model devised for various tags ; they provide
the corresponding view models for their tag viewer counterparts, for
example, SortableModel CollectionModeland RowKeySet for tr:table,
ChildPropertyTreeModel for tr:tree and ChartModel for tr:chart.
•
A couple of converter components from trinidad.convert equip JSF
and Trinidad input components with powerful JSF conversion, that is,
convertNumber and convertDateTime.
•
Validator components from trinidad.validator equip JSF and Trinidad
input components with powerful JSF validation such as range validation
(validateDateTimeRange) and validation by regular expression match
(validateRegExp).
•
Events and event listeners from trinidad.event add new event
types and listeners specific for Trinidad components such as those that
support Trinidad's dialog framework, for example, commandButton
to launch a popup dialogue using LaunchEvent, ReturnEvent, and
ReturnListener. It provides only a few tags, but these can be very utile,
for example, fileDownloadActionListener, resetActionListener,
returnActionListener, and setActionListener.
There is a lot more to be found on the pure Java API side that either surfaces
indirectly on the tag library as attributes, or is used implicitly by the tags themselves.
Furthermore, there are utility classes and context support classes—RequestContext
being probably the most prominent one because it offers a lot of functionality, for
example, PPR from the server side. This is described in the upcoming chapter.
[ 55 ]
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Most Wanted Tags and Tag Attributes
The following figure illustrates the Java side of things (it shows what the structure of
some of the classes behind core.input look like):
The preceding figure is an outline of the core.input API hierarchy. Again, we can
see the typical UIX* and Core* structure.
Finally, let us take a closer look at the tag attributes.
[ 56 ]
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Chapter 3
Standard tag attributes
We begin by taking a closer look at the attributes that practically always occur, no
matter which tag is actually involved.
As mentioned before, this occurrence is because of Trinidad's
design which is noted by its consequent application of attributes
that are shared by many different tags.
The following attributes occur almost always:
•
id: As it is already known from JSF itself, it ought to be set in most cases as it
is used by Trinidad itself to identify the component. However, if it is not set
by the developer, Trinidad sets up arbitrary, but not very legible, IDs.
•
rendered: Typical for JSF; it is a Boolean attribute that allows setting if the
component is to become part of the page sent to the client—in other words if
it is considered by the Trinidad renderer.
•
binding, attributeChangeListener: These are attributes that are
practically never used because binding is an architecturally questionable
JSF attribute as it incurs a traffic-intense, tight coupling between view and
server-side model and is therefore not supported by Seam. On the other
hand, attributeChangeListener is rather an internal Trinidad attribute
to tell a Trinidad to re-render itself if renderer attributes of some other
component have changed.
°
onmousedown, onmousemove, onmouseout, onmouseover,
onmouseup, ondblclick, onclick: These are the usual
JavaScript mouse event listeners, onclick is typically used to
implement simple JavaScript confirm dialogues "Are you sure
(Y or N)?".
°
onkeydown, onkeypress, onkeyup: These are the usual
JavaScript keyboard, single key event listeners and may
be of interest although the attributes accessKey and
textAccessKey are usually more practical.
°
shortDesc: This attribute serves to set a short tool tip that
is displayed when the user hovers with the mouse on the
respective component.
[ 57 ]
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Most Wanted Tags and Tag Attributes
°
and styleClass: The former attribute is very
practical because it allows explicitly setting the style and
overriding default style settings. However, it is cleaner to
use styleClass, which is analogous to the XHTML style
attribute, and define this explicit setup as a style sheet
class in the style sheet (note that there are a couple of less
frequent style attributes geared towards Trinidad-specific
contents of component parts: contentStyle, labelStyle,
inlineStyle
listStyle, dateStyle, timeStyle, warnStyle,
infoStyle, fatalStyle, errorStyle, defaultStyle,
stateStyle, userStyle).
°
partialTriggers: This attribute serves to state the IDs of
the components (separated by single spaces) that trigger
a partial page refresh (PPR) which is discussed in the
upcoming chapter.
Standard tag attributes in tag groups
Let's take a look at the attributes that almost always occur in certain tag groups
(mentioned in the beginning of this chapter):
Attributes that occur in form and display tags
This relates to the second tag group we learned in the earlier section named
Trinidad's core tag library namespace (tr). The following Trinidad-specific attributes
occur there:
•
label: This attribute serves to set the label of an input field; note that
Trinidad support label indication, along with the respective input
field, is also used for error or info messaging, for example, in the
messages component.
•
accessKey, labelAndAccessKey: Both attributes allow keyboard
shortcuts for an input field, but labelAndAccessKey allows you to
indicate the shortcut as part of the label. For example, label="&amp;9:
date" activates the 9 key as keyboard shortcut for the respective input
field (e.g. pressing Alt + Shift + 9 in Firefox). Note that, its analogon,
textAndAccessKey in the command area.
•
contentStyle: This attribute is used to set the style of the tag's content area,
for example, the style used within input text's box.
•
disabled, readOnly: These are Boolean attributes that both deactivate input
fields, but disabled differs in its look by keeping the frame around the box.
[ 58 ]
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Chapter 3
•
autoSubmit: If "true", it sends the enclosing form when this Boolean
attribute's field is somehow manipulated, for example, by changing its entry
and pressing tab or return. Note that this attribute must be "true" if partial
page rendering is started from this attribute's field (refer to the upcoming
chapter for detailed information).
•
required, requiredMessageDetail, showRequired: The attribute required
is a Boolean attribute to indicate if an input field entry must be provided
by the user, and when it is not provided, it is allowed to indicate a custom
message (requiredMessageDetail) and display a missing symbol
(showRequired="true").
•
simple: This is a Boolean attribute to control if Trinidad's label and
messaging support is used. It also appears in the table tag.
A series of attributes in this group are those that stem from the core JSF tag libraries:
•
immediate: This is a JSF attribute and serves to have the respective input
field converted, and validated before the process validator phase of the
JSF lifecycle so that its possible server request may directly follow (apply
request phase). For example, this occurs when using action listeners, which
is a common practice.
•
onblur, onfocus, onchange: These attributes expect the usual JavaScript
handlers to be assigned.
•
validator, converter: Both attributes serve to reference JSF's usual
conversion and validation mechanisms, but validator differs in expecting
a method call instead of a class. This is somewhat confusing, but JSF's core
library supports the tag <f:validator validatorId="aValidatorClass"/
> which can be very practically used inside of any Trinidad input field tag.
•
value: This is JSF's standard attribute to assign the model behind the
respective tag, for example, a view model or a real domain object.
Finally, in this group are listener attributes which come both from pure JSF
and Trinidad:
•
actionListener: This attribute is based on the ActionEvent
•
valueChangeListener: This attribute is based on the ValueChangeEvent
•
returnListener: A Trinidad-specific listener called returnListener,
is supported, and is used to indicate a listener method for a Trinidad
Return Event when control returns from a Trinidad dialog (see respective
dialogs chapter)
[ 59 ]
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Most Wanted Tags and Tag Attributes
Attributes that occur in command and
navigation components
These are attributes that occur in the third tag group. We have learned about the
command and navigation tags, to which these attributes are related, in the earlier
section. Here we can see their attributes:
•
launchListener: This attribute serves to indicate a listener method that is
called just before a Trinidad dialogue is displayed.
•
partialSubmit: This is a Boolean attribute, which when set to "true" has
the effect that its tag acts as a partial page rendering source (refer to the
upcoming chapter for details).
•
blocking: This is a Boolean attribute that, when true lets Trinidad block any
other user input while the respective request is ongoing.
•
textAndAccessKey: This is, as mentioned earlier, an attribute that allows
assigning a keyboard shortcut. Note that its the power of Trinidad's
consistent support of the keyboard that makes it a framework for all
applications that heavily support keyboard users with minimal
mouse activity.
•
useWindow, windowHeight, windowWidth: These attributes are used to setup
a Trinidad dialogue popup (useWindow="true") and its window size.
Attributes that occur in large input and output
components
These attributes come from the fourth tag group, the rather heavyweight input
and output components as described in the beginning section. They can be further
grouped into the following attribute categories:
•
component attributes specific for table, treeTable, and tree
•
attributes specific for table and treeTable components only
•
attributes specific for tree and treeTable components only
•
attributes specific for the treeTable component only
•
attributes specific for the table component only
In the following section, we will give an overview of each of the above
attribute categories.
[ 60 ]
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Chapter 3
The tag attributes for table, treeTable, and tree
First, we come across a couple of listeners that deal with selection and disclosure:
•
A Trinidad-specific selectionListener serves to handle a SelectionEvent
that is raised when the user selects a row
•
A Trinidad-specific rowDisclosureListener to handle a
RowDisclosureEvent that is raised when the users clicks on a detail item or
any other node that is closed
Next, follow the row-specific attributes:
•
selectedRowKeys: This is the set of all rows (or row indices) that are selected
•
disclosedRowKeys: This is the set of all open nodes and rows
•
var, varStatus: As known from JSF; note that varStatus serves to set if a
model-based reference is used, for example, when returning a selected row
or if an index is preferred
The tag attributes for table and treeTable
A series of facets are supported that deal with the inclusion of developer own parts
in certain areas of the views:
•
actions: This attribute is used to indicate any other action areas that are to
be shown on the same line as Trinidad's built-in table or treeTable actions
•
footer: This serves to setup anything in the footer area
•
header: This is to setup anything in the header area
A couple of specific listeners are provided to deal with sorting and range change:
•
A Trinidad-specific sortListener is provided to allow handling any
SortEvent that occurs when the user clicks on the label of a column that has
sorting activated
•
A rangeChangeListener is supported to handle any RangeChangeEvent
that occurs when the user thumbs through the data when it is displayed
page-wise
[ 61 ]
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Most Wanted Tags and Tag Attributes
In connection with the sortListener table and treeTable, we need to provide the
following attribute for setting up a selection mode:
•
rowSelection: This attribute serves to indicate if any selection at all is to be
supported ("none"), and if so which type ("multiple" or "single")
°
autoSubmit: This is to enable partial page rendering which
also sends the enclosing form
°
emptyText: This is used to indicate any text that is displayed
when there is no data to be obtained from the model
The following series of attributes deal with the general view setup:
•
rows: This is the number of lines to be displayed at once
•
summary: This is used to indicate the purpose and structure of this
component (only useful for non-visual output)
•
rowBandingInterval, columnBandingInterval: These attributes serve to
setup band style for easier reading and in particular, to indicate when which
(horizontal, vertical, or both) band is changed (for example, every two lines)
•
horizontalGridVisible, verticalGridVisible: These Boolean attributes
are used to display a horizontal grid, vertical grid, or both
•
width: This attribute serves to define the overall width of this component
The tag attributes for tree and treeTable
There are just three attributes that are specific for both tree and treeTable:
•
nodeStamp: This facet allows to build the tree nodes by specifying a single
looped node that allows us to build a tree in a highly dynamic way using an
implicit loop (see the tree chapter for details)
•
focusListener, focusRowKey: These attributes allow handling the focus
when it is on a node, which raises a FocusEvent that may be handled by
the indicated focusListener and that is accessible in the object indicated
as focusRowKey
•
initiallyExpanded: This is used to set if the component shows all the nodes
when shown for the first time
[ 62 ]
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Chapter 3
The tag attributes for treeTable
The treeTable tag is exclusively supported by the following attributes:
•
rowsByDepth: This allows us to set the maximum size of displayed nodes
depending on the actual level(depth) by passing an array of integers for
the depths that the developer wants to specify (for more details refer to
Chapter 8, Growing a Tree)
•
rootNoteRendered: This is used to set if the root is rendered at all
The tag attributes for tree
Actually, there is only one attribute here that exclusively supports this tag:
•
allDetailsEnabled: This serves to set if the detail feature of a table is to be
used, thereby allowing to display additional detail information per line
Summary
We have seen what Trinidad is all about with regards to its component set. More
concretely, we have first looked at the XHTML-focused Trinidad namespace trh
that basically contains a component set for XHTML layout.
Furthermore, we looked at Trinidad's core namespace which is its tr JSF tag library.
It contains a large component set with various types of components for basic
document composition, form input and display, command and navigation, large
and basic input and output, layout, models, converters, validators, events, and
event listeners.
Finally, we looked at the attributes of all those tags and found out that a
straight-forward orientation along tag groups is possible. This is thanks to
Trinidad's framework character.
[ 63 ]
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book
Where to buy this book
You can buy Apache MyFaces Trinidad 1.2 from the Packt Publishing website:
http://www.packtpub.com/apache-myfaces-trinidad-1-2-apractical-guide/book
Free shipping to the US, UK, Europe and selected Asian countries. For more information, please
read our shipping policy.
Alternatively, you can buy the book from Amazon, BN.com, Computer Manuals and
most internet book retailers.
www.PacktPub.com
For More Information:
www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book