Download PDF Home History |  | API Search Feedback FAQ

> ## Using Custom Tags

> Custom tags are user-defined JSP language elements that encapsulate recurring tasks. Custom tags are distributed in a tag library, which defines a set of related custom tags and contains the objects that implement the tags.

> Custom tags have the syntax

>     <prefix:tag attr1="value" ... attrN="value" />

> or

>     <prefix:tag attr1="value" ... attrN="value" >
>       body
>     </prefix:tag>

> where `prefix` distinguishes tags for a library, `tag` is the tag identifier, and `attr1 ... attrN` are attributes that modify the behavior of the tag.

> To use a custom tag in a JSP page, you must

> - Declare the tag library containing the tag
> - Make the tag library implementation available to the Web application

> See Chapter 15 for detailed information on the different types of tags and how to implement tags.

> ### 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. A sample `iterator.war` is provided in `<``INSTALL``>/j2eetutorial14/examples/web/provided-wars/`. To build the example, follow these steps:

> 1. In a terminal window, go to `<``INSTALL``>/j2eetutorial14/examples/web/iterator/`.
> 2. Run `asant` `build`. This target will spawn any necessary compilations and will copy files to the `<``INSTALL``>/j2eetutorial14/examples/web/iterator/build/` directory.

> To package and deploy the example using `asant`, follow these steps:

> 1. Run `asant` `create-war`.
> 2. Run `asant` `deploy-war`.

> To learn how to configure the example, use `deploytool` to package and deploy it:

> 1. Start `deploytool`.
> 2. Create a Web application called `iterator` by running the New Web Component wizard. Select FileNewWeb Component.
> 3. In the New Web Component wizard:
> 1. Select the Create New Stand-Alone WAR Module radio button.
> 2. Click Browse.
> 3. In the WAR Location field, enter `<``INSTALL``>/docs/tutorial/examples/web/iterator/iterator.war`.
> 4. In the WAR Name field, enter `iterator`.
> 5. In the Context Root field, enter `/iterator`.
> 6. Click Edit Contents.
> 7. In the Edit Contents dialog box, navigate to `<``INSTALL``>/docs/tutorial/examples/web/iterator/build/`. Select the `index.jsp` and `list.jsp` JSP pages and `iterator.tld` and click Add. Notice that `iterator.tld` is put into `/WEB-INF/`.
> 8. Click Next.
> 9. Select the No Component radio button.
> 10. Click Next.
> 11. Click Finish.

> You map a logical name to an absolute location in the Web application deployment descriptor. For the iterator example, map the logical name `/tlt` to the absolute location `/WEB-INF/iterator.tld` using `deploytool` by following these steps:

> 1. Select the File Ref's tab.
> 2. Click the Add Tag Library button in the JSP Tag Libraries tab.
> 3. Enter the relative URI `/tlt` in the Coded Reference field.
> 4. Enter the absolute location `/WEB-INF/iterator.tld` in the Tag Library field.

> You can also reference a TLD in a `taglib` directive by using an absolute URI. For example, the absolute URIs for the JSTL library are as follows:

> - Core: `http://java.sun.com/jsp/jstl/core`
> - XML: `http://java.sun.com/jsp/jstl/xml`
> - Internationalization: `http://java.sun.com/jsp/jstl/fmt`
> - SQL: `http://java.sun.com/jsp/jstl/sql`
> - Functions: `http://java.sun.com/jsp/jstl/functions`

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

> ### Including the Tag Library Implementation

> In addition to declaring the tag library, you also must make the tag library implementation available to the Web application. There are several ways to do this. Tag library implementations can be included in a WAR in an unpacked format: Tag files are packaged in the `/WEB-INF/tag/` directory, and tag handler classes are packaged in the `/WEB-INF/classes/` directory of the WAR. Tag libraries already packaged into a JAR file are included in the `/WEB-INF/lib/` directory of the WAR. Finally, an application server can load a tag library into all the Web applications running on the server. For example, in the Application Server, the JSTL TLDs and libraries are distributed in the archive `appserv-jstl.jar` in `<``J2EE_HOME``>/lib/`. This library is automatically loaded into the classpath of all Web applications running on the Application Server so you don't need to add it to your Web application.

> To package the `iterator` tag library implementation in the `/WEB-INF/classes/` directory and deploy the `iterator` example with `deploytool`, follow these steps:

> 1. Select the General tab.
> 2. Click Edit Contents.
> 3. Add the iterator tag library classes.
> 1. In the Edit Contents dialog box, navigate to `<``INSTALL``>/docs/tutorial/examples/web/iterator/build/`.
> 2. Select the `iterator` and `myorg` packages and click Add. Notice that the tag library implementation classes are packaged into `/WEB-INF/classes/`.
> 4. Click OK.
> 5. Select FileSave.
> 6. Start the Application Server.
> 7. Deploy the application.
> 1. Select ToolsDeploy.
> 2. Click OK.

> To run the `iterator` application, open the URL `http://localhost:8080/iterator` in a browser.

Download PDF Home History |  | API Search Feedback FAQ

All of the material in The J2EE(TM) 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.