The J2EETM Tutorial

Using Tags

This section describes how a page author specifies that a JSP page is using a tag library and introduces the different types of tags.

Declaring Tag Libraries

You declare that a JSP page will use tags defined in a tag library by including a taglib directive in the page before any custom tag is used:

<%@ taglib uri="/WEB-INF/tutorial-template.tld" prefix="tt" %>

The uri attribute refers to a URI that uniquely identifies the tag library descriptor (TLD), described in the section Tag Library Descriptors. This URI can be direct or indirect. The prefix attribute defines the prefix that distinguishes tags defined by a given tag library from those provided by other tag libraries.

Tag library descriptor file names must have the extension .tld. TLD files are stored in the WEB-INF directory of the WAR or in a subdirectory of WEB-INF. You can reference a TLD directly and indirectly.

The following taglib directive directly references a TLD filename:

<%@ taglib uri="/WEB-INF/tutorial-template.tld" prefix="tt" %>

This taglib directive uses a short logical name to indirectly reference the TLD:

<%@ taglib uri="/tutorial-template" prefix="tt" %>

A logical name must be mapped to an absolute location in the Web application deployment descriptor. To map the logical name /tutorial-template to the absolute location /WEB-INF/tutorial-template.tld,

  1. Select Bookstore3WAR.
  2. Select the File Refs tab
  3. Click the Add button in the JSP Tag Libraries subpane.
  4. Enter the relative URI /tutorial-template in the Coded Reference field.
  5. Enter the absolute location /WEB-INF/tutorial-template.tld in the Tag Library field.

Types of Tags

JSP custom tags are written using XML syntax. They have a start tag and end tag, and possibly a body:


A custom tag with no body is expressed as follows:

<tt:tag />

Simple Tags

A simple tag contains no body and no attributes:

<tt:simple />

Tags With Attributes

A custom tag can have attributes. Attributes are listed in the start tag and have the syntax attr="value". Attribute values serve to customize the behavior of a custom tag just as parameters are used to customize the behavior of a method.

You specify the types of a tag's attributes in a tag library descriptor (see Tag Library Descriptors).

You can set an attribute value from a String constant or a runtime expression. The conversion process between the constants and runtime expressions and attribute types follows the rules described for JavaBeans component properties in Setting JavaBeans Component Properties.

The attributes of the Struts logic:present tag determine whether the body of the tag is evaluated. In the following example, an attribute specifies a request parameter named Clear:

<logic:present parameter="Clear">

The Duke's Bookstore application page catalog.jsp uses a runtime expression to set the value of the attribute that determines the collection of books over which the Struts logic:iterate tag iterates:

<logic:iterate collection="<%=bookDB.getBooks()%>" 	
   id="book" type="database.BookDetails">

Tags with Bodies

A custom tag can contain custom and core tags, scripting elements, HTML text, and tag-dependent body content between the start and end tag.

In the following example, the Duke's Bookstore application page showcart.jsp uses the Struts logic:present tag to clear the shopping cart and print a message if the request contains a parameter named Clear:

<logic:present parameter="Clear">	
   <% cart.clear(); %>	
   <font color="#ff0000" size="+2"><strong> 	
   You just cleared your shopping cart! 	

Choosing between Passing Information as Attributes or Body

As shown in the last two sections, it is possible to pass a given piece of data as an attribute of the tag or as the tag's body. Generally speaking, any data that is a simple string or can be generated by evaluating a simple expression is best passed as an attribute.

Tags That Define Scripting Variables

A custom tag can define a variable that can be used in scripts within a page. The following example illustrates how to define and use a scripting variable that contains an object returned from a JNDI lookup. Examples of such objects include enterprise beans, transactions, databases, environment entries, and so on:

<tt:lookup id="tx" type="UserTransaction" 	
   name="java:comp/UserTransaction" />	
<% tx.begin(); %>

In the Duke's Bookstore application, several pages use bean-oriented tags from Struts to define scripting variables. For example, bookdetails.jsp uses the bean:parameter tag to create the bookId scripting variable and set it to the value of the bookId request parameter. The jsp:setProperty statement also sets the bookId property of the bookDB object to the value of the bookId request parameter. The bean:define tag retrieves the value of the bookstore database property bookDetails and defines the result as the scripting variable book:

<bean:parameter id="bookId" name="bookId" />	
<jsp:setProperty name="bookDB" property="bookId"/>	
<bean:define id="book" name="bookDB" property="bookDetails"	
<h2><jsp:getProperty name="book" property="title"></h2>

Cooperating Tags

Customer tags can cooperate with each other through shared objects. In the following example, tag1 creates an object called obj1, which is then reused by tag2.

<tt:tag1 attr1="obj1" value1="value" />	
<tt:tag2 attr1="obj1" />

In the next example, an object created by the enclosing tag of a group of nested tags is available to all inner tags. Since the object is not named, the potential for naming conflicts is reduced. This example illustrates how a set of cooperating nested tags would appear in a JSP page.

   <tt:innerTag />	

The Duke's Bookstore page template.jsp uses a set of cooperating tags to define the screens of the application. These tags are described in the section A Template Tag Library.