Developing Complex Custom Widgets

There is no clear dividing line between simple widgets and complex widgets. The more control over the presentation that the developer exerts through a custom widget, the more complex the implementation of that widget will become. Some indicators of increased complexity are:

• The value of the field may be more than a simple string or numeric value. For example, the value may be an XML document containing several separate values, such as the data for a bar chart.
• Multiple values may be presented to the user differently from the usual grid layout of a cluster or list. For example, a photograph of a person may be presented with the person's name below the image and with no field label to the side.
• A widget may present information by delegating significant parts of the presentation to the renderer plug-ins of other widgets. For example, in presenting a non-grid layout for the details of a person, the value of the single UIM field may be an XML document containing all of those details. A single widget is invoked by the CDEJ for that XML document value. That widget may then produce the non-grid layout in HTML and, in each position within this layout, delegate the rendering of the values within the XML document to other widgets. This is similar to the way the CDEJ delegates to widgets when rendering the contents of the cells in the grid layout presented by a UIM cluster.

While a UIM FIELD is always required to anchor a custom widget, a UIM page can contain little more than a single FIELD element and leave most of the rendering of the HTML page content to the associated custom widget. (The page title and other surrounding content are still rendered independently of the field.) The ability to place a UIM FIELD element directly within a PAGE element without any CLUSTER or LIST element, is a new feature of the CDEJ. While it allows a widget more control over the layout of the data, this approach should only be used if the presentation requirement is such that it cannot be achieved using only UIM, or using a combination of UIM and one or more simple widgets.

Even if a presentation requirement can be met using only UIM, the developer may prefer to use a custom widget to allow the customization to be applied automatically to many application pages, via the domain definition association, rather than repeat the UIM-only solution on every page that needs it. Where the use of VIM VIEW elements cannot achieve this, a complex custom widget may be necessary.

This guide presents the development of several complex widgets in later chapters. The developer should not assume that because much of the guide is concerned with the development of complex widgets that complex widgets are the preferred approach. On the contrary, much of this guide covers complex widgets because their very complexity requires more explanation. The developer should always opt for the simplest possible approach first and only resort to complex widget development when there are no simple alternatives.