Displays a message to the user and a variety of input fields for user input. These input fields can then be validated and processed. Input dialogs of this type have many uses, ranging from configuration dialogs, and login dialogs to practically anything that requires user input.
Calling .input() while a dialog is already being displayed will result in this existing dialog being removed entirely and rendering its input values null and void: they will not get validated or processed.
Returns a customised Promise object.
Options is a struct that can have the following items, all of which are optional.
Validate-input-function is a function that is called when the user presses a dialog button that causes the dialog to close. The function is used to validate the input fields and receives the pressed button’s "Id" value and the values of all the fields. Validation can result in the function returning false (i.e. validation failed). In that case, the dialog is kept open. In any other case, the dialog is closed. It is possible to use validate-input-function to process the input values as well, but you can also do that in the .then() clause of the Promise instead. Instead of passing validate-input-function as an option, you can chain it as a .validate() function, in the same way that you can chain .then() and .catch() with a Promise.
The validate-input-function and any ensuing .then() and .close() Promise functions do NOT execute if you have closeButton: true and the user closes the dialog by clicking the close icon ( 'X' ) in the top-right corner.
Dialog-message is the message that the dialog must display. This can be either a string, or an object with a message parameter string and an optional params array. Both options are processed by the translation engine to create the required end user message. Passing an empty message (or omitting it) will result in no dialog being displayed.
Dialog-title is the title of the dialog. Its default value is "Data input". The title is displayed in a title bar at the top of the dialog. If set to ' ' (the empty string), this title bar will not be displayed. In the same way as with dialog-message, the title can be either a string, or an object with a message parameter string with an optional params array, and both are processed by the translation engine to create the required title string.
Fields-array is an array of one or more input field definitions. Each field is a JSON object, a field-object. A field-object must have specific parameters to work correctly. The parameters may differ from one field-object to the next.
Field-id is a string that identifies the field in the generated dialog. If omitted, the value becomes ‘field’ followed by the array index of this field-object, eg., ‘field1’.
Field-prompt is the string displayed alongside the input field. If left empty, the value of field-id is used.
Field-type is the type of the input field. The default is ‘text’:
Field-value is the initial value of the input field. The default is the empty string.
Field-height is the height of the field; this is used for customised fields and for multi-line fields such as text areas. By default, the height is automatically calculated, which means the value ‘auto’ is used for the field.
Field-max-length is the maximum number of characters the field is allowed to contain. This applies only to text boxes, password boxes and multi-line text areas. If not specified, there is no maximum.
Field-allowed-values is an array with all the possible values this field may have. This applies to selection input fields: radio button groups and dropdown lists. You can supply simple text strings or you can supply a name-value pair that represents a prompt with a value.
Field-helpinfo-text is a text that appears when the user hovers the mouse above a question mark icon to the right of the input field. This text is used to further explain the meaning or usage of the input field. If omitted (which is the default), the text is empty, and the question mark icon is not shown.
Field-custom-function is a function that can be used to further customise the behaviour of an input field, eg., to add behaviour that it normally does not have. This allows you, for example, to add autocompletion features to a text input field. The field-custom-function receives the generated HTML object and the field object as its parameters.
Buttons is an array of button definitions for one or more buttons displayed at the bottom of the dialog. For each button you can pass either a string value or a button object:
•If a string is passed, its value will be used for the button's "Id" attribute and for the button's text label (which is also processed by the translation engine).
•If a button object is passed, its parameters will be used to create a customised button. The syntax of these button objects is the same as for the .usdialog() framework API function. The default is a single "OK" button without any special customisation.
Use-opacity is a boolean that determines if the dialog is displayed as a modal dialog, in which case an Opacity Control is displayed behind the dialog so that anything on the underlying page becomes inaccessible. The dialog is modal if use-opacity is true (the default), and non-modal otherwise.
Close-button is a boolean that determines if a close icon ( 'X' ) is displayed in the top-right corner of the dialog.
If promise is true (the default), a Promise object is returned. Otherwise, ‘undefined’ is returned.