If you want to redistribute your tag files or implement your custom tags with tag handlers written in Java, you must declare the tags in a tag library descriptor (TLD). A tag library descriptor is an XML document that 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. Tag library descriptor file names must have the extension .tld and must be packaged in the /WEB-INF/ directory or subdirectory of the WAR file or in the /META-INF/ directory or subdirectory of a tag library packaged in a JAR. If a tag is implemented as a tag file and is packaged in /WEB-INF/tags/ or a subdirectory, a TLD will be generated automatically by the web container, though you can provide one if you wish. Most containers set the JSP version of this automatically generated TLD (called an implicit TLD) to 2.0. Therefore, in order to take advantage of JSP 2.1 features, you must provide a TLD that sets the JSP version to 2.1 if you don't have a TLD already. This TLD must be named implicit.tld and placed into the same directory as the tag files. You set the JSP version using the version attribute of the root taglib element that of the TLD, as shown here: <taglib xsi:schemaLocation= "http://java.sun.com/xml/ns/javaee web- jsptaglibrary_2_1.xsd" xmlns="http://java.sun.com/xml/ns/javaee"| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.1"> Table 76 lists the subelements of the taglib element.
Top-Level Tag Library Descriptor ElementsThis section describes some top-level TLD elements. Subsequent sections describe how to declare tags defined in tag files, how to declare tags defined in tag handlers, and how to declare tag attributes and variables. validator ElementThis element defines an optional tag library validator that can be used to validate the conformance of any JSP page importing this tag library to its requirements. Table 77 lists the subelements of the validator element.
listener ElementA tag library can specify some classes that are event listeners (see Handling Servlet Life-Cycle Events, page 63). The listeners are listed in the TLD as listener elements, and the web container will instantiate the listener classes and register them in a way analogous to that of 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. Declaring Tag FilesAlthough not required for tag files, providing a TLD allows you to share the tag across more than one tag library and lets you import the tag library using a URI instead of the tagdir attribute. tag-file TLD ElementA tag file is declared in the TLD using a tag-file element. Its subelements are listed in Table 78.
Unpackaged Tag FilesTag files placed in a subdirectory of /WEB-INF/tags/ do not require a TLD file and don't have to be packaged. Thus, to create reusable JSP code, you simply create a new tag file and place the code inside it. The web container generates an implicit tag library for each directory under and including /WEB-INF/tags/. There are no special relationships between subdirectories; they are allowed simply for organizational purposes. For example, the following web application contains three tag libraries: /WEB-INF/tags/ /WEB-INF/tags/a.tag /WEB-INF/tags/b.tag /WEB-INF/tags/foo/ /WEB-INF/tags/foo/c.tag /WEB-INF/tags/bar/baz/ /WEB-INF/tags/bar/baz/d.tag The implicit TLD for each library has the following values:
So, for the example, the implicit TLD for the /WEB-INF/tags/bar/baz/ directory would be as follows: <taglib> <tlib-version>1.0</tlib-version> <short-name>bar-baz</short-name> <tag-file> <name>d</name> <path>/WEB-INF/tags/bar/baz/d.tag</path> </tag-file> </taglib> Despite the existence of an implicit tag library, a TLD in the web application can still create additional tags from the same tag files. To accomplish this, you add a tag-file element with a path that points to the tag file. Packaged Tag FilesTag files can be packaged in the /META-INF/tags/ directory in a JAR file installed in the /WEB-INF/lib/ directory of the web application. Tags placed here are typically part of a reusable library of tags that can be used easily in any web application. Tag files bundled in a JAR require a tag library descriptor. Tag files that appear in a JAR but are not defined in a TLD are ignored by the web container. When used in a JAR file, the path subelement of the tag-file element specifies the full path of the tag file from the root of the JAR. Therefore, it must always begin with /META-INF/tags/. Tag files can also be compiled into Java classes and bundled as a tag library. This is useful when you wish to distribute a binary version of the tag library without the original source. If you choose this form of packaging, you must use a tool that produces portable JSP code that uses only standard APIs. Declaring Tag HandlersWhen tags are implemented with tag handlers written in Java, each tag in the library must be declared in the TLD with a tag element. The tag element contains the tag name, the class of its tag handler, information on the tag's attributes, and information on the variables created by the tag (see Tags That Define Variables, page 211). Each attribute declaration contains an indication of whether the attribute is required, whether its value can be determined by request-time expressions, the type of the attribute, and whether the attribute is a fragment. Variable information can be given directly in the TLD or through a tag extra info class. Table 79 lists the subelements of the tag element.
body-content ElementYou specify the type of body that is valid for a tag by using the body-content element. This element is used by the web container to validate that a tag invocation has the correct body syntax and is used by page-composition tools to assist the page author in providing a valid tag body. There are three possible values:
Declaring Tag Attributes for Tag HandlersFor each tag attribute, you must specify whether the attribute is required, whether the value can be determined by an expression, the type of the attribute in an attribute element (optional), and whether the attribute is a fragment. If the rtexprvalue element is TRue or yes, then the type element defines the return type expected from any expression specified as the value of the attribute. For static values, the type is always java.lang.String. An attribute is specified in a TLD in an attribute element. Table 710 lists the subelements of the attribute element.
If a tag attribute is not required, a tag handler should provide a default value. The tag element for a tag that outputs its body if a test evaluates to true declares that the test attribute is required and that its value can be set by a runtime expression. <tag> <name>present</name> <tag-class>condpkg.IfSimpleTag</tag-class> <body-content>scriptless</body-content> ... <attribute> <name>test</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> ... </tag> Declaring Tag Variables for Tag HandlersThe example described in Tags That Define Variables (page 211) defines an EL variable departmentName: <tlt:iterator var="departmentName" type="java.lang.String" group="${myorg.departmentNames}"> <tr> <td><a href="list.jsp?deptName=${departmentName}"> ${departmentName}</a></td> </tr> </tlt:iterator> When the JSP page containing this tag is translated, the web container generates code to synchronize the variable with the object referenced by the variable. To generate the code, the web container requires certain information about the variable:
There are two ways to provide this information: by specifying the variable TLD subelement or by defining a tag extra info class and including the tei-class element in the TLD (see TagExtraInfo Class, page 248). Using the variable element is simpler but less dynamic. With the variable element, the only aspect of the variable that you can specify at runtime is its name (via the name-from-attribute element). If you provide this information in a tag extra info class, you can also specify the type of the variable at runtime. Table 711 lists the subelements of the variable element.
Table 712 summarizes a variable's availability according to its declared scope.
You can define the following variable element for the tlt:iterator tag: <tag> <variable> <name-given>var</name-given> <variable-class>java.lang.String</variable-class> <declare>true</declare> <scope>NESTED</scope> </variable> </tag> |