-C H A P T E R

The JATO tag library is a powerful tool for rendering dynamic JSP output when used in conjunction with the JATO framework. This document is intended to be a brief introduction to the tag library, as well as a comprehensive reference to the tags available within the library. See supplemental JATO documentation for more complete information on writing a JATO application.

How the Tag Library Interacts With JATO

JATO is architected around the idea of arbitrarily nested View objects. Some of these views are ContainerViews, containing other Views (including other ContainerViews), and others are DisplayFields, with a notion of a value which can be accessed.

Each JSP has a single ViewBean associated with it. This object is also referred to as the root view of the JSP, as it is the top-level view object containing all other views used in that JSP. Each tag in the JATO tag library is a reference to one of these contained Views. The objects the tags refer to are called peer views, or simply peers. Each tag a developer uses in his or her JSP must refer to an existing peer object in that JSP's ViewBean or one of the ViewBean's child views.

The bulk of the tags in the JATO tag library establish either a context within which other peers can be easily referenced, or they actually reference a peer view to render a visualHTML fragment such as a string value, a text field, or a list box. When a JSP using the tag library is rendered, it contains visual HTML form controls or other content derived from the interactions with each peer from within each tag. Thus, tags work in conjunction with a a set of predefined peers to render a dynamic HTML page from a JSP.

Using the Tag Library in Your Application

To use the JATO tag library within your Web application, each JSP using the tag library must reference the JATO Tag Library Descriptor, or TLD. This is accomplished by including the following directive at the top of your JSP:

(Note: If you are using the Sun ONE Application Framework IDE toolset, this is automatically managed for you.) The location of the TLD specified by the uri attribute, as well as the tag prefix name, are arbitrary. However, it is recommended that you use the above values and including the JATO TLD file in the root of your application WAR file's WEB-INF directory. Within this document, assume the jato tag prefix.

Using the Tag Library in non-HTML JSPs

The JATO tag library contains both visual and non-visual tags. The visual tags render HTML 4.01 compliant markup, but non-visual tags have no associated markup, or allow developers to specify the markup they wish to render. Non-visual tags fall into several categories, but generally they represent the structure of your JATO View hierarchy in an abstract way. Because this hierarchy remains the same across content types, you can develop non-HTML markup-based JSPs using JATO, with the only additional requirement being able to specify visual markup for the appropriate content type.

The existing getDisplayFieldValue tag provides a way to easily inline dynamic display field data without any associated markup, while still firing display events and working with the current ContainerView context. This allows developers to add dynamic values to static markup declared in a JSP. Use of this tag is an easy way to develop non-HTML (or even HTML) pages without creating new JSP tags. However, in general, creating new JSP tags is the easier approach to render non-HTML JSPs.

Beginning with JATO 2.0, component libraries gave developers the ability to easily package and deliver components that automatically manage their own tags for multiple content types, whether they are the standard JATO tag library tags or custom-built tags. Furthermore, beginning with JATO 2.1, JATO's taglib package has been reimplemented to provide much easier ways for developers to create new custom tags that render View components in arbitrary ways. Using these tools, it is easy for developers to either find an existing component library that handles visual markup of the content type they require, or create a component library that renders components using non-HTML content types. See the documentation for the taglib package for more information on creating your own visual tags.

Including JSP Content: Pagelets

JSPs allows inclusion of outside content in the currently rendering page (see the JSP 1.1 specification for full details). This allows developers to modularize JSP content and then combine this content into compound documents. This capability has interesting implications for JATO applications.

There are two ways to include content in a JSP: translation-time includes, and request-time includes. A translation-time include pulls an outside file's content into the enclosing JSP before it is translated into a servlet by the container. The benefit of this approach is that it performs well, and the included content acts just like it were part of the enclosing page. The downside is that it is not at all dynamic--the included content is statically enclosed and cannot be chosen or replaced at runtime.

A request-time include does a RequestDispatcher.include() operation on a target URL/JSP, dynamically inlining the target content into the enclosing page. This include is done every time the enclosing page is rendered. The benefit of this approach is that the included file can be chosen dynamically. The downside is that there is some performance overhead in dispatching the request to the included resource.

It is generally advocated translation-time includes of JSP fragments in JATO applications because they perform well, and can include just the views/fields appropriate for the scope of the inclusion. This approach lets a component writer compose a fragment of JSP/JATO content and conveniently reuse it in several pages. But, as noted above, the choice of which fragment to include in the enclosing page is determined at translation time and is then fixed, significantly limiting the dynamism of the rendered page.

