Download FAQ History |  | API Search Feedback

> ## Determining if You Need a Custom Component or Renderer

> The JavaServer Faces implementation already supports a rich set of components and associated renderers, which are enough for most simple applications. This section helps you decide if you need a custom component or custom renderer or if you can use a standard component and renderer.

> ### When to Use a Custom Component

> A component class defines the state and behavior of a UI component. This behavior includes: converting the value of a component to the appropriate markup, queuing events on components, performing validation, and other functionality.

> Situations in which you need to create a custom component include:

> - If you need to add new behavior to a standard component, such as generating an additional type of event.
> - If you need to aggregate components to create a new component that has its own unique behavior. The new component must be a custom component. One example is a datechooser component consisting of three drop-down lists.
> - If you need a component that is supported by an HTML client, but is not currently implemented by JavaServer Faces technology. The current release does not contain standard components for complex HTML components, like frames; however, because of the extensibility of the component architecture, you can use JavaServer Faces technology to create components like this.
> - If you need to render to a non-HTML client, which requires extra components not supported by HTML. Eventually, the standard HTML render kit will provide support for all standard HTML components. However, if you are rendering to a different client--such as a phone--you might need to create custom components to represent the controls uniquely supported by the client. For example, the MIDP component architecture includes support for tickers and progress bars, which are not available on an HTML client. In this case, you might also need a custom renderer along with the component; or, you might just need a custom renderer.

> You do not need to create a custom component if:

> - You need to simply manipulate data on the component or add application-specific functionality to it. In this situation, you should create a model object for this purpose and bind it to the standard component rather than create a custom component. See Writing a Model Object Class for more information on creating a model object.
> - You need to convert a component's data to a type not supported by its renderer. See Performing Data Conversions for more information about converting a component's data.
> - You need to perform validation on the component data. Both standard validators and custom validators can be added to a component by using the validator tags from the page. See Performing Validation for more information about validating a component's data.
> - You need to register event listeners on components. You can register event listeners on components with the `valuechanged_event` and `action_listener` tags. See Handling Events for more information on using these tags.

> ### When to Use a Custom Renderer

> If you are creating a custom component, you need to ensure--among other things--that your component class performs these operations:

> - Decoding: converting the incoming request parameters to the local value of the component.
> - Encoding: converting the current local value of the component into the corresponding markup that represents it in the response.

> The JavaServer Faces specification supports two programming models for handling encoding and decoding:

> - Direct implementation: The component class itself implements the decoding and encoding.
> - Delegated implementation: The component class delegates the implementation of encoding and decoding to a separate renderer

> By delegating the operations to the renderer, you have the option of associating your custom component with different renderers so that you can represent the component in different ways on the page. If you don't plan to render a particular component in different ways, it's simpler to let the component class handle the rendering.

> If you aren't sure if you will need the flexibility offered by separate renderers, but want to use the simpler direct implementation approach, you can actually use both models. Your component class can include some default rendering code, but it can delegate rendering to a renderer if there is one.

> ### Component, Renderer, and Tag Combinations

> When you create a custom component, you will usually create a custom renderer to go with it. You will also need a custom tag to associate the component with the renderer and to reference the component from the page.

> In rare situations, however, you might use a custom renderer with a standard component rather than a custom component. Or, you might use a custom tag without a renderer or a component. This section gives examples of these situations and provides a summary of what's required for a custom component, renderer, and tag.

> One example of using a custom renderer without a custom component is when you want to add some client-side validation on a standard component. You would implement the validation code with a client-side scripting language, such as JavaScript. You render the JavaScript with the custom renderer. In this situation, you will need a custom tag to go with the renderer so that its tag handler can register the renderer on the standard component.

> Both custom components and custom renderers need custom tags associated with them. However, you can have a custom tag without a custom renderer or custom component. One example is when you need to create a custom validator that requires extra attributes on the validator tag. In this case, the custom tag corresponds to a custom validator, not to a custom component or custom renderer. In any case, you still need to associate the custom tag with a server-side object.

> Table 22-1 summarizes what you must or can associate with a custom component, custom renderer, or custom tag.

> Table 22-1 Requirements for Custom Components, Custom Renderers, and Custom Tags
> | Must have | Can have
> --- | --- | ---
> custom component | custom tag | custom renderer
> custom renderer | custom tag | custom component or standard component
> custom JavaServer Faces tag | some server-side object, like a component, a custom renderer, or custom validator | custom component or standard component associated with a custom renderer

Download FAQ History |  | API Search Feedback

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.