Generating the HTML Content

The same technique, described in previous chapters, of using the DOM API to generate HTML content can be used to output the HTML show earlier in this chapter. The only new concept comes at the point when the HTML for the e-mail address is to be output. The e-mail address widget will be re-used within the details widget to output the HTML required for an e-mail address.

The render method of a widget is usually invoked by directly by the Cúram infrastructure. The parameters provided to the render method are set based on what was specified in UIM. For example, the source path of the Field object's Binding is set based on CONNECT and SOURCE element's used within a FIELD element. To invoke one widget from another it becomes the developer's responsibility to ensure the appropriate widget is invoked and the correct parameters are supplied to it. The code required to do this is as follows:

Figure 1. Invoking the E-Mail Address Widget from the Details Widget

FieldBuilder fb =
      ComponentBuilderFactory.createFieldBuilder();
    fb.setDomain(
      context.getDomain("SAMPLE_EMAIL"));
    fb.setSourcePath(
      field.getBinding().getSourcePath()
                        .extendPath("/details/e-mail"));
    DocumentFragment emailFragment = doc.createDocumentFragment();
    context.render(fb.getComponent(), emailFragment,
                   contract.createSubcontract());
    div.appendChild(emailFragment);

The steps to invoke the e-mail address widget are:

Create a Field component.
A FieldBuilder is required to create a Field. The ComponentBuilderFactory can be used to create a FieldBuilder as shown above. See Overview of the Renderer Component Model for full details.
Set the domain of the Field.
The underlying domain definition of a Field is used to select the appropriate widget. An E-Mail Address Widget showed how the e-mail address widget was associated with the SAMPLE_EMAIL domain definition. This domain definition is set on the Field as shown above.
Set the source path of the Field.
An E-Mail Address Widget chapter showed how the e-mail address widget used it's source path to access the value of the e-mail address. This is normally set based on the CONNECT in UIM. In this case the source path for the widget has to be specified "manually". The details widget has to tell the e-mail address widget where to get its data from. As shown earlier the e-mail address is embedded in the XML document supplied to the details widget. The path extension technique to access XML data, that has been described in previous chapters, can be used to specify the source path for the e-mail address widget.

The setSourcePath method of the FieldBuilder is used to set the source path as shown in the following excerpt from the example above. The source path is the same as used to access other values from the XML document. The difference is that instead of retrieving the value directly in the details widget, it is set as the source path of the e-mail address widget.
```
fb.setSourcePath(
    field.getBinding().getSourcePath()
                      .extendPath("/details/e-mail"));
```
This demonstrates the benefits of the path system to access data. In An E-Mail Address Widget, the e-mail address was retrieved directly from a server interface property. In this chapter the e-mail address is retrieved from an XML document. However the e-mail address widget is identical in both cases. It retrieves its data using a source path and is abstracted from what source path actually resolves to "behind the scenes".
Create a DocumentFragment for the widget content
As shown in previous chapters, he DOM API has been used to create HTML elements and add them to a DocumentFragment, supplied as the fragment parameter to the render method. The DocumentFragment is usually supplied by the Cúram infrastructure. In this case the fragment has to be created using the createDocumentFragment as shown above.
Invoke the e-mail address widget
The e-mail address widget is invoked by calling context.render. The first parameter to the method is a Field. The FieldBuilder was used to set the domain and source path and the Field is retrieved by calling the getComponent method. The second parameter is the DocumentFragment created earlier. The widget will add it's HTML content to this fragment. The final parameter is reserved and should always be set to contract.createSubcontract().
Append HTML generated from e-mail address widget
After the e-mail address widget has been invoked, the DocumentFragment will contain its HTML content. This fragment can be added to the appropriate place in the details widget. In the HTML described earlier the HTML should be added as a child of the div element with the contact-info CSS class.

The first three steps above build up a "component model", in this case a single Field. The remaining steps then render the model as HTML. The Overview of the Renderer Component Model appendix provides more details on the classes and APIs which can be used to build a "component model".