Application Development : Text Controls (part 2) – Validator, TextArea

Validator

You can make sure that the user’s input conforms to a certain set of rules by specifying a Validator class for the TextField using its validator property. For example, for a password field you could ensure that it is of a certain length and that it contains at least a digit. You can use the validator’s mode property to specify when text validation should occur. For example, by setting the mode property to ValidationMode.Immediate, the user’s input will be validated as the user types along, and by setting the property to ValidationMode.FocusLost, the user’s input will be validated once the TextField has lost focus.  During validation, you can update the validator’s state by setting its state property, which can take one of the following values:

• ValidatationState.Unknown: Validation state is unknown. This state is used for cases where the validation process has not been initiated.
• ValidationState.InProgress: Validation is currently in progress.
• ValidationState.Valid: Validation has succeeded.
• ValidationState.Invalid: Validation has failed.

You should implement the actual validation in JavaScript by handling the validator’s validate signal, as illustrated in Listing 6.

Listing 6.  JavaScript Validation Using a Regular Expression

import bb.cascades 1.2
 
Page {
    Container {
        TextField {
            id: myField
            inputMode: TextFieldInputMode.NumbersAndPunctuation
            input {
                submitKey: SubmitKey.Go
                onSubmitted: {
                    // handle input when submit key is pressed
                    // by extracting value text from myField.text
                }
            }
            validator: Validator {
                mode: ValidationMode.Immediate
                errorMessage: "Invalid integer!"
                onValidate: {
                   // regexp for valid integer including optional sign
                    var regexp = /^\s*(\+|-)?\d+\s*$/;
                    var isValidInteger = regexp.test(myField.text);
                    if (regexp.test(myField.text))
                        state = ValidationState.Valid;
                    else
                        state = ValidationState.Invalid;
                }
            }
        }
    }
}

The regexp variable defines a valid integer (for example, 10, -99, and 0 are valid expressions, but 10.0 would be considered as invalid). The important point is that I am using the regexp variable to toggle the validator’s validation state.

Finally, here a few best practices to consider:

• Use a text field to let users input a single line of text, such as an e-mail address, a password, or a contact name.
• Include hint texts in text fields (by doing so, you won’t need to add a label describing the text field’s purpose).
• Don’t use word prediction in e-mail, password, and contact name fields. Using word prediction in these cases will simply get in the user’s way.
• Provide clear error messages when using validators.

TextArea

A TextArea is very similar to a TextField and shares many of its properties (which they both inherit from AbstractTextControl). The main difference comes from the fact that a TextArea can handle multiple lines of text, whereas a TextField provides a single line. You can set the TextArea’s inputMode using a TextAreaInputMode object (the possible values are TextAreaInputMode.Default, TextAreaInputMode.Text, TextAreaInputMode.Chat, TextAreaInputMode.Email, and TextAreaInputMode.Custom). Finally, you can also use the TextArea’s editor object to track the current cursor position or the current selected text (see Listing 4-13).

Listing 4-13.  TextArea Signal Handling

import bb.cascades 1.2
Page {
    Container {
        layout: DockLayout {
             
        }
        leftPadding: 20
        rightPadding: 20
         
        TextArea {
            id: myField
            inputMode: TextAreaInputMode.Chat
            hintText: "Enter some text"
            verticalAlignment: VerticalAlignment.Center
            preferredHeight: 500
             
            scrollMode: TextAreaScrollMode.Elastic
            onTextChanging: {
                console.log("text changing: "+text)
            }
             
            editor.onSelectionStartChanged: {
                console.log("selection start: "+selectionStart);
            }
            editor.onSelectionEndChanged: {
                console.log("selection end: "+selectionEnd);
            }
            editor.onSelectedTextChanged: {
                console.log("selectedTextChanged: " + selectedText)
            }
            editor.onCursorPositionChanged: {
                console.log("cursorPositionChanged: " + cursorPosition)
            }
        }
    }
}