X Tutup
Skip to content

Commit 1fe7e3a

Browse files
IgorMinarIgorMinar
committed
add jsdocs for angular and filter namespaces + all filters
1 parent aec3c84 commit 1fe7e3a

File tree

2 files changed

+277
-10
lines changed

2 files changed

+277
-10
lines changed

‎src/Angular.js‎

Lines changed: 110 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,30 @@
33
if (typeof document.getAttribute == $undefined)
44
document.getAttribute = function() {};
55

6-
//The below may not be true on browsers in the Turkish locale.
6+
/**
7+
* @ngdoc
8+
* @name angular.lowercase
9+
* @function
10+
*
11+
* @description Converts string to lowercase
12+
* @param {string} value
13+
* @return {string} Lowercased string.
14+
*/
715
var lowercase = function (value){ return isString(value) ? value.toLowerCase() : value; };
16+
17+
18+
/**
19+
* @ngdoc
20+
* @name angular#uppercase
21+
* @function
22+
*
23+
* @description Converts string to uppercase.
24+
* @param {string} value
25+
* @return {string} Uppercased string.
26+
*/
827
var uppercase = function (value){ return isString(value) ? value.toUpperCase() : value; };
28+
29+
930
var manualLowercase = function (s) {
1031
return isString(s) ? s.replace(/[A-Z]/g,
1132
function (ch) {return fromCharCode(ch.charCodeAt(0) | 32); }) : s;
@@ -14,6 +35,11 @@ var manualUppercase = function (s) {
1435
return isString(s) ? s.replace(/[a-z]/g,
1536
function (ch) {return fromCharCode(ch.charCodeAt(0) & ~32); }) : s;
1637
};
38+
39+
40+
// String#toLowerCase and String#toUpperCase don't produce correct results in browsers with Turkish
41+
// locale, for this reason we need to detect this case and redefine lowercase/uppercase methods with
42+
// correct but slower alternatives.
1743
if ('i' !== 'I'.toLowerCase()) {
1844
lowercase = manualLowercase;
1945
uppercase = manualUppercase;
@@ -57,12 +83,95 @@ var _undefined = undefined,
5783
slice = Array.prototype.slice,
5884
push = Array.prototype.push,
5985
error = window[$console] ? bind(window[$console], window[$console]['error'] || noop) : noop,
86+
87+
/**
88+
* @name angular
89+
* @namespace The exported angular namespace.
90+
*/
6091
angular = window[$angular] || (window[$angular] = {}),
6192
angularTextMarkup = extensionMap(angular, 'markup'),
6293
angularAttrMarkup = extensionMap(angular, 'attrMarkup'),
6394
angularDirective = extensionMap(angular, 'directive'),
6495
angularWidget = extensionMap(angular, 'widget', lowercase),
6596
angularValidator = extensionMap(angular, 'validator'),
97+
98+
99+
/**
100+
* @ngdoc overview
101+
* @name angular.filter
102+
* @namespace Namespace for all filters.
103+
*
104+
* # Overview
105+
* Filters are a standard way to format your data for display to the user. For example, you
106+
* might have the number 1234.5678 and would like to display it as US currency: $1,234.57.
107+
* Filters allow you to do just that. In addition to transforming the data, filters also modify
108+
* the DOM. This allows the filters to for example apply css styles to the filtered output if
109+
* certain conditions were met.
110+
*
111+
*
112+
* # Standard Filters
113+
*
114+
* The Angular framework provides a standard set of filters for common operations, including:
115+
* {@link angular.filter.currency}, {@link angular.filter.json}, {@link angular.filter.number},
116+
* and {@link angular.filter.html}. You can also add your own filters.
117+
*
118+
*
119+
* # Syntax
120+
*
121+
* Filters can be part of any {@link angular.scope} evaluation but are typically used with
122+
* {{bindings}}. Filters typically transform the data to a new data type, formating the data in
123+
* the process. Filters can be chained and take optional arguments. Here are few examples:
124+
*
125+
* * No filter: {{1234.5678}} => 1234.5678
126+
* * Number filter: {{1234.5678|number}} => 1,234.57. Notice the “,” and rounding to two
127+
* significant digits.
128+
* * Filter with arguments: {{1234.5678|number:5}} => 1,234.56780. Filters can take optional
129+
* arguments, separated by colons in a binding. To number, the argument “5” requests 5 digits
130+
* to the right of the decimal point.
131+
*
132+
*
133+
* # Writing your own Filters
134+
*
135+
* Writing your own filter is very easy: just define a JavaScript function on `angular.filter`.
136+
* The framework passes in the input value as the first argument to your function. Any filter
137+
* arguments are passed in as additional function arguments.
138+
*
139+
* You can use these variables in the function:
140+
*
141+
* * `this` — The current scope.
142+
* * `$element` — The DOM element containing the binding. This allows the filter to manipulate
143+
* the DOM in addition to transforming the input.
144+
*
145+
* The following example filter reverses a text string. In addition, it conditionally makes the
146+
* text upper-case (to demonstrate optional arguments) and assigns color (to demonstrate DOM
147+
* modification).
148+
*
149+
* @example
150+
<script type="text/javascript">
151+
angular.filter.reverse = function(input, uppercase, color) {
152+
var out = "";
153+
for (var i = 0; i < input.length; i++) {
154+
out = input.charAt(i) + out;
155+
}
156+
if (uppercase) {
157+
out = out.toUpperCase();
158+
}
159+
if (color) {
160+
this.$element.css('color', color);
161+
}
162+
return out;
163+
};
164+
</script>
165+
<span ng:non-bindable="true">{{"hello"|reverse}}</span>: {{"hello"|reverse}}<br>
166+
<span ng:non-bindable="true">{{"hello"|reverse:true}}</span>: {{"hello"|reverse:true}}<br>
167+
<span ng:non-bindable="true">{{"hello"|reverse:true:"blue"}}</span>:
168+
{{"hello"|reverse:true:"blue"}}
169+
170+
* //TODO: I completely dropped a mention of using the other option (setter method), it's
171+
* confusing to have two ways to do the same thing. I just wonder if we should prefer using the
172+
* setter way over direct assignment because in the future we might want to be able to intercept
173+
* filter registrations for some reason.
174+
*/
66175
angularFilter = extensionMap(angular, 'filter'),
67176
angularFormatter = extensionMap(angular, 'formatter'),
68177
angularService = extensionMap(angular, 'service'),

‎src/filters.js‎

Lines changed: 167 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,74 @@
1+
/**
2+
* @ngdoc filter
3+
* @name angular.filter.currency
4+
* @function
5+
*
6+
* @description
7+
* Formats a number as a currency (ie $1,234.56).
8+
*
9+
* @param {number} amout Input to filter.
10+
* @returns {string} Formated number.
11+
*
12+
* @css ng-format-negative
13+
* When the value is negative, this css class is applied to the binding making it by default red.
14+
*
15+
* @example
16+
* <input type="text" name="amount" value="1234.56"/> <br/>
17+
* {{amount | currency}}
18+
*
19+
* @scenario
20+
* it('should init with 1234.56', function(){
21+
* expect(bind('amount')).toEqual('$1,234.56');
22+
* });
23+
* it('should update', function(){
24+
* element(':input[name=amount]').value('-1234');
25+
* expect(bind('amount')).toEqual('-$1,234.00');
26+
* expect(bind('amount')).toHaveColor('red');
27+
* });
28+
*/
129
angularFilter.currency = function(amount){
230
this.$element.toggleClass('ng-format-negative', amount < 0);
331
return '$' + angularFilter['number'].apply(this, [amount, 2]);
432
};
533

6-
angularFilter.number = function(amount, fractionSize){
7-
if (isNaN(amount) || !isFinite(amount)) {
34+
35+
/**
36+
* @ngdoc filter
37+
* @name angular.filter.number
38+
* @function
39+
*
40+
* @description
41+
* Formats a number as text.
42+
*
43+
* If the input is not a number empty string is returned.
44+
*
45+
* @param {(number|string)} number Number to format.
46+
* @param {(number|string)=} fractionSize Number of decimal places to round the number to. Default 2.
47+
* @returns {string} Number rounded to decimalPlaces and places a “,” after each third digit.
48+
*
49+
* @example
50+
* <span ng:non-bindable="true">{{1234.56789|number}}</span>: {{1234.56789|number}}<br/>
51+
* <span ng:non-bindable="true">{{1234.56789|number:0}}</span>: {{1234.56789|number:0}}<br/>
52+
* <span ng:non-bindable="true">{{1234.56789|number:2}}</span>: {{1234.56789|number:2}}<br/>
53+
* <span ng:non-bindable="true">{{-1234.56789|number:4}}</span>: {{-1234.56789|number:4}}
54+
*
55+
* @scenario
56+
* it('should format numbers', function(){
57+
* expect(element('span[ng\\:bind="1234.56789|number"]').val()).toBe('1,234.57');
58+
* expect(element('span[ng\\:bind="1234.56789|number:0"]').val()).toBe('1,234');
59+
* expect(element('span[ng\\:bind="1234.56789|number:2"]').val()).toBe('1,234.56');
60+
* expect(element('span[ng\\:bind="-1234.56789|number:4"]').val()).toBe('-1,234.56789');
61+
* });
62+
*/
63+
angularFilter.number = function(number, fractionSize){
64+
if (isNaN(number) || !isFinite(number)) {
865
return '';
966
}
1067
fractionSize = typeof fractionSize == $undefined ? 2 : fractionSize;
11-
var isNegative = amount < 0;
12-
amount = Math.abs(amount);
68+
var isNegative = number < 0;
69+
number = Math.abs(number);
1370
var pow = Math.pow(10, fractionSize);
14-
var text = "" + Math.round(amount * pow);
71+
var text = "" + Math.round(number * pow);
1572
var whole = text.substring(0, text.length - fractionSize);
1673
whole = whole || '0';
1774
var frc = text.substring(text.length - fractionSize);
@@ -30,6 +87,8 @@ angularFilter.number = function(amount, fractionSize){
3087
}
3188
return text;
3289
};
90+
91+
3392
function padNumber(num, digits, trim) {
3493
var neg = '';
3594
if (num < 0) {
@@ -42,6 +101,8 @@ function padNumber(num, digits, trim) {
42101
num = num.substr(num.length - digits);
43102
return neg + num;
44103
}
104+
105+
45106
function dateGetter(name, size, offset, trim) {
46107
return function(date) {
47108
var value = date['get' + name]();
@@ -51,6 +112,8 @@ function dateGetter(name, size, offset, trim) {
51112
return padNumber(value, size, trim);
52113
};
53114
}
115+
116+
54117
var DATE_FORMATS = {
55118
yyyy: dateGetter('FullYear', 4),
56119
yy: dateGetter('FullYear', 2, 0, true),
@@ -66,15 +129,32 @@ var DATE_FORMATS = {
66129
m: dateGetter('Minutes', 1),
67130
ss: dateGetter('Seconds', 2),
68131
s: dateGetter('Seconds', 1),
69-
a: function(date){return date.getHours() < 12 ? 'am' : 'pm'; },
132+
a: function(date){return date.getHours() < 12 ? 'am' : 'pm';},
70133
Z: function(date){
71134
var offset = date.getTimezoneOffset();
72135
return padNumber(offset / 60, 2) + padNumber(Math.abs(offset % 60), 2);
73136
}
74137
};
138+
139+
75140
var DATE_FORMATS_SPLIT = /([^yMdHhmsaZ]*)(y+|M+|d+|H+|h+|m+|s+|a|Z)(.*)/;
76141
var NUMBER_STRING = /^\d+$/;
77142

143+
144+
/**
145+
* @ngdoc filter
146+
* @name angular.filter.date
147+
* @function
148+
*
149+
* @description
150+
* Formats `date` to a string based on the requested `format`.
151+
*
152+
* @param {(Date|number|string)} date Date to format either as Date object or milliseconds.
153+
* @param {string=} format Formatting rules. If not specified, Date#toLocaleDateString is used.
154+
* @returns {string} Formatted string or the input if input is not recognized as date/millis.
155+
*
156+
* //TODO example + scenario
157+
*/
78158
angularFilter.date = function(date, format) {
79159
if (isString(date) && NUMBER_STRING.test(date)) {
80160
date = parseInt(date, 10);
@@ -102,23 +182,101 @@ angularFilter.date = function(date, format) {
102182
return text;
103183
};
104184

185+
186+
/**
187+
* @ngdoc filter
188+
* @name angular.filter.json
189+
* @function
190+
*
191+
* @description
192+
* Allows you to convert a JavaScript object into JSON string.
193+
*
194+
* This filter is mostly useful for debugging. When using the double curly {{value}} notation
195+
* the binding is automatically converted to JSON.
196+
*
197+
* @param {*} object Any JavaScript object (including arrays and primitive types) to filter.
198+
* @returns {string} JSON string.
199+
*
200+
* @css ng-monospace Always applied to the encapsulating element.
201+
*
202+
* @example
203+
* <span ng:non-bindable>{{ {a:1, b:[]} | json }}</span>: <pre>{{ {a:1, b:[]} | json }}</pre>
204+
*
205+
* @scenario
206+
* it('should jsonify filtered objects', function() {
207+
* expect(element('pre[ng\\:bind-template="{{ {a:1, b:[]} | json }}"]').val()).toBe(
208+
* '{\n "a":1,\n "b":[]}'
209+
* );
210+
* }
211+
*
212+
*/
105213
angularFilter.json = function(object) {
106214
this.$element.addClass("ng-monospace");
107215
return toJson(object, true);
108216
};
109217

218+
219+
/**
220+
* @ngdoc filter
221+
* @name angular.filter.lowercase
222+
* @function
223+
*
224+
* @see angular.lowercase
225+
*/
110226
angularFilter.lowercase = lowercase;
111227

228+
229+
/**
230+
* @ngdoc filter
231+
* @name angular.filter.uppercase
232+
* @function
233+
*
234+
* @see angular.uppercase
235+
*/
112236
angularFilter.uppercase = uppercase;
113237

114-
/**</>
115-
* @exportedAs filter:html
116-
* @param {string=} option if 'unsafe' then do not sanitize the HTML input
238+
239+
/**
240+
* @ngdoc filter
241+
* @name angular.filter.html
242+
* @function
243+
*
244+
* @description
245+
* Prevents the input from getting escaped by angular. By default the input is sanitized and
246+
* inserted into the DOM as is.
247+
*
248+
* The input is sanitized by parsing the html into tokens. All safe tokens (from a whitelist) are
249+
* then serialized back to properly escaped html string. This means that no unsafe input can make
250+
* it into the returned string, however since our parser is more strict than a typical browser
251+
* parser, it's possible that some obscure input, which would be recognized as valid HTML by a
252+
* browser, won't make it through the sanitizer.
253+
*
254+
* If you hate your users, you may call the filter with optional 'unsafe' argument, which bypasses
255+
* the html sanitizer, but makes your application vulnerable to XSS and other attacks. Using this
256+
* option is strongly discouraged and should be used only if you absolutely trust the input being
257+
* filtered and you can't get the content through the sanitizer.
258+
*
259+
* @param {string} html Html input.
260+
* @param {string=} option If 'unsafe' then do not sanitize the HTML input.
261+
* @returns {string} Sanitized or raw html.
117262
*/
118263
angularFilter.html = function(html, option){
119264
return new HTML(html, option);
120265
};
121266

267+
268+
/**
269+
* @ngdoc filter
270+
* @name angular.filter.linky
271+
* @function
272+
*
273+
* @description
274+
* Finds links in text input and turns them into html links. Supports http/https/ftp/mailto links.
275+
*
276+
* @param {string} text Input text.
277+
* @returns {string} Html-linkified text.
278+
*/
279+
//TODO: externalize all regexps
122280
angularFilter.linky = function(text){
123281
if (!text) return text;
124282
function regExpEscape(text) {

0 commit comments

Comments
 (0)
X Tutup