A HTML form page contains HTML input controls, such as text fields and check-boxes. Input controls are required where a UIM FIELD element contains a TARGET connection, as the user must have somewhere to enter the value before submitting it to the targeted server interface property. An edit-renderer must create the appropriate HTML to present an input control.
To select an edit-renderer, the system identifies the domain definition associated with the server interface property of the target connection. Each domain definition has associated edit-renderer and view-renderer plug-in classes. As a target connection is present, the system will automatically use the edit-renderer instead of the view-renderer when rendering the field.
When a form page is presented to a user, the user sets the values of the input controls in the browser. The user then submits the form to send these values to the server's client-tier in a new request. The edit-renderer plug-in type differs from the view-renderer in that the edit-renderer must declare to the system what input control it adds to a form page, so that the system can process the corresponding values when it receives the form submission request. A view-renderer does not add input controls, so it has no such requirement.
The RendererContext provides a method for recording form items as they are added to the form page. The addFormItem method returns the identifier that should be used as the value of the id and name attributes of the HTML element. Before calling this method, the title (or label) of the field must be determined.
String title = getTitle(field, context.getDataAccessor());
String targetID = context.addFormItem(field, title, null);
The abstract base class provides a getTitle method that can determine the title of the given field. This renderer passes the field and this title value to the addFormItem method. The third parameter, null, specifies an optional extended path value. Extended path values for form items are not supported in custom widgets.The addFormItem method returns a target ID string value that must be used to identify the input control that will be created to correspond to this newly registered form item.
The addFormItem method uses the Field object and the title string to record the target path of the entered value of that control, the domain definition of the targeted server interface property, and the label of that field. As the form page is rendered, the system records the form items added by all of the edit renderers and embeds all of this extra information into the HTML form on the page.
When the user submits the form, the values of all of the input controls are submitted as ID/value pairs. The ID is the id or name attribute value of the respective HTML input control element (which attribute is used depends on the browser, so both attributes are added and set to the same value by the edit-renderer plug-in). The information about the form items recorded and embedded in the form by the system is also submitted at this time. The system combines the input control's ID and value with the embedded form item data that records IDs and target paths. The system can thus determine automatically which submitted values should be assigned to which server interface properties identified by the target paths. The label is used in the event of a validation error, so that the error message can report the label of the field in error.