Defining the Custom Component Tag in a Tag Library Descriptor
To use a custom tag, you declare it in a Tag Library Descriptor (TLD). The TLD file defines how the custom tag is used in a JavaServer Faces page. 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, available at http://docs.oracle.com/javaee/6/javaserverfaces/2.1/docs/renderkitdocs/.
The TLD file name must end with taglib.xml. In the Duke's Bookstore case study, the custom tags area and map are defined in the file web/WEB-INF/bookstore.taglib.xml.
All tag definitions must be nested inside the facelet-taglib element in the TLD. Each tag is defined by a tag element that specifies a particular combination of a component type and a renderer type. Here are the tag definitions for the area and map components:
<facelet-taglib xmlns="http://java.sun.com/xml/ns/javaee" ... > <namespace>http://dukesbookstore</namespace> <tag> <tag-name>area</tag-name> <component> <component-type>DemoArea</component-type> <renderer-type>DemoArea</renderer-type> </component> </tag> <tag> <tag-name>map</tag-name> <component> <component-type>DemoMap</component-type> <renderer-type>DemoMap</renderer-type> </component> </tag> </facelet-taglib>
The component-type element specifies the name defined in the @FacesComponent annotation, while the renderer-type element specifies the rendererType defined in the @FacesRenderer annotation.
The facelet-taglib element must also include a namespace element, which defines the namespace to be specified in pages that use the custom component. See Using a Custom Component for information on specifying the namespace in pages.
The TLD file is located in the WEB-INF directory. In addition, an entry is included in the web deployment descriptor (web.xml) to identify the custom tag library descriptor file, as follows:
<context-param> <param-name>javax.faces.FACELETS_LIBRARIES</param-name> <param-value>/WEB-INF/bookstore.taglib.xml</param-value> </context-param>