Merge pull request #4635 from imbalind/validate

feature(validation): add validation feature

misc/tutorial/322_validation.ngdoc

@@ -0,0 +1,119 @@
+@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` wich adds the error message to the title attribute of the cell.
+- `cellTooltipValidator` wich 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 (`newValue`, `oldValue`, `rowEntity`, `colDef`);
+
+@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(newValue, oldValue, 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')
+        .success(function(data) {
+          $scope.gridOptions.data = 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>