Programming WebLogic JSP Tag Extensions

Understanding and Creating Custom JSP Tags

The following sections provide an overview of custom JSP tag functionality, format, and components, as well as procedures for creating and configuring a tag library:

Tag Handler API and Implementation

You write a custom JSP tag by writing a Java class called a tag handler.

The JSP 2.0 API defines a set of classes and interfaces that you use to write custom tag handlers. Documentation for the javax.servlet.jsp.tagext API is available at http://java.sun.com/j2ee/j2sdkee/techdocs/api/index.html.

Your tag handler must be of one of the following two types:

Classic Tag Handlers implement one of three interfaces:

Tag

Implement the javax.servlet.jsp.tagext.Tag interface if you are creating a custom tag that does not need access to its interface. The API also provides a convenience class TagSupport that implements the Tag interface and provides default empty methods for the methods defined in the interface.

BodyTag

Implement the javax.servlet.jsp.tagext.BodyTag interface if your custom tag needs to use a body. The API also provides a convenience class BodyTagSupport that implements the BodyTag interface and provides default empty methods for the methods defined in the interface. Because BodyTag extends Tag it is a super set of the interface methods.

IterationTag

Implement the javax.servlet.jsp.tagext.IterationTag interface to extend Tag by defining an additional method doAfterBody() that controls the reevaluation of the body.

Simple Tag Handlers (SimpleTag interface):

Implement the javax.servlet.jsp.tagext.SimpleTag interface if you wish to use a much simpler invocation protocol. The SimpleTag interface does not extend the javax.servlet.jsp.tagext.Tag interface as does the BodyTag interface. Therefore, instead of supporting the doStartTag() and doEndTag() methods, the SimpleTag interface provides a simple doTag() method, which is called once and only once for each tag invocation.

You write the tag handler class by doing one of the following:

Implement one of three interfaces, SimpleTag, Tag, or BodyTag, which define methods that are invoked during the life cycle of the tag.
Extend an abstract base class that implements the SimpleTag, Tag, or BodyTag interfaces.

Extending an abstract base class relieves the tag handler class from having to implement all methods in the interfaces and also provides other convenient functionality. The SimpleTagSupport, TagSupport, and BodyTagSupport classes implement the SimpleTag, Tag or BodyTag interfaces and are included in the API.

You can include one or more custom JSP tags in a tag library. You define a tag library by a tag library descriptor (.tld) file. The TLD describes the syntax for each tag and ties it to the Java classes that execute its functionality.

Custom Tag Library

JSP tag libraries include one or more custom JSP tags and are defined in a tag library descriptor (.tld) file. To use a custom tag library from a JSP page, reference its tag library descriptor with a <%@ taglib %> directive. For example:

  <%@ taglib uri="myTLD" prefix="mytaglib" %>

uri

The JSP engine attempts to find the tag library descriptor by matching the uri attribute to a uri that is defined in the Web application deployment descriptor (web.xml) with the <taglib-uri> element. For example, myTLD in the above the taglib directive would reference its tag library descriptor (library.tld) in the Web application deployment descriptor like this:

<taglib>

  <taglib-uri>myTLD</taglib-uri>
  <taglib-location>library.tld</taglib-location>

</taglib>

prefix

The prefix attribute assigns a label to the tag library. You use this label to reference its associated tag library when writing your pages using custom JSP tags. For example, if the library (called mytaglib) from the example above defines a new tag called newtag, you would use the tag in your JSP page like this:

<mytaglib:newtag>

For more information, see Creating a Tag Library Descriptor.

Custom Tag Format

A custom tag format can be empty, called an empty tag, or can contain a body, called a body tag. Both types of tags can accept a number of attributes that are passed to the Java class that implements the tag. For more details, see Handling Exceptions within a Tag Body.

An empty tag takes the following form:

<mytaglib:newtag attr1="aaa" attr2="bbb" ... />

