Defining the Renderer Class

The Cúram Renderer API defines the DomainRenderer interface that is used when writing renderer plug-in classes, such as for the e-mail address widget. A plug-in class has a render method that is provided with details of the field to be rendered and the method must retrieve the data bound to that field and add the HTML mark-up to that data.

The developer must not implement the DomainRenderer interface directly. Instead, the OOTB application provides abstract base classes that the developer must use as the base of any custom renderer plug-in class. The e-mail address widget produces a read-only value, so it will be presented using a view-renderer plug-in based on the AbstractViewRenderer class. The developer should place the EMailAddressViewRenderer.java source file in the sample package sub-folder of the javasource folder of the client application component.

public class EMailAddressViewRenderer
       extends AbstractViewRenderer {

  public void render(
        Field field, DocumentFragment fragment,
        RendererContext context, RendererContract contract)
        throws ClientException, DataAccessException,
               PlugInException {
    // Create the HTML here....
  }
}

A renderer plug-in class uses the W3C DOM Level 3 Core API to create the HTML content. This API is a standard component of the Java Runtime Environment for Java 5 and above. It is documented in the Javadoc supplied for the corresponding JDK. For further information about this API, refer to that documentation.

The first argument to the render method is a Field object that represents the details of the UIM FIELD element to be rendered and the data bound to it by its connections.

The second argument is a DOM DocumentFragment node. The goal of the render method is to append DOM nodes representing the data and its HTML mark-up to this fragment. The system will automatically serialize these nodes to HTML in string form and include this in the HTML stream for the page that is returned to the web browser.

The third argument is a RendererContext object. This object provides access to the context in which a renderer is invoked. It includes facilities to delegate rendering to other renderers, to resolve the data identified by the paths associated with a Field object, to include JavaScript resources in the page that can be shared with other renderers, and other facilities that are elaborated upon in the API documentation.

Use of the RendererContract argument to the render method is not supported except in the limited manner described later in this guide.

See the Cúram Javadoc for full details on each of these arguments and their interface types.