The Java EE 5 Tutorial

Declaring Tag Libraries

To declare that a JSP page will use tags defined in a tag library, you include a taglib directive in the page before any custom tag from that tag library is used. If you forget to include the taglib directive for a tag library in a JSP page, the JSP compiler will treat any invocation of a custom tag from that library as static data and will simply insert the text of the custom tag call into the response.

<%@ taglib prefix="tt" [tagdir=/WEB-INF/tags/dir | uri=URI ] %>

The prefix attribute defines the prefix that distinguishes tags defined by a given tag library from those provided by other tag libraries.

If the tag library is defined with tag files (see Encapsulating Reusable Content Using Tag Files), you supply the tagdir attribute to identify the location of the files. The value of the attribute must start with /WEB-INF/tags/. A translation error will occur if the value points to a directory that doesn’t exist or if it is used in conjunction with the uri attribute.

The uri attribute refers to a URI that uniquely identifies the tag library descriptor (TLD), a document that describes the tag library (see Tag Library Descriptors).

Tag library descriptor file names must have the extension .tld. TLD files are stored 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. You can reference a TLD directly or indirectly.

The following taglib directive directly references a TLD file name:

<%@ taglib prefix="tlt" uri="/WEB-INF/iterator.tld"%>

This taglib directive uses a short logical name to indirectly reference the TLD:

<%@ taglib prefix="tlt" uri="/tlt"%>

The iterator example defines and uses a simple iteration tag. The JSP pages use a logical name to reference the TLD.

    To deploy and run the iterator application with NetBeans IDE, follow these steps:

  1. In NetBeans IDE, select File->Open Project.

  2. In the Open Project dialog, navigate to:

  3. Select the iterator folder.

  4. Select the Open as Main Project check box.

  5. Click Open Project.

  6. In the Projects tab, right-click the iterator project, and select Undeploy and Deploy.

  7. To run the application, open the bookstore URL http://localhost:8080/iterator.

    To deploy and run the iterator application with Ant, follow these steps:

  1. In a terminal window, go to tut-install/javaeetutorial5/examples/web/iterator/.

  2. Type ant. This command will spawn any necessary compilations, copy files to the tut-install/javaeetutorial5/examples/web/iterator/build/ directory, and create a WAR file.

  3. Start the Application Server.

  4. Type ant deploy.

  5. To run the example, open your browser to http://localhost:8080/iterator.

To learn how to configure the example, refer to the deployment descriptor, which includes the following configurations:

The absolute URIs for the JSTL library are as follows:

When you reference a tag library with an absolute URI that exactly matches the URI declared in the taglib element of the TLD (see Tag Library Descriptors), you do not have to add the taglib element to web.xml; the JSP container automatically locates the TLD inside the JSTL library implementation.