Creating a Tag Library Descriptor

Download Docs

Site Map

Glossary

e-docs > WebLogic Server > Programming WebLogic JSP Tag Extensions > Creating a Tag Library Descriptor

Programming WebLogic JSP Tag Extensions

Creating a Tag Library Descriptor

The following sections describe how to create a tag library descriptor (TLD) file:

Overview of Tag Library Descriptors

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 following procedure. The XML parser throws 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 also 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.

The example in 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:

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.

Include the following header:

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

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>
```
Identify the tag library:

<tlib-version>version_number</tlib-version>

(Required) The version number of the tag library.

<jsp-version>version_number</jsp-version>

(Required) Describes the JSP specification version (number) this tag library requires in order to function. The default is 1.2.

<shortname>TagLibraryName</shortname>

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

<uri>unique_string</uri>

(Required) Defines a public URI that uniquely identifies this version of the tag library.

<displayname>display_name</displayname>

(Required) Contains a short name that is intended to be displayed by tools.

<smallicon>icon.jpg</smallicon>

(Optional) Contains the name of a file containing a small (16 x 16) icon image. The file name is relative path within the tag library. The image must be either in the JPEG or GIF format, and the file name must end with the suffix ".jpg" or ".gif" respectively. The icon can be used by tools.

<largeicon>icon.jpg</uri>

(Optional) Contains the name of a file containing a large (32 x 32) icon image. The file name is relative path within the tag library. The image must be either in the JPEG or GIF format, and the file name must end with the suffix ".jpg" or ".gif" respectively. The icon can be used by tools.

<description>...text...</description>

(Required) Defines an arbitrary text string describing the tag library.

<validator>unique_string</validator>

(Optional) Provides information on the scripting variables defined by this tag. It is a (translation-time) error for a tag that has one or more variable subelements to have a TagExtraInfo class that returns a non-null object.

<listener>unique_string</listener>

(Optional) Defines an optional event listener object to be instantiated and registered automatically.
Define a tag library validator (Optional).

<validator>

Top level element for a validator.

   <validator-class>my.validator</validator-class>

(Required) The Java class that performs the validation.

      <init-param>

(Optional) Defines initialization parameters for the validator class.

         <param-name>param</param-name>

Defines the name of this parameter.

         <param-value>value</param-value>

Defines the value of this parameter.
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. You can also package the classes in a tag library jar file; for more information, see Deploying a JSP Tag Library as a JAR File.

<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. You can perform validation of the tag's attributes in this class.

Place the class files under the WEB-INF/classes directory of your Web Application, under a directory structure reflecting the package name. You can also package the classes in a tag library jar file; for more information, see Deploying a JSP Tag Library as a JAR File.

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

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

<taglib:mytag myAttribute="myAttributeValue">

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>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>
Define scripting variables (optional).
Within the <tag> element, you can define scripting variables.

<variable>

Top level element for declaring a variable.

   <name-given>someName</name-given>

Defines the name of the variable, or you can define the name from an attribute using

   <name-from-attribute>attrName</name-from-attribute>

Names the variable with the value of attrName.

   <variable-class>some.java.type</variable-class>

The Java type of this variable.

   <declare>true</declare>

(Optionals) If set to true, indicates that the variable is to be defined.

   <scope>AT_BEGIN</scope>

The scope of the scripting variable. Valid options are:

NESTED (The variable is only available inside the tag body)

AT_BEGIN (The variable is defined just before executing the body)

AT_END (The variable is defined just after executing the body.)

</variable>

Sample Tag Library Descriptor

The following is a sample listing of a tag library descriptor.

Listing 3-1 Sample Tag Library 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>