Data Validation
Overview
Validators are used to ensure that any user input into your editable cells matches your requirements.
Validators can be applied by using the validator property in a columns definition object (see Define Columns for more details).
{title:"Rating", field:"rating", editor:"input", validator:"required"}
When using validators that take properties you can pass in an object:
{title:"Rating", field:"rating", editor:"input", validator:{
type:"max",
parameters:5,
}}
Or you can use the shorthand notation, separating the type and parameter with a : symbol:
{title:"Rating", field:"rating", editor:"input", validator:"max:5"}
Validation Mode
There are three different validation modes available to customise the validation experience:
- blocking - if a user enters an invalid value while editing, they are blocked from leaving the cell until a valid value is entered (default)
- highlight - if a user enters an invalid value, then the edit will complete as usual and they are allowed to exit the cell but a highlight is applied to the cell using the tabulator-validation-fail class
- manual - no vaildation is automatically performed on edit, but it can be triggered by calling the validate function on the table or any Component Object
The validation mode can be set using the validationMode setup option:
var table = new Tabulator("#example-table", {
validationMode:"highlight", //highlight cells with validation errors but don't stop the edit
});
Validator Functions
Built In Validators
Tabulator has a wide variety of built in validators:
Note: For a guide to adding your own validators to this list, have a look at the Extending Tabulator section.
Note By default all validators, except the required validator will approve any empty value (ie. empty string, null or undefined). to ensure empty values are rejected you should use the required validator.
Required
The required validator allows values that are not null or an empty string
{title:"Example", field:"example", validator:"required"}
Unique
The unique validator allows values that do not match the value of any other cell in this column
{title:"Example", field:"example", validator:"unique"}
Integer
The integer validator allows values that are valid integers
{title:"Example", field:"example", validator:"integer"}
Float
The float validator allows values that are valid floats
{title:"Example", field:"example", validator:"float"}
Numeric
The numeric validator allows values that are valid numbers
{title:"Example", field:"example", validator:"numeric"}
String
The string validator allows values that are a non-numeric string
{title:"Example", field:"example", validator:"string"}
Minimum Numeric Value
The min validator allows numeric values that are greater than or equal to parameter
{title:"Example", field:"example", validator:"min:5"} \\value must be greater than or equal to 5
Maximum Numeric Value
The max validator allows numeric values that are less than or equal to parameter
{title:"Example", field:"example", validator:"max:5"} \\value must be less than or equal to 5
Minimum String Length
The minLength validator allows string values that have a length greater than or equal to parameter
{title:"minLength", field:"example", validator:"minLength:5"} \\value must have a length greater than or equal to 5
Maximum String Length
The maxLength validator allows string values that have a length less than or equal to parameter
{title:"Example", field:"example", validator:"maxLength:5"} \\value must have a length less than or equal to 5
In List
The in validator allows values that match a value from the | delimited string in the parameter
{title:"Example", field:"example", validator:"in:red|green|blue"} \\value must be 'red', 'green' or 'blue'
Starts With
The starts validator allows string values that start with the parameter (case insensitive)
{title:"Example", field:"example", validator:"starts:bob"} \\value must start with 'bob'
Ends With
The ends validator allows string values that start with the parameter (case insensitive)
{title:"Example", field:"example", validator:"ends:green"} \\value must end with 'green'
Regular Expression
The regex validator allows values that match the supplied regex
{title:"Example", field:"example", validator:"regex:\\.com$"} \\allow strings that end in '.com'
Validation Failure
If the validation fails the tabulator-validation-fail class will be applied to the cell and the validationFailed callback will be triggered.
The user will not be able to leave the a cell that has failed vailidation until they input a valid value or cancel the edit (press escape)
Custom Validator Functions
If you want to add your own custom validation functions, you can pass a function to the validator property. It should return true if the value passes validation and false if it fails:
//validator to prevent values divisible by the provided divisor
var noDivide = function(cell, value, parameters){
//cell - the cell component for the edited cell
//value - the new input value of the cell
//parameters - the parameters passed in with the validator
return value % parameters.divisor; //don't allow values divisible by divisor ;
}
//in your column definition for the column
{title:"Age", field:"age", editor:"input", validator:[
{
type:noDivide,
parameters:{
divisor:5,
}
}
]}
Applying Multiple Validators
You can use multiple validators on the same column by passing an array to the validator property
{title:"Rating", field:"rating", editor:"input", validator:["required", "max:5"]}
Highlight Validation
If you are using the highlight validation mode then Tabulator provides a variety of ways to check the validation state of different cells in the table.
Retrieve Invalid Cells
The getInvalidCells method returns an array of Cell Components for all cells flagged as invalid after a user edit.
var invalid = table.getInvalidCells();
Tabulator will continue to add cells to this list until the table in the data is replaced by the setData function or the invalid list is cleared.
Check Cell as Passed Validation
The isValid can be called on a Cell Component to check if a cell has previously passed a validation check without revalidating it.
var valid = cell.isValid();
This will return a value of true if every cell passes validation, or false if it fails validation.
This function is different from the validate function which actively validates the cell, the isValid function only checks to see if a user has edited the cell and that it has passed validation when that happened
Clear Invalid Validation
You can clear the invalid validation state of a cell in a couple of ways.
The clearValidation can be called on a Cell Component to clear the invalid flag used by the isValid function and mark the cell as valid.
cell.clearValidation();
Alternativly, the clearCellValidation can be called on the table to clear the invalid state on all cells in the table
table.clearCellValidation();
Or optionally you can pass in a Cell Component or an array of Cell Components to the clearCellValidation function to clear the invalid state on specific cells
table.clearCellValidation([cell1, cell2]);
Manual Validation
If you are using the manual validation mode then Tabulator provides a variety of ways to trigger validation of the table.
Table Validation
You can validate the whole table in one go by calling the validate method on the table instance.
var valid = table.validate();
This will return a value of true if every cell passes validation, if any cells fail, then it will return an array of Cell Components representing each cell that has failed validation.
Row Validation
You can validate a row by calling the validate method on any Row Component
var valid = row.validate();
This will return a value of true if every cell passes validation, if any cells fail, then it will return an array of Cell Components representing each cell in that row that has failed validation.
Column Validation
You can validate a column by calling the validate method on any Column Component
var valid = column.validate();
This will return a value of true if every cell passes validation, if any cells fail, then it will return an array of Cell Components representing each cell in that column that has failed validation.
Cell Validation
You can validate a cell by calling the validate method on any Cell Component
var valid = cell.validate();
This will return a value of true if every cell passes validation, or false if it fails validation.
Callbacks
A range of callbacks are available for validation. See the Validation Callbacks section for more information.