Home | Download | PDF | API | FAQ | Search | Feedback | History

> ## 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 in one of the following ways:

> - Reference the converter from the component tag's `converter` attribute
> - Nest a `converter` tag inside the component's tag and reference the custom converter from one of the `converter` tag's attributes.

> A custom validator is applied to a component in one of the following ways:

> - Nest a `validator` tag inside the component's tag and reference the custom validator from the `validator` tag.
> - Nest the validator's custom tag (if there is one) inside the component's tag.

> To use a custom component, you add the custom tag associated with the component to the page.

> As explained in Setting Up a Page, you must ensure that the TLD that defines any custom tags is packaged in the application if you intend to use the tags in your pages. 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 file.

> You also need to 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

> As described in the previous section, to apply the data conversion performed by a custom converter to a particular component's value, you must either reference the custom converter from the component tag's `converter` attribute or from a `converter` tag nested inside the component tag.

> If you are using the component tag's `converter` attribute, this attribute must reference the `Converter` implementation's identifier or the fully-qualified class name of the converter. The application architect provides this identifier when registering the `Converter` implementation with the application, as explained in Registering a Custom Converter (page 464). Creating a Custom Converter (page 396) 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 or its class name, you cause that component's local value to be automatically converted according to the rules specified in the `Converter` implementation.

> Instead of referencing the converter from the component tag's `converter` attribute, you can reference the converter from a `converter` tag nested inside the component's tag. To reference the custom converter using the `converter` tag, you do one of the following:

> - Set the `converter` tag's `converterId` attribute to the `Converter` implementation's identifier defined in the application configuration file.
> - Bind the `Converter` implementation to a backing bean property using the `converter` tag's `binding` attribute, as described in Binding Converters, Listeners, and Validators to Backing Bean Properties.

> ### Using a Custom Validator

> To register a custom validator on a component, you must do one of the following:

> - Nest the validator's custom tag inside the tag of the component whose value you want to be validated.
> - Nest the standard `validator` tag within the tag of the component and reference the custom `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 (page 401) 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.

> In this case, the page author must nest the `validator` tag inside the tag of the component whose data needs to be validated. Then the page author needs to do one of the following:

> 1. 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 (page 463) explains how to configure the validator in the application configuration resource file.
> 2. Bind the custom `Validator` implementation to a backing bean property using the `validator` tag's `binding` attribute, as described in Binding Converters, Listeners, and Validators to Backing Bean Properties.

> The following tag registers a hypothetical validator on a component using a `validator` tag and references 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, as explained in Using Custom Objects, and you add the component's tag to the page.

> 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 standard `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 specify 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 12 describes the custom tags in more detail and also explains how to create the custom image map components, renderers, and tags.