Although 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.
A tag file is declared in the TLD using a tag-file element. Its subelements are listed in Table 8–8.
Table 8–8 tag-file Subelements
Element |
Description |
---|---|
description |
(optional) A description of the tag. |
display-name |
(optional) Name intended to be displayed by tools. |
icon |
(optional) Icon that can be used by tools. |
name |
The unique tag name. |
path |
Where to find the tag file implementing this tag, relative to the root of the web application or the root of the JAR file for a tag library packaged in a JAR. This must begin with /WEB-INF/tags/ if the tag file resides in the WAR, or /META-INF/tags/ if the tag file resides in a JAR. |
example |
(optional) Informal description of an example use of the tag. |
tag-extension |
(optional) Extensions that provide extra information about the tag for tools. |
Tag 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:
tlib-version for the tag library. Defaults to 1.0.
short-name is derived from the directory name. If the directory is /WEB-INF/tags/, the short name is simply tags. Otherwise, the full directory path (relative to the web application) is taken, minus the /WEB-INF/tags/ prefix. Then all / characters are replaced with - (hyphen), which yields the short name. Note that short names are not guaranteed to be unique.
A tag-file element is considered to exist for each tag file, with the following subelements:
The name for each is the filename of the tag file, without the .tag extension.
The path for each is the path of the tag file, relative to the root of the web application.
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.
Tag 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.