Apache MyFaces Trinidad 1.2 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.

also read:

• Introduction to JSF
• JSF Interview Questions
• Request Processing Lifecycle phases in JSF

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 theirattributes 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 file.

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.

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

The following image provides an outline of Trinidad’s structural package design:

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 supportlibrary 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).

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>

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 over view 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 refl ected 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.
• 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.

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.

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.
• inlineStyle 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,
  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=”&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.
• 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)

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: T his 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.

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

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

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.