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

> ## Understanding the Image Map Example

> Duke's Bookstore includes a custom image map component on the `chooselocale.jsp` page. This image map displays a map of the world. When the user clicks on one of a particular set of regions in the map, the application sets the locale on the `UIViewRoot` component of the current `FacesContext` to the language spoken in the selected region. The hotspots of the map are the United States, Spanish-speaking Central and South America, France, and Germany.

> ### Why Use JavaServer Faces Technology to Implement an Image Map?

> JavaServer Faces technology is an ideal framework to use for implementing this kind of image map because it can perform the work that must be done on the server without requiring you to create a server-side image map.

> In general, client-side image maps are preferred over server-side image maps for several reasons. One reason is that the client-side image map allows the browser to provide immediate feedback when a user positions the mouse over a hotspot. Another reason is that client-side image maps perform better because they don't require round-trips to the server. However, in some situations, your image map might need to access the server to retrieve data or to change the appearance of nonform controls, tasks that a client-side image map cannot do.

> Because the image map custom component uses JavaServer Faces technology, it has the best of both styles of image maps: It can handle the parts of the application that need to be performed on the server, while allowing the other parts of the application to be performed on the client side.

> ### Understanding the Rendered HTML

> Here is an abbreviated version of the form part of the HTML page that the application needs to render:

>     <form id="_id38" method="post"
>       action="/bookstore6/chooselocale.faces" ... >
>       ...
>       <img id="_id38:mapImage"
>         src="/bookstore6/template/world.jpg"
>         alt="Choose Your Preferred Locale from the Map"
>         usemap="#worldMap" />
>         <map name="worldMap">
>           <area alt="NAmerica"
>             coords="53,109,1,110,2,167,,..."
>             shape="poly"
>             onmouseout=
>               "document.forms[0]['_id_id38:mapImage'].src=
>                 '/bookstore6/template/world.jpg'"
>             onmouseover=
>               "document.forms[0]['_id_id38:mapImage'].src=
>                 '/bookstore6/template/world_namer.jpg'"
>             onclick=
>               "document.forms[0]['worldMap_current'].
>                 value=
>                   'NAmerica';document.forms[0].submit()"
>           />
>           <input type="hidden" name="worldMap_current">
>         </map>
>         ...
>     </form>

> The `img` tag associates an image (`world.jpg`) with the image map referenced in the `usemap` attribute value.

> The `map` tag specifies the image map and contains a set of `area` tags.

> Each a`rea` tag specifies a region of the image map. 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. If the user clicks on a region, the `onclick` function sets the value of the `input` tag to the ID of the selected area and submits the page.

> The `input` tag represents a hidden control that stores the value of the currently selected area between client-server exchanges so that the server-side component classes can retrieve the value.

> The server-side objects retrieve the value of `worldMap_current` and set the locale in the `FacesContext` instance according to the region that was selected.

> ### Understanding the JSP Page

> Here is an abbreviated form of the JSP page that the image map component will use to generate the HTML page shown in the preceding section:

>     <f:view>
>       <f:loadBundle basename="messages.BookstoreMessages"
>         var="bundle"/>
>       <h:form>
>         ...
>         <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="SAmerica" value="#{SA}"
>             onmouseover="/template/world_samer.jpg"
>             onmouseout="/template/world.jpg"
>             targetImage="mapImage" />
>           <bookstore:area id="Germany" value="#{gerA}"
>             onmouseover="/template/world_germany.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>
>         ...
>       </h:form>
>     </f:view>

> The `alt` attribute of `graphicImage` maps to the localized string `"Choose Your Locale from the Map"`.

> The `actionListener` attribute of the `map` tag points at a method in `LocaleBean` that accepts an action event. This method changes the locale according to the area selected from the image map. The way this event is handled is explained more in Handling Events for Custom Components.

> The `action` attribute specifies a logical outcome `String`, which is matched against the navigation rules in the application configuration resource file. For more information on navigation, see the section Configuring Navigation Rules (page 465).

> The `immediate` attribute of the `map` tag is set to `true`, which indicates that the default `ActionListener` implementation should execute during the apply request values phase of the request-processing life cycle, instead of waiting for the invoke application phase. Because the request resulting from clicking the map does not require any validation, data conversion, or server-side object updates, it makes sense to skip directly to the invoke application phase.

> The `current` attribute of the `map` tag is set to the default area, which is `NAmerica`.

