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.
Rich UI offers two variations of form processing:
- 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 }
]};
- A validating form is a container that also lets you
define and process a set of form fields. The validating form is easy
to use but less flexible, requiring that the displayable aspects of
the form fields be arranged in three columns, at most. The displayable
aspects in this case can include a label, a controller view, and an
error field.
Here is a declaration of a validating form:
employeeForm ValidatingForm { entries = [
new FormField { displayName="Name:", controller=nameController },
new FormField { displayName="Age:", controller=ageController },
new FormField { displayName="Salary:", controller=salaryController }
]};
When using a validating form, you specify only
the displayName and controller values
in a form field. The rest of the values are handled by the validating
form itself.
In either case, you invoke functions that handle each of the form
fields in turn; for example, to validate the form as a whole.
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, 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 |
Context |
Details |
| controller |
Controller |
Form manager or validating form |
The controller is a definition that relates
a view to a model. |
| displayName |
String? |
Validating form |
The string is assigned to a field label that
is provided for you by the validating form. The string is ignored
if you are using a form manager. |
| errorLabel |
TextLabel |
Form manager |
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. If you are using a form manager, supply
the text label when you declare the form field. However, if you are
using a validating form, the text label is provided for you.
|
| nameLabel |
TextLabel |
Form manager |
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? |
For use by Rich UI |
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 validating form, provide the controller and displayName values.
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. The order of the invocations
is opposite to the order of the form fields 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.