$.udb.input()

note

This article is about the input() function of the udb object.

$.udb.input()

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 an InputPromise object.

tip

$.udb.input() is similar to $.udb.dialog() but more complex due to the fields it can be supplied with. This fields option can also be passed to $.udb.dialog(), which will then let $.udb.input() handle it.

NB: InputPromise is a sub-class of the UdbPromise class which adds some extra functionality, like .validate() step before the .then() Promise clause for value validation. See below for more information.

Syntax

$.udb.input( *options* )
.validate( *result* => {
    ...
})
.then( *result* => {
    ...
})
.catch(() => {
     // failure
})
.finally(() => {
     // executed after success / failure is handled
});

*options*  ::=  {
    [message]:     *dialog-message*,
    [title]:       *dialog-title*,
    *fields*:      *fields-array*,
    [buttons]:     *buttons-list*,
    [useOpacity]:  *use-opacity*,
    [closeButton]: *close-button*,
    [promptWidth]: Integer
    [width]:       Integer
}

*dialog-message* ::= { *string* | *message-object* }
*message-object* ::= {
    [code]:       *string*,
    [params]:     Array[*string*],
    [string]:     *string*
}

*fields-array*   ::=  Array[*field-object*]
*field-object*   ::=  {
    *type*:          *field-type*,
    [id]:            *field-id*,
    [prompt]:        *field-prompt*,
    [class]:         *field-classes*,
    [value]:         *field-value*,
    [height]:        *field-height*,
    [maxlength]:     *field-max-length*,
    [allowedValues]: *field-allowed-values*,
    [help]:          *field-helpinfo-text*,
    [min]:           *field-min-value*,
    [max]:           *field-max-value*,
    [step]:          *field-step*,
    [readOnly]:      *field-read-only*,
    [func]:          *field-custom-fn*
}

*field-type* ::=  { [text] | password | textarea |
    checkbox | radio | select | static | htmlarea | range }
*field-height*          ::=  Integer
*field-max-length*      ::=  Integer

*field-step*            ::=  Integer
*field-min-value*       ::=  Integer
*field-max-value*       ::=  Integer

*field-allowed-values*  ::=  Array[*field-allowed-value*]
*field-allowed-value*   ::=  { *value* | *prompted-value* }
*prompted-value*        ::=  { prompt: *value-prompt*, value: *value* }

*dialog-title*   ::= { ['Warning'] | *string* }
*dialog-icon*    ::= { ['bi-exclamation-triangle-fill'] | *string* }
*width*          ::=  Integer
*use-opacity*    ::=  { [true] | false }
*close-button*   ::=  { [true] | false }

*button-list*    ::=   Array[*button*]
*button*         ::=   { *string* | *button-object* }
*button-object*  ::= {
    *id*:       *string*,
    [label]:    *string*,
    [func]:     *button-function*,
    [class]:    *button-class*,
    [default]:  *button-default*
}

*result*  ::= {
   answer: *answer*,
   fields: *fields-array*,
   caller: *options*
}

Options is a struct that can have the following items, all of which are optional, although for it to be treated as an input dialog, the fields option is required. If the fields option is omitted, then the call is treated as a $.udb.dialog() call instead. If added, an input dialog with the specified fields is generated and displayed.

Dialog-message is the message that the dialog must display. This can be either a string, or an object with either a code string (referring to a translatable message in the JSON file that contains these messages), or 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 message being displayed.

Dialog-title is the title of the dialog. The default value is 'Warning'. The title is displayed in a title bar across 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.

Button-list 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 is considered to be both the button 'id' and its text label. This text label is also processed by the translation engine.
• If a button-object is passed, its parameters will be used to create a customised button. The default is a single 'OK' button without any special customisation. The syntax of these button objects is the listed above, and is also same as for the .usdialog() function:
  • the id and label properties are strings, of which at least id is mandatory.
  • the button-function is a function that must be executed if that button gets pressed.
  • the button-class is a string which designates a CSS class that must be added to the button. It could be used to add an icon on the button, or e.g. to change its background color.
  • the button-default is a boolean to indicate if the button must be selected on default. The first button in the list to have this property set to true is considered default. If none have it, this is always the first button.

When one of these buttons in the button-list is pressed, the id property of that button is stored in the result.answer property sent to its .validate() and .then() clauses afterwards.