> Notice that the `area` tags do not contain any of the JavaScript, coordinate, or shape data that is displayed on the HTML page. The JavaScript is generated by the `AreaRenderer` class. The `onmouseover` and `onmouseout` attribute values indicate the image to be loaded when these events occur. How the JavaScript is generated is explained more in Performing Encoding.

> The coordinate, shape, and alternate text data are obtained through the `value` attribute, whose value refers to an attribute in application scope. The value of this attribute is a bean, which stores the coordinate, shape, and alt data. How these beans are stored in the application scope is explained more in the next section.

> ### Configuring Model Data

> In a JavaServer Faces application, data such as the coordinates of a hotspot of an image map is retrieved from the `value` attribute via a bean. However, the shape and coordinates of a hotspot should be defined together because the coordinates are interpreted differently depending on what shape the hotspot is. Because a component's value can be bound only to one property, the `value` attribute cannot refer to both the shape and the coordinates.

> To solve this problem, the application encapsulates all of this information in a set of `ImageArea` objects. These objects are initialized into application scope by the managed bean creation facility (see Backing Beans, page 295). Here is part of the managed bean declaration for the `ImageArea` bean corresponding to the South America hotspot:

>     <managed-bean>
>       ...
>       <managed-bean-name>SA</managed-bean-name>
>       <managed-bean-class>
>         components.model.ImageArea
>       </managed-bean-class>
>       <managed-bean-scope>application</managed-bean-scope>
>       <managed-property>
>         <property-name>shape</property-name>
>         <value>poly</value>
>       </managed-property>
>       <managed-property>
>         <property-name>alt</property-name>
>         <value>SAmerica</value>
>       </managed-property>
>       <managed-property>
>         <property-name>coords</property-name>
>         <value>89,217,95,100...</value>
>       </managed-property>
>     </managed-bean>

> For more information on initializing managed beans with the managed bean creation facility, see the section Application Configuration Resource File (page 450).

> The `value` attributes of the `area` tags refer to the beans in the application scope, as shown in this `area` tag from `chooselocale.jsp`:

>     <bookstore:area id="NAmerica"
>         value="#{NA}"
>         onmouseover="/template/world_namer.jpg"
>         onmouseout="/template/world.jpg" />

> To reference the `ImageArea` model object bean values from the component class, you implement a `getValue` method in the component class. This method calls `super.getValue`. The superclass of `AreaComponent`, `UIOutput`, has a `getValue` method that does the work of finding the `ImageArea` object associated with `AreaComponent`. The `AreaRenderer` class, which needs to render the alt, shape, and coords values from the `ImageArea` object, calls the `getValue` method of `AreaComponent` to retrieve the `ImageArea` object.

>     ImageArea iarea = (ImageArea) area.getValue();

> `ImageArea` is only a simple bean, so you can access the shape, coordinates, and alternative text values by calling the appropriate accessor methods of `ImageArea`. Creating the Renderer Class explains how to do this in the `AreaRenderer` class.

> ### Summary of the Application Classes

> Table 12-2 summarizes all the classes needed to implement the image map component.

> Table 12-2 Image Map Classes
> Class | Function
> --- | ---
> AreaSelectedEvent | The `ActionEvent` indicating that an `AreaComponent` from the `MapComponent` has been selected.
> `AreaTag` | The tag handler that implements the `area` custom tag.
> `MapTag` | The tag handler that implements the `map` custom tag.
> `AreaComponent` | The class that defines `AreaComponent`, which corresponds to the `area` custom tag.
> `MapComponent` | The class that defines `MapComponent`, which corresponds to the `map` custom tag.
> `AreaRenderer` | This `Renderer` performs the delegated rendering for `AreaComponent`.
> `ImageArea` | The bean that stores the shape and coordinates of the hotspots.
> LocaleBean | The backing bean for the `chooselocale.jsp` page.

> The event and listener classes are located in `<INSTALL>``/javaeetutorial5/examples/web/bookstore6/src/listeners`. The tag handlers are located in `<INSTALL>``/javaeetutorial5/examples/web/bookstore6/src/taglib/`. The component classes are located in `<INSTALL>``/javaeetutorial5/examples/web/bookstore6/src/components/`. The renderer classes are located in `<INSTALL>``/javaeetutorial5/examples/web/bookstore6/src/renderers/`. `ImageArea` is located in `<INSTALL>``/javaeetutorial5/examples/web/bookstore6/src/model/`. `LocaleBean` is located in `<INSTALL>``/javaeetutorial5/examples/web/bookstore6/src/backing/`.