Friday, April 27, 2007

Creating a custom component

The primary responsibility of a component is to decode and encode data.
encode = convert request parameters to component attributes
decode = render component attributes to the view (render html mostly...)

The rendering can be directly implemented by the component or can be delegated to a renderer. We use a special renderer(s) when we want different types of rendering for that component (maybe for different display devices).

So a JSF component has 2 parts: the component + renderer

Image by Rick Hightower explaining on where rendering fits in the JSF lifecycle - Ref

All custom components have to be subclasses of UIComponent. However, we subclass UICOmponentBase which is an abstract class that gives us a skeletal implementation of UIComponent.

Creating the custom component:
As an exercise, I will create a simple custom component that renders a 5x5 grid (as an html table). Here are the steps:
  1. Create a subclass of UIComponent (I chose UIOutput, since this is an output only component, ie. we do not modify the component from the view). This class does not have any properties at the moment, since the component is a simple display component that spits out a simple table. Since we do not have any properties I have not overriden the methods for saving and restoring state. Overriding encodeEnd() and decode() and returning null from them.
  2. Implemented LabelComponentTag as a subclass of UIComponentTag. The responsibility of this class is to return the component_family and component_renderer.
  3. Wrote the TLD file defining the spanningTable tag
My custom component is throwing a NullPointerException. This is because the server was not able to locate the projects tld file. When the app reads the JSP pages, it will try to locate and load all referenced tld files. Our JSP pages, declare tags with their corresponding URI's, and web.xml maps the URI's to tld files. The app gets the tld file names from web.xml, and loads the files. When a tag needs to be rendered, the server looks up the tld file to validate the tag, and if valid it gets the UIComponentTag subclass for this tag. This files in turn tells the server the name of the JSF component. This name is mapped to an actual class in faces-config.xml. That's how the server loads the component class (some subclass of UIComponent).

Anyways, so far my problem was an improperly named tld file in web.xml.
Fixed the problem, and got the simple table exercise to run.

This seems to be the order in which various methods of the Tag class, Component class, and Backing Bean are invoked.
  1. The Tag class is instantiated
  2. Properties specified in the JSP page for that tag are set in the Tag class
  3. The runtime tries to get the type of the component by invoking the getComponentType() method of the Tag class
  4. The runtime looks in faces-config.xml (it must be looking elsewhere also because core components are not defined in faces-config.xml) to see if a component has been defined with that type (nexted tag, in the tag). It gets the fully qualified class name of the component
  5. The component is instantiated
  6. The Tag class' setProperties() method is invoked. This method is responsible for setting properties from the Tag class to the component class. Not all properties in the Tag class will have corresponding properties in the component class. Some may in which case, they will be set directly (or after some conversions). Some properties may be set in the attributes Map of the component. These properties are usually those that will not be needed directly by the component but will be used by other classes such as the Renderer. Some properties may be bound to the backing bean. These properties are saved in the component using ValueBindings (The ValueBinding class interprets the JSF-EL and figures out the property of the backing bean we want to bind to).
  7. The component is Rendered by either invoking encodeBegin() or by invoking a custom Renderer. Here we may use properties from the backing bean. We can retrieve them by using the ValueBinding object.
  8. The save of the component is saved after rendering is complete.

No comments: