Home | Download | PDF | API | FAQ | Search | Feedback | History

> ## Tag Library Descriptors

> 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 7-6 lists the subelements of the `taglib` element.

> Table 7-6 taglib Subelements
> Element | Description
> --- | ---
> description | (optional) A string describing the use of the tag library.
> `display-name` | (optional) Name intended to be displayed by tools.
> `icon` | (optional) Icon that can be used by tools.
> `tlib-version` | The tag library's version.
> `short-name` | (optional) Name that could be used by a JSP page-authoring tool to create names with a mnemonic value.
> `uri` | A URI that uniquely identifies the tag library.
> validator | See validator Element .
> `listener` | See listener Element .
> `tag-file | tag` | Declares the tag files or tags defined in the tag library. See Declaring Tag Files and Declaring Tag Handlers. A tag library is considered invalid if a `tag-file` element has a `name` subelement with the same content as a `name` subelement in a `tag` element.
> function | Zero or more EL functions (see Functions, page 129) defined in the tag library.
> tag-extension | (optional) Extensions that provide extra information about the tag library for tools.

> ### Top-Level Tag Library Descriptor Elements

> This 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 Element

> This 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 7-7 lists the subelements of the `validator` element.

> Table 7-7 validator Subelements
> Element | Description
> --- | ---
> `validator-class` | The class implementing `javax.servlet.jsp.tagext.TagLibraryValidator`
> `init-param` | (optional) Initialization parameters

> #### listener Element

> A tag library can specify some classes that are event listeners (see Handling Servlet Life-Cycle Events, page 61). 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 Files

> 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.

> #### tag-file TLD Element

> A tag file is declared in the TLD using a `tag-file` element. Its subelements are listed in Table 7-8.

> Table 7-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.

> #### Unpackaged Tag Files

> 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.

> #### Packaged Tag Files

> 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.

> ### Declaring Tag Handlers

> When 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).

> 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 7-9 lists the subelements of the `tag` element.

> Table 7-9 tag 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.
> `tag-class` | The fully qualified name of the tag handler class.
> `tei-class` | (optional) Subclass of `javax.servlet.jsp.tagext.TagExtraInfo`. See Declaring Tag Variables for Tag Handlers.
> `body-content` | The body content type. See body-content Element .
> `variable` | (optional) Declares an EL variable exposed by the tag to the calling page. See Declaring Tag Variables for Tag Handlers.
> `attribute` | Declares an attribute of the custom tag. See Declaring Tag Attributes for Tag Handlers.
> dynamic-attributes | Whether the tag supports additional attributes with dynamic names. Defaults to `false`. If true, the tag handler class must implement the `javax.servlet.jsp.tagext.DynamicAttributes` interface.
> example | (optional) Informal description of an example use of the tag.
> tag-extension | (optional) Extensions that provide extra information about the tag for tools.

> #### body-content Element

> You 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:

> - `tagdependent`: The body of the tag is interpreted by the tag implementation itself, and is most likely in a different language, for example, embedded SQL statements.
> - `empty`: The body must be empty.
> - `scriptless`: The body accepts only static text, EL expressions, and custom tags. No scripting elements are allowed.

> ### Declaring Tag Attributes for Tag Handlers

> For 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 7-10 lists the subelements of the `attribute` element.

> Table 7-10 attribute Subelements
> Element | Description
> --- | ---
> description | (optional) A description of the attribute.
> `name` | The unique name of the attribute being declared. A translation error results if more than one `attribute` element appears in the same tag with the same `name`.
> `required` | (optional) Whether the attribute is required. The default is `false`.
> `rtexprvalue` | (optional) Whether the attribute's value can be dynamically calculated at runtime by an EL expression. The default is `false`. When this element is set to `true` and the attribute definition also includes either a `deferred-value` or `deferred-method` element then the attribute accepts both dynamic and deferred expressions.
> `type` | (optional) The runtime type of the attribute's value. Defaults to `java.lang.String` if not specified.
> `fragment` | (optional) Whether this attribute is a fragment to be evaluated by the tag handler (`true`) or a normal attribute to be evaluated by the container before being passed to the tag handler. If this attribute is `true`: You do not specify the `rtexprvalue` attribute. The container fixes the `rtexprvalue` attribute at `true`. You do not specify the `type` attribute. The container fixes the `type` attribute at `javax.servlet.jsp.tagext.JspFragment`. Defaults to `false`.
> deferred-value | (optional) Indicates that the tag attribute accepts deferred value expressions. This element includes an optional `type` child element, which indicates the type of object to which the expression resolves. If no `type` element is included, the type is `java.lang.Object`. Either the `deferred-value` or `deferred-method` element (but not both) can be defined for the same attribute.
> deferred-method | (optional) Indicates that the tag attribute accepts deferred method expressions. This element includes an optional `method-signature` child element, which indicates the signature of the method that the expression invokes. If no method signature is defined, the method signature default is `void` `methodName()`. Either the `deferred-value` or `deferred-method` element (but not both) can be defined for the same attribute.

> 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 Handlers

> The example described in Tags That Define Variables 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:

> - Variable name
> - Variable class
> - Whether the variable refers to a new or an existing object
> - The availability of 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). 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 7-11 lists the subelements of the `variable` element.

> Table 7-11 variable Subelements
> Element | Description
> --- | ---
> `description` | (optional) A description of the variable.
> `name-given | name-from-attribute` | Defines an EL variable to be used in the page invoking this tag. Either `name-given` or `name-from-attribute` must be specified. If `name-given` is specified, the value is the name of the variable. If `name-from-attribute` is specified, the value is the name of an attribute whose (translation-time) value at the start of the tag invocation will give the name of the variable. Translation errors arise in the following circumstances: 1. Specifying neither `name-given` nor `name-from-attribute` or both. 2. If two `variable` elements have the same `name-given`.
> `variable-class` | (optional) The fully qualified name of the class of the object. `java.lang.String` is the default.
> `declare` | (optional) Whether or not the object is declared. `True` is the default. A translation error results if both `declare` and `fragment` are specified.
> `scope` | (optional) The scope of the variable defined. Can be either `AT_BEGIN`, `AT_END`, or `NESTED` (see Table 7-12). Defaults to `NESTED`.

> Table 15-12 summarizes a variable's availability according to its declared scope.

> Table 7-12 Variable Availability
> Value | Availability
> --- | ---
> `NESTED` | Between the start tag and the end tag.
> `AT_BEGIN` | From the start tag until the scope of any enclosing tag. If there's no enclosing tag, then to the end of the page.
> `AT_END` | After the end tag until the scope of any enclosing tag. If there's no enclosing tag, then to the end of the page.

> 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>