Skip to content

Commit 74fac45

Browse files
mheverymhevery
committed
doc($filter): added $filter documentation
1 parent f0fa5e6 commit 74fac45

10 files changed

Lines changed: 115 additions & 64 deletions

File tree

‎docs/spec/ngdocSpec.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -547,7 +547,7 @@ describe('ngdoc', function() {
547547
});
548548
doc.html_usage_filter(dom);
549549
expect(dom).toContain('myFilter_expression | myFilter:b');
550-
expect(dom).toContain('angular.filter.myFilter(a, b)');
550+
expect(dom).toContain('$filter(\'myFilter\')(a, b)');
551551
});
552552
});
553553

‎docs/src/ngdoc.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -380,9 +380,9 @@ Doc.prototype = {
380380

381381
dom.h('In JavaScript', function() {
382382
dom.tag('code', function() {
383-
dom.text('angular.filter.');
383+
dom.text('$filter(\'');
384384
dom.text(self.shortName);
385-
dom.text('(');
385+
dom.text('\')(');
386386
self.parameters(dom, ', ');
387387
dom.text(')');
388388
});

‎src/service/filter.js‎

Lines changed: 87 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,87 @@
11
'use strict';
22

3+
/**
4+
* @ngdoc object
5+
* @name angular.module.NG.$filterProvider
6+
* @description
7+
*
8+
* Filters are just functions which transform input to an output. However filters need to be Dependency Injected. To
9+
* achieve this a filter definition consists of a factory function which is annotated with dependencies and is
10+
* responsible for creating a the filter function.
11+
*
12+
* <pre>
13+
* // Filter registration
14+
* function MyModule($provide, $filterProvider) {
15+
* // create a service to demonstrate injection (not always needed)
16+
* $provide.value('greet', function(name){
17+
* return 'Hello ' + name + '!':
18+
* });
19+
*
20+
* // register a filter factory which uses the
21+
* // greet service to demonstrate DI.
22+
* $filterProvider.register('greet', function(greet){
23+
* // return the filter function which uses the greet service
24+
* // to generate salutation
25+
* return function(text) {
26+
* // filters need to be forgiving so check input validity
27+
* return text && greet(text) || text;
28+
* };
29+
* };
30+
* }
31+
* </pre>
32+
*
33+
* The filter function is registered with the `$injector` under the filter name suffixe with `$Filter`.
34+
* <pre>
35+
* it('should be the same instance', inject(
36+
* function($filterProvider) {
37+
* $filterProvider.register('reverse', function(){
38+
* return ...;
39+
* });
40+
* },
41+
* function($filter, revers$Filter) {
42+
* expect($filter('reverse')).toBe(reverse$Filter);
43+
* });
44+
* </pre>
45+
*
46+
*
47+
* For more information about how angular filters work, and how to create your own filters, see
48+
* {@link guide/dev_guide.templates.filters Understanding Angular Filters} in the angular Developer
49+
* Guide.
50+
*/
51+
/**
52+
* @ngdoc method
53+
* @name angular.module.NG.$filterProvider#register
54+
* @methodOf angular.module.NG.$filterProvider
55+
* @description
56+
* Register filter factory function.
57+
*
58+
* @param {String} name Name of the filter.
59+
* @param {function} fn The filter factory function which is injectable.
60+
*/
61+
62+
63+
/**
64+
* @ngdoc function
65+
* @name angular.module.NG.$filter
66+
* @function
67+
* @description
68+
* Filters are used for formatting data displayed to the user.
69+
*
70+
* The general syntax in templates is as follows:
71+
*
72+
* {{ expression | [ filter_name ] }}
73+
*
74+
* @param {String} name Name of the filter function to retrieve
75+
* @return {Function} the filter function
76+
*/
377
$FilterProvider.$inject = ['$provide'];
478
function $FilterProvider($provide) {
579
var suffix = '$Filter';
680

7-
$provide.filter = function(name, factory) {
81+
function register(name, factory) {
882
return $provide.factory(name + suffix, factory);
983
};
84+
this.register = register;
1085

1186
this.$get = ['$injector', function($injector) {
1287
return function(name) {
@@ -16,15 +91,15 @@ function $FilterProvider($provide) {
1691

1792
////////////////////////////////////////
1893

19-
$provide.filter('currency', currencyFilter);
20-
$provide.filter('date', dateFilter);
21-
$provide.filter('filter', filterFilter);
22-
$provide.filter('html', htmlFilter);
23-
$provide.filter('json', jsonFilter);
24-
$provide.filter('limitTo', limitToFilter);
25-
$provide.filter('linky', linkyFilter);
26-
$provide.filter('lowercase', lowercaseFilter);
27-
$provide.filter('number', numberFilter);
28-
$provide.filter('orderBy', orderByFilter);
29-
$provide.filter('uppercase', uppercaseFilter);
94+
register('currency', currencyFilter);
95+
register('date', dateFilter);
96+
register('filter', filterFilter);
97+
register('html', htmlFilter);
98+
register('json', jsonFilter);
99+
register('limitTo', limitToFilter);
100+
register('linky', linkyFilter);
101+
register('lowercase', lowercaseFilter);
102+
register('number', numberFilter);
103+
register('orderBy', orderByFilter);
104+
register('uppercase', uppercaseFilter);
30105
}

‎src/service/filter/filter.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
'use strict';
22

33
/**
4-
* @ngdoc function
5-
* @name angular.service.filter.filter
4+
* @ngdoc filter
5+
* @name angular.module.NG.$filter.filter
66
* @function
77
*
88
* @description

‎src/service/filter/filters.js‎

Lines changed: 13 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,8 @@
11
'use strict';
22

3-
/**
4-
* @ngdoc overview
5-
* @name angular.filter
6-
* @description
7-
*
8-
* Filters are used for formatting data displayed to the user.
9-
*
10-
* The general syntax in templates is as follows:
11-
*
12-
* {{ expression | [ filter_name ] }}
13-
*
14-
* Following is the list of built-in angular filters:
15-
*
16-
* * {@link angular.filter.currency currency}
17-
* * {@link angular.filter.date date}
18-
* * {@link angular.filter.html html}
19-
* * {@link angular.filter.json json}
20-
* * {@link angular.filter.linky linky}
21-
* * {@link angular.filter.lowercase lowercase}
22-
* * {@link angular.filter.number number}
23-
* * {@link angular.filter.uppercase uppercase}
24-
*
25-
* For more information about how angular filters work, and how to create your own filters, see
26-
* {@link guide/dev_guide.templates.filters Understanding Angular Filters} in the angular Developer
27-
* Guide.
28-
*/
29-
303
/**
314
* @ngdoc filter
32-
* @name angular.filter.currency
5+
* @name angular.module.NG.$filter.currency
336
* @function
347
*
358
* @description
@@ -80,7 +53,7 @@ function currencyFilter($locale) {
8053

8154
/**
8255
* @ngdoc filter
83-
* @name angular.filter.number
56+
* @name angular.module.NG.$filter.number
8457
* @function
8558
*
8659
* @description
@@ -266,7 +239,7 @@ var DATE_FORMATS_SPLIT = /((?:[^yMdHhmsaZE']+)|(?:'(?:[^']|'')*')|(?:E+|y+|M+|d+
266239

267240
/**
268241
* @ngdoc filter
269-
* @name angular.filter.date
242+
* @name angular.module.NG.$filter.date
270243
* @function
271244
*
272245
* @description
@@ -391,7 +364,7 @@ function dateFilter($locale) {
391364

392365
/**
393366
* @ngdoc filter
394-
* @name angular.filter.json
367+
* @name angular.module.NG.$filter.json
395368
* @function
396369
*
397370
* @description
@@ -427,27 +400,29 @@ function jsonFilter() {
427400

428401
/**
429402
* @ngdoc filter
430-
* @name angular.filter.lowercase
403+
* @name angular.module.NG.$filter.lowercase
431404
* @function
432-
*
405+
* @description
406+
* Converts string to lowercase.
433407
* @see angular.lowercase
434408
*/
435409
var lowercaseFilter = valueFn(lowercase);
436410

437411

438412
/**
439413
* @ngdoc filter
440-
* @name angular.filter.uppercase
414+
* @name angular.module.NG.$filter.uppercase
441415
* @function
442-
*
416+
* @description
417+
* Converts string to uppercase.
443418
* @see angular.uppercase
444419
*/
445420
var uppercaseFilter = valueFn(uppercase);
446421

447422

448423
/**
449424
* @ngdoc filter
450-
* @name angular.filter.html
425+
* @name angular.module.NG.$filter.html
451426
* @function
452427
*
453428
* @description
@@ -539,6 +514,7 @@ var uppercaseFilter = valueFn(uppercase);
539514
</doc:scenario>
540515
</doc:example>
541516
*/
517+
//TODO(misko): turn sensitization into injectable service
542518
function htmlFilter() {
543519
return function(html, option){
544520
return new HTML(html, option);
@@ -548,7 +524,7 @@ function htmlFilter() {
548524

549525
/**
550526
* @ngdoc filter
551-
* @name angular.filter.linky
527+
* @name angular.module.NG.$filter.linky
552528
* @function
553529
*
554530
* @description

‎src/service/filter/limitTo.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
/**
44
* @ngdoc function
5-
* @name angular.service.filter.limitTo
5+
* @name angular.module.NG.$filter.limitTo
66
* @function
77
*
88
* @description

‎src/service/filter/orderBy.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
/**
44
* @ngdoc function
5-
* @name angular.Array.orderBy
5+
* @name angular.module.NG.$filter.orderBy
66
* @function
77
*
88
* @description

‎test/directivesSpec.js‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ describe("directive", function() {
4141
expect(lowercase(element.html())).toEqual('<div onclick="">hello</div>');
4242
}));
4343

44-
it('should set element element', inject(function($rootScope, $compile, $provide) {
45-
$provide.filter('myElement', valueFn(function() {
44+
it('should set element element', inject(function($rootScope, $compile, $filterProvider) {
45+
$filterProvider.register('myElement', valueFn(function() {
4646
return jqLite('<a>hello</a>');
4747
}));
4848
var element = $compile('<div ng:bind="0|myElement"></div>')($rootScope);
@@ -73,9 +73,9 @@ describe("directive", function() {
7373
expect(element.text()).toEqual('Hello Misko!');
7474
}));
7575

76-
it('should have $element set to current bind element', inject(function($rootScope, $compile, $provide) {
76+
it('should have $element set to current bind element', inject(function($rootScope, $compile, $filterProvider) {
7777
var innerText;
78-
$provide.filter('myFilter', valueFn(function(text) {
78+
$filterProvider.register('myFilter', valueFn(function(text) {
7979
innerText = innerText || this.$element.text();
8080
return text;
8181
}));

‎test/service/filter/filtersSpec.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ describe('filters', function() {
88
filter = $filter;
99
}));
1010

11-
it('should called the filter when evaluating expression', inject(function($rootScope, $provide) {
11+
it('should called the filter when evaluating expression', inject(function($rootScope, $filterProvider) {
1212
var filter = jasmine.createSpy('myFilter');
13-
$provide.filter('myFilter', valueFn(filter));
13+
$filterProvider.register('myFilter', valueFn(filter));
1414

1515
$rootScope.$eval('10|myFilter');
1616
expect(filter).toHaveBeenCalledWith(10);

‎test/service/parseSpec.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -191,8 +191,8 @@ describe('parser', function() {
191191
expect(scope.$eval("'a' + 'b c'")).toEqual("ab c");
192192
});
193193

194-
it('should parse filters', inject(function($provide) {
195-
$provide.filter('substring', valueFn(function(input, start, end) {
194+
it('should parse filters', inject(function($filterProvider) {
195+
$filterProvider.register('substring', valueFn(function(input, start, end) {
196196
return input.substring(start, end);
197197
}));
198198

0 commit comments

Comments
 (0)