/ S

This page covers a next version of Handsontable, and is not published yet.

This page covers a non-latest version of Handsontable.

# Cell validator

Table of contents

When you create a validator, a good idea is to assign it as an alias that will refer to this particular validator function. Handsontable defines 5 aliases by default:

  • autocomplete for Handsontable.validators.AutocompleteValidator
  • date for Handsontable.validators.DateValidator
  • dropdown for Handsontable.validators.DropdownValidator
  • numeric for Handsontable.validators.NumericValidator
  • time for Handsontable.validators.TimeValidator

It gives users a convenient way for defining which validator should be used when table validation was triggered. User doesn't need to know which validator function is responsible for checking the cell value, he does not even need to know that there is any function at all. What is more, you can change the validator function associated with an alias without a need to change code that defines a table.

# Registering custom cell validator

To register your own alias use Handsontable.validators.registerValidator() function. It takes two arguments:

  • validatorName - a string representing a validator function
  • validator - a validator function that will be represented by validatorName

If you'd like to register creditCardValidator under alias credit-card you have to call:

Handsontable.validators.registerValidator('credit-card', creditCardValidator);

Choose aliases wisely. If you register your validator under name that is already registered, the target function will be overwritten:

Handsontable.validators.registerValidator('date', creditCardValidator);

Now 'date' alias points to creditCardValidator function, not Handsontable.validators.DateValidator.

So, unless you intentionally want to overwrite an existing alias, try to choose a unique name. A good practice is prefixing your aliases with some custom name (for example your GitHub username) to minimize the possibility of name collisions. This is especially important if you want to publish your validator, because you never know aliases has been registered by the user who uses your validator.

Handsontable.validators.registerValidator('credit-card', creditCardValidator);

Someone might already registered such alias.

Handsontable.validators.registerValidator('my.credit-card', creditCardValidator);

That's better.

# Using an alias

The final touch is to use the registered aliases, so that users can easily refer to it without the need to now the actual validator function is.

To sum up, a well prepared validator function should look like this:

(Handsontable => {
  function customValidator(query, callback) {
    // ...your custom logic of the validator

    callback(/* Pass `true` or `false` based on your logic */);
  }

  // Register an alias
  Handsontable.validators.registerValidator('my.custom', customValidator);

})(Handsontable);

From now on, you can use customValidator like so:

const container = document.querySelector('#container')
const hot = new Handsontable(container, {
  columns: [{
    validator: 'my.custom'
  }]
});

Use the validator method to easily validate synchronous or asynchronous changes to a cell. If you need more control, beforeValidate and afterValidate plugin hooks are available. In the below example, email_validator_fn is an async validator that resolves after 1000 ms.

Use the allowInvalid option to define if the grid should accept input that does not validate. If you need to modify the input (e.g., censor bad words, uppercase first letter), use the plugin hook beforeChange.

By default, all invalid cells are marked by htInvalid CSS class. If you want to change class to another you can basically add the invalidCellClassName option to Handsontable settings. For example:

For whole table

invalidCellClassName: 'myInvalidClass'

For specific columns

columns: [
  { data: 'firstName', invalidCellClassName: 'myInvalidClass' },
  { data: 'lastName', invalidCellClassName: 'myInvalidSecondClass' },
  { data: 'address' }
]

Callback console log:

    Edit the above grid to see callback

    Note: Please keep in mind that changes in table are applied after running all validators (both synchronous and and asynchronous) from every changed cells.

    ← Cell type →