Using Custom Objects

Using a Custom Converter

Using a Custom Validator

Using a Custom Component

Using Custom Objects

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

A custom converter is applied to a component in one of the followingways:

• Reference the converter from the component tag’sconverter attribute.

• Nest aconverter tag inside the component’s tag and reference the custom converter from one of theconverter tag’s attributes.

A custom validator is applied to a component in one of thefollowing ways:

• Nest avalidator tag inside the component’s tag and reference the custom validator from thevalidator 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 thecomponent to the page.

As explained inSetting Up a Page, you must ensure that the TLD that defines anycustom tags is packaged in the application if you intend to use thetags in your pages. TLD files are stored in theWEB-INF/ directory orsubdirectory of the WAR file or in theMETA-INF/ directory or subdirectory of atag library packaged in a JAR file.

You also need to include ataglib declaration in the page so thatthe page has access to the tags. All custom objects for the Duke’sBookstore application are defined inbookstore.tld. Here is thetaglib declaration that you wouldinclude on your page so that you can use the tags fromthis TLD:

<%@ taglib uri="/WEB-INF/bookstore.tld" prefix="bookstore" %>

When including the custom tag in the page, you can consult theTLD to determine which attributes the tag supports and how they are used.

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

Using a Custom Converter

As described in the previous section, to apply the data conversion performed bya custom converter to a particular component’s value, you must either reference thecustom converter from the component tag’sconverter attribute or from aconvertertag nested inside the component tag.

If you are using the component tag’sconverter attribute, this attribute must referencetheConverter implementation’s identifier or the fully-qualified class name of the converter. Theapplication architect provides this identifier when registering theConverter implementation with the application, asexplained inRegistering a Custom Converter.Creating a Custom Converter explains how a custom converter is implemented.

The identifier for the credit card converter isCreditCardConverter. TheCreditCardConverter instanceis registered on theccno component, as shown in this tag from thebookcashier.jsp page:

<h:inputText    size="19"    converter="CreditCardConverter"    required="true">    ...</h:inputText>

By setting theconverter attribute of a component’s tag to the converter’sidentifier or its class name, you cause that component’s local value to beautomatically converted according to the rules specified in theConverter implementation.

Instead of referencing the converter from the component tag’sconverter attribute, youcan reference the converter from aconverter tag nested inside the component’stag. To reference the custom converter using theconverter tag, you do oneof the following:

• Set theconverter tag’sconverterId attribute to theConverter implementation’s identifier defined in the application configuration file.

• Bind theConverter implementation to a backing bean property using theconverter tag’sbinding attribute, as described inBinding Converters, Listeners, and Validators to Backing Bean Properties.

Using a Custom Validator

To register a custom validator on a component, you must do one ofthe following:

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

• Nest the standardvalidator tag within the tag of the component and reference the customValidator implementation from thevalidator tag.

Here is the customformatValidator tag from theccno field on thebookcashier.jsp page of the Duke’s Bookstore application:

<h:inputText 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 theccno field against the patterns definedby the page author in theformatPatterns attribute.

You can use the same custom validator for any similar component bysimply 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 theattributes in theValidator implementation rather than allow the page author to configurethe attributes from the page, the developer will not create a custom tagfor use with the validator.

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

1. Set thevalidator tag’svalidatorId 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.

2. Bind the customValidator implementation to a backing bean property using thevalidator tag’sbinding attribute, as described inBinding Converters, Listeners, and Validators to Backing Bean Properties.

The following tag registers a hypothetical validator on a component using avalidatortag and references the ID of the validator:

<h:inputText 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 needto declare the tag library that defines the custom tag that renders thecustom component, as explained inUsing Custom Objects, and you add the component’s tag to thepage.

The Duke’s Bookstore application includes a custom image map component on thechooselocale.jsppage. This component allows you to select the locale for the application byclicking on a region of the image map:

...<h:graphicImage url="/template/world.jpg"    alt="#{bundle.chooseLocale}"    usemap="#worldMap" />    <bookstore:map current="NAmericas"         immediate="true"        action="bookstore"        actionListener="#{localeBean.chooseLocaleFromMap}">        <bookstore:area value="#{NA}"             onmouseover="/template/world_namer.jpg"             onmouseout="/template/world.jpg"            targetImage="mapImage" />        ...        <bookstore:area value="#{fraA}"            onmouseover="/template/world_france.jpg"             onmouseout="/template/world.jpg"            targetImage="mapImage" /></bookstore:map>

The standardgraphicImage tag associates an image (world.jpg) with an image map thatis referenced in theusemap attribute value.

The custommap tag that represents the custom component,MapComponent, specifies theimage map, and contains a set ofarea tags. Each customareatag represents a customAreaComponent and specifies a region of the imagemap.

On the page, theonmouseover andonmouseout attributes specify the image that isdisplayed when the user performs the actions described by the attributes. The pageauthor defines what these images are. The custom renderer also renders anonclickattribute.

In the rendered HTML page, theonmouseover,onmouseout, andonclick attributes definewhich JavaScript code is executed when these events occur. When the user movesthe mouse over a region, theonmouseover function associated with the region displays themap with that region highlighted. When the user moves the mouse out ofa region, theonmouseout function redisplays the original image. When the user clicksa region, theonclick function sets the value of a hiddeninput tagto the ID of the selected area and submits the page.

When the custom renderer renders these attributes in HTML, it also renders theJavaScript code. The custom renderer also renders the entireonclick attribute ratherthan let the page author set it.

The custom renderer that renders themap tag also renders a hiddeninputcomponent that holds the current area. The server-side objects retrieve the value of thehiddeninput field and set the locale in theFacesContext instance accordingto which region was selected.

Chapter 13, Creating Custom UI Components describes the custom tags in more detail and also explains how tocreate the custom image map components, renderers, and tags.

Copyright © 2010, Oracle and/or its affiliates. All rights reserved.Legal Notices