Tag Handler API and Implementation
You write a custom JSP tag by writing a Java class that is called a tag handler.
The JSP 2.1 API defines a set of classes and interfaces that you use to write custom tag handlers.
See the JSP 2.1 Specification at
Documentation for the
javax.servlet.jsp.tagext API is available at
Your tag handler must be of one of the following two types:
Classic Tag Handlers implement one of three interfaces:
javax.servlet.jsp.tagext.Taginterface if you are creating a custom tag that does not need access to its interface. The API also provides a convenience class
TagSupportthat implements the
Taginterface and provides default empty methods for the methods defined in the interface.
javax.servlet.jsp.tagext.BodyTaginterface if your custom tag needs to use a body. The API also provides a convenience class
BodyTagSupportthat implements the
BodyTaginterface and provides default empty methods for the methods defined in the interface. Because
Tagit is a super set of the interface methods.
javax.servlet.jsp.tagext.IterationTaginterface to extend
Tagby defining an additional method
doAfterBody()that controls the reevaluation of the body.
Simple Tag Handlers (
javax.servlet.jsp.tagext.SimpleTaginterface if you wish to use a much simpler invocation protocol. The
SimpleTaginterface does not extend the
javax.servlet.jsp.tagext.Taginterface as does the
BodyTaginterface. Therefore, instead of supporting the
SimpleTaginterface 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,
BodyTag, which define methods that are invoked during the life cycle of the tag.
Extend an abstract base class that implements the
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
BodyTagSupport classes implement the
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.
<%@ taglib uri="myTLD" prefix="mytaglib" %>
The JSP engine attempts to find the tag library descriptor by matching the
uriattribute to a
urithat is defined in the web application deployment descriptor (web.xml) with the
You do not need to mention the
<taglib>tag in the web.xml if the value of uri in
<%@ taglib uri='myTLD' prefix='mytaglib' %>is the same as the uri specified in the
.tldfile, provided the
.tldfile is in the default location (
/WEB-INF/tags/). See the JSP 2.1 specification.
myTLDin the above the
taglibdirective 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>
prefixattribute 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:
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.
See Handling Exceptions within a Tag Body for more information.
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.
<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:repeater>are first evaluated and their output becomes part of the evaluated body of the
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
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
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.
- 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.
- 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.
- Reference the TLD in the Web application deployment descriptor (web.xml).
- Use your custom tag in your JSP.