Execution behavior:
1. On input event:
- Reads current value.
- Cleans value according to configured rules.
- Enforces max length.
- Updates field and triggers change when modification occurs.
2. On paste event:
- Blocks paste entirely when AllowPaste is False.
- Otherwise captures clipboard text, sanitizes it, injects cleaned text at cursor selection.
- Enforces max length based on available space.
3. On keypress event:
- Prevents disallowed characters before they appear in the input.
- Checks custom regex when enabled.
- Validates projected length before allowing additional character.
Validation priority:
1. MaxLength rule
2. Custom regex rule (if enabled)
3. Character-set rule (alpha/numeric/Arabic/special configuration)
Detailed Input Descriptions
1. WidgetId
Purpose: Identifies the input widget where validation should be applied.
Type expectation: Text (DOM id of target input element).
Behavior: Event handlers are attached using this id.
Important note: If the id is missing, incorrect, or not yet rendered, validation will not attach.
2. AllowedSpecialChars
Purpose: Defines which special characters are permitted when AllowSpecialChars is False.
Type expectation: Text containing allowed symbols only.
Example values:
- @._-
- /()
Behavior:
- Used to build the allowed-character regex.
- Regex-sensitive characters are escaped internally.
- Dash handling is made safe to avoid regex range conflicts.
3. AllowAlpha
Purpose: Controls acceptance of English alphabetic characters.
Type expectation: Boolean.
Default: True.
When True: Allows A-Z and a-z.
When False: Alphabetic characters are removed/blocked.
4. AllowNumeric
Purpose: Controls acceptance of numeric characters.
When True: Allows 0-9.
When False: Numeric characters are removed/blocked.
5. AllowArabic
Purpose: Controls acceptance of Arabic script characters and Arabic numerals.
Default: False.
When True: Allows configured Arabic Unicode ranges.
When False: Arabic characters are removed/blocked.
6. AllowPaste
Purpose: Enables or disables paste into the input field.
When True: Pasted content is sanitized before insertion.
When False: Paste action is prevented completely.
7. MaxLength
Purpose: Limits final input length.
Type expectation: Integer.
Default: 0.
- 0 means no maximum length restriction.
- For typing, blocks additional characters once max is reached.
- For paste, trims inserted text to fit remaining capacity.
8. CustomRegexPattern
Purpose: Provides custom validation logic beyond standard character-set options.
Type expectation: Text representing a regex pattern.
Default: empty.
- Used only when UseCustomRegex is True.
- Invalid pattern is caught safely; error logged, and standard validation continues.
9. UseCustomRegex
Purpose: Toggles use of CustomRegexPattern.
When True: Custom regex is evaluated during typing and cleaning.
When False: Standard character-set validation only.
10. AllowSpecialChars
Purpose: Controls global special character behavior.
When True:
- All special characters are accepted.
- Special character filtering is effectively relaxed.
When False:
- Only special characters listed in AllowedSpecialChars are accepted.
- Any other special character is blocked/removed.
Recommended Configuration Patterns
1. Strict alphanumeric ID field
- AllowAlpha: True
- AllowNumeric: True
- AllowSpecialChars: False
- AllowedSpecialChars: empty
- MaxLength: set as needed
2. Username with dot and underscore
- AllowedSpecialChars: ._
- MaxLength: 30
3. Free-text multilingual comment
- AllowArabic: True
- AllowSpecialChars: True
- MaxLength: 500
4. Regex-controlled format (example: uppercase letters and digits only)
- UseCustomRegex: True
- CustomRegexPattern: [A-Z0-9]
- Keep other flags aligned to business need
Operational Notes and Caveats
1. Attach this action once per input instance to avoid duplicate handlers.
2. Ensure widget exists in DOM before binding.
3. Custom regex should be tested for both typing and pasted text scenarios.
4. If using complex regex anchors like ^...$, remember character-by-character checks may need pattern design adjustments.
If you want, I can next provide:
1. A production-ready parameter table in OutSystems documentation style (Name, Type, Mandatory, Default, Example, Notes).
2. A validation matrix showing exactly what is allowed or blocked for every flag combination.
3. A test checklist with concrete input samples and expected results.