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:
- The application publishes data; that is, presents data to the
user.
- The user updates the data and then clicks a button or presses
a key to submit the data.
- The code validates the input, transmits all the validated data
to a service, and responds to the user.
A
form manager is a handler declaration that gives
you the following capabilities:
- To define a set of form fields, each of which can include a field
label, a controller, and an error field. The displayable components
can be anywhere on the user interface and can be separate from one
another.
- To process the set of form fields, including output formatting,
input validation, and input unformatting. For example, if a money
value is being stored in a field of type NUM, the currency symbol
is removed from the input value before the value is stored.
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:
- Open a handler in the Rich UI editor and drag and drop a record
definition to the Design tab.
- 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:
- Your invocation of the form-level isValid function
has the following effect for every controller in turn:
- 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.
- Invokes the controller's validStateSetter function.
By default, this function is the form-level validStateSetter function.
- 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.