Apache MyFaces Trinidad 1

Apache MyFaces Trinidad 1.2A 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 AuthorDavid Thomas is a developer and technical project manager of Java-based webapplications, and has well over 10 years of experience in various web technologies.

He began writing applications based on the Common Gateway Interface (CGI), HTMLand Javascript, with a short Java Applets interlude.

The main occupation with Java began when Java took charge of the server. A series ofJava Servlet applications were developed using an early, self-built Model-2 controllerarchitecture.

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. Thisalso included the development of major portal applications in the finance and bankingsector.

Shortly after Java Server Faces 1.2 (JSF) emerged, began the development of a major JSFweb application including the development of a high-level framework based on ApacheMy Faces Trinidad, Facelets and JBOSS Seam in the area of controlling. This projectspawned 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

http://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 hisexperience 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 aregoing on holidays, reading books, walking, swimming, making tea, and taking trains.

Furthermore, he is a firm believer in vegetarianism and the responsibility of each humanbeing for her or his well-being and surroundings—in short, of acting locally whilethinking globally.

Regarding this book he hopes it will be of great value to many people to enjoy aneffective and efficient use of Trinidad.

I would like to thank my wife for her patience during the writing ofthis book.



Apache MyFaces Trinidad 1.2A Practical GuideIn 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 Ajaxtechnology. You will implement login, authorization, navigation, internationalization,polling and browser issues with the help of these technologies. You will then use Seam-gen for deployment.

As you move through the book, you will develop a web application example where aseries of selected Trinidad components are applied and their capabilities explored.

Finally, you will master the Trinidad dialog framework, a Trinidad key technology thatallows the application of dialogs.

What This Book CoversChapter 1, Introducing Trinidad, introduces you to the Trinidad component library. Wegive a general idea of this component library, the areas covered by its components, andcompare 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 basicmeans to structure and build pages using Facelet page composition, Facelet compositioncomponents, 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 Trinidadallowing you to draw an efficient mental map of the library and make an effectiveselection and application of tags.

Chapter 4, Rendering Pages Partially, introduces you to the Trinidad's Ajax technologycalled PPR (Partial Page Rendering). PPR is inspected from two points of view—the puretag-based partial rendering and the pure Java-side partial rendering techniques.

Chapter 5, Web Application Groundwork, teaches you how to develop the basic parts ofthe web application that serves as our Trinidad example. We present using Seam-gen torapidly deploy after each change of any fi le.



Chapter 6, Building a Panel-based Content, deals with Trinidad's panelAccordion andshowDetailItem 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 Faceletcomposition components to build highly flexible and well-formatted forms, includingmessaging support.

Chapter 8, Growing a Tree, deals with Trinidad's tree components and models andexemplify their application. We present an effective shortcut that makes Trinidad's treesupport an easy, and yet powerful, technology.

Chapter 9, The table and treeTable Components, gives an insight to Trinidad's table andtreeTable components and exemplifies their application. We apply the components in anincreasingly refined way, revealing most of their features one at a time.

Chapter 10, The Chart Component, deals with Trinidad's chart component and shows itsapplication. You will learn to competently set up representation parameters, effectivelyachieving the intended representation focus and thus graphically materializing hiddeninformation in an appropriate way.

Chapter 11, Building a Wizard, deals with Trinidad's components to implement a wizardand 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-upwindow techniques. We revisit Seam conversations to address the specific necessities forpop-up dialogs in Trinidad and Seam. We enhance the web application with a couple ofpop-up windows including wizard pop-up support.

Appendix, References, provides us with useful references and links related to ApacheMyFaces 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 effi cient 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 trhAn overview of the central Trinidad namespace trAn orientation and classifi cation on the attributes supported by Trinidad

Component library structureTrinidad'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).

•

•

•




[ 52 ]

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

<<Access, Derive>>

<<Access, Derive>>

<<Access, Derive>>

<<Access, Derive>>

<<Call>>

<<Call>>

<<Call>> <<Call>>

<<Call>>

<<Call>>

<<Import, Access, Instantiate, Derive, Call>>

<<Import, Instantiate, Call>>

org.apache.myfaces.trinidad.component.core.output

org.apache.myfaces.trinidad.component.core.nav

org.apache.myfaces.trinidad.component.core

