Using Tags

This section describes how a JSP page uses tags and introduces the different types of tags.

Declare the tag library containing the tag

Make the tag library implementation available to the Web application

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

<%@ 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" %>

You map a logical name 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, you add a taglib element to web.xml:

<taglib>
  <taglib-uri>/tutorial-template</taglib-uri>
  <taglib-location>
    /WEB-INF/tutorial-template.tld
  </taglib-location>
</taglib>

Making the Tag Library Implementation Available

A tag library implementation can be made available to a Web application in two basic ways. The classes implementing the tag handlers can be stored in an unpacked form in the WEB-INF/classes subdirectory of the Web application. Alternatively, if the library is distributed as a JAR, it is stored the WEB-INF/lib directory of the Web application. A tag library shared between more than one application is stored in the <JWSDP_HOME>/common/lib directory of the Java WSDP.

Types of Tags

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

<tt:tag>
  body
</tt:tag>

<tt:tag />

Simple Tags

<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 Tags with Attributes).

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! 
  </strong><br>&nbsp;<br></font>
</logic:present>

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"
  type="database.BookDetails"/>
<h2><jsp:getProperty name="book" property="title"></h2>

Cooperating Tags

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:outerTag>
  <tt:innerTag />
</tt:outerTag>

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 A Template Tag Library.