Text With Image custom builder
This is an example of a simple “control” builder that adds a couple of elements to the specified page location. It also shows how a custom builder can be automatically applied to data fields using a Rich Data Definition library along with the Data Field Settings builder.
This builder adds these elements:
- Some text (typically an indirect reference to some element of a data structure).
- An image such as an icon.
It also optionally calls the Visibility Setter builder so that the image is hidden when the text value is null. The customer use case was for displaying a phone number with a little phone icon, and when the phone number is null the icon should not be displayed. For example in this screenshot there are three phone number fields, but the third “Mobile Phone” field is null, so the phone icon is not displayed.
In a list/table view, the icon is hidden based on the value in that row, as shown below.
The builder is shown here.
Now, using that builder on its own may be slightly useful, but the real value comes when it's referenced via a Rich Data Definition (RDD) base library and used with Data Field Settings.
Using a builder as a “rendering builder” with Data Field Settings
The real value of a builder like this comes when it's used as a “rendering builder” which is automatically applied to data fields via the Page Automation system. Any control builder can be used as a rendering builder if:
- It uses a builder input “PageLocation” to define where it generates UI.
- It uses a builder input named “Value” for the value it is displaying/updating.
- Any other required builder inputs can be defined via XML settings in an RDD file.
To add a rendering builder to a base RDD file, you can use the “DisplayControl” or “DataEntryControl” elements in the base RDD file. This is documented here:
http://infolib.lotus.com/resources/portletfactory/8.0.0/WEF80ABD003/en_us/wef.8.0.0.html-wrapper.html#r_data_def_props
Here is the relevant section of the RDD base library in the sample package. Notice that the “HideIfNull” input is set and the ImageFile” input refers to the phone GIF file.
"base_PhoneWithImage"
com.ibm.samples.builders.TextWithImageBuilder
Phone With Image
"HideIfNull"
true
"ImageFile"
/samples/demos/images/phone_16.gif
Once this is done, you can apply the builder to any of your data fields using the Data Field Settings builder as shown here. Notice how the “Phone With Image” field type is offered along with all the standard field types.
Sample files:
- TextWithImageBuilder.bdef – the BuilderDef file for the builder (this was created using the Builder Skeleton builder).
- TextWithImageBuilder.java – the builder's regen class.
- sample_base_datadef.xml – the base RDD file where the “Phone With Image” field type is defined.
- CustomerInfoService.model – the simple provider model using XML data from a Variable.
- CustomerInfo1.model – this shows how the icon would be applied without the custom builder, using Image and Visibility Setter builders.
- CustomerInfo2.model – this shows how the custom builder can be manually applied to data fields (this is not the recommended approach).
- CustomerInfo3.model – this shows the recommended approach for using the custom builder. The custom builder is used in a base field type in the RDD library, and it's applied to three fields (on all pages) using the Data Field Settings builder.