Using Custom Objects - The J2EE 1.4 Tutorial

Using Custom Objects

As a page author, you might need to use custom converters, validators, or components packaged with the application on your JSP pages.

A custom converter is applied to a component either by using the component tag's converter attribute or by nesting a converter tag inside the component's tag.

A custom validator is applied to a component by nesting either a validator tag or the validator's custom tag inside the component's tag.

To use a custom component, you use the custom tag associated with the component.

As explained in Setting Up a Page, you must ensure that the TLD that defines the custom tags is packaged in the application. TLD files are stored in the WEB-INF directory or subdirectory of the WAR file or in the META-INF/ directory or subdirectory of a tag library packaged in a JAR.

Next, you include a taglib declaration in the page so that the page has access to the tags. All custom objects for the Duke's Bookstore application are defined in bookstore.tld. Here is the taglib declaration that you would include on your page so that you can use the tags from this TLD:
<%@ taglib uri="/WEB-INF/bookstore.tld" prefix="bookstore" %> 
When including the custom tag in the page, you can consult the TLD to determine which attributes the tag supports and how they are used.

The next three sections describe how to use the custom converter, validator, and UI components included in the Duke's Bookstore application.

Using a Custom Converter

To apply the data conversion performed by a custom converter to a particular component's value, you must either set the converter attribute of the component's tag to the Converter implementation's identifier or set the nested converter tag's converterId attribute to the Converter implementation's identifier. The application architect provides this identifier when registering the Converter implementation with the application, as explained in Registering a Custom Converter. Creating a Custom Converter explains how a custom converter is implemented.

The identifier for the credit card converter is CreditCardConverter. The CreditCardConverter instance is registered on the ccno component, as shown in this tag from the bookcashier.jsp page:
<h:inputText id="ccno"
  size="19"
  converter="CreditCardConverter"
  required="true">
  ...
</h:inputText> 
By setting the converter attribute of a component's tag to the converter's identifier, you cause that component's local value to be automatically converted according to the rules specified in the Converter implementation.

A page author can use the same custom converter with any similar component by simply supplying the Converter implementation's identifier to the converter attribute of the component's tag or to the convertId attribute of a nested converter tag.

Using a Custom Validator

To use a custom validator in a JSP page, you must either

Nest the validator's custom tag inside the tag of the component whose value you want to be validated by the custom validator.

Nest a validator tag within the tag of the component and reference the Validator implementation from the validator tag.

Here is the custom formatValidator tag from the ccno field on the bookcashier.jsp page of the Duke's Bookstore application:
<h:inputText id="ccno" size="19"
  ...
  required="true">
  <bookstore:formatValidator 
    formatPatterns="9999999999999999|9999 9999 9999 9999|
    9999-9999-9999-9999" />
</h:inputText>
<h:message styleClass="validationMessage"  for="ccno"/>  
This tag validates the input of the ccno field against the patterns defined by the page author in the formatPatterns attribute.

You can use the same custom validator for any similar component by simply nesting the custom validator tag within the component tag.

Creating a Custom Validator describes how to create the custom validator and its custom tag.

If the application developer who created the custom validator prefers to configure the attributes in the Validator implementation rather than allow the page author to configure the attributes from the page, the developer will not create a custom tag for use with the validator. Instead, the page author must follow these steps:

Nest the validator tag inside the tag of the component whose data needs to be validated.

Set the validator tag's validatorId attribute to the ID of the validator that is defined in the application configuration resource file. Registering a Custom Validator explains how to configure the validator in the application configuration resource file.

The following tag registers a hypothetical validator on a component using a validator tag and referencing the ID of the validator:
<h:inputText id="name" value="#{CustomerBean.name}"
      size="10" ... >
  <f:validator validatorId="customValidator" />
  ...
</h:inputText> 
Using a Custom Component

In order to use a custom component in a page, you need to declare the tag library that defines the custom tag that renders the custom component. This is explained in Using Custom Objects.

The Duke's Bookstore application includes a custom image map component on the chooselocale.jsp page. This component allows you to select the locale for the application by clicking on a region of the image map:
...
<h:graphicImage id="mapImage" url="/template/world.jpg"
  alt="#{bundle.chooseLocale}"
  usemap="#worldMap" />
  <bookstore:map id="worldMap" current="NAmericas" 
    immediate="true"
    action="bookstore"
    actionListener="#{localeBean.chooseLocaleFromMap}">
    <bookstore:area id="NAmerica" value="#{NA}" 
      onmouseover="/template/world_namer.jpg" 
      onmouseout="/template/world.jpg"
      targetImage="mapImage" />
    ...
    <bookstore:area id="France" value="#{fraA}"
      onmouseover="/template/world_france.jpg" 
      onmouseout="/template/world.jpg"
      targetImage="mapImage" />
</bookstore:map> 
The graphicImage tag associates an image (world.jpg) with an image map that is referenced in the usemap attribute value.

The custom map tag that represents the custom component, MapComponent, specifies the image map, and contains a set of area tags. Each custom area tag represents a custom AreaComponent and specifies a region of the image map.

On the page, the onmouseover and onmouseout attributes define the image that is displayed when the user performs the actions described by the attributes. The page author defines what these images are. The custom renderer also renders an onclick attribute.

In the rendered HTML page, the onmouseover, onmouseout, and onclick attributes define which JavaScript code is executed when these events occur. When the user moves the mouse over a region, the onmouseover function associated with the region displays the map with that region highlighted. When the user moves the mouse out of a region, the onmouseout function redisplays the original image. When the user clicks a region, the onclick function sets the value of a hidden input tag to the ID of the selected area and submits the page.

When the custom renderer renders these attributes in HTML, it also renders the JavaScript code. The custom renderer also renders the entire onclick attribute rather than let the page author set it.

The custom renderer that renders the map tag also renders a hidden input component that holds the current area. The server-side objects retrieve the value of the hidden input field and set the locale in the FacesContext instance according to which region was selected.

Chapter 20 describes the custom tags in more detail and also explains how to create the custom image map components, renderers, and tags.