Options
Mask
Element masks enable user input to be restricted and formatted to meet a pre-defined format. A mask
can be defined programmatically using the ElementMask
class, or in an XML layout file as a pattern String
.
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto">
<com.basistheory.android.view.TextElement
android:id="@+id/masked_value"
android:layout_width="match_parent"
android:layout_height="wrap_content"
app:bt_mask="###-##-####" />
</layout>
When setting a mask programmatically, the ElementMask
class supports two constructors:
ElementMask(characterMasks: List<Any>)
: a list of character-wise values defining the allowable input for each character position. Each character position either defines a static value in the mask (specified as aChar
or single characterString
) or a range of allowable characters (specified as aRegex
object).
For example, to support US Social Security Numbers of the form 123-45-6789
, you can specify the mask as:
val digit = Regex("""\d""")
element.mask = ElementMask(listOf(digit, digit, digit, "-", digit, digit, "-", digit, digit, digit, digit))
ElementMask(pattern: String)
: specifies a range of allowable characters using the wildcard characters:#
: numeric value, equivalent toRegex("""\d""")
x
: alphabetic value, equivalent toRegex("[A-Za-z]")
*
: any value, equivalent toRegex(".")
For example, to support US Social Security Numbers of the form 123-45-6789
, you can specify the
mask as:
element.mask = ElementMask("###-##-####")
Transform
Element transforms define functions that mutate the value of the element prior to tokenization and when computing properties published within ChangeEvents.
The following types of transforms are supported:
RegexReplaceElementTransform
Replaces all matches of the given regular expression with the replacement text.
// removes all non-numeric characters
element.transform = RegexReplaceElementTransform(
regex = Regex("[^\\d]"),
replacement = ""
)
Validator
Element validators define functions to determine whether the value of the Element is considered valid. Validators are executed on the transformed Element value.
The validation state of an Element is only used when computing ChangeEvents
and all invalid state behavior (e.g., styling changes, displaying validation errors,
disabling submit buttons) are expected to be implemented within your application in response to ChangeEvents
.
The following types of validators are supported:
RegexValidator
Matches the input value against the given regular expression.
// validates that the value only contains 3-4 digits
element.validator = RegexValidator(
regex = Regex("^\\d{3,4}$")
)
LuhnValidator
Validates that the input value is a Luhn-valid credit card number. This is the default validator for the CardNumberElement.
element.validator = LuhnValidator()
FutureDateValidator
Validates that the input value is a future date of the form MM/yy
. This is the default
validator for the CardExpirationDateElement.
element.validator = FutureDateValidator()
Input Types
All Elements expose an inputType
property to indicate the content type of the Element.
This property can be set via XML using the android:inputType
attribute. This property can be used to control the virtual keyboard type displayed while editing an Element and
also whether data entered into an Element will be displayed or hidden (replaced with dots) on the device's screen.
Enum Value | XML Attribute Value | Keyboard Type | Display Format |
---|---|---|---|
TEXT | text | Alphanumeric | Plaintext |
NUMBER | number | Numeric | Plaintext |
TEXT_PASSWORD | textPassword | Alphanumeric | Hidden |
NUMBER_PASSWORD | numberPassword | Numeric | Hidden |
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 |
---|---|
ElementValueType.STRING | String |
ElementValueType.INTEGER | Int |
ElementValueType.DOUBLE | Double |
ElementValueType.BOOLEAN | Boolean |
element.getValueType = ElementValueType.INTEGER
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.
element.enableCopy = true
Copy Icon Color
The color of the icon can be changed from the default black through the copyIconColor
attribute.
That attribute takes in a int
value. For example, to change the color to red, you can do the following:
element.copyIconColor = Color.RED
The android.graphics
package has a number of color constants that can be used, but you can use any custom colors by encoding them as integers.
Styling
Elements have been designed to take advantage of all pre-existing native layout properties available on a FrameLayout, as well as several additional styling customizations typically available to a native EditText view.
Styling in XML
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto">
<com.basistheory.android.TextElement
android:id="@+id/my_text_element"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="@drawable/my_custom_background"
android:padding="5dp"
android:text="Initial Value"
android:hint="Placeholder"
android:textColor="@color/my_color"
android:typeface="sans"
android:gravity="center" />
</layout>
See TextElement for an exhaustive list of supported XML attributes.
Styling Programmatically
val textElement = binding.myTextElement // or findViewById<TextElement>(R.id.my_text_element)
textElement.setPadding(5, 5, 5, 5)
textElement.hint = "Placeholder"
textElement.textColor = Color.CYAN
textElement.background = Color.WHITE.toDrawable()
textElement.typeface = getFont(requireContext(), R.font.my_custom_font)
textElement.gravity = Gravity.CENTER
See TextElement for an exhaustive list of supported properties.