A body tag takes the following form:

<mytaglib:newtag attr1="aaa" attr2="bbb" ... >
  body
</mytaglib:newtag>

A tag body can include more JSP syntax, and even other custom JSP tags that also have nested bodies. Tags can be nested within each other to any level. For example:

<mytaglib:tagA>
   <h2>This is the body of tagA</h2>
   You have seen this text <mytaglib:counter /> times!
  <p>
  <mytaglib:repeater repeat=4>
     <p>Hello World!
  </mytaglib:repeater>
</mytaglib:tagA>

The preceding example uses three custom tags to illustrate the ability to nest tags within a body tag. The tags function like this:

The body tag <mytaglib:tagA> only sees the HTML output from its evaluated body. That is, the nested JSP tags <mytaglib:counter> and <mytaglib:repeater> are first evaluated and their output becomes part of the evaluated body of the <mytaglib:tagA> tag.
The body of a body tag is first evaluated as JSP and all tags that it contains are translated, including nested body tags, whose bodies are recursively evaluated. The result of an evaluated body can then be used directly as the output of a body tag, or the body tag can determine its output based on the content of the evaluated body.
The output generated from the JSP of a body tag is treated as plain HTML. That is, the output is not further interpreted as JSP.

What Can You Do with Custom Tags?

Custom tags can perform the following tasks:

Produce output. The output of the tag is sent to the surrounding scope. The scope can be one of the following:

If the tag is included directly in the JSP page, then the surrounding scope is the JSP page output.
If the tag is nested within another parent tag, then the output becomes part of the evaluated body of its parent tag.

Define new objects that can be referenced and used as scripting variables in the JSP page. A tag can introduce fixed-named scripting variables, or can define a dynamically named scripting variable with the id attribute.
Iterate over body content of the tags until a certain condition is met. Use iteration to create repetitive output, or to repeatedly invoke a server side action.
Determine whether the rest of the JSP page should be processed as part of the request, or skipped.
An empty tag can perform server-side work based on the tag's attributes. The action that the tag performs can determine whether the rest of the page is interpreted or some other action is taken, such as a redirect. This function is useful for checking that users are logged in before accessing a page, and redirecting them to a login page if necessary.
An empty tag can insert content into a page based on its attributes. You can use such a tag to implement a simple page-hits counter or another template-based insertion.
An empty tag can define a server-side object that is available in the rest of the page, based on its attributes. You can use this tag to create a reference to an EJB, which is queried for data elsewhere in the JSP page.
A body tag has the option to process its output before the output becomes part of the HTML page sent to the browser, evaluate that output, and then determine the resulting HTML that is sent to the browser. This functionality could be used to produce "quoted HTML," reformatted content, or used as a parameter that you pass to another function, such as an SQL query, where the output of the tag is a formatted result set.
A body tag can repeatedly process its body until a particular condition is met.

Creating and Configuring a JSP Tag Library: Example Procedures

Perform the following steps to create and use custom JSP tags:

Write a tag handler class. When you use a custom tag in your JSP, this class executes the functionality of the tag. A tag handler class implements one of three interfaces:

javax.servlet.jsp.tagext.BodyTag
javax.servlet.jsp.tagext.Tag
javax.servlet.jsp.tagext.SimpleTag
Your tag handler class is implemented as part of a tag library. For more information, see Implementing the Tag Handler.

Reference the tag library in your JSP source using the JSP <taglib> directive. A tag library is a collection of JSP tags. Include this directive at the top of your JSP source. For more information, see Configuring JSP Tag Libraries.

Write the tag library descriptor (TLD). The TLD defines the tag library and provides additional information about each tag, such as the name of the tag handler class, attributes, and other information about the tags. For more information, see Creating a Tag Library Descriptor.

Reference the TLD in the Web application deployment descriptor (web.xml).

Use your custom tag in your JSP. For more information, see Configuring JSP Tag Libraries.