Handling Events for Custom Components

As explained in Handling Events, a standard component queues events automatically on the FacesContext. Custom components on the other hand must manually queue the event from the decode method.

Performing Decoding explained how to write the decode method of UIMap to queue an event on the FacesContext component. This section explains how to write an event handler to handle this event and to register the event handler on the component.

The JavaServer Faces implementation calls the processing methods of any event handlers registered on components and queued on the FacesContext. The UIMap component queues an event on the FacesContext. In the JSP page, the ImageMapEventHandler is registered on map because the action_listener tag is nested within the map tag:

<d:map id="worldMap" currentArea="NAmericas" >
  <f:action_listener type="cardemo.ImageMapEventHandler"/>
  ...
</d:map>

Since ImageMapEventHandler is registered on the map component, the JavaServer Faces implementation calls the ImageMapEventHandler's processAction method when the user clicks on the image map:

public void processAction(ActionEvent event) {
  UIMap map = (UIMap)event.getSource();
  String value = (String) map.getAttribute("currentArea");
  Locale curLocale = (Locale) localeTable.get(value);
  if ( curLocale != null) { 
    FacesContext context = FacesContext.getCurrentInstance();
    context.setLocale(curLocale);
    String treeId = "/Storefront.jsp";
    TreeFactory treeFactory = (TreeFactory)
    FactoryFinder.getFactory(FactoryFinder.TREE_FACTORY);
    Assert.assert_it(null != treeFactory);
    context.setTree(treeFactory.getTree(context,treeId));
  }
}

When the JavaServer Faces implementation calls this method, it passes in an ActionEvent, representing the event generated by clicking on the image map. This method first gets the UIMap component that generated the event by calling event.getSource. From this component, this method gets the currentArea attribute value, which is the ID of the currently-selected area. With this value, this method gets the locale corresponding to the selected area and sets the locale in the FacesContext. The rest of the code sets the component tree in FacesContext to that corresponding to Storefront.jsp, causing Storefront.jsp to load after the user clicks the image map.

It is possible to implement event-handling code in the custom component class instead of in an event handler if the component receives application events. This component class must subclass UIComponentBase. It must also implement the appropriate listener interface. This scenario allows an application developer to create a component that registers itself as a listener so that the page author doesn't need to register it.