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.
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 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).
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: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. 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.
- 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, CollectionModel and 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.
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.
- 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).
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 article):
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.
- 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.
- 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
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.
- 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.
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
- 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
- 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
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.
If you have read this article you may be interested to view :