The Java EE 5 Tutorial

Defining the Custom Component Tag in a Tag Library Descriptor

To define a tag, you declare it in a TLD. The web container uses the TLD to validate the tag. The set of tags that are part of the HTML render kit are defined in the html_basic TLD.

The custom tags area and map are defined in bookstore.tld. The bookstore.tld file defines tags for all the custom components and the custom validator tag described in Creating a Custom Tag.

All tag definitions must be nested inside the taglib element in the TLD. Each tag is defined by a tag element. Here is part of the tag definition of the map tag:

<tag>
    <name>map</name>
    <tag-class>taglib.MapTag</tag-class>
    <attribute>
        <name>binding</name>
        <required>false</required>
        <deferred-value>
            <type>
                javax.faces.component.UIComponent
            </type>
        </deferred-value>
    </attribute>
    <attribute>
        <name>current</name>
        <required>false</required>
        <deferred-value>
            <type>
                java.lang.String
            </type>
        </deferred-value>
    </attribute>
    ...
    <attribute>
        <name>actionListener</name>
        <required>false</required>
        <deferred-method>
            <method-signature>
                void actionListener(javax.faces.event.ActionEvent)
            </method-signature>
        </deferred-method>
        <type>String</type>
    </attribute>
    ...
</tag>

At a minimum, each tag must have a name (the name of the tag) and a tag-class attribute, which specifies the fully-qualified class name of the tag handler.

Each attribute element defines one of the tag attributes. As described in Defining a Tag Attribute Type, the attribute element must define what kind of value the attribute accepts, which for JavaServer Faces tags is either a deferred value expression or a method expression.

To specify that an attribute accepts a deferred value expression, you define the type that the corresponding component property accepts using a type element nested inside of a deferred-value element, as shown for the binding and current attribute definitions in the preceding code snippet.

To specify that an attribute accepts a method expression, you define the signature of the method that expression references using a method-signature element nested inside a deferred-method element, as shown by the actionListener attribute definition in the preceding code snippet. The actual name of the method is ignored by the runtime.

For more information on defining tags in a TLD, consult the Tag Library Descriptors section of this tutorial.