DojoDateTextBox widget

The DojoDateTextBox widget defines a text box that contains a date or part of a date. This widget is based on the Dojo dijit.form.DateTextBox definition.

Here are the supported fields:
contraints
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:

DateTextBox.constraints = new Dictionary
   { min=DateTimeLib.mdy(1, 1, 2011), max=DateTimeLib.currentDate()};	

In this case, you set values for two keys of type DATE:  max and min. The effect of this setting is to restrict user input to the specified date range.

errorMessage
The message that is displayed when the input is present but invalid. The message is displayed in an output field or tooltip that is provided for you.
formatLength
The format of the displayed data. The effect of using one or the other formatLength values is specific to the locale. In any case, the value is one of the following ones, as explained here for American English:
DATEBOX_FORMAT_FULL
Includes the day of the week; for example, Monday, March 16, 2009.
DATEBOX_FORMAT_LONG
Includes the day, month, and year; for example, March 16, 2009.
DATEBOX_FORMAT_MEDIUM
Includes a shortened month; for example, Mar 16, 2009.
DATEBOX_FORMAT_SHORT
Includes the day, month, and year in numeric format; for example, 03/16/2009.
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.”
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 date text box gains focus after having lost focus.

inputRequiredMessage
A string that is displayed when the InputRequired field is true, the date text box has no content, and the field gains focus after having lost focus. The message is displayed in an output field or tooltip 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”.

placeholder
A string that is displayed in the Dojo date text box but that is removed as soon as the user clicks into the box. The string is re-displayed in the field whenever the box is empty and the user is not working there.
promptMessage
A string that prompts the user's input. When the date text box gains focus, the string is displayed next to the box, in a tooltip 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 date text box is protected from user input.
selectOnClick
A Boolean value that indicates what happens when the user clicks from outside the date text box into the box:
False (the default)
The content of the date text box is not selected. The update cursor is displayed at the click position.
True
The content of the date text box is selected. Any subsequent click displays the update cursor at the click position, and the content of the date text box is no longer selected.
text
A string that is formatted to match the default format in use. If you set the field in the widget declaration, the string must match the setting of the defaultDateFormat build descriptor option. If you set the field at run time, the string must match the setting of the StrLib.defaultDateFormat system function, which itself defaults to the value of the defaultDateFormat build descriptor option.

The default value of the defaultDateFormat option is MM/dd/yyyy.

validators
An array of validator functions that are invoked in array-element order. 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 when the widget loses focus.

If the Dojo date text box 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 input.
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.

value
A date variable, although an automatic conversion allows use of a string.
The following functions are supported:
clear
Clears the current value.
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.DojoDateTextBox;