15.7 Handling Events for Custom Components

As explained in Implementing an Event Listener, events are automatically queued on standard components that fire events. A custom component, on the other hand, must manually queue events from its decode method if it fires events.

Performing Decoding explains how to queue an event on MapComponent using its decode method. This section explains how to write the class that represents the event of clicking on the map and how to write the method that processes this event.

As explained in Understanding the Facelets Page, the actionListener attribute of the bookstore:map tag points to the MapBookChangeListener class. The listener class's processAction method processes the event of clicking the image map. Here is the processAction method:

@Override
public void processAction(ActionEvent actionEvent)
        throws AbortProcessingException {

    AreaSelectedEvent event = (AreaSelectedEvent) actionEvent;
    String current = event.getMapComponent().getCurrent();
    FacesContext context = FacesContext.getCurrentInstance();
    String bookId = books.get(current);
    context.getExternalContext().getSessionMap().put("bookId", bookId);
}

When the JavaServer Faces implementation calls this method, it passes in an ActionEvent object that represents the event generated by clicking on the image map. Next, it casts it to an AreaSelectedEvent object (see tut-install/examples/case-studies/dukes-bookstore/src/java/dukesbookstore/listeners/AreaSelectedEvent.java). Then this method gets the MapComponent associated with the event. Next, it gets the value of the MapComponent object's current attribute, which indicates the currently selected area. The method then uses the value of the current attribute to get the book's ID value from a HashMap object, which is constructed elsewhere in the MapBookChangeListener class. Finally, the method places the ID obtained from the HashMap object into the session map for the application.

In addition to the method that processes the event, you need the event class itself. This class is very simple to write; you have it extend ActionEvent and provide a constructor that takes the component on which the event is queued and a method that returns the component. Here is the AreaSelectedEvent class used with the image map:

public class AreaSelectedEvent extends ActionEvent {
    public AreaSelectedEvent(MapComponent map) {
        super(map);
    }
    public MapComponent getMapComponent() {
        return ((MapComponent) getComponent());
    }
}

As explained in the section Creating Custom Component Classes, in order for MapComponent to fire events in the first place, it must implement ActionSource. Because MapComponent extends UICommand, it also implements ActionSource.