Defining Tags

Defining Tags

To define a tag, you need to:

• Develop a tag handler and helper classes for the tag

• Declare the tag in a tag library descriptor (TLD)

This section describes the properties of tag handlers and TLDs and explains how to develop tag handlers and library descriptor elements for each type of tag introduced in the previous section.

1 Tag Handlers

A tag handler is an object invoked by a Web container to evaluate a custom tag during the execution of the JSP page that references the tag. Tag handlers must implement either the Tag or BodyTag interface. Interfaces can be used to take an existing Java object and make it a tag handler. For newly created handlers, you can use the TagSupport and BodyTagSupport classes as base classes. These classes and interfaces are contained in the javax.servlet.jsp.tagext package.

Tag handler methods defined by the Tag and BodyTag interfaces are called by the JSP page's servlet at various points during the evaluation of the tag. When the start tag of a custom tag is encountered, the JSP page's servlet calls methods to initialize the appropriate handler and then invokes the handler's doStartTagmethod. When the end tag of a custom tag is encountered, the handler's doEndTagmethod is invoked. Additional methods are invoked in between when a tag handler needs to interact with the body of the tag. For further information, see Tags with Bodies (page 446). In order to provide a tag handler implementation, you must implement the methods, summarized in Figure, that are invoked at various stages of processing the tag.

A tag handler has access to an API that allows it to communicate with the JSP page. The entry point to the API is the page context object (javax.servlet.jsp.PageContext) through which a tag handler can retrieve all the other implicit objects (request, session, and application) accessible from a JSP page.

Implicit objects can have named attributes associated with them. Such attributes are accessed using [set|get]Attribute methods.

If the tag is nested, a tag handler also has access to the handler (called the parent) associated with the enclosing tag.

A set of related tag handler classes (a tag library) is usually packaged and deployed as a JAR archive.

2 Tag Library Descriptors

A tag library descriptor (TLD) is an XML document that describes a tag library. A TLD contains information about a library as a whole and about each tag contained in the library. TLDs are used by a Web container to validate the tags and by JSP page development tools.

TLD filenames must have the extension .tld. TLD files are stored in the WEB-INF directory of the WAR file or a subdirectory of WEB-INF.

A TLD must begin with an XML document prolog that specifies the version of XML and the document type definition (DTD):

<?xml version="1.0" encoding="ISO-8859-1" ?> 
<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag 
Library 1.2//EN" 
"http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd">

Tomcat supports 1.1 and 1.2 version DTDs. However, this chapter documents the 1.2 version because you should use the newer version in any tag libraries that you develop. The template library TLD, tutorial-template.tld, conforms to the 1.2 version. The Struts library TLDs conform to the 1.1 version of the DTD, which has fewer elements and uses slightly different names for some of the elements.

The root of a TLD is the taglib element. The subelements of taglib are listed in Figure.

Listener Element

A tag library can specify some classes that are event listeners (see Handling Servlet Life Cycle Events (page 370)). The listeners are listed in the TLD as listenerelements and the Web container will instantiate the listener classes and register them in a way analogous to listeners defined at the WAR level. Unlike WAR-level listeners, the order in which the tag library listeners are registered is undefined. The only subelement of the listener element is the listener-class element, which must contain the fully-qualified name of the listener class.