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

If no transform is set, the value is sent to be tokenized as is, including the mask, if set.

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

Validation is performed on the transformed value when transform is set. Had a transform not been set above removing the parentheses and dashes, the validation would be performed on a value like (123)456-7890. The proper NSRegularExpression pattern for that would be "^\\(\\d{3}\\)\\d{3}-\\d{4}$"