Use-opacity is a boolean that determines if the dialog is displayed as a modal dialog, in which case a modal backdrop layer 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 the user presses this icon, then its consecutive .then() clause gets executed with the result.answer value being empty, because none of the buttons was pressed. Pressing the close-button will also skip the optional .validate() clause of the InputPromise returned by the $.udb.input() function.

After pressing any button (including the close button at the top-right), the .then() clause of the UdbPromise resulting from the .dialog() function is called, with its result parameter filled with the id value of the pressed button in its answer field, and the original options passed to the function in the caller parameter of result.

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. A field-object have a lot of common options, most of which are optional, except for the type, which determines what kind of field is displayed.

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, e.g., 'field1'.

Field-prompt is the string displayed alongside the input field. If left empty, the value of field-id is used. If the field type is a checkbox, then the prompt is displayed after the checkbox. In all other cases, it will be in front of the field input instead.

Field-type is the type of the input field. The default is 'text'. Field types are:

Type	Contents	Specific fields
'text'	Text box	field-max-length
'password'	Password box	field-max-length
'textarea'	Multi-line text area	field-max-length
'checkbox'	Checkbox
'radio'	Radio button group	field-allowed-values
'range'	Range selection box	field-step, field-min, field-max
'select'	Dropdown list	field-allowed-values
'static'	Read-only field showing regular text string
'htmlarea'	Read-only field showing HTML-formatted text string

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-fn is a function that can be used to further customise the behaviour of an input field, e.g. to add behaviour that it normally does not have. This allows you for example, to add auto-completion features to a text input field. Field-custom-fn receives the generated HTML object and the field object as its parameters.

The usage of field-step, field-min-value and field-max-value are solely for fields of type 'range'. They are used to determine the increment step, minimum and maximum value of the field respectively. All three of these are integers.

Buttons is an array of button definitions for one or more buttons displayed at the bottom of the dialog. The default is an array with an "OK" and a "Cancel" button without any special customisation. 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 $.udb.dialog() function.

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.

The resulting result object passed to the clauses following .input() contain the id of the button in the result.answer field, and all of the field data (and the entered values as well) in the result.fields field. There is also the result.caller field that contains all the options that were originally passed to the .input() call.

As mentioned, the .input() function returns an InputPromise, which is a sub-class of the UdbPromise class. This means it contains all the regular UdbPromise and Promise functionality, with the addition of the .validate() function which is specific for the InputPromise. If used, it must be chained directly after the .input() function. In here, you can inspect the contents of the result.fields values, and take appropriate actions (e.g. showing validation errors) if any values are incorrect or not allowed. If you want to allow the user to correct these values afterwards, then .validate() must return the value false. Not returning a value or returning true instead will allow execution to continue with the next .then() clause, if present. Any .catch() or .finally() clauses afterward will also be executed as normally.

Example

$.udb.input({
    title: "Log In",
    message: "Please enter your credentials",
    buttons: ["Log In", "Cancel"],
    fields: [   { id: 'user', prompt: 'User name', type: 'text' },
                { id: 'cred', prompt: 'Password', type: 'password' }
            ]
})
.validate((result) => {
    if (result.answer === "Log In") {
        let user = result.fields[0].value;
        let pwd = result.fields[1].value;
        if (!user || !pwd) {
            $.udb.dialog({message: 'You must enter a username and password'});
            return false;
        }
        if (!pwd || pwd.length < 4) {
            $.udb.dialog({message: 'Passwords are expected to be at least 4 characters long'});
            return false;
        }
    }
})
.then((result) => {
    let user = result.fields[0].value;
    let pwd = result.fields[1].value;
    if (result.answer === "Log In") {
        return $.udb.login(user, pwd)
            .then(() => $.udb.dialog({message: 'Login successful'}) )
            .catch(() => $.udb.dialog({message: 'Login failed'}) );
    }
});

Related events

Event	Applies to	Occurs when
dialogopen	Dialog controls	Right after a dialog has been shown
dialogclose	Dialog controls	Right after a dialog has closed
dialogbeforeclose	Dialog controls	Immediately before a dialog closes

note

.input() displays its dialog through a DataInputControl, whose show()/close() handling is what triggers these events.