[ Team LiB ] Previous Section Next Section

Packaging and Installing a Tag

When you create a custom tag library, you must also create a tag library descriptor (TLD) that describes each tag in your tag library. Listing 16.3 shows the TLD for the HelloWorldTag Java class.

Listing 16.3 Source Code for hello.tld
<?xml version="1.0" encoding="ISO-8859-1"?>

<taglib xmlns="http://java.sun.com/xml/ns/j2ee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee/web-jsptaglibrary_2_0.xsd"
      version="2.0">
   <tlib-version>1.0</tlib-version>
   <short-name>hello</short-name>
   <description>
       An example Hello World tag.
   </description>
   <tag>
     <name>hello</name>
     <tag-class>examples.taglibs.HelloWorldTag</tag-class>
     <body-content>empty</body-content>
   </tag>
</taglib>

The first few lines of hello.tld are pretty standard for an XML file. You must start with the <?xml?> tag, of course. The next line specifies the schema and required JSP version. You can usually use this "as is" unless you need to specify additional namespaces or schema locations.

<taglib> is the root tag for a TLD and encloses all the other tags. Remember that an XML document has a single root tag that encloses everything else in the document. The next few tags describe the tag library.

The <tlib-version> tag describes the version number of the tag library. The <short-name> tag gives a short name for the tag library that might be used within a JSP Page Authoring tool. The idea is that you would load various tag libraries and see a list of the available libraries. The short name is the name you would see in the list. The <description> tag gives the long description of the tag library.

After the initial information describing the tag library, you can list the tags contained in the library. This tag library contains a single tag with a name of hello (as indicated by the <name> tag). The tag name, along with the prefix for the tag library, makes up the full tag that you put in the JSP. In other words, you take the tag name hello and combine it with the prefix specified in the JSP (mytag in Listing 16.1) to get the tag's full name, which is <mytag:hello>.

Why Tag Names Are Made Up of Two Parts

graphics/bytheway_icon.gif

The reason for splitting the name into two parts is that several people might make a tag named hello in their tag libraries. You need a way to specify which tag you mean, so you must use a prefix to indicate which library you are referring to.


Following <name>, the <tag-class> tag indicates the fully qualified pathname of the class that implements this tag. Finally, the <body-content> tag indicates that this tag will not have a body; in other words, the tag is an empty tag as shown, or there is nothing between the start and end tags.

Now that you have created the TLD file, you must deploy the tag library and test your Web page as a Web application. Create a directory called WEB-INF, and then in the WEB-INF directory create a web.xml that looks like the file in Listing 16.4.

Listing 16.4 Source Code for web.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
    version="2.4">

    <display-name>Tag Demo</display-name>
    <description>An application for testing custom tags</description>
    <taglib>
        <taglib-uri>/hello</taglib-uri>
        <taglib-location>/WEB-INF/tld/hello.tld</taglib-location>
    </taglib>
</web-app>

Most of the web.xml file should be familiar from the example in Hour 2, "JavaServer Pages Behind the Scenes," where you packaged a Web application into a WAR file. There are a few tags that you haven't seen before, however. The <taglib> tag defines a tag library that the Web application uses. The <taglib-uri> tag defines the name that a JSP would use as the URI for this tag library. Look back at Listing 16.2 and you can see that TestHello.jsp specifies /hello as the URI for the tag library, which matches what you see in web.xml. The <taglib-location> tag specifies the location of the hello.tld file, which is the file from Listing 16.3. According to the web.xml file, hello.tld should be stored in a directory called tld, which is below the WEB-INF directory.

Now, under the WEB-INF directory, create a classes/examples/taglibs/ directory and copy the HelloWorldTag.class file to that directory. Make sure that TestHello.jsp is in the same directory as the WEB-INF directory. Now create a file called tagdemo.war by going to the directory where WEB-INF and TestHello.jsp are located and entering the following command:


jar cvf tagdemo.war WEB-INF TestHello.jsp

Now install the WAR file in your Web server. After the file is installed, you should be able to access TestHello.jsp and see the output shown previously in Figure 16.1.

Having Trouble with the Example?

graphics/bytheway_icon.gif

If you are having trouble installing your custom tag library, see the "Q&A" section at the end of this hour.


    [ Team LiB ] Previous Section Next Section