Creating a Tag Library Descriptor

 

This section discusses how to create a Tag Library Descriptor (TLD) file. The following topics are discussed:

• Overview

• Writing the Tag Library Descriptor

• Sample Tag Library Descriptor

Overview

A tag library allows a developer to group together tags with related functionality. A tag library uses a tag library Descriptor (tld) file that describes the tag extensions and relates them to their Java classes. WebLogic Server and some authoring tools use the TLD to get information about the extensions. TLD files are written in XML notation.

The syntax for a tag library Descriptor is specified in the document type descriptor (DTD) available at: http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd.

Writing the Tag Library Descriptor

Order the elements in the Tag Library Descriptor file as they are defined in the DTD. This ordering is used in the steps below. The XML parser will throw an exception if you incorrectly order the TLD elements.

The body of the TLD contains additional nested elements inside of the <taglib> ... </taglib> element. These nested elements are described in the steps below. For display in this document, nested elements are indented from their parent elements, but indenting is not required in the TLD.

A Sample Tag Library Descriptor declares a new tag called code. The functionality of this tag is implemented by the Java class weblogic.taglib.quote.CodeTag.

To create a tag library descriptor:

1. Create a text file with an appropriate name and the extension .tld, and locate it in the WEB-INF directory of the Web Application containing your JSP(s). Content beneath the WEB-INF directory is non-public and is not served over HTTP by WebLogic Server.

2. Include the following header:

   <!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.
    //DTD JSP Tag Library 1.1//EN" "web-jsptaglib_1_1.dtd">

3. Add the contents of the TLD, embedded in a <taglib> element. The contents include elements containing information about the tag library and elements that define each tag. For example:

   <taglib>
     ... body of taglib descriptor ...
   </taglib>

4. Identify the Tag Library

   <tlibversion>version_number</tlibversion>

   (Required) The version number of the tag library.

   <jspversion>version_number</jspversion>

   (Optional) The JSP version that this tag library is designed to work with. WebLogic supports JSP version 1.1 from this release.

   <shortname>TagLibraryName</shortname>

   (Required) Assigns a short name to this tag library. This element is not used by WebLogic Server.

   <uri>unique_string</uri>

   (Optional) This element is not used by WebLogic Server.

   <info>...text...</info>

   (Optional) Use this element to provide a description of the tag library. This element is not used by WebLogic Server.

5. Define a Tag

   Use a separate <tag> element to define each new tag in the tag library. The <tag> element takes the following nested tags:

   <name>tag_name</name>

   (Required) Defines the name of the tag. This is used when referencing the tag in a JSP file, after the ":" symbol, For example:

   <mytaglib:tag_name>

   For more information, see Using Custom Tags in a JSP.

   <tagclass>package.class.name</tagclass>

   (Required) Declares the tag handler class that implements the functionality of this tag. Specify the fully qualified package name of the class.

   Locate the class file under the WEB-INF/classes directory, in a directory structure reflecting the package name.

   <teiclass>package.class.name</teiclass>

   (Optional) Declares the subclass of TagExtraInfo that describes the scripting variables introduced by this tag. If your tag does not define new scripting variables, it does not use this element. Specify the fully qualified package name of the class.

   Place the class files under the WEB-INF/classes directory of your Web Application, under a directory structure reflecting the package name.

   <bodycontent>tagdependent | JSP | empty</bodycontent>

   (Optional) Defines the content of the tag body.

   empty means that you use the tag in the empty tag format in the JSP page. For example: <taglib:tagname/>

   JSP means that the contents of the tag can be interpreted as JSP and that you must use the tag in the body tag format. For example:

   <taglib:tagname>...</taglib:tagname>.

   tagdependent means that your tag will interpret the contents of the body as non-JSP (for instance an SQL statement).

   If the <bodycontent> element is not defined, the default value is JSP.

   <attribute>

   Use a separate <attribute> element to define each attribute that the tag can take. Tag attributes allow the JSP author to alter the behavior of your tags.

      <name>myAttribute</name>

   (Required) Defines the name of the attribute as it appears in the tag element in the JSP page. For example:

   <taglib:mytag myAttribute="myAttributeValue">

      <required>true | false</required>

   (Optional) Defines whether this attribute has optional use in the JSP page.

   If not defined here, the default is false - that is, the attribute is optional by default.

   If true is specified, and the attribute is not used in a JSP page, a translation-time error occurs.

      <rtexprvalue>true | false</rtexprvalue>

   (Optional) Defines whether this attribute can take a scriptlet expression as a value, allowing it to be dynamically calculated at request time.

   If this element is not specified, the value is presumed to be false.

   </attribute>

Sample Tag Library Descriptor

The following is a sample listing of a Taglib Descriptor.

Listing 3-1 Sample Taglib Descriptor (tld)

---

<taglib>

  <tlibversion>1.0</tlibversion>
  <jspversion>1.1</jspversion>
  <shortname>quote</shortname>
  <info>
     This tag library contains several tag extensions 
     useful for formatting content for HTML. 
  </info>

  <tag>
    <name>code</name>
    <tagclass>weblogic.taglib.quote.CodeTag</tagclass>
    <bodycontent>tagdependent</bodycontent>
    <attribute>
      <name>fontAttributes</name>
    </attribute>
    <attribute>
      <name>commentColor</name>
    </attribute>
    <attribute>
      <name>quoteColor</name>
    </attribute>
  </tag>

</taglib>