Options
Mask
Element masks enable user input to be restricted and formatted to meet a pre-defined format.
A TextElementUITextField
allows you to restrict and fill user input, through the mask
attribute.
It consists of an array of NSRegularExpression
objects and Strings, used to restrict and fill input, respectively.
The position of each item in the mask array corresponds to the restriction or fill used for that input's position.
The length of the array determines how long an input is allowed to be.
For example, the mask for a US based phone number shown below will have the following rules:
let regexDigit = try! NSRegularExpression(pattern: "\\d")
let phoneMask = [ // (123)456-7890
"(",
regexDigit,
regexDigit,
regexDigit,
")",
regexDigit,
regexDigit,
regexDigit,
"-",
regexDigit,
regexDigit,
regexDigit,
regexDigit
] as [Any]
myTextElement.setConfig(options: TextElementOptions(mask: phoneMask))
- The input must be at most 13 characters long
- Only digits are allowed in the 2-4, 6-8, 10-13 positions
(
will be filled in the 1 position)
will be filled in the 5 position-
will be filled in the 8 position
The mask will be displayed as the user is typing, and will be used as the value for tokenization performed with that text element. If the value does not satisfy the mask in its entirety, the field is considered incomplete. This is reflected in the element events and will fail validation before tokenization.
Transform
Element transforms define functions that mutate the value of the element prior to tokenization.
A TextElementUITextField
allows you to modify user input before tokenization, through the transform
attribute. It’s a struct that takes in an NSRegularExpression
and a String
.
It works by making use of the stringByReplacingMatches function on the NSRegularExpression
provided.
If no string is defined, an empty string will be used as the argument for withTemplate
. For instance, the mask for a US based phone number shown below will modify user input to look like this: (123)456-7890
.
The transform
setting set below, in this case, will modify the user input to remove (
, )
, and -
from the input. The resulting value is 1234567890
, which will be the value that gets tokenized.
let regexDigit = try! NSRegularExpression(pattern: "\\d")
let phoneMask = [ // (123)456-7890
"(",
regexDigit,
regexDigit,
regexDigit,
")",
regexDigit,
regexDigit,
regexDigit,
"-",
regexDigit,
regexDigit,
regexDigit,
regexDigit
] as [Any]
let transformMatcher = try! NSRegularExpression(pattern: "[()-]") // Regex to remove parentheses & dashes
textElementUITextField.setConfig(options: TextElementOptions(mask: phoneMask, transform: ElementTransform(matcher: transformMatcher))
Validation
Element validators define functions to determine whether the value of the Element is considered valid.
A TextElementUITextField
allows you to validate user input before tokenization, through the validation
attribute. The validation
attribute is of type NSRegularExpression
.
Text is validated after every change and is considered valid if any matches are found using the NSRegularExpression
provided. If the text is nil
and a validation
attribute is set, the text will be considered invalid. Let's run through
an example. Say you want to validate a US based phone number. You can use the following NSRegularExpression
to validate the phone number:
let regexDigit = try! NSRegularExpression(pattern: "\\d")
let phoneMask = [ // (123)456-7890
"(",
regexDigit,
regexDigit,
regexDigit,
")",
regexDigit,
regexDigit,
regexDigit,
"-",
regexDigit,
regexDigit,
regexDigit,
regexDigit
] as [Any]
let transformMatcher = try! NSRegularExpression(pattern: "[()-]") // Regex to remove parentheses & dashes
let phoneNumberRegex = try! NSRegularExpression(pattern: "^\\d{10}$") // Regex to validate phone number, after the transform is applied
textElementUITextField.setConfig(options: TextElementOptions(mask: phoneMask, transform: ElementTransform(matcher: transformMatcher), validation: phoneNumberRegex))
(123)456-7890
. The proper NSRegularExpression
pattern for that would be "^\(\d{3}\)\d{3}-\d{4}$"
Enable Copy
Enable Copy allows users to copy the value of the Element to their clipboard without the implementer touching the data.
A copy icon is added to the right side of the input field through the enableCopy
attribute. The icon can be tapped to copy the Element value to the clipboard.
The icon will change to a checkmark when the value has been copied and change back to the copy icon after a brief moment.
textElementUITextField.setConfig(options: TextElementOptions(enableCopy: true))
Copy Icon Color
The color of the icon can be changed from the default iOS blue through the copyIconColor
attribute.
That attribute takes in a UIColor
object. For example, to change the color to red, you can do the following:
textElementUITextField.setConfig(options: TextElementOptions(enableCopy: true, copyIconColor: UIColor.red))
Get Value Type
The getValueType
attribute allows you to specify the type of value that will be rendered when the Element is sent to the API.
If none is specified, the value will be rendered as a String
. The following types are supported:
getValueType Value | Type |
---|---|
.string | String |
.int | Int |
.double | Double |
.bool | Bool |
textElementUITextField.setConfig(options: TextElementOptions(getValueType: .int))