Validating Data Items

The library provides a special extension to validate data in dhtmlxGrid on the client side (for server-side validation use the dhtmlxConnector library).

Enabling validation

Validation can be enabled for a whole column or for a specific cell.

Per-column validation

To validate grid's column, call the setColValidators method to assign validators to columns:

mygrid = new dhtmlXGridObject('gridbox');  
mygrid.setSkin("dhx_skyblue");                
mygrid.setImagePath("./codebase/imgs/");       
mygrid.setHeader("Name,Email,Age"); 
mygrid.setColValidators("NotEmpty,ValidEmail,ValidInteger"); mygrid.init();

After these 2 steps are performed each time when the user finishes editing validation will be triggered.

Related sample:  Basic validation


To set several validators to the same column, call the setColValidators as in:

mygrid.setColValidators(["ValidInteger,ValidEmail","ValidEmail"]);
//the 1st column has 2 validators assigned: "ValidInteger" and "ValidEmail"
//the 2nd column has 1 validator assigned: "ValidEmail"


If you need to define validation rules just for some columns, set an empty or 'null' value for the columns which shouldn't be affected by validation.

mygrid.setColValidators("ValidInteger,,,ValidEmail");
//or
mygrid.setColValidators(["ValidInteger",null,null,"ValidEmail"]);

Per-cell validation

To validate a grid's cell:

  1. Call the enableValidation() method to enable the cell-level validation:
    mygrid = new dhtmlXGridObject('gridbox');  
    mygrid.setSkin("dhx_skyblue");                
    mygrid.setImagePath("./codebase/imgs/");       
    mygrid.setHeader("Name,Email,Age"); 
    mygrid.enableValidation(true); mygrid.init();
  2. Call the setAttribute method to assign a validator to a cell:
    mygrid = new dhtmlXGridObject('gridbox');  
    mygrid.setSkin("dhx_skyblue");                
    mygrid.setImagePath("./codebase/imgs/");       
    mygrid.setHeader("Name,Email,Age"); 
    mygrid.enableValidation(true); mygrid.init();
    mygrid.load("data/grid.php");
    mygrid.cells(mygrid.getSelectedId(),0).setAttribute("validate","NotEmpty");

Related sample:  Per cell rules


If you configure the grid from XML, you can assign validators directly in the XML file:

Assigning validators directly in an XML file

<row id="11">
    <cell validate="NotEmpty">some</cell>
    <cell>some value</cell>
    <cell>some value</cell>
</row>

Forcing validation

To force validation for a certain cell manually use the validateCell method:

mygrid = new dhtmlXGridObject('gridbox');  
mygrid.setSkin("dhx_skyblue");                
mygrid.setImagePath("./codebase/imgs/");       
mygrid.setHeader("Name,Email,Age"); 
mygrid.enableValidation(true); 
mygrid.init();
mygrid.load("data/grid.php");
mygrid.validateCell(1,1,dhtmlxValidation.isValidTime);

Related sample:  Forced validation

Validation rules

There are 2 types of validation rules:

  1. Standard rules.
  2. Custom rules.

Standard rules

Standard rules are the following:

  • Empty - must be empty;
  • NotEmpty - must contain at least one symbol;
  • ValidAplhaNumeric;
  • ValidBoolean - can contain one of 4 values: 'true', 'false', 0 or 1;
  • ValidCurrency;
  • ValidDate (value from 0000-00-00 to 9999-12-31);
  • ValidDatetime (value from 0000-00-00 00:00:00 to 9999:12:31 59:59:59);
  • ValidEmail;
  • ValidInteger;
  • ValidIPv4 (value from 0.0.0.0 to 255.255.255.255);
  • ValidNumeric;
  • ValidSIN (Social Insurance Number);
  • ValidSSN (Social Security Number);
  • ValidTime (value from 00:00:00 to 59:59:59).

Custom rules

To create a custom rule define a new method for the dhtmlxValidation object and use the name of that method as the name of the rule.

Note,

  • The method's name must start from 'is'.
  • While specifying the method, the prefix 'is' must be omitted.
  • The method takes only 1 parameter - the value of the cell. Returns true if validation is successful and false, otherwise.
