1+ @ngdoc overview
2+ @name Tutorial: 322 Validation
3+ @description
4+
5+ <div class="alert alert-warning" role="alert"><strong>Alpha</strong> This feature is in development.
6+ There will almost certainly be breaking api changes, or there are major outstanding bugs.</div>
7+
8+ Feature ui.grid.validate allows validating cells after they are changed. To enable, you must include the
9+ `ui.grid.validate` module and you must include the `ui-grid-validate` directive on your grid element.
10+
11+ This feature depends on ui.grid.edit.
12+
13+ Documentation for the validation feature is provided in the api documentation, in particular:
14+
15+ - {@link api/ui.grid.validate.api:PublicApi publicApi}
16+
17+ ## Validators
18+
19+ Validation is based on validation functions defined at service level (thus valid through all the application).
20+
21+ Some custom validators come with the feature and are:
22+
23+ - `required`: to ensure that a field is not empty.
24+ - `minLength`: to ensure that the value inserted is at least X characters long.
25+ - `maxLength`: to ensure that the value inserted is at most X characters long.
26+
27+ To define a new validator you should use the {@link
28+ api/ui.grid.validate.service:uiGridValidateService#methods_setValidator setValidator} method.
29+
30+ To add a validator to a column you just need to add a `validators` property to its `colDef`
31+ object, containing a property for each validator you want to add. The name of the property
32+ will set the validator and the value of the property will be treated as an argument by the validator function.
33+
34+ When a field does not pass validation it gets a `invalid` class so you can customize it via css.
35+
36+ The feature adds 2 templates to ui-grid:
37+
38+ - `cellTitleValidator` wich adds the error message to the title attribute of the cell.
39+ - `cellTooltipValidator` wich depends on ui-bootstrap to add a tooltip.
40+
41+ ## External Factory
42+
43+ In case you have an external service providing validators, you can add a function calling said service
44+ by setting an external validator factory function via {@link
45+ api/ui.grid.validate.service:uiGridValidateService#methods_setExternalFactoryFunction setExternalFactoryFunction}.
46+
47+ Please be advised that external validators should accept the same parameters (or at least an ordered subset) as
48+ our validators do (`newValue`, `oldValue`, `rowEntity`, `colDef`);
49+
50+ @example
51+ <example module="app">
52+ <file name="app.js">
53+ var app = angular.module('app', ['ngTouch', 'ui.grid', 'ui.grid.edit', 'ui.grid.cellNav', 'ui.grid.validate', 'addressFormatter']);
54+
55+ angular.module('addressFormatter', []).filter('address', function () {
56+ return function (input) {
57+ return input.street + ', ' + input.city + ', ' + input.state + ', ' + input.zip;
58+ };
59+ });
60+
61+ app.controller('MainCtrl', ['$scope', '$http', '$window', 'uiGridValidateService', function ($scope, $http, $window, uiGridValidateService) {
62+
63+ uiGridValidateService.setValidator('startWith',
64+ function(argument) {
65+ return function(newValue, oldValue, rowEntity, colDef) {
66+ if (!newValue) {
67+ return true; // We should not test for existence here
68+ } else {
69+ return newValue.startsWith(argument);
70+ }
71+ };
72+ },
73+ function(argument) {
74+ return 'You can only insert names starting with: "' + argument + '"';
75+ }
76+ );
77+
78+ $scope.gridOptions = { enableCellEditOnFocus: true };
79+
80+ $scope.gridOptions.columnDefs = [
81+ { name: 'id', enableCellEdit: false, width: '10%' },
82+ { name: 'name', displayName: 'Name (editable)', width: '20%',
83+ validators: {required: true, startWith: 'M'}, cellTemplate: 'ui-grid/cellTitleValidator' }
84+ ];
85+
86+
87+
88+ $scope.msg = {};
89+
90+ $scope.gridOptions.onRegisterApi = function(gridApi){
91+ //set gridApi on scope
92+ $scope.gridApi = gridApi;
93+ gridApi.validate.on.validationFailed($scope,function(rowEntity, colDef, newValue, oldValue){
94+ $window.alert('rowEntity: '+ rowEntity + '\n' +
95+ 'colDef: ' + colDef + '\n' +
96+ 'newValue: ' + newValue + '\n' +
97+ 'oldValue: ' + oldValue);
98+ });
99+ };
100+
101+ $http.get('/data/500_complex.json')
102+ .success(function(data) {
103+ $scope.gridOptions.data = data;
104+ });
105+ }]);
106+ });
107+ </file>
108+ <file name="index.html">
109+ <div ng-controller="MainCtrl">
110+ <div ui-grid="gridOptions" ui-grid-edit ui-grid-cellNav ui-grid-validate class="grid"></div>
111+ </div>
112+ </file>
113+ <file name="main.css">
114+ .grid {
115+ width: 600px;
116+ height: 450px;
117+ }
118+ </file>
119+ </example>
0 commit comments