org.apache.myfaces.trinidad.component org.apache.myfaces.trinidad.util

org.apache.myfaces.trinidad.component.core.data

org.apache.myfaces.trinidad.component.core.layout

org.apache.myfaces.trinidad.event

org.apache.myfaces.trinidad.component.core.input

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 specifi c JSF lifecycle processing methods, and Core* classes that deal with the specifi c properties (getters or setters).

•

•



Chapter 3

[ 53 ]

Trinidad’s XHTML tag library namespace (trh)Two groups can be distinguished from the trh namespace. The fi rst one deals with the defi nition of an XHTML page and provides the developer with the following tags:

<trh:html>: It is used to defi ne the whole XHTML page, analogous to <html><trh:head>: It is used to defi ne the header, analogous to <head><trh:body>: It is used to defi ne the main contents, analogous to <body><trh:script>: It is used to defi ne a JavaScript to be executed, analogous to <script>

•

•

•

•




[ 54 ]

The second group deals with the layout of an XHTML table:

<trh:tableLayout>: It is used to defi ne an XHTML table.<trh:rowLayout>: It is used to defi ne 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 defi ne an XHTML table cell as part of an XHTML table.

The attributes of each tag are defi ned 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 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.

•

•

•

•

•

•

°

°



Chapter 3

[ 55 ]

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 swing-like 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 specifi c 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.

•

•

•

•

•

•

•




[ 56 ]

The following fi gure illustrates the Java side of things (it shows what the structure of some of the classes behind core.input look like):

The preceding fi gure 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.



Chapter 3

[ 57 ]

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 traffi c-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 confi rm 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.

•

•

•

°

°

°




[ 58 ]

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 defi ne 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-specifi c 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-specifi c attributes occur there:

label: This attribute serves to set the label of an input fi eld; note that Trinidad support label indication, along with the respective input fi eld, is also used for error or info messaging, for example, in the messages component. accessKey, labelAndAccessKey: Both attributes allow keyboard shortcuts for an input fi eld, 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 fi eld (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 fi elds, but disabled differs in its look by keeping the frame around the box.

°

°

•

•

•

•



Chapter 3

[ 59 ]

autoSubmit: If "true", it sends the enclosing form when this Boolean attribute's fi eld 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 fi eld (refer to the upcoming chapter for detailed information). required, requiredMessageDetail, showRequired: The attribute required is a Boolean attribute to indicate if an input fi eld 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 fi eld 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 fi eld 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-specifi c 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)

•

•

•

•

•

•

•

•

•

•




[ 60 ]

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 specifi c for table, treeTable, and tree attributes specifi c for table and treeTable components onlyattributes specifi c for tree and treeTable components onlyattributes specifi c for the treeTable component onlyattributes specifi c for the table component only

In the following section, we will give an overview of each of the above attribute categories.

•

•

•

•

•

•

•

•

•

•



Chapter 3

[ 61 ]

The tag attributes for table, treeTable, and tree First, we come across a couple of listeners that deal with selection and disclosure:

A Trinidad-specifi c selectionListener serves to handle a SelectionEvent that is raised when the user selects a row A Trinidad-specifi c 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-specifi c 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 specifi c listeners are provided to deal with sorting and range change:

A Trinidad-specifi c 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

•

•

•

•

•

•

•

•

•

•




[ 62 ]

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 formemptyText: 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 defi ne the overall width of this component

The tag attributes for tree and treeTable There are just three attributes that are specifi c 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 fi rst time

•

°

°

•

•

•

•

•

•

•

•



Chapter 3

[ 63 ]

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

SummaryWe have seen what Trinidad is all about with regards to its component set. More concretely, we have fi rst 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.

•

•

•



Where to buy this bookYou can buy Apache MyFaces Trinidad 1.2 from the Packt Publishing website:http://www.packtpub.com/apache-myfaces-trinidad-1-2-a-practical-guide/book

Free shipping to the US, UK, Europe and selected Asian countries. For more information, pleaseread our shipping policy.

Alternatively, you can buy the book from Amazon, BN.com, Computer Manuals andmost internet book retailers.

www.PacktPub.com


http://www.packtpub.com/apache-myfaces-trinidad-1-2-a-


http://www.packtpub.com/Shippingpolicy

Documents

Apache MyFaces Trinidad 1