DigitGrid Block Documentation

Overview

The DigitGrid block is a flexible and highly customizable UI component designed for numeric input, such as PIN codes, OTPs, card numbers, and more. It dynamically generates multiple input fields based on specified parameters, allowing for smooth focus management, smart clipboard handling, and visually distinct states.

Features

Dynamic Input Generation: Easily configure the number of input fields and digits per field.
Customizable Styles: Apply specific styles for normal, filled, active, and error states.
Smooth Focus Handling: Automatically moves focus between fields and manages focus behavior dynamically.
Password Support: Enables masking of digits for secure data entry.
Smart Clipboard Handling: Supports pasting data at any position, automatically placing the pasted data from the start and splitting it across input fields.
Input Validation: Validates the input length to ensure it matches the expected digit count.
Event Handling: Emits events to track input changes and focus updates.
Responsive and Accessible: Works seamlessly on various devices and supports keyboard navigation.

Inputs

Name	Type	Description
NumberOfControls	Integer	Specifies the number of input fields to generate.
DigitsPerControl	Integer	Defines how many digits each input field can hold.
Value	Text	Holds the concatenated value from all input fields. Used only to update the values programmatically.
ContainerStyleClass	Text	CSS class to style the outer container of the digit input group.
InputStyleClass	Text	CSS class to style each individual input field.
FilledStyleClass	Text	CSS class applied when an input field contains a value.
ErrorStyleClass	Text	CSS class applied when an input field contains invalid or incomplete data.
StartFocus	Boolean	Sets focus on the first input field when True.
IsMandatory	Boolean	Specifies whether the input is required.
IsSelectedOnFocus	Boolean	Automatically selects the entire content of an input field when focused.
IsEnabled	Boolean	Enables or disables the input fields.
IsPassword	Boolean	Masks the input with a password style.

Events

UpdateAfterFocus

Fires when StartFocus is set to True and the focus on the first input field is completed. Triggers with False to update the parent StartFocus property, allowing focus to be triggered again.

Outputs:
- UpdatedFocus (Boolean): Holds the False value to update the parent StartFocus.

ValueChanged

Fires whenever an input field value changes, providing essential information about the current state.

Outputs:
- Value (Text): The concatenated value from all input fields.
- HasLostFocus (Boolean): Indicates whether an input field has lost focus.
- IsLast (Boolean): Specifies whether the last input field in the sequence has been focused and started receiving input.
- IsValid (Boolean): Indicates whether the length of the current value matches NumberOfControls * DigitsPerControl.

Usage Example

Add the DigitGrid block to your screen or UI component.
Set the desired number of input fields using NumberOfControls and digits per field with DigitsPerControl.
Customize styles using ContainerStyleClass, InputStyleClass, FilledStyleClass, and ErrorStyleClass.
Set IsPassword to True if masking is required.
Bind the Value output to capture the concatenated result.
Handle the ValueChanged event to process the entered digits and manage validation.

Best Practices

Use IsSelectedOnFocus to provide a better user experience when navigating between fields.
Combine StartFocus with the UpdateAfterFocus event to handle focus transitions efficiently.
Leverage Clipboard Support to allow pasting multi-digit codes directly into any field.

Common Use Cases

PIN Code Entry: Quickly gather numeric PINs with password masking.
OTP Verification: Seamlessly enter multi-digit one-time passwords.
Card Number Input: Split long numbers into segments for readability.