dhtmlxValidation.isMin4=function(data){ // data should include more than 4 symbols    return data.length>=4;};dhtmlxValidation.isMax10=function(data){// data should include less than 10 symbols    return data.length<=10;};mygrid = new dhtmlXGridObject('gridbox');  
mygrid.setSkin("dhx_skyblue");                
mygrid.setImagePath("./codebase/imgs/");       
mygrid.setColValidators("Min4,Max10"); mygrid.init();

Related sample:  Custom rule


In case you want to validate a cell just if it contains something (i.e. don't validate the cell if it's empty), use the following technique:

dhtmlxValidation.isGreater100=function(data){
    if (data=="") return true;// returns 'true' if a cell is empty
    return (data>100);
};
mygrid = new dhtmlXGridObject('gridbox');  
mygrid.setSkin("dhx_skyblue");                
mygrid.setImagePath("./codebase/imgs/");       
mygrid.setHeader("Name,Email,Age"); 
mygrid.setColValidators("Greater100,,"); mygrid.init();

Working modes

Validation can be used in 2 modes:

  1. Basic;
  2. Live.

Basic mode

The basic mode is enabled by default and invokes validation just after the user finishes editing. In the live mode validation is executed on each keystroke (during the editing process).

Live mode

To enable the live mode call the enableValidation method with two true parameters.

Enabling the live update mode

mygrid = new dhtmlXGridObject('gridbox');  
mygrid.setSkin("dhx_skyblue");                
mygrid.setImagePath("./codebase/imgs/");       
mygrid.setHeader("Name,Email,Age"); 
mygrid.enableValidation(true, true); mygrid.setColValidators("NotEmpty,ValidEmail");mygrid.init();
  • The methods and techniques used of the live mode are exactly the same as those of the basic mode.
  • When an input fails validation in the live mode, it's get marked with the dhtmlx_live_validation_error css class.
  • If a user ignores the validation mark and continues editing the incorrect value, after he finishes the editing, the logic of the basic mode will be applied to the input, i.e. dhtmlx_live_validation_error will be changed to dhtmlx_validation_error and the related events will be generated.

Related sample:  Live validation

Validation events

The 'validation' extension provides the following validation-related events:

Basic mode

mygrid.attachEvent("onValidationCorrect",function(id,ind,value){
    mygrid.setCellTextStyle(id,ind,"");
    document.getElementById('message').innerHTML="";
    return false;
});

Related sample:  Basic custom validation

Live mode

mygrid.attachEvent("onLiveValidationError",function(id,ind,value){
    document.getElementById('message').innerHTML="Error at cell ("+id+","+ind
    +"), value must "+(ind==0?"not be empty":"be a valid email");
    return false;
});
mygrid.attachEvent("onLiveValidationCorrect",function(id,ind,value){
    document.getElementById('message').innerHTML="";
    return false;
});

Related sample:  Live custom validation

Common events

You can also use the onCellChanged and onEditCell events for validation purposes. Note, while using these events you don't need to include the source file of the 'validation' extension on your page.

Using common dhtmlxGrid events for validation

mygrid.attachEvent("onCellChanged",function(id,index,value){
     if (index == SOME && !some_check(value))
          grid.cellById(id,index).setCValue("invalid");
})
//or
mygrid.attachEvent("onEditCell",function(stage,id,index,new_value,old_value){
     if (stage == 2 && index == SOME && !some_check(new_value))
          return false; //deny edit operation
})

Styling

When an input fails validation it's get marked with a special css class.

  • For the basic mode - dhtmlx_validation_error.
  • For the live mode - dhtmlx_live_validation_error.

To set custom styling you should redefine the related css class:

<style>
.dhtmlx_validation_error{
      ... any custom marking rules here ...
}
</style>

The custom messages can be added by using validation events.

Validation and dataProcessor

The native dhtmlxGrid validation described above doesn't affect DataProcessor behaviour. What does it mean?

All changes made in the grid are sent to the server, no matter if they're correct or not. Cells that fail validation are marked with a special style but their values are saved on the server.

To block sending incorrect data to the server specify the validation rules using the API of dataProcessor, particularly the setVerificator method. dataProcessor validates data before sending it to the server and prevents saving the data that failed validation.

dp.setVerificator(1,dhtmlxValidation.isValidEmail);

Read more details on dataProcessor validation here.

Back to top