Registering a Custom Renderer with a Render Kit

For every UI component that a render kit supports, the render kit defines a set of Renderer objects that can render the component in different ways to the client supported by the render kit. For example, the standard UISelectOne component class defines a component that allows a user to select one item from a group of items. This component can be rendered using the Listbox renderer, the Menu renderer, or the Radio renderer. Each renderer produces a different appearance for the component. The Listbox renderer renders a menu that can display an entire set of values. The Menu renderer renders a subset of all possible values. The Radio renderer renders a set of radio buttons.

When the application developer creates a custom renderer, as described in Delegating Rendering to a Renderer, you must register it using the appropriate render kit. Because the image map application implements an HTML image map, AreaRenderer (as well as MapRenderer) should be registered using the HTML render kit.

You register the renderer using the render-kit element of the application configuration resource file. Here is the configuration of AreaRenderer from the Duke's Bookstore application:

<render-kit>
  <renderer>
    <component-family>Area</component-family>
    <renderer-type>DemoArea</renderer-type>
    <renderer-class>
      renderers.AreaRenderer
    </renderer-class>
    <attribute>
      <attribute-name>onmouseout</attribute-name>
      <attribute-class>java.lang.String</attribute-class>
    </attribute>
    <attribute>
      <attribute-name>onmouseover</attribute-name>
      <attribute-class>java.lang.String</attribute-class>
    </attribute>
    <attribute>
      <attribute-name>styleClass</attribute-name>
      <attribute-class>java.lang.String</attribute-class>
    </attribute>
  </renderer>
  ...

The render-kit element represents a RenderKit implementation. If no render-kit-id is specified, the default HTML render kit is assumed. The renderer element represents a Renderer implementation. By nesting the renderer element inside the render-kit element, you are registering the renderer with the RenderKit associated with the render-kit element.

The component-family and renderer-type elements are used by a component to find renderers that can render it. The component-family identifier must match that returned by the component class's getFamily method. The renderer-type identifier must match that returned by the getRendererType method of the tag handler class. The component's configuration also needs to specify the component family and renderer type, which the next section explains.

Each of the attribute tags specifies a render-dependent attribute and its type. The attribute element doesn't affect the runtime execution of your application. Instead, it provides information to tools about the attributes the Renderer supports.

The object that is responsible for rendering a component (be it the component itself or a renderer to which the component delegates the rendering) can use facets to aid in the rendering process. These facets allow the custom component developer to control some aspects of rendering the component. Consider this custom component tag example:

<d:dataScroller>
  <f:facet name="header">
    <h:panelGroup>
      <h:outputText value="Account Id"/>
      <h:outputText value="Customer Name"/>
      <h:outputText value="Total Sales"/>
    </h:panelGroup>
  </f:facet>
  <f:facet name="next">
    <h:panelGroup>
      <h:outputText value="Next"/>
      <h:graphicImage url="/images/arrow-right.gif" />
    </h:panelGroup>
  </f:facet>
    ...
</d:dataScroller>

The dataScroller component tag includes a component that will render the header and a component that will render the Next button. If the renderer associated with this component renders the facets you can include the following facet elements in the renderer element:

<facet>
  <description>This facet renders as the 
    header of the table. It should be a panelGroup 
    with the same number of columns as the data
  </description>
  <display-name>header</display-name>
  <facet-name>header</facet-name>
</facet> 
<facet>
  <description>This facet renders as the content 
    of the "next" button in the scroller. It should be a 
    panelGroup that includes an outputText tag that 
    has the text "Next" and a right arrow icon.
  </description> 
  <display-name>Next</display-name>
  <facet-name>next</facet-name>
</facet>

If a component that supports facets provides its own rendering and you want to include facet elements in the application configuration resource file, you need to put them in the component's configuration rather than the renderer's configuration.