Every Onit app builder wants to avoid bad data. The values entered into your forms are only helpful if they are valid, without typos or other errors. If you ask a user to enter a phone number, but they forget the area code, the data may not be useable.
That’s where Field-level validation comes in. Onit enables you to build custom Field validation rules to match against any type of data. When a user enters data into a Field, the validation rule runs in real-time (before the user submits the overall form) and kicks back an error to the user if the validation rule fails. A failed validation rule also prevents a user from submitting the form.
For example, you could build a Field validation that ensures the value entered matches that of a standard phone number: 888-555-1234. If a user entered a value that didn’t match this pattern, the validation would fail.
You can build custom Field validations that match any pattern you like, not just phone numbers. For example, a custom ID number that your company uses, a social security number, whatever you need. This is done using Regular Expressions, which are a special text string for describing a search pattern. If you’ve never used regular expressions before, you can think of them as robust pattern matchers.
In this tutorial, we’ll build a validation for a phone_number Field.
Before We Start ...
This tutorial will assume you understand the following concepts:
Additionally, it will be helpful to understand the basics of how Regular Expressions work. Regular Expressions, (often known by their nickname: RegEx), allow you to define a method for searching and matching text -- in our case Field inputs. RegEx is a standard tool used in software (not just in Onit), so there is a wealth of information online about it. If you’re brand new to RegEx, we recommend that you check out 8 Regular Expressions You Should Know and Regex Quick Start.
While, at first, RegEx can be a bit of a headache to learn and write, keep in mind that if you need to a validate a pretty standard expression (like a phone number) you can probably find a pattern online that you can borrow.
Let's Get Started!
In this tutorial, we’ll create a Validator that checks a user’s input to see that it is in an acceptable phone number format.
1. Add a New Regex Validator
Browse to an App’s Advanced Designer page. In the left-hand pane, select the Validators node.
Click the Plus button to add a Regex validator.
2. Configure Your Validator
Provide a Name for your Validator.
In the Input Mask property, provide your Regex pattern, prepended with a # character.
In Onit, the # character tells the system, “Hey, I’m about to enter some RegEx.” Onit will then interpret everything to the right of the # as a RegEx pattern. There other places in Onit where you will use this same approach (e.g., when filtering transactions on an app’s Dashboard).
Provide a Validation Message, which will display when a user hovers over an invalid Field input, coaching him/her to follow a certain format.
Save your new Validator by selecting OK.
3. Attach Your Validator to a Field
Lastly, we'll need to attach our Validator to the Field it should validate. Jump over to the Wizard and browse to your Fields screen.
For the Field you need validated, select your newly created Validator from the Validator property's dropdown. In our example, we'll attach our Phone Number Validation to a phone_number Field.
Test Out the Validator
Congrats! You’ve just created your very own Validator.
Launch a new transaction to test it out.