Creating a Tag Library Descriptor

3 Creating a Tag Library Descriptor

The following topics describe how to create a tag library descriptor (TLD).

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 have the file extension .tld and are written in XML notation.

Parent topic: Creating a Tag Library Descriptor

Writing the Tag Library Descriptor

Order the elements in the tag library descriptor file as they are defined in the XSD. 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 save 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:

<taglib version="2.0" xmlns="http://java.sun.com/xml/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee/web-jsptaglibrary_2_0.xsd">

Add the contents of the TLD, embedded in a <taglib> element, as indicated in steps 4-7. 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 2.0.
```
<short-name>TagLibraryName</short-name>
```
(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.
```
<display-name>display_name</display-name>
```
(Optional) Contains a short name that is intended to be displayed by tools.
```
<icon>
  <small-icon>icon.jpg</small-icon>
```
(Optional) Contains the name of a file containing a small (16 x 16) icon image. The file name is a 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.
```
  <large-icon>icon.jpg</large-icon>
```
(Optional) Contains the name of a file containing a large (32 x 32) icon image. The file name is a 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.
```
</icon>
<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. A translation-time error occurs if a tag that has one or more variable subelements has 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 name 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>
```
See What's New in Oracle WebLogic Server for a comprehensive listing of the new and changed JSP features in this release.
```
<tag-class>package.class.name</tag-class>
```
(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.

See Packaging a JSP Tag Library as JAR File.
```
<tei-class>package.class.name</tei-class>
```
(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.

See Packaging a JSP Tag Library as JAR File.
```
<body-content>empty | JSP | scriptless | tagdependent</body-content>
```
(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 a JSP and that you must use the tag in the body tag format. For example:
```
<taglib:tagname>...</taglib:tagname>
```
scriptless means that the contents of the tag do not contain any scripts or scripting elements.

tagdependent means that your tag will interpret the contents of the body as a non-JSP (for example, an SQL statement).
```
<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).
In 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>
```
(Optional) 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>
```

Parent topic: Creating a Tag Library Descriptor

Sample Tag Library Descriptor

The following example represents a listing of a tag library descriptor:

<taglib version="2.0" xmlns="http://java.sun.com/xml/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee/web-jsptaglibrary_2_0.xsd">
<taglib>
  <tlib-version>2.0</tlib-version>
  <jsp-version>2.0</jsp-version>
  <short-name>quote</short-name>
<uri>tag lib version id</uri>
  <description>
     This tag library contains several tag extensions 
     useful for formatting content for HTML. 
  </description>

  <tag>
    <name>code</name>
    <tag-class>weblogic.taglib.quote.CodeTag</tag-class>
    <body-content>tagdependent</body-content>
    <attribute>
      <name>fontAttributes</name>
    </attribute>
    <attribute>
      <name>commentColor</name>
    </attribute>
    <attribute>
      <name>quoteColor</name>
    </attribute>
  </tag>
</taglib>

Parent topic: Creating a Tag Library Descriptor

The DynamicAttributes Interface

You can use the DynamicAttributes interface, supported by the JSP 2.0 container, as tags with values that are treated in a consistent manner but with names that are not necessarily known at development time.

For example, if you want to customize the width portion of the <table> HTML tag by determining its value at runtime, you could make use of the DynamicAttributes interface to customize only the portion of the tag you want to change, without needing to specify anything about the other portions of the <table> tag (border, cellspacing, and so on). Without the DynamicAttributes interface, you would have needed to write a Tag Handler or other complicated code to accomplish the task of determining the value of width dynamically at runtime.

Parent topic: Creating a Tag Library Descriptor

Tag Handler Support of Dynamic Attributes

The TLD is what ultimately determines whether a tag handler accepts dynamic attributes or not. If a tag handler declares that it supports dynamic attributes in the TLD but it does not implement the DynamicAttributes interface, the tag handler must be considered invalid by the container.

If the dynamic-attributes element (a child element to the tag element for the tag library being authored) for a tag being invoked contains the value true, the following requirements apply:

For each attribute specified in the tag invocation that does not have a corresponding attribute element in the TLD for this tag, a call must be made to setDynamicAttribute(), passing in the namespace of the attribute (or null if the attribute does not have a namespace or prefix), the name of the attribute without the namespace prefix, and the final value of the attribute.
Dynamic attributes must be considered to accept request-time expression values.
Dynamic attributes must be treated as though they were of type java.lang.Object.
The JSP container must recognize dynamic attributes that are passed to the tag handler using the <jsp:attribute> standard action.
If the setDynamicAttribute() method throws JspException, the doStartTag() or doTag() method is not invoked for this tag, and the exception must be treated in the same manner as if it came from a regular attribute setter method.
For a JSP document in either standard or XML syntax, if a dynamic attribute has a prefix that does not map to a namespace, a translation error must occur. In standard syntax, only namespaces defined using taglib directives are recognized.

Parent topic: Creating a Tag Library Descriptor

Dynamic Attributes Example

In the following example attributes a and b are declared by using the attribute element in the TLD, attributes d1 and d2 are not declared, and the dynamic-attributes element is set to true.

You set the attributes using the calls:

setA( "1" ),
setDynamicAttribute( null, "d1", "2" ),
setDynamicAttribute( "http://www.foo.com/jsp/taglib/mytag.tld", "d2", "3" ),
setB( "4" ),
setDynamicAttribute( null, "d3", "5" ), and
setDynamicAttribute( "http://www.foo.com/jsp/taglib/mytag.tld", "d4", "6" ).

Example 3-1 Dynamic Attribute Example

<jsp:root xmlns:mytag="http://www.foo.com/jsp/taglib/mytag.tld" version="2.0">
<mytag:invokeDynamic a="1" d1="2" mytag:d2="3">
<jsp:attribute name="b">4</jsp:attribute>
<jsp:attribute name="d3">5</jsp:attribute>
<jsp:attribute name="mytag:d4">6</jsp:attribute>
</mytag:invokeDynamic>
</jsp:root>

Dynamic Attributes Syntax

Parent topic: Creating a Tag Library Descriptor

Dynamic Attributes Syntax

For a tag to declare that it accepts dynamic attributes, it must implement the DynamicAttributes interface. The syntax is as follows:

public interface DynamicAttributes

You must also configure an entry for the tag in the TLD to indicate dynamic attributes are accepted. For any attribute that is not declared in the TLD for this tag, instead of getting an error at translation time, the setDynamicAttribute() method is called, with the name and value of the attribute. You configure the tag to remember the names and values of the dynamic attributes.

The setDynamicAttribute() method is called when a tag declared to accept dynamic attributes passes an attribute that is not declared in the TLD. The syntax is as follows:

public void setDynamicAttribute(java.lang.String uri, java.lang.String localName, java.lang.Object value)

The parameter values are as follows:

uri - the namespace of the attribute, or null if in the default namespace.
localName - the name of the attribute being set.
value - the value of the attribute.

A JspException is thrown if the tag handler signals that it does not accept the given attribute. The container must not call doStartTag() or doTag() for this tag.

See the DynamicAttributes API at http://docs.oracle.com/javaee/7/api/javax/servlet/jsp/tagext/DynamicAttributes.html for more information about these interfaces.

Parent topic: Dynamic Attributes Example