322_validation.ngdoc

@ngdoc overview
@name Tutorial: 322 Validation
@description

<div class="alert alert-warning" role="alert"><strong>Alpha</strong> This feature is in development.
There will almost certainly be breaking api changes, or there are major outstanding bugs.</div>

Feature ui.grid.validate allows validating cells after they are changed. To enable, you must include the
`ui.grid.validate` module and you must include the `ui-grid-validate` directive on your grid element.

This feature depends on ui.grid.edit.

Documentation for the validation feature is provided in the api documentation, in particular:

- {@link api/ui.grid.validate.api:PublicApi publicApi}

## Validators

Validation is based on validation functions defined at service level (thus valid through all the application).

Some custom validators come with the feature and are:

- `required`: to ensure that a field is not empty.
- `minLength`: to ensure that the value inserted is at least X characters long.
- `maxLength`: to ensure that the value inserted is at most X characters long.

To define a new validator you should use the {@link
api/ui.grid.validate.service:uiGridValidateService#methods_setValidator setValidator} method.

To add a validator to a column you just need to add a `validators` property to its `colDef`
object, containing a property for each validator you want to add. The name of the property
will set the validator and the value of the property will be treated as an argument by the validator function.

When a field does not pass validation it gets a `invalid` class so you can customize it via css.

The feature adds 2 templates to ui-grid:

- `cellTitleValidator` which adds the error message to the title attribute of the cell.
- `cellTooltipValidator` which depends on ui-bootstrap to add a tooltip.

## External Factory

In case you have an external service providing validators, you can add a function calling said service
by setting an external validator factory function via {@link
api/ui.grid.validate.service:uiGridValidateService#methods_setExternalFactoryFunction setExternalFactoryFunction}.

Please be advised that external validators should accept the same parameters (or at least an ordered subset) as
our validators do (`oldValue`, `newValue`, `rowEntity`, `colDef`);

For better performance with the following example, you can choose to load the ui-grid.core.js and specific feature files instead:
<pre>
  <script src="/release/ui-grid.core.min.js"></script>
  <script src="/release/ui-grid.cellnav.min.js"></script>
  <script src="/release/ui-grid.edit.min.js"></script>
  <script src="/release/ui-grid.validate.min.js"></script>
</pre>

@example
<example module="app">
  <file name="app.js">
    var app = angular.module('app', ['ngTouch', 'ui.grid', 'ui.grid.edit', 'ui.grid.cellNav', 'ui.grid.validate', 'addressFormatter']);

    angular.module('addressFormatter', []).filter('address', function () {
      return function (input) {
          return input.street + ', ' + input.city + ', ' + input.state + ', ' + input.zip;
      };
    });

    app.controller('MainCtrl', ['$scope', '$http', '$window', 'uiGridValidateService', function ($scope, $http, $window, uiGridValidateService) {

      uiGridValidateService.setValidator('startWith',
        function(argument) {
          return function(oldValue, newValue, rowEntity, colDef) {
            if (!newValue) {
              return true; // We should not test for existence here
            } else {
              return newValue.startsWith(argument);
            }
          };
        },
        function(argument) {
          return 'You can only insert names starting with: "' + argument + '"';
        }
      );

      $scope.gridOptions = { enableCellEditOnFocus: true };

      $scope.gridOptions.columnDefs = [
        { name: 'id', enableCellEdit: false, width: '10%' },
        { name: 'name', displayName: 'Name (editable)', width: '20%',
          validators: {required: true, startWith: 'M'}, cellTemplate: 'ui-grid/cellTitleValidator' }
      ];



     $scope.msg = {};

     $scope.gridOptions.onRegisterApi = function(gridApi){
              //set gridApi on scope
              $scope.gridApi = gridApi;
              gridApi.validate.on.validationFailed($scope,function(rowEntity, colDef, newValue, oldValue){
                $window.alert('rowEntity: '+ rowEntity + '\n' +
                              'colDef: ' + colDef + '\n' +
                              'newValue: ' + newValue + '\n' +
                              'oldValue: ' + oldValue);
              });
            };

      $http.get('/data/500_complex.json')
        .then(function(response) {
          $scope.gridOptions.data = response.data;
        });
    }]);
  });
  </file>
  <file name="index.html">
    <div ng-controller="MainCtrl">
      <div ui-grid="gridOptions" ui-grid-edit ui-grid-cellNav ui-grid-validate class="grid"></div>
    </div>
  </file>
  <file name="main.css">
    .grid {
      width: 600px;
      height: 450px;
    }
  </file>
</example>