Home TOC

Search Feedback

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 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 filenames 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 the bookstore3 WAR.
2. Select the File Ref's tab
3. Click the Add button in the JSP Tag Libraries subpanel.
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:

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

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.

An attribute value can be set from a String constant or a runtime expression. An attribute value set from a String constant must have a type listed in Table 20; the conversion applied is shown in the table. The value assigned to an indexed attribute must be an array and the rules just described apply to the elements.

Table 20 Valid Tag Attribute Value Assignments

Attribute Type	Conversion on String Value
boolean or Boolean	As indicated in java.lang.Boolean.valueOf(String)
byte or Byte	As indicated in java.lang.Byte.valueOf(String)
char or Character	As indicated in java.lang.Character.valueOf(String)
double or Double	As indicated in java.lang.Double.valueOf(String)
int or Integer	As indicated in java.lang.Integer.valueOf(String)
float or Float	As indicated in java.lang.Float.valueOf(String)
long or Long	As indicated in java.lang.Long.valueOf(String)

You can also use a runtime expression to set the value of an attribute whose type is a compound Java programming language type. Recall from Expressions that a JSP expression is used to insert the value of a scripting language expression, converted into a String, into the stream returned to the client. When used within a custom tag, an expression simply returns its value; no automatic conversion is performed. As a consequence, the type returned from an expression must match or be castable to the type of the attribute, which is specified in the object that implements the tag.

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 to 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 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 retrieve the value of the bookId request parameter, and define the result as the scripting variable bookId. The bean:define tag is used to retrieve the value of the bookstore database property bookDetails and define 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"/>
<font color="#ff00000" size="+2">You just removed:
<strong>
<jsp:getProperty name="book" property="title">
</strong> 
<br>&nbsp;<br> 
</font> 

Cooperating Tags

Tags can cooperate with each other through shared objects.

In the following example, tag1 creates a named object called obj1, which is then reused by tag2. The convention encouraged by the JSP specification is that a tag with attribute named id creates and names an object and that object is referenced by other tags with an attribute named name.

<tt:tag1 id="obj1" attr2="value" />
<tt:tag2 name="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. The following 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.

Home TOC

Search Feedback