Form processing with Rich UI

Rich UI provides a way to implement the kind of form processing that is traditional in business software. The processing depends on the Rich UI controller, which is a definition that relates a single view—a widget—with a single model—a data field. For details on Rich UI controllers, see “Rich UI validation and formatting.”

You might use form processing in an application that fulfills the following steps:
A form manager is a handler declaration that gives you the following capabilities:

You interact with a form manager by writing code or by using code that the Rich UI editor provides for you.

Here is a declaration of a form manager:
employeeForm FormManager { entries = [
   new FormField { nameLabel="Name:",   controller=nameController },
   new FormField { nameLabel="Age:",    controller=ageController },
   new FormField { nameLabel="Salary:", controller=salaryController }
]};

You invoke functions that handle each of the form fields in turn; for example, to validate the form as a whole. The order of the form-field processing is generally the order in which the form are listed in the entries array, in the declaration of the form manager.

A starting point for form development

EGL provides a starting point for form development. In brief, the Rich UI editor provides application-specific code, and you add logic to invoke it. To cause the initial development in the EDT IDE, do as follows:
  1. Open a handler in the Rich UI editor and drag and drop a record definition to the Design tab.
  2. Work with a wizard, as described in “Creating widgets by dragging data into the Rich UI editor.”
In response to your keystrokes, the editor adds the following code to your handler:
  • A form manager. The form fields in the declaration are specific to your need.
  • Functions that access the general form-processing logic in the form manager.

Form fields

A form field is itself a data collection: a record of type FormField. The record is used differently for a form manager and for a validating form. The use of a single record type for both of those mechanisms means that you can easily switch between the two.

As suggested in the next table, you set the record fields that are appropriate for your use.

Field in the record of type FormField Field value Details
controller Controller The controller is a definition that relates a view to a model.
errorLabel TextLabel The text label named errorLabel is the error field; it displays the error message, if any, that is output during validation of a form field. The appearance of the error field changes when an error occurs.

Supply the text label when you declare the form field.

nameLabel TextLabel The form-field label. The setting is ignored if you are using a validating form, which provides a label and assigns the displayName value to that label.
labelClass String? A CSS class. Do not change this value, which is used to change the form-field label to its original appearance after an error is resolved.

The class name is EglRuiTextLabel; and the same class name is used when an error occurs, with the addition of the following, secondary class: FormErrorLabel.

When you work with a form manager, provide the controller and nameLabel values and, optionally, the errorLabel value.

Form-level functions

The form-level functions invoke controller-specific functions; and in each case, the order of the invocations is the order in which the form fields are listed in the entries array.

Your code is likely to invoke functions for validating, committing, and publishing data. For example, your code might expand on the following logic:
if (employeeForm.isValid())
   employeeForm.commit();
end

The controller itself invokes a controller-specific validStateSetter function at the end of validation.

Note the order of events:
  1. Your invocation of the form-level isValid function has the following effect for every controller in turn:
    1. Invokes the controller's isValid function, which in turn invokes the validator functions referenced in the controller definition. The process also involves elementary validations such as for the isDecimalDigit property of the controller model.
    2. Invokes the controller's validStateSetter function. By default, this function is the form-level validStateSetter function.
  2. If all the controller views contain valid data, your code invokes the form-level commit function. That function invokes each controller-specific commit function to unformat the data in a controller view and to write the value to a controller model.
Given the preceding order, you might want to invoke your own cross-field validation after the form validations succeed. Your code might look as follows:
if (employeeForm.isValid())
   if (myValidation())
      employeeForm.commit();
   end
end

Here are the form-level functions in alphabetical order:

commit()
Lets you commit all the views to the related models with one command. After you invoke the form-level commit function, you can transmit all the model data to a service.

The function has no parameters or return value.

isValid()
Invokes the controller-specific isValid functions.
The function has no parameters and returns a Boolean to indicate whether validation succeeded for all form fields.
publish()
Invokes each controller-specific publish function to format data stored in the controller model and to write the formatted data to a controller view. Your code might invoke the form-level publish command in a callback function, which is invoked after your code receives data that is returned from a service.

The function has no parameters or return value.

validate()
Invokes the controller-specific validate functions.

The function has no parameters and returns a Boolean to indicate whether the validations succeeded; that is, whether all the controller-specific validate functions returned a null or blank.