The DojoTextField widget defines a text box containing
a single line of text. This widget is based on the Dojo dijit.form.ValidationTextBox
definition.
Here are the supported fields:
- constraints
- A dictionary that is used as an argument during the invocation
of functions that in turn validate user input. Those functions are
referenced by the validators field and are
referred to as validator functions.
The content of
the dictionary is appropriate to your business need. Here is an example
assignment:
constraints = new Dictionary{timeFormat = "hh:mm:ss"}
In
this case, a validator function might return an error message if the
user's input is not formatted to show hours, minutes, and seconds
with intervening colons.
- inputRequired
- A Boolean value that indicates whether input is required. The
error message in this case is the value of the inputRequiredMessage field.
This
validation precedes any others, but is active only after the field
gains focus after having lost focus.
- inputRequiredMessage
- A string that is displayed when the InputRequired field
is true, the text field has no content, and the field gains focus
after having lost focus. The message is displayed in an output field
that is provided for you.
If the inputRequiredMessage field
is not present, the error message is the following string, as appropriate
to the locale: “This value is required”.
Note: To
set the locale used in the Rich UI editor, see the directions for
the Languages tab in “Setting preferences for Rich UI appearance.”
To set the runtime locale at deployment time, see “Adding Rich UI
deployment entries in the EGL deployment descriptor.”
- maxLength
- The maximum number of characters that can be typed into the field.
- placeholder
- A string that is displayed in the Dojo text field but that is
removed as soon as the user clicks into the field. The string is re-displayed
in the field whenever the field is empty and the user is not working
there.
- promptMessage
- A string that prompts the user's input. When the text field gains
focus, the string is displayed next to the text field, in an output
field that is provided for you, and the display continues until the
user begins adding or changing content. To further set the string
position, set the tooltipPosition field.
- readOnly
- A Boolean value that indicates whether the text field is protected
from user input.
- selectOnClick
- A Boolean value that indicates what happens when the user clicks
from outside the text field into the field:
- False (the default)
- The content of the text field is not selected. The update cursor
is displayed at the click position.
- True
- The content of the text field is selected. Any subsequent click
displays the update cursor at the click position, and the content
of the text field is no longer selected.
- text
- The string content of the Dojo text field.
- textCase
- A string constant that indicates what happens to the case of the
input when the user finishes typing and navigates to another field.
One of the following values:
- CASE_NONE (the default)
- The user's string is left as is.
- UPPER_CASE
- The user's string is set to uppercase.
- LOWER_CASE
- The user's string is set to lowercase.
- PROPER_CASE
- The first letter in each word is set to uppercase, as if the string
were a title.
- tooltipPosition
- An array of string constants that specify a sequence of message
positions in order of your decreasing preference.
The EGL runtime
code tries each constant in the array in turn. The message is displayed
as appropriate for a given constant in the array unless the space
in the window or scrolling area is insufficient. If the space is insufficient,
the handler tries the direction that is represented by the next constant
in the array.
The following constants are valid:
- TOOLTIP_AFTER
- The message is displayed to the right of the text field.
- TOOLTIP_BEFORE
- The message is displayed to the left of the text field.
- TOOLTIP_ABOVE
- The message is displayed above the text field.
- BELOW
- The message is displayed below the text field.
If no values are usable for space reasons, the message
is displayed on top of the field.
If you do not specify any
values, the value of tooltipPosition is [DojoLib.AFTER,
DojoLib.BEFORE].
- trim
- A Boolean value that indicates whether preceding and trailing
blanks are removed when the user finishes typing and navigates to
another field.
- validators
- An array of validator functions that are invoked in array-element
order in response to each user keystroke. If the user's input passed
validation in a given function, that function indicates the success
by returning a null or blank; and only in that case is the next function
in the array invoked. If the user's input did not pass validation,
the function indicates a failure by returning a nonblank string.
The
sequence of validators is invoked at each keystroke.
If the
Dojo text field is referenced by a controller, you can code controller-specific
validator functions, which are wholly separate from the functions
being described. The controller-specific functions are invoked only
if the field-specific validation is successful and only after the
widget loses focus.
For details on controllers, see “Rich UI
validation and formatting.”
Each of the field-specific validator
functions conforms to the following Delegate part:
Delegate Validator(input String in, constraints dictionary in)
returns(string?) end
- input
- The user's collected input, including characters from previous
keystrokes in the same Dojo text field.
- constraints
- A dictionary that provides information used to construct a regular
expression or to guide processing inside the validator functions.
For example, the dictionary might specify the user's level of security.
- string?
- A null or blank (if no error occurred) or a nonblank string (to
indicate that an error occurred).
You might want to invoke, from your validator,
one or more of the functions provided in the DojoLib library.
The following functions are specific to the EGL Dojo widget types
that support view-level validation, as listed in “Rich UI validation
and formatting”:
- getValidState
- Is solely for internal use.
- showErrorIndicator
- Accepts a Boolean value that sets or clears the error indicator
in the widget. Here is the function prototype:
function showErrorIndicator(aboolean boolean in);
- showErrorMessage
- Accepts an error message for display in the error-message tooltip
near the widget. The tooltip is shown when the widget gains focus
and is hidden when the widget loses focus. Here is the function prototype:
function showErrorMessage(msg string in);
Other supported fields and functions are described in the following
topics in the EGL Programmer’s Guide: “Rich UI widget fields” and
”Rich UI widget functions.”
Use of this widget requires the following statement:
import dojo.widgets.DojoTextField;