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) } } } }