Request-time includes in JATO applications would be a nice way to get around the static nature of translation-time includes, except that in prior versions of JATO, there was not any way to request-time include anything but a full ViewBean and its contents. This meant that developers had to basically include a root view inside another root view, which was both confusing and not always guaranteed to work correctly--there should only be one root view per logical page. The other downside to that approach is that the included content lost the scope of the enclosing JSP's container view; the scope of objects accessed in the included page is limited by the immediately enclosing ViewBean, meaning that the page cannot necessarily be arbitrarily included in other JSPs like a translation-time include would allow.

Since JATO 1.2, a solution has been offered to these limitations in the form of pagelets, accompanied by a <jato:pagelet> tag. In JATO, a pagelet is distinguished from an arbitrary non-pagelet JSP fragment by the fact that it can be seamlessly request-time included in a JATO JSP. This is accomplished by the use of the <jato:pagelet> tag, which connects the view tags in the included JSP to the enclosing JSP's container scope, so that an included pagelet uses the enclosing JSP's current container view as its container view scope.

EnclosingPage.jsp

<%@page info="E0130" language="java"%>

<%@taglib uri="/WEB-INF/jato.tld" prefix="jato"%>

<jato:useViewBean ...>

<jato:containerView name="foo">

...

    <jsp:include page="MyPagelet.jsp"/>

...

</jato:containerView>

</jato:useViewBean>

MyPagelet.jsp

<%@page info="MyPagelet" language="java"%>

<%@taglib uri="/WEB-INF/jato.tld" prefix="jato"%>

<jato:pagelet>

    <jato:combobox name="month"/>...

</jato:pagelet>

The "month" field sees container view "foo" as its enclosing container, and thus can be declared a proper child of "foo". The <jato:pagelet> tag acts as a proxy to the enclosing page's container view tag, connecting the two JSPs as though they were part of the same rendering, when in fact they are two separate renderings.

Even more interesting, developers can use the display events in JATO 1.2 to dynamically choose which pagelet to include at request time (by using the PageContext.include() method in the event). This technique is demonstrated in the JATO sample application.

The following matrix summarizes the types of inclusion techniques developers can use in JATO:

JSP Fragment Type	Translation-time Include	Runtime Include
Pagelet	Yes*	Yes
Fragment (no ViewBean)	Yes	No
Fragment (with ViewBean)	No	Yes

* Technically, this works; however, there is no reason other than consistency to use the <jato:pagelet> tag in this situation, since the included JSP will simply become part of the enclosing JSP. The pagelet tag is written to do nothing in this situation.

Tag Overview

The tags in the JATO tag library fall into three basic groups: context tags, value tags, and visual tags. See the following sections for more information.

Context Tags

These tags are oriented toward declaring a peer view's scope, within which the referenced object will define the current context for other embedded tags. Specifically, this means that each of these tags declare usage of a ContainerView (or a specialization of ContainerView). Each such declaration establishes a name scope in which child Views can be referred to by their short, non-qualified names. ContainerView contexts may be nested, and do not directly result in any rendered HTML.

Tag Name	Alternate Names	Description
containerView		Declare usage of `ContainerView`
tiledView		Declare usage of a `TiledView`
treeView		Declare usage of a `TreeView`
useViewBean	viewBean	Declare usage of a `ViewBean`

Value Tags

These tags allow for direct manipulation of DisplayField and Model values. Developers may embed these tags in scriptlets, expressions, or HTML within the JSP. Unlike the visual tags described below, these tags do not render an HTML form control; rather, these tags manipulate values directly. The value tags can be used to get/set values on any of the DisplayField subtypes, or any Model instance available in the application. These tags must appear with the scope of a context tag.

Tag Name	Description
getDisplayFieldValue	Retrieve a value from a `DisplayField`
getModelFieldValue	Retrieve a value from a `Model` field
setDisplayFieldValue	Set the value of a `DisplayField`
setModelFieldValue	Set the value of a `Model` field

Visual (HTML) Tags

These tags use a a combination of tag attributes and values from DisplayField peers to render HTML form controls. These tags must also appear with the scope of a context tag.

Tag Name	Alternate Names	Description
button		Render a button control
checkbox	checkBox	Render a checkbox control
combobox	comboBox	Render a combobox control
fileUpload		Render a file upload element
form		Define an HTML form
frameSrc		Render a frame source element
hidden		Render a hidden element
href		Render a hyperlink element
image		Render an image
listbox	listBox	Render a list control
password		Render a password control
radioButtons		Render a group of radio button controls
text	staticText	Render arbitrary text
textArea		Render a multi-line text area control
textField		Render a single line text control
validatingTextArea		Render a multi-line text area control
validatingTextField		Render a single line text control

Tree Tags

These tags can be combined with the treeTag to specify tree rendering logic.

Tag Name	Description
treeLevel	Denote a content section that will be rendered "level-times" for matching tree levels
treeNode	Denote a content section that will be rendered for matching tree nodes
treeNodeHandle	Renders a expand/collapse node control

Tag Library Overview