Creating the Component Tag Handler

If you've created your own JSP custom tags before, creating a component tag and tag handler should be easy for you.

In JavaServer Faces applications, the tag handler class associated with a component drives the Render Response phase of the JavaServer Faces lifecycle. For more information on the JavaServer Faces lifecycle, see The Lifecycle of a JavaServer Faces Page. The first thing that the tag handler does is retrieve the type of the component associated with the tag. Next, it sets the component's attributes to the values given in the page. Finally, it returns the type of the renderer (if there is one) to the JavaServer Faces implementation so that the component's encoding can be performed when the tag is processed.

The image map custom component includes two tag handlers: AreaTag and MapTag. To see how the operations on a JavaServer Faces tag handler are implemented, let's take a look at MapTag:

  public class MapTag extends FacesTag {
    public String currentArea = null;
    public MapTag(){
      super();
    }
    public String getCurrentArea() {
      return currentArea;
    }
    public void setCurrentArea(String area) {
      currentArea = area;
    }
    public void overrideProperties(UIComponent component) {
      super.overrideProperties(component);
      UIMap map = (UIMap) component;
      if(map.getAttribute("currentArea") == null)
        map.setAttribute("currentArea", getCurrentArea());
      } 
      public String getRendererType() { return null; }
      public UIComponent createComponent() {
        return (new UIMap());
      }
    } // end of class

The first thing to notice is that MapTag extends FacesTag, which supports jsp.tagext.Tag functionality as well as JavaServer Faces-specific functionality. FacesTag is the base class for all JavaServer Faces tags that correspond to a component. Tags that need to process their tag bodies should subclass FacesBodyTag instead.

As explained above, the first thing MapTag does is to retrieve the type of the component. This is done with the getComponentType operation,:

  public String getComponentType() {
    return ("Map");
  }

Next, the tag handler sets the component's attribute values to those supplied as tag attributes in the page. The MapTag handler gets the attribute values from the page via JavaBeans properties that correspond to the attributes. UIMap only has one attribute, currentArea. Here is the property used to access the value of currentArea:

  public String currentArea = null;
  ...
  public String getCurrentArea() {return currentArea;}
  public void setCurrentArea(String area) { 
    currentArea = area;
  }

To pass the value of currentArea to the UIMap component, the tag handler implements the overrideProperties method, which calls the UIMap.setAttribute method with the name and value of currentArea attribute:

  public void overrideProperties(UIComponent component) {
    super.overrideProperties(component);
    UIMap map = (UIMap) component;
    if(map.getAttribute("currentArea") == null)
      map.setAttribute("currentArea", getCurrentArea());
  }

Finally, the tag handler provides a renderer type--if there is a renderer associated with the component--to the JavaServer Faces implementation. It does this with the getRendererType method:

  public String getRendererType() {return null;}

Since UIMap does not have a renderer associated with it, this method returns null. In this case, the JavaServer Faces implementation will invoke the encoding methods of UIMap to perform the rendering.