As described in an earlier chapter, the Field object has a Binding property that defines the source path and target path that identify the data that is bound to the field. For a view-renderer, only the source path is set; it can be resolved to get the value to be displayed. For an edit-renderer, the target path is always set, as it determines where the value will go when the form is submitted. However, the source path may or may not be set. If the source path is set, then the resolved value is used as the initial value of the input control. If the source path is not set, then the input control will have no explicit initial value.
When no explicit initial value is defined, an initial value may still be displayed. The UIM FIELD element supports a USE_DEFAULT attribute. If this attribute is set to false, then no default initial value will be displayed in the absence of a source connection. However, if the attribute is set to true, then the default value is determined from a default value domain plug-in. The domain of the targeted server interface property is identified and the associated default value plug-in is invoked to get the default value to be displayed in the input control. If not set, the value of the USE_DEFAULT attribute is assumed to be true.
Default value plug-ins are configured for all domains out-of-the-box in Cúram, but they may be customized. Typically, the default value of a string domain is an empty string, the default value of a numeric domain is zero and the default value of a date or date-time domain is the current date and time. See the Cúram Web Client Reference Manual for more information about default value domain plug-ins and the user of the USE_DEFAULT attribute.
Catering for explicit or default initial values is still not sufficient to determine the correct initial value. When a validation error occurs, the system renders the form again and displays error messages detailing what fields are in error. The values displayed in the HTML input controls in this case are the values entered by the user before submitting the form. Regardless of what initial values where originally shown, the user may have changed any or all of these values. Depending on circumstances, then, the initial value of the HTML input control could be set from the source path, set from a default value plug-in or set by the user. To simplify the handling of these conditions, the RendererContext provides a facility to get the appropriate initial value for a form item.
boolean useDefault = !"false".equalsIgnoreCase(
field.getParameters().get(FieldParameters.USE_DEFAULT));
String value = context.getFormItemInitialValue(
field, useDefault, null);
First, the renderer retrieves the parameters of the field argument. The parameters are a map that associates named parameters with values, all strings. These represent, for the most part, the attributes set on the UIM FIELD element. Where attributes are not set in the UIM and default values for those attributes need to be handled, the renderer must respect this requirement. Above, if the value of the USE_DEFAULT field parameter is anything other than "false", including if it is not defined, then the useDefault variable will be set to true, which is the correct default value for this UIM attribute and field parameter.
The appropriate initial value for the input control can now be retrieved by calling getFormItemInitialValue on the context object. The third argument, null, is an optional extended path value that is not supported in custom renderers.