-
Notifications
You must be signed in to change notification settings - Fork 9
Expand file tree
/
Copy pathangular.cix
More file actions
523 lines (523 loc) · 164 KB
/
angular.cix
File metadata and controls
523 lines (523 loc) · 164 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
<?xml version="1.0" encoding="UTF-8"?>
<codeintel description="HTML enhanced for web apps!" name="AngularJS-1.4.9" version="2.0">
<file lang="JavaScript" path="AngularJS">
<scope ilk="blob" lang="JavaScript" name="AngularJS-1.4.9">
<scope ilk="namespace" name="angular">
<scope doc="Returns a function which calls function `fn` bound to `self` (`self` becomes the `this` for
`fn`). You can supply optional `args` that are prebound to the function. This feature is also
known as [partial application](http://en.wikipedia.org/wiki/Partial_application), as
distinguished from [function currying](http://en.wikipedia.org/wiki/Currying#Contrast_with_partial_function_application).
" ilk="function" name="bind" returns="function()" signature="bind(self,args) => function()">
<variable citdl="Object" doc="Context which `fn` should be evaluated in." ilk="argument" name="self" />
<variable citdl="...*" doc="Optional arguments to be prebound to the `fn` function call." ilk="argument" name="args" />
</scope>
<scope doc="Use this function to manually start up angular application.
* See: {@link guide/bootstrap Bootstrap}
* Note that Protractor based end-to-end tests cannot use this function to bootstrap manually.
They must use {@link ng.directive:ngApp ngApp}.
* Angular will detect if it has been loaded into the browser more than once and only allow the
first loaded script to be bootstrapped and will report a warning to the browser console for
each of the subsequent scripts. This prevents strange results in applications, where otherwise
multiple instances of Angular try to work on the DOM.
* ```html
<!doctype html>
<html>
<body>
<div ng-controller="WelcomeController">
{{greeting}}
</div>
* <script src="angular.js"></script>
<script>
var app = angular.module('demo', [])
.controller('WelcomeController', function($scope) {
$scope.greeting = 'Welcome!';
});
angular.bootstrap(document, ['demo']);
</script>
</body>
</html>
```
" ilk="function" name="bootstrap" returns="auto.$injector" signature="bootstrap(element) => auto.$injector">
<variable citdl="DOMElement" doc="DOM element which is the root of angular application." ilk="argument" name="element" />
</scope>
<scope doc="Creates a deep copy of `source`, which should be an object or an array.
* * If no destination is supplied, a copy of the object or array is created.
* If a destination is provided, all of its elements (for arrays) or properties (for objects)
are deleted and then all elements/properties from the source are copied to it.
* If `source` is not an object or array (inc. `null` and `undefined`), `source` is returned.
* If `source` is identical to 'destination' an exception will be thrown.
" ilk="function" name="copy" returns="*" signature="copy() => *" />
<scope doc="Wraps a raw DOM element or HTML string as a [jQuery](http://jquery.com) element.
* If jQuery is available, `angular.element` is an alias for the
[jQuery](http://api.jquery.com/jQuery/) function. If jQuery is not available, `angular.element`
delegates to Angular's built-in subset of jQuery, called "jQuery lite" or **jqLite**.
* jqLite is a tiny, API-compatible subset of jQuery that allows
Angular to manipulate the DOM in a cross-browser compatible way. jqLite implements only the most
commonly needed functionality with the goal of having a very small footprint.
* To use `jQuery`, simply ensure it is loaded before the `angular.js` file. You can also use the
{@link ngJq `ngJq`} directive to specify that jqlite should be used over jQuery, or to use a
specific version of jQuery if multiple versions exist on the page.
* <div class="alert alert-info">**Note:** All element references in Angular are always wrapped with jQuery or
jqLite (such as the element argument in a directive's compile / link function). They are never raw DOM references.</div>
* <div class="alert alert-warning">**Note:** Keep in mind that this function will not find elements
by tag name / CSS selector. For lookups by tag name, try instead `angular.element(document).find(...)`
or `$document.find()`, or use the standard DOM APIs, e.g. `document.querySelectorAll()`.</div>
* ## Angular's jqLite
jqLite provides only the following jQuery methods:
* - [`addClass()`](http://api.jquery.com/addClass/)
- [`after()`](http://api.jquery.com/after/)
- [`append()`](http://api.jquery.com/append/)
- [`attr()`](http://api.jquery.com/attr/) - Does not support functions as parameters
- [`bind()`](http://api.jquery.com/bind/) - Does not support namespaces, selectors or eventData
- [`children()`](http://api.jquery.com/children/) - Does not support selectors
- [`clone()`](http://api.jquery.com/clone/)
- [`contents()`](http://api.jquery.com/contents/)
- [`css()`](http://api.jquery.com/css/) - Only retrieves inline-styles, does not call `getComputedStyle()`.
As a setter, does not convert numbers to strings or append 'px', and also does not have automatic property prefixing.
- [`data()`](http://api.jquery.com/data/)
- [`detach()`](http://api.jquery.com/detach/)
- [`empty()`](http://api.jquery.com/empty/)
- [`eq()`](http://api.jquery.com/eq/)
- [`find()`](http://api.jquery.com/find/) - Limited to lookups by tag name
- [`hasClass()`](http://api.jquery.com/hasClass/)
- [`html()`](http://api.jquery.com/html/)
- [`next()`](http://api.jquery.com/next/) - Does not support selectors
- [`on()`](http://api.jquery.com/on/) - Does not support namespaces, selectors or eventData
- [`off()`](http://api.jquery.com/off/) - Does not support namespaces, selectors or event object as parameter
- [`one()`](http://api.jquery.com/one/) - Does not support namespaces or selectors
- [`parent()`](http://api.jquery.com/parent/) - Does not support selectors
- [`prepend()`](http://api.jquery.com/prepend/)
- [`prop()`](http://api.jquery.com/prop/)
- [`ready()`](http://api.jquery.com/ready/)
- [`remove()`](http://api.jquery.com/remove/)
- [`removeAttr()`](http://api.jquery.com/removeAttr/)
- [`removeClass()`](http://api.jquery.com/removeClass/)
- [`removeData()`](http://api.jquery.com/removeData/)
- [`replaceWith()`](http://api.jquery.com/replaceWith/)
- [`text()`](http://api.jquery.com/text/)
- [`toggleClass()`](http://api.jquery.com/toggleClass/)
- [`triggerHandler()`](http://api.jquery.com/triggerHandler/) - Passes a dummy event object to handlers.
- [`unbind()`](http://api.jquery.com/unbind/) - Does not support namespaces or event object as parameter
- [`val()`](http://api.jquery.com/val/)
- [`wrap()`](http://api.jquery.com/wrap/)
* ## jQuery/jqLite Extras
Angular also provides the following additional methods and events to both jQuery and jqLite:
* ### Events
- `$destroy` - AngularJS intercepts all jqLite/jQuery's DOM destruction apis and fires this event
on all DOM nodes being removed. This can be used to clean up any 3rd party bindings to the DOM
element before it is removed.
* ### Methods
- `controller(name)` - retrieves the controller of the current element or its parent. By default
retrieves controller associated with the `ngController` directive. If `name` is provided as
camelCase directive name, then the controller for this directive will be retrieved (e.g.
`'ngModel'`).
- `injector()` - retrieves the injector of the current element or its parent.
- `scope()` - retrieves the {@link ng.$rootScope.Scope scope} of the current
element or its parent. Requires {@link guide/production#disabling-debug-data Debug Data} to
be enabled.
- `isolateScope()` - retrieves an isolate {@link ng.$rootScope.Scope scope} if one is attached directly to the
current element. This getter should be used only on elements that contain a directive which starts a new isolate
scope. Calling `scope()` on this element always returns the original non-isolate scope.
Requires {@link guide/production#disabling-debug-data Debug Data} to be enabled.
- `inheritedData()` - same as `data()`, but walks up the DOM until a value is found or the top
parent element is reached.
" ilk="function" name="element" returns="Object" signature="element(element) => Object">
<variable citdl="string|DOMElement" doc="HTML string or DOMElement to be wrapped into jQuery." ilk="argument" name="element" />
</scope>
<scope doc="Determines if two objects or two values are equivalent. Supports value types, regular
expressions, arrays and objects.
* Two objects or values are considered equivalent if at least one of the following is true:
* * Both objects or values pass `===` comparison.
* Both objects or values are of the same type and all of their properties are equal by
comparing them with `angular.equals`.
* Both values are NaN. (In JavaScript, NaN == NaN => false. But we consider two NaN as equal)
* Both values represent the same regular expression (In JavaScript,
/abc/ == /abc/ => false. But we consider two regular expressions as equal when their textual
representation matches).
* During a property comparison, properties of `function` type and properties with names
that begin with `$` are ignored.
* Scope and DOMWindow objects are being compared only by identify (`===`).
" ilk="function" name="equals" returns="boolean" signature="equals(o1) => boolean">
<variable citdl="*" doc="Object or value to compare." ilk="argument" name="o1" />
</scope>
<scope doc="Extends the destination object `dst` by copying own enumerable properties from the `src` object(s)
to `dst`. You can specify multiple `src` objects. If you want to preserve original objects, you can do so
by passing an empty object as the target: `var object = angular.extend({}, object1, object2)`.
* **Note:** Keep in mind that `angular.extend` does not support recursive merge (deep copy). Use
{@link angular.merge} for this.
" ilk="function" name="extend" returns="Object" signature="extend(dst) => Object">
<variable citdl="Object" doc="Destination object." ilk="argument" name="dst" />
</scope>
<scope doc="Invokes the `iterator` function once for each item in `obj` collection, which can be either an
object or an array. The `iterator` function is invoked with `iterator(value, key, obj)`, where `value`
is the value of an object property or an array element, `key` is the object property key or
array element index and obj is the `obj` itself. Specifying a `context` for the function is optional.
* It is worth noting that `.forEach` does not iterate over inherited properties because it filters
using the `hasOwnProperty` method.
* Unlike ES262's
[Array.prototype.forEach](http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.18),
Providing 'undefined' or 'null' values for `obj` will not throw a TypeError, but rather just
return the value provided.
```js
 var values = {name: 'misko', gender: 'male'};
 var log = [];
 angular.forEach(values, function(value, key) {
 this.push(key + ': ' + value);
 }, log);
 expect(log).toEqual(['name: misko', 'gender: male']);
 ```
" ilk="function" name="forEach" returns="Object|Array" signature="forEach(obj,context) => Object|Array">
<variable citdl="Object|Array" doc="Object to iterate over." ilk="argument" name="obj" />
<variable citdl="Object=" doc="Object to become context (`this`) for the iterator function." ilk="argument" name="context" />
</scope>
<scope doc="Deserializes a JSON string.
" ilk="function" name="fromJson" returns="Object|Array|string|number" signature="fromJson(json) => Object|Array|string|number">
<variable citdl="string" doc="JSON string to deserialize." ilk="argument" name="json" />
</scope>
<scope doc="A function that returns its first argument. This function is useful when writing code in the
functional style.
```js
 function transformer(transformationFn, value) {
 return (transformationFn || angular.identity)(value);
 };
 ```" ilk="function" name="identity" returns="*" signature="identity(value) => *">
<variable citdl="*" doc="to be returned." ilk="argument" name="value" />
</scope>
<scope doc="Creates an injector object that can be used for retrieving services as well as for
dependency injection (see {@link guide/di dependency injection}).
" ilk="function" name="injector" returns="injector" signature="injector() => injector" />
<scope doc="Determines if a reference is an `Array`.
" ilk="function" name="isArray" returns="boolean" signature="isArray(value) => boolean">
<variable citdl="*" doc="Reference to check." ilk="argument" name="value" />
</scope>
<scope doc="Determines if a value is a date.
" ilk="function" name="isDate" returns="boolean" signature="isDate(value) => boolean">
<variable citdl="*" doc="Reference to check." ilk="argument" name="value" />
</scope>
<scope doc="Determines if a reference is defined.
" ilk="function" name="isDefined" returns="boolean" signature="isDefined(value) => boolean">
<variable citdl="*" doc="Reference to check." ilk="argument" name="value" />
</scope>
<scope doc="Determines if a reference is a DOM element (or wrapped jQuery element).
" ilk="function" name="isElement" returns="boolean" signature="isElement(value) => boolean">
<variable citdl="*" doc="Reference to check." ilk="argument" name="value" />
</scope>
<scope doc="Determines if a reference is a `Function`.
" ilk="function" name="isFunction" returns="boolean" signature="isFunction(value) => boolean">
<variable citdl="*" doc="Reference to check." ilk="argument" name="value" />
</scope>
<scope doc="Determines if a reference is a `Number`.
* This includes the "special" numbers `NaN`, `+Infinity` and `-Infinity`.
* If you wish to exclude these then you can use the native
[`isFinite'](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/isFinite)
method.
" ilk="function" name="isNumber" returns="boolean" signature="isNumber(value) => boolean">
<variable citdl="*" doc="Reference to check." ilk="argument" name="value" />
</scope>
<scope doc="Determines if a reference is an `Object`. Unlike `typeof` in JavaScript, `null`s are not
considered to be objects. Note that JavaScript arrays are objects.
" ilk="function" name="isObject" returns="boolean" signature="isObject(value) => boolean">
<variable citdl="*" doc="Reference to check." ilk="argument" name="value" />
</scope>
<scope doc="Determines if a reference is a `String`.
" ilk="function" name="isString" returns="boolean" signature="isString(value) => boolean">
<variable citdl="*" doc="Reference to check." ilk="argument" name="value" />
</scope>
<scope doc="Determines if a reference is undefined.
" ilk="function" name="isUndefined" returns="boolean" signature="isUndefined(value) => boolean">
<variable citdl="*" doc="Reference to check." ilk="argument" name="value" />
</scope>
<scope doc="Converts the specified string to lowercase." ilk="function" name="lowercase" returns="string" signature="lowercase(string) => string">
<variable citdl="string" doc="String to be converted to lowercase." ilk="argument" name="string" />
</scope>
<scope doc="Deeply extends the destination object `dst` by copying own enumerable properties from the `src` object(s)
to `dst`. You can specify multiple `src` objects. If you want to preserve original objects, you can do so
by passing an empty object as the target: `var object = angular.merge({}, object1, object2)`.
Unlike {@link angular.extend extend()}, `merge()` recursively descends into object properties of source
objects, performing a deep copy.
" ilk="function" name="merge" returns="Object" signature="merge(dst) => Object">
<variable citdl="Object" doc="Destination object." ilk="argument" name="dst" />
</scope>
<scope doc="* The `angular.module` is a global place for creating, registering and retrieving Angular
modules.
All modules (angular core or 3rd party) that should be available to an application must be
registered using this mechanism.
* Passing one argument retrieves an existing {@link angular.Module},
whereas passing more than one argument creates a new {@link angular.Module}
*
# Module
* A module is a collection of services, directives, controllers, filters, and configuration information.
`angular.module` is used to configure the {@link auto.$injector $injector}.
* ```js
// Create a new module
var myModule = angular.module('myModule', []);
* // register a new service
myModule.value('appName', 'MyCoolApp');
* // configure existing services inside initialization blocks.
myModule.config(['$locationProvider', function($locationProvider) {
// Configure existing providers
$locationProvider.hashPrefix('!');
}]);
```
* Then you can create an injector and load your modules like this:
* ```js
var injector = angular.injector(['ng', 'myModule'])
```
* However it's more likely that you'll just use
{@link ng.directive:ngApp ngApp} or
{@link angular.bootstrap} to simplify this process for you.
" ilk="function" name="module" returns="angular.Module" signature="module(name) => angular.Module">
<variable citdl="!string" doc="The name of the module to create or retrieve." ilk="argument" name="name" />
</scope>
<scope ilk="function" name="noop" signature="noop()" />
<scope ilk="function" name="reloadWithDebugInfo" signature="reloadWithDebugInfo()" />
<scope doc="Serializes input into a JSON-formatted string. Properties with leading $$ characters will be
stripped since angular uses this notation internally.
" ilk="function" name="toJson" returns="string|undefined" signature="toJson(obj) => string|undefined">
<variable citdl="Object|Array|Date|string|number" doc="Input to be serialized into JSON." ilk="argument" name="obj" />
</scope>
<scope doc="Converts the specified string to uppercase." ilk="function" name="uppercase" returns="string" signature="uppercase(string) => string">
<variable citdl="string" doc="String to be converted to uppercase." ilk="argument" name="string" />
</scope>
<scope ilk="class" name="Module">
<scope ilk="function" name="animation" signature="animation(name)">
<variable citdl="string" doc="animation name" ilk="argument" name="name" />
</scope>
<scope ilk="function" name="config" signature="config()" />
<scope ilk="function" name="constant" signature="constant(name)">
<variable citdl="string" doc="constant name" ilk="argument" name="name" />
</scope>
<scope ilk="function" name="controller" signature="controller(constructor)">
<variable citdl="Function" doc="Controller constructor function." ilk="argument" name="constructor" />
</scope>
<scope ilk="function" name="decorator" signature="decorator(The)">
<variable citdl="string" doc="name of the service to decorate." ilk="argument" name="The" />
</scope>
<scope ilk="function" name="directive" signature="directive()" />
<scope ilk="function" name="factory" signature="factory(name)">
<variable citdl="string" doc="service name" ilk="argument" name="name" />
</scope>
<scope ilk="function" name="filter" signature="filter(name)">
<variable citdl="string" doc="Filter name - this must be a valid angular expression identifier" ilk="argument" name="name" />
</scope>
<scope ilk="function" name="provider" signature="provider(name)">
<variable citdl="string" doc="service name" ilk="argument" name="name" />
</scope>
<scope ilk="function" name="run" signature="run()" />
<scope ilk="function" name="service" signature="service(name)">
<variable citdl="string" doc="service name" ilk="argument" name="name" />
</scope>
<scope ilk="function" name="value" signature="value(name)">
<variable citdl="string" doc="service name" ilk="argument" name="name" />
</scope>
<variable name="name" />
<variable name="requires" />
</scope>
<variable name="version" />
</scope>
<scope ilk="class" name="$anchorScrollProvider">
<scope ilk="function" name="disableAutoScrolling" signature="disableAutoScrolling()" />
</scope>
<scope ilk="class" name="$animateProvider">
<scope doc="Sets and/or returns the CSS class regular expression that is checked when performing
an animation. Upon bootstrap the classNameFilter value is not set at all and will
therefore enable $animate to attempt to perform an animation on any element that is triggered.
When setting the `classNameFilter` value, animations will only be performed on elements
that successfully match the filter expression. This in turn can boost performance
for low-powered devices as well as applications containing a lot of structural operations." ilk="function" name="classNameFilter" signature="classNameFilter(expression)">
<variable citdl="RegExp=" doc="The className expression which will be checked against all animations" ilk="argument" name="expression" />
</scope>
<scope doc="Registers a new injectable animation factory function. The factory function produces the
animation object which contains callback functions for each event that is expected to be
animated.
* * `eventFn`: `function(element, ... , doneFunction, options)`
The element to animate, the `doneFunction` and the options fed into the animation. Depending
on the type of animation additional arguments will be injected into the animation function. The
list below explains the function signatures for the different animation methods:
* - setClass: function(element, addedClasses, removedClasses, doneFunction, options)
- addClass: function(element, addedClasses, doneFunction, options)
- removeClass: function(element, removedClasses, doneFunction, options)
- enter, leave, move: function(element, doneFunction, options)
- animate: function(element, fromStyles, toStyles, doneFunction, options)
* Make sure to trigger the `doneFunction` once the animation is fully complete.
* ```js
return {
//enter, leave, move signature
eventFn : function(element, done, options) {
//code to run the animation
//once complete, then run done()
return function endFunction(wasCancelled) {
//code to cancel the animation
}
}
}
```
" ilk="function" name="register" signature="register(name)">
<variable citdl="string" doc="The name of the animation (this is what the class-based CSS value will be compared to)." ilk="argument" name="name" />
</scope>
</scope>
<scope ilk="class" name="$compileProvider">
<scope doc="Retrieves or overrides the default regular expression that is used for whitelisting of safe
urls during a[href] sanitization.
* The sanitization is a security measure aimed at preventing XSS attacks via html links.
* Any url about to be assigned to a[href] via data-binding is first normalized and turned into
an absolute url. Afterwards, the url is matched against the `aHrefSanitizationWhitelist`
regular expression. If a match is found, the original url is written into the dom. Otherwise,
the absolute url is prefixed with `'unsafe:'` string and only then is it written into the DOM.
" ilk="function" name="aHrefSanitizationWhitelist" returns="RegExp|ng.$compileProvider" signature="aHrefSanitizationWhitelist(regexp) => RegExp|ng.$compileProvider">
<variable citdl="RegExp=" doc="New regexp to whitelist urls with." ilk="argument" name="regexp" />
</scope>
<scope ilk="function" name="debugInfoEnabled" returns="*" signature="debugInfoEnabled() => *" />
<scope doc="Register a new directive with the compiler.
" ilk="function" name="directive" returns="ng.$compileProvider" signature="directive() => ng.$compileProvider" />
<scope doc="Retrieves or overrides the default regular expression that is used for whitelisting of safe
urls during img[src] sanitization.
* The sanitization is a security measure aimed at prevent XSS attacks via html links.
* Any url about to be assigned to img[src] via data-binding is first normalized and turned into
an absolute url. Afterwards, the url is matched against the `imgSrcSanitizationWhitelist`
regular expression. If a match is found, the original url is written into the dom. Otherwise,
the absolute url is prefixed with `'unsafe:'` string and only then is it written into the DOM.
" ilk="function" name="imgSrcSanitizationWhitelist" returns="RegExp|ng.$compileProvider" signature="imgSrcSanitizationWhitelist(regexp) => RegExp|ng.$compileProvider">
<variable citdl="RegExp=" doc="New regexp to whitelist urls with." ilk="argument" name="regexp" />
</scope>
</scope>
<scope ilk="class" name="$controllerProvider">
<scope ilk="function" name="allowGlobals" signature="allowGlobals()" />
<scope ilk="function" name="register" signature="register()" />
</scope>
<scope ilk="class" name="$filterProvider">
<scope ilk="function" name="register" returns="Object" signature="register(factory) => Object">
<variable citdl="Function" doc="If the first argument was a string, a factory function for the filter to be registered." ilk="argument" name="factory" />
</scope>
</scope>
<scope ilk="class" name="$httpProvider">
<scope doc="* Configure $http service to combine processing of multiple http responses received at around
the same time via {@link ng.$rootScope.Scope#$applyAsync $rootScope.$applyAsync}. This can result in
significant performance improvement for bigger applications that make many HTTP requests
concurrently (common during application bootstrap).
* Defaults to false. If no value is specified, returns the current configured value.
" ilk="function" name="useApplyAsync" returns="boolean|Object" signature="useApplyAsync() => boolean|Object" />
<scope doc="* Configure `$http` service to return promises without the shorthand methods `success` and `error`.
This should be used to make sure that applications work without these methods.
* Defaults to true. If no value is specified, returns the current configured value.
" ilk="function" name="useLegacyPromiseExtensions" returns="boolean|Object" signature="useLegacyPromiseExtensions() => boolean|Object" />
<variable name="defaults" />
<variable name="interceptors" />
</scope>
<scope doc="* Used for configuring the interpolation markup. Defaults to `{{` and `}}`.
" ilk="class" name="$interpolateProvider">
<scope doc="Symbol to denote the end of expression in the interpolated string. Defaults to `}}`.
" ilk="function" name="endSymbol" returns="string|self" signature="endSymbol(value) => string|self">
<variable citdl="string=" doc="new value to set the ending symbol to." ilk="argument" name="value" />
</scope>
<scope doc="Symbol to denote start of expression in the interpolated string. Defaults to `{{`.
" ilk="function" name="startSymbol" returns="string|self" signature="startSymbol(value) => string|self">
<variable citdl="string=" doc="new value to set the starting symbol to." ilk="argument" name="value" />
</scope>
</scope>
<scope ilk="class" name="$locationProvider">
<scope doc="@param {string=} prefix Prefix for hash part (containing path and search)" ilk="function" name="hashPrefix" returns="*" signature="hashPrefix(prefix) => *">
<variable citdl="string=" doc="Prefix for hash part (containing path and search)" ilk="argument" name="prefix" />
</scope>
<scope doc="@param {(boolean|Object)=} mode If boolean, sets `html5Mode.enabled` to value.
If object, sets `enabled`, `requireBase` and `rewriteLinks` to respective values. Supported
properties:
- **enabled** – `{boolean}` – (default: false) If true, will rely on `history.pushState` to
change urls where supported. Will fall back to hash-prefixed paths in browsers that do not
support `pushState`.
- **requireBase** - `{boolean}` - (default: `true`) When html5Mode is enabled, specifies
whether or not a <base> tag is required to be present. If `enabled` and `requireBase` are
true, and a base tag is not present, an error will be thrown when `$location` is injected.
See the {@link guide/$location $location guide for more information}
- **rewriteLinks** - `{boolean}` - (default: `true`) When html5Mode is enabled,
enables/disables url rewriting for relative links.
" ilk="function" name="html5Mode" returns="Object" signature="html5Mode() => Object" />
</scope>
<scope ilk="class" name="$logProvider">
<scope doc="@param {boolean=} flag enable or disable debug level messages" ilk="function" name="debugEnabled" returns="*" signature="debugEnabled(flag) => *">
<variable citdl="boolean=" doc="enable or disable debug level messages" ilk="argument" name="flag" />
</scope>
</scope>
<scope ilk="class" name="$parseProvider" />
<scope ilk="class" name="$rootScopeProvider">
<scope doc="* Sets the number of `$digest` iterations the scope should attempt to execute before giving up and
assuming that the model is unstable.
* The current default is 10 iterations.
* In complex applications it's possible that the dependencies between `$watch`s will result in
several digest iterations. However if an application needs more than the default 10 digest
iterations for its model to stabilize then you should investigate what is causing the model to
continuously change during the digest.
* Increasing the TTL could have performance implications, so you should not change it without
proper justification.
" ilk="function" name="digestTtl" signature="digestTtl()" />
</scope>
<scope ilk="class" name="$sceDelegateProvider">
<scope ilk="function" name="resourceUrlBlacklist" signature="resourceUrlBlacklist()" />
<scope ilk="function" name="resourceUrlWhitelist" signature="resourceUrlWhitelist()" />
</scope>
<scope ilk="class" name="$sceProvider">
<scope ilk="function" name="enabled" signature="enabled(value)">
<variable citdl="boolean=" doc="If provided, then enables/disables SCE." ilk="argument" name="value" />
</scope>
</scope>
<scope doc="When called, it scrolls to the element related to the specified `hash` or (if omitted) to the
current value of {@link ng.$location#hash $location.hash()}, according to the rules specified
in the
[HTML5 spec](http://www.w3.org/html/wg/drafts/html/master/browsers.html#the-indicated-part-of-the-document).
* It also watches the {@link ng.$location#hash $location.hash()} and automatically scrolls to
match any anchor whenever it changes. This can be disabled by calling
{@link ng.$anchorScrollProvider#disableAutoScrolling $anchorScrollProvider.disableAutoScrolling()}.
* Additionally, you can use its {@link ng.$anchorScroll#yOffset yOffset} property to specify a
vertical scroll-offset (either fixed or dynamic).
" ilk="class" name="$anchorScroll" />
<scope ilk="class" name="$animate">
<scope doc="Triggers an addClass animation surrounding the addition of the provided CSS class(es). Upon
execution, the addClass operation will only be handled after the next digest and it will not trigger an
animation if element already contains the CSS class or if the class is removed at a later step.
Note that class-based animations are treated differently compared to structural animations
(like enter, move and leave) since the CSS classes may be added/removed at different points
depending if CSS or JavaScript animations are used.
" ilk="function" name="addClass" signature="addClass(element)">
<variable citdl="DOMElement" doc="the element which the CSS classes will be applied to" ilk="argument" name="element" />
</scope>
<scope doc="Performs an inline animation on the element which applies the provided to and from CSS styles to the element.
If any detected CSS transition, keyframe or JavaScript matches the provided className value, then the animation will take
on the provided styles. For example, if a transition animation is set for the given className, then the provided `from` and
`to` styles will be applied alongside the given transition. If the CSS style provided in `from` does not have a corresponding
style in `to`, the style in `from` is applied immediately, and no animation is run.
If a JavaScript animation is detected then the provided styles will be given in as function parameters into the `animate`
method (or as part of the `options` parameter):
* ```js
ngModule.animation('.my-inline-animation', function() {
return {
animate : function(element, from, to, done, options) {
//animation
done();
}
}
});
```
" ilk="function" name="animate" signature="animate(element,to)">
<variable citdl="DOMElement" doc="the element which the CSS styles will be applied to" ilk="argument" name="element" />
<variable citdl="object" doc="the to (destination) CSS styles that will be applied to the element and across the animation." ilk="argument" name="to" />
</scope>
<scope doc="Cancels the provided animation.
" ilk="function" name="cancel" signature="cancel()" />
<scope doc="Used to get and set whether animations are enabled or not on the entire application or on an element and its children. This
function can be called in four ways:
* ```js
// returns true or false
$animate.enabled();
* // changes the enabled state for all animations
$animate.enabled(false);
$animate.enabled(true);
* // returns true or false if animations are enabled for an element
$animate.enabled(element);
* // changes the enabled state for an element and its children
$animate.enabled(element, true);
$animate.enabled(element, false);
```
" ilk="function" name="enabled" signature="enabled(element)">
<variable citdl="DOMElement=" doc="the element that will be considered for checking/setting the enabled state" ilk="argument" name="element" />
</scope>
<scope doc="Inserts the element into the DOM either after the `after` element (if provided) or
as the first child within the `parent` element and then triggers an animation.
A promise is returned that will be resolved during the next digest once the animation
has completed.
" ilk="function" name="enter" signature="enter(element,after)">
<variable citdl="DOMElement" doc="the element which will be inserted into the DOM" ilk="argument" name="element" />
<variable citdl="DOMElement=" doc="the sibling element after which the element will be appended" ilk="argument" name="after" />
</scope>
<scope doc="Triggers an animation and then removes the element from the DOM.
When the function is called a promise is returned that will be resolved during the next
digest once the animation has completed.
" ilk="function" name="leave" signature="leave(element)">
<variable citdl="DOMElement" doc="the element which will be removed from the DOM" ilk="argument" name="element" />
</scope>
<scope doc="Inserts (moves) the element into its new position in the DOM either after
the `after` element (if provided) or as the first child within the `parent` element
and then triggers an animation. A promise is returned that will be resolved
during the next digest once the animation has completed.
" ilk="function" name="move" signature="move(element,after)">
<variable citdl="DOMElement" doc="the element which will be moved into the new DOM position" ilk="argument" name="element" />
<variable citdl="DOMElement=" doc="the sibling element after which the element will be appended" ilk="argument" name="after" />
</scope>
<scope doc="Deregisters an event listener based on the event which has been associated with the provided element. This method
can be used in three different ways depending on the arguments:
* ```js
// remove all the animation event listeners listening for `enter`
$animate.off('enter');
* // remove all the animation event listeners listening for `enter` on the given element and its children
$animate.off('enter', container);
* // remove the event listener function provided by `listenerFn` that is set
// to listen for `enter` on the given `element` as well as its children
$animate.off('enter', container, callback);
```
" ilk="function" name="off" signature="off(event)">
<variable citdl="string" doc="the animation event (e.g. enter, leave, move, addClass, removeClass, etc...)" ilk="argument" name="event" />
</scope>
<scope doc="Sets up an event listener to fire whenever the animation event (enter, leave, move, etc...)
has fired on the given element or among any of its children. Once the listener is fired, the provided callback
is fired with the following params:
* ```js
$animate.on('enter', container,
function callback(element, phase) {
// cool we detected an enter animation within the container
}
);
```
" ilk="function" name="on" signature="on(event)">
<variable citdl="string" doc="the animation event that will be captured (e.g. enter, leave, move, addClass, removeClass, etc...)" ilk="argument" name="event" />
</scope>
<scope doc="Associates the provided element with a host parent element to allow the element to be animated even if it exists
outside of the DOM structure of the Angular application. By doing so, any animation triggered via `$animate` can be issued on the
element despite being outside the realm of the application or within another application. Say for example if the application
was bootstrapped on an element that is somewhere inside of the `<body>` tag, but we wanted to allow for an element to be situated
as a direct child of `document.body`, then this can be achieved by pinning the element via `$animate.pin(element)`. Keep in mind
that calling `$animate.pin(element, parentElement)` will not actually insert into the DOM anywhere; it will just create the association.
* Note that this feature is only active when the `ngAnimate` module is used.
" ilk="function" name="pin" signature="pin(element)">
<variable citdl="DOMElement" doc="the external element that will be pinned" ilk="argument" name="element" />
</scope>
<scope doc="Triggers a removeClass animation surrounding the removal of the provided CSS class(es). Upon
execution, the removeClass operation will only be handled after the next digest and it will not trigger an
animation if element does not contain the CSS class or if the class is added at a later step.
Note that class-based animations are treated differently compared to structural animations
(like enter, move and leave) since the CSS classes may be added/removed at different points
depending if CSS or JavaScript animations are used.
" ilk="function" name="removeClass" signature="removeClass(element)">
<variable citdl="DOMElement" doc="the element which the CSS classes will be applied to" ilk="argument" name="element" />
</scope>
<scope doc="Performs both the addition and removal of a CSS classes on an element and (during the process)
triggers an animation surrounding the class addition/removal. Much like `$animate.addClass` and
`$animate.removeClass`, `setClass` will only evaluate the classes being added/removed once a digest has
passed. Note that class-based animations are treated differently compared to structural animations
(like enter, move and leave) since the CSS classes may be added/removed at different points
depending if CSS or JavaScript animations are used.
" ilk="function" name="setClass" signature="setClass(element,remove)">
<variable citdl="DOMElement" doc="the element which the CSS classes will be applied to" ilk="argument" name="element" />
<variable citdl="string" doc="the CSS class(es) that will be removed (multiple classes are separated via spaces)" ilk="argument" name="remove" />
</scope>
</scope>
<scope ilk="class" name="$animateCss" />
<scope doc="Factory that constructs {@link $cacheFactory.Cache Cache} objects and gives access to
them.
* ```js
* var cache = $cacheFactory('cacheId');
expect($cacheFactory.get('cacheId')).toBe(cache);
expect($cacheFactory.get('noSuchCacheId')).not.toBeDefined();
* cache.put("key", "value");
cache.put("another key", "another value");
* // We've specified no options on creation
expect(cache.info()).toEqual({id: 'cacheId', size: 2});
* ```
*" ilk="class" name="$cacheFactory">
<scope ilk="class" name="Cache">
<scope ilk="function" name="destroy" signature="destroy()" />
<scope doc="Retrieves named data stored in the {@link $cacheFactory.Cache Cache} object.
" ilk="function" name="get" returns="*" signature="get(key) => *">
<variable citdl="string" doc="the key of the data to be retrieved" ilk="argument" name="key" />
</scope>
<scope doc="Retrieve information regarding a particular {@link $cacheFactory.Cache Cache}.
" ilk="function" name="info" returns="object" signature="info() => object" />
<scope doc="Inserts a named entry into the {@link $cacheFactory.Cache Cache} object to be
retrieved later, and incrementing the size of the cache if the key was not already
present in the cache. If behaving like an LRU cache, it will also remove stale
entries from the set.
* It will not insert undefined values into the cache.
" ilk="function" name="put" returns="*" signature="put(key) => *">
<variable citdl="string" doc="the key under which the cached data is stored." ilk="argument" name="key" />
</scope>
<scope doc="Removes an entry from the {@link $cacheFactory.Cache Cache} object.
" ilk="function" name="remove" signature="remove()" />
<scope ilk="function" name="removeAll" signature="removeAll()" />
</scope>
<scope doc="Get access to a cache object by the `cacheId` used when it was created.
" ilk="function" name="get" returns="object" signature="get(cacheId) => object">
<variable citdl="string" doc="Name or id of a cache to access." ilk="argument" name="cacheId" />
</scope>
<scope doc="Get information about all the caches that have been created
" ilk="function" name="info" returns="Object" signature="info() => Object" />
</scope>
<scope doc="Compiles an HTML string or DOM into a template and produces a template function, which
can then be used to link {@link ng.$rootScope.Scope `scope`} and the template together.
* The compilation is a process of walking the DOM tree and matching DOM elements to
{@link ng.$compileProvider#directive directives}.
* <div class="alert alert-warning">
**Note:** This document is an in-depth reference of all directive options.
For a gentle introduction to directives with examples of common use cases,
see the {@link guide/directive directive guide}.
</div>
* ## Comprehensive Directive API
* There are many different options for a directive.
* The difference resides in the return value of the factory function.
You can either return a "Directive Definition Object" (see below) that defines the directive properties,
or just the `postLink` function (all other properties will have the default values).
* <div class="alert alert-success">
**Best Practice:** It's recommended to use the "directive definition object" form.
</div>
* Here's an example directive declared with a Directive Definition Object:
* ```js
var myModule = angular.module(...);
* myModule.directive('directiveName', function factory(injectables) {
var directiveDefinitionObject = {
priority: 0,
template: '<div></div>', // or // function(tElement, tAttrs) { ... },
// or
// templateUrl: 'directive.html', // or // function(tElement, tAttrs) { ... },
transclude: false,
restrict: 'A',
templateNamespace: 'html',
scope: false,
controller: function($scope, $element, $attrs, $transclude, otherInjectables) { ... },
controllerAs: 'stringIdentifier',
bindToController: false,
require: 'siblingDirectiveName', // or // ['^parentDirectiveName', '?optionalDirectiveName', '?^optionalParent'],
compile: function compile(tElement, tAttrs, transclude) {
return {
pre: function preLink(scope, iElement, iAttrs, controller) { ... },
post: function postLink(scope, iElement, iAttrs, controller) { ... }
}
// or
// return function postLink( ... ) { ... }
},
// or
// link: {
// pre: function preLink(scope, iElement, iAttrs, controller) { ... },
// post: function postLink(scope, iElement, iAttrs, controller) { ... }
// }
// or
// link: function postLink( ... ) { ... }
};
return directiveDefinitionObject;
});
```
* <div class="alert alert-warning">
**Note:** Any unspecified options will use the default value. You can see the default values below.
</div>
* Therefore the above can be simplified as:
* ```js
var myModule = angular.module(...);
* myModule.directive('directiveName', function factory(injectables) {
var directiveDefinitionObject = {
link: function postLink(scope, iElement, iAttrs) { ... }
};
return directiveDefinitionObject;
// or
// return function postLink(scope, iElement, iAttrs) { ... }
});
```
*
* ### Directive Definition Object
* The directive definition object provides instructions to the {@link ng.$compile
compiler}. The attributes are:
* #### `multiElement`
When this property is set to true, the HTML compiler will collect DOM nodes between
nodes with the attributes `directive-name-start` and `directive-name-end`, and group them
together as the directive elements. It is recommended that this feature be used on directives
which are not strictly behavioural (such as {@link ngClick}), and which
do not manipulate or replace child nodes (such as {@link ngInclude}).
* #### `priority`
When there are multiple directives defined on a single DOM element, sometimes it
is necessary to specify the order in which the directives are applied. The `priority` is used
to sort the directives before their `compile` functions get called. Priority is defined as a
number. Directives with greater numerical `priority` are compiled first. Pre-link functions
are also run in priority order, but post-link functions are run in reverse order. The order
of directives with the same priority is undefined. The default priority is `0`.
* #### `terminal`
If set to true then the current `priority` will be the last set of directives
which will execute (any directives at the current priority will still execute
as the order of execution on same `priority` is undefined). Note that expressions
and other directives used in the directive's template will also be excluded from execution.
* #### `scope`
The scope property can be `true`, an object or a falsy value:
* * **falsy:** No scope will be created for the directive. The directive will use its parent's scope.
* * **`true`:** A new child scope that prototypically inherits from its parent will be created for
the directive's element. If multiple directives on the same element request a new scope,
only one new scope is created. The new scope rule does not apply for the root of the template
since the root of the template always gets a new scope.
* * **`{...}` (an object hash):** A new "isolate" scope is created for the directive's element. The
'isolate' scope differs from normal scope in that it does not prototypically inherit from its parent
scope. This is useful when creating reusable components, which should not accidentally read or modify
data in the parent scope.
* The 'isolate' scope object hash defines a set of local scope properties derived from attributes on the
directive's element. These local properties are useful for aliasing values for templates. The keys in
the object hash map to the name of the property on the isolate scope; the values define how the property
is bound to the parent scope, via matching attributes on the directive's element:
* * `@` or `@attr` - bind a local scope property to the value of DOM attribute. The result is
always a string since DOM attributes are strings. If no `attr` name is specified then the
attribute name is assumed to be the same as the local name.
Given `<widget my-attr="hello {{name}}">` and widget definition
of `scope: { localName:'@myAttr' }`, then widget scope property `localName` will reflect
the interpolated value of `hello {{name}}`. As the `name` attribute changes so will the
`localName` property on the widget scope. The `name` is read from the parent scope (not
component scope).
* * `=` or `=attr` - set up bi-directional binding between a local scope property and the
parent scope property of name defined via the value of the `attr` attribute. If no `attr`
name is specified then the attribute name is assumed to be the same as the local name.
Given `<widget my-attr="parentModel">` and widget definition of
`scope: { localModel:'=myAttr' }`, then widget scope property `localModel` will reflect the
value of `parentModel` on the parent scope. Any changes to `parentModel` will be reflected
in `localModel` and any changes in `localModel` will reflect in `parentModel`. If the parent
scope property doesn't exist, it will throw a NON_ASSIGNABLE_MODEL_EXPRESSION exception. You
can avoid this behavior using `=?` or `=?attr` in order to flag the property as optional. If
you want to shallow watch for changes (i.e. $watchCollection instead of $watch) you can use
`=*` or `=*attr` (`=*?` or `=*?attr` if the property is optional).
* * `&` or `&attr` - provides a way to execute an expression in the context of the parent scope.
If no `attr` name is specified then the attribute name is assumed to be the same as the
local name. Given `<widget my-attr="count = count + value">` and widget definition of
`scope: { localFn:'&myAttr' }`, then isolate scope property `localFn` will point to
a function wrapper for the `count = count + value` expression. Often it's desirable to
pass data from the isolated scope via an expression to the parent scope, this can be
done by passing a map of local variable names and values into the expression wrapper fn.
For example, if the expression is `increment(amount)` then we can specify the amount value
by calling the `localFn` as `localFn({amount: 22})`.
* In general it's possible to apply more than one directive to one element, but there might be limitations
depending on the type of scope required by the directives. The following points will help explain these limitations.
For simplicity only two directives are taken into account, but it is also applicable for several directives:
* * **no scope** + **no scope** => Two directives which don't require their own scope will use their parent's scope
* **child scope** + **no scope** => Both directives will share one single child scope
* **child scope** + **child scope** => Both directives will share one single child scope
* **isolated scope** + **no scope** => The isolated directive will use it's own created isolated scope. The other directive will use
its parent's scope
* **isolated scope** + **child scope** => **Won't work!** Only one scope can be related to one element. Therefore these directives cannot
be applied to the same element.
* **isolated scope** + **isolated scope** => **Won't work!** Only one scope can be related to one element. Therefore these directives
cannot be applied to the same element.
*
#### `bindToController`
This property is used to bind scope properties directly to the controller. It can be either
`true` or an object hash with the same format as the `scope` property. Additionally, a controller
alias must be set, either by using `controllerAs: 'myAlias'` or by specifying the alias in the controller
definition: `controller: 'myCtrl as myAlias'`.
* When an isolate scope is used for a directive (see above), `bindToController: true` will
allow a component to have its properties bound to the controller, rather than to scope. When the controller
is instantiated, the initial values of the isolate scope bindings are already available.
* It is also possible to set `bindToController` to an object hash with the same format as the `scope` property.
This will set up the scope bindings to the controller directly. Note that `scope` can still be used
to define which kind of scope is created. By default, no scope is created. Use `scope: {}` to create an isolate
scope (useful for component directives).
* If both `bindToController` and `scope` are defined and have object hashes, `bindToController` overrides `scope`.
*
#### `controller`
Controller constructor function. The controller is instantiated before the
pre-linking phase and can be accessed by other directives (see
`require` attribute). This allows the directives to communicate with each other and augment
each other's behavior. The controller is injectable (and supports bracket notation) with the following locals:
* * `$scope` - Current scope associated with the element
* `$element` - Current element
* `$attrs` - Current attributes object for the element
* `$transclude` - A transclude linking function pre-bound to the correct transclusion scope:
`function([scope], cloneLinkingFn, futureParentElement)`.
* `scope`: optional argument to override the scope.
* `cloneLinkingFn`: optional argument to create clones of the original transcluded content.
* `futureParentElement`:
* defines the parent to which the `cloneLinkingFn` will add the cloned elements.
* default: `$element.parent()` resp. `$element` for `transclude:'element'` resp. `transclude:true`.
* only needed for transcludes that are allowed to contain non html elements (e.g. SVG elements)
and when the `cloneLinkinFn` is passed,
as those elements need to created and cloned in a special way when they are defined outside their
usual containers (e.g. like `<svg>`).
* See also the `directive.templateNamespace` property.
*
#### `require`
Require another directive and inject its controller as the fourth argument to the linking function. The
`require` takes a string name (or array of strings) of the directive(s) to pass in. If an array is used, the
injected argument will be an array in corresponding order. If no such directive can be
found, or if the directive does not have a controller, then an error is raised (unless no link function
is specified, in which case error checking is skipped). The name can be prefixed with:
* * (no prefix) - Locate the required controller on the current element. Throw an error if not found.
* `?` - Attempt to locate the required controller or pass `null` to the `link` fn if not found.
* `^` - Locate the required controller by searching the element and its parents. Throw an error if not found.
* `^^` - Locate the required controller by searching the element's parents. Throw an error if not found.
* `?^` - Attempt to locate the required controller by searching the element and its parents or pass
`null` to the `link` fn if not found.
* `?^^` - Attempt to locate the required controller by searching the element's parents, or pass
`null` to the `link` fn if not found.
*
#### `controllerAs`
Identifier name for a reference to the controller in the directive's scope.
This allows the controller to be referenced from the directive template. This is especially
useful when a directive is used as component, i.e. with an `isolate` scope. It's also possible
to use it in a directive without an `isolate` / `new` scope, but you need to be aware that the
`controllerAs` reference might overwrite a property that already exists on the parent scope.
*
#### `restrict`
String of subset of `EACM` which restricts the directive to a specific directive
declaration style. If omitted, the defaults (elements and attributes) are used.
* * `E` - Element name (default): `<my-directive></my-directive>`
* `A` - Attribute (default): `<div my-directive="exp"></div>`
* `C` - Class: `<div class="my-directive: exp;"></div>`
* `M` - Comment: `<!-- directive: my-directive exp -->`
*
#### `templateNamespace`
String representing the document type used by the markup in the template.
AngularJS needs this information as those elements need to be created and cloned
in a special way when they are defined outside their usual containers like `<svg>` and `<math>`.
* * `html` - All root nodes in the template are HTML. Root nodes may also be
top-level elements such as `<svg>` or `<math>`.
* `svg` - The root nodes in the template are SVG elements (excluding `<math>`).
* `math` - The root nodes in the template are MathML elements (excluding `<svg>`).
* If no `templateNamespace` is specified, then the namespace is considered to be `html`.
* #### `template`
HTML markup that may:
* Replace the contents of the directive's element (default).
* Replace the directive's element itself (if `replace` is true - DEPRECATED).
* Wrap the contents of the directive's element (if `transclude` is true).
* Value may be:
* * A string. For example `<div red-on-hover>{{delete_str}}</div>`.
* A function which takes two arguments `tElement` and `tAttrs` (described in the `compile`
function api below) and returns a string value.
*
#### `templateUrl`
This is similar to `template` but the template is loaded from the specified URL, asynchronously.
* Because template loading is asynchronous the compiler will suspend compilation of directives on that element
for later when the template has been resolved. In the meantime it will continue to compile and link
sibling and parent elements as though this element had not contained any directives.
* The compiler does not suspend the entire compilation to wait for templates to be loaded because this
would result in the whole app "stalling" until all templates are loaded asynchronously - even in the
case when only one deeply nested directive has `templateUrl`.
* Template loading is asynchronous even if the template has been preloaded into the {@link $templateCache}
* You can specify `templateUrl` as a string representing the URL or as a function which takes two
arguments `tElement` and `tAttrs` (described in the `compile` function api below) and returns
a string value representing the url. In either case, the template URL is passed through {@link
$sce#getTrustedResourceUrl $sce.getTrustedResourceUrl}.
*
#### `replace` ([*DEPRECATED*!], will be removed in next major release - i.e. v2.0)
specify what the template should replace. Defaults to `false`.
* * `true` - the template will replace the directive's element.
* `false` - the template will replace the contents of the directive's element.
* The replacement process migrates all of the attributes / classes from the old element to the new
one. See the {@link guide/directive#template-expanding-directive
Directives Guide} for an example.
* There are very few scenarios where element replacement is required for the application function,
the main one being reusable custom components that are used within SVG contexts
(because SVG doesn't work with custom elements in the DOM tree).
* #### `transclude`
Extract the contents of the element where the directive appears and make it available to the directive.
The contents are compiled and provided to the directive as a **transclusion function**. See the
{@link $compile#transclusion Transclusion} section below.
* There are two kinds of transclusion depending upon whether you want to transclude just the contents of the
directive's element or the entire element:
* * `true` - transclude the content (i.e. the child nodes) of the directive's element.
* `'element'` - transclude the whole of the directive's element including any directives on this
element that defined at a lower priority than this directive. When used, the `template`
property is ignored.
*
#### `compile`
* ```js
function compile(tElement, tAttrs, transclude) { ... }
```
* The compile function deals with transforming the template DOM. Since most directives do not do
template transformation, it is not used often. The compile function takes the following arguments:
* * `tElement` - template element - The element where the directive has been declared. It is
safe to do template transformation on the element and child elements only.
* * `tAttrs` - template attributes - Normalized list of attributes declared on this element shared
between all directive compile functions.
* * `transclude` - [*DEPRECATED*!] A transclude linking function: `function(scope, cloneLinkingFn)`
* <div class="alert alert-warning">
**Note:** The template instance and the link instance may be different objects if the template has
been cloned. For this reason it is **not** safe to do anything other than DOM transformations that
apply to all cloned DOM nodes within the compile function. Specifically, DOM listener registration
should be done in a linking function rather than in a compile function.
</div>
<div class="alert alert-warning">
**Note:** The compile function cannot handle directives that recursively use themselves in their
own templates or compile functions. Compiling these directives results in an infinite loop and a
stack overflow errors.
* This can be avoided by manually using $compile in the postLink function to imperatively compile
a directive's template instead of relying on automatic template compilation via `template` or
`templateUrl` declaration or manual compilation inside the compile function.
</div>
* <div class="alert alert-danger">
**Note:** The `transclude` function that is passed to the compile function is deprecated, as it
e.g. does not know about the right outer scope. Please use the transclude function that is passed
to the link function instead.
</div>
A compile function can have a return value which can be either a function or an object.
* * returning a (post-link) function - is equivalent to registering the linking function via the
`link` property of the config object when the compile function is empty.
* * returning an object with function(s) registered via `pre` and `post` properties - allows you to
control when a linking function should be called during the linking phase. See info about
pre-linking and post-linking functions below.
*
#### `link`
This property is used only if the `compile` property is not defined.
* ```js
function link(scope, iElement, iAttrs, controller, transcludeFn) { ... }
```
* The link function is responsible for registering DOM listeners as well as updating the DOM. It is
executed after the template has been cloned. This is where most of the directive logic will be
put.
* * `scope` - {@link ng.$rootScope.Scope Scope} - The scope to be used by the
directive for registering {@link ng.$rootScope.Scope#$watch watches}.
* * `iElement` - instance element - The element where the directive is to be used. It is safe to
manipulate the children of the element only in `postLink` function since the children have
already been linked.
* * `iAttrs` - instance attributes - Normalized list of attributes declared on this element shared
between all directive linking functions.
* * `controller` - the directive's required controller instance(s) - Instances are shared
among all directives, which allows the directives to use the controllers as a communication
channel. The exact value depends on the directive's `require` property:
* no controller(s) required: the directive's own controller, or `undefined` if it doesn't have one
* `string`: the controller instance
* `array`: array of controller instances
* If a required controller cannot be found, and it is optional, the instance is `null`,
otherwise the {@link error:$compile:ctreq Missing Required Controller} error is thrown.
* Note that you can also require the directive's own controller - it will be made available like
any other controller.
* * `transcludeFn` - A transclude linking function pre-bound to the correct transclusion scope.
This is the same as the `$transclude`
parameter of directive controllers, see there for details.
`function([scope], cloneLinkingFn, futureParentElement)`.
* #### Pre-linking function
* Executed before the child elements are linked. Not safe to do DOM transformation since the
compiler linking function will fail to locate the correct elements for linking.
* #### Post-linking function
* Executed after the child elements are linked.
* Note that child elements that contain `templateUrl` directives will not have been compiled
and linked since they are waiting for their template to load asynchronously and their own
compilation and linking has been suspended until that occurs.
* It is safe to do DOM transformation in the post-linking function on elements that are not waiting
for their async templates to be resolved.
*
### Transclusion
* Transclusion is the process of extracting a collection of DOM elements from one part of the DOM and
copying them to another part of the DOM, while maintaining their connection to the original AngularJS
scope from where they were taken.
* Transclusion is used (often with {@link ngTransclude}) to insert the
original contents of a directive's element into a specified place in the template of the directive.
The benefit of transclusion, over simply moving the DOM elements manually, is that the transcluded
content has access to the properties on the scope from which it was taken, even if the directive
has isolated scope.
See the {@link guide/directive#creating-a-directive-that-wraps-other-elements Directives Guide}.
* This makes it possible for the widget to have private state for its template, while the transcluded
content has access to its originating scope.
* <div class="alert alert-warning">
**Note:** When testing an element transclude directive you must not place the directive at the root of the
DOM fragment that is being compiled. See {@link guide/unit-testing#testing-transclusion-directives
Testing Transclusion Directives}.
</div>
* #### Transclusion Functions
* When a directive requests transclusion, the compiler extracts its contents and provides a **transclusion
function** to the directive's `link` function and `controller`. This transclusion function is a special
**linking function** that will return the compiled contents linked to a new transclusion scope.
* <div class="alert alert-info">
If you are just using {@link ngTransclude} then you don't need to worry about this function, since
ngTransclude will deal with it for us.
</div>
* If you want to manually control the insertion and removal of the transcluded content in your directive
then you must use this transclude function. When you call a transclude function it returns a a jqLite/JQuery
object that contains the compiled DOM, which is linked to the correct transclusion scope.
* When you call a transclusion function you can pass in a **clone attach function**. This function accepts
two parameters, `function(clone, scope) { ... }`, where the `clone` is a fresh compiled copy of your transcluded
content and the `scope` is the newly created transclusion scope, to which the clone is bound.
* <div class="alert alert-info">
**Best Practice**: Always provide a `cloneFn` (clone attach function) when you call a translude function
since you then get a fresh clone of the original DOM and also have access to the new transclusion scope.
</div>
* It is normal practice to attach your transcluded content (`clone`) to the DOM inside your **clone
attach function**:
* ```js
var transcludedContent, transclusionScope;
* $transclude(function(clone, scope) {
element.append(clone);
transcludedContent = clone;
transclusionScope = scope;
});
```
* Later, if you want to remove the transcluded content from your DOM then you should also destroy the
associated transclusion scope:
* ```js
transcludedContent.remove();
transclusionScope.$destroy();
```
* <div class="alert alert-info">
**Best Practice**: if you intend to add and remove transcluded content manually in your directive
(by calling the transclude function to get the DOM and calling `element.remove()` to remove it),
then you are also responsible for calling `$destroy` on the transclusion scope.
</div>
* The built-in DOM manipulation directives, such as {@link ngIf}, {@link ngSwitch} and {@link ngRepeat}
automatically destroy their transluded clones as necessary so you do not need to worry about this if
you are simply using {@link ngTransclude} to inject the transclusion into your directive.
*
#### Transclusion Scopes
* When you call a transclude function it returns a DOM fragment that is pre-bound to a **transclusion
scope**. This scope is special, in that it is a child of the directive's scope (and so gets destroyed
when the directive's scope gets destroyed) but it inherits the properties of the scope from which it
was taken.
* For example consider a directive that uses transclusion and isolated scope. The DOM hierarchy might look
like this:
* ```html
<div ng-app>
<div isolate>
<div transclusion>
</div>
</div>
</div>
```
* The `$parent` scope hierarchy will look like this:
```
 - $rootScope
 - isolate
 - transclusion
 ```
* but the scopes will inherit prototypically from different scopes to their `$parent`.
```
 - $rootScope
 - transclusion
 - isolate
 ```
*
### Attributes
* The {@link ng.$compile.directive.Attributes Attributes} object - passed as a parameter in the
`link()` or `compile()` functions. It has a variety of uses.
* accessing *Normalized attribute names:*
Directives like 'ngBind' can be expressed in many ways: 'ng:bind', `data-ng-bind`, or 'x-ng-bind'.
the attributes object allows for normalized access to
the attributes.
* * *Directive inter-communication:* All directives share the same instance of the attributes
object which allows the directives to use the attributes object as inter directive
communication.
* * *Supports interpolation:* Interpolation attributes are assigned to the attribute object
allowing other directives to read the interpolated value.
* * *Observing interpolated attributes:* Use `$observe` to observe the value changes of attributes
that contain interpolation (e.g. `src="{{bar}}"`). Not only is this very efficient but it's also
the only way to easily get the actual value because during the linking phase the interpolation
hasn't been evaluated yet and so the value is at this time set to `undefined`.
* ```js
function linkingFn(scope, elm, attrs, ctrl) {
// get the attribute value
console.log(attrs.ngModel);
* // change the attribute
attrs.$set('ngModel', 'new value');
* // observe changes to interpolated attribute
attrs.$observe('ngModel', function(value) {
console.log('ngModel has changed value to ' + value);
});
}
```
* ## Example
* <div class="alert alert-warning">
**Note**: Typically directives are registered with `module.directive`. The example below is
to illustrate how `$compile` works.
</div>
<example module="compileExample">
 <file name="index.html">
 <script>
 angular.module('compileExample', [], function($compileProvider) {
 // configure new 'compile' directive by passing a directive
 // factory function. The factory function injects the '$compile'
 $compileProvider.directive('compile', function($compile) {
 // directive factory creates a link function
 return function(scope, element, attrs) {
 scope.$watch(
 function(scope) {
 // watch the 'compile' expression for changes
 return scope.$eval(attrs.compile);
 },
 function(value) {
 // when the 'compile' expression changes
 // assign it into the current DOM
 element.html(value);

 // compile the new DOM and link it to the current
 // scope.
 // NOTE: we only compile .childNodes so that
 // we don't get into infinite loop compiling ourselves
 $compile(element.contents())(scope);
 }
 );
 };
 });
 })
 .controller('GreeterController', ['$scope', function($scope) {
 $scope.name = 'Angular';
 $scope.html = 'Hello {{name}}';
 }]);
 </script>
 <div ng-controller="GreeterController">
 <input ng-model="name"> <br/>
 <textarea ng-model="html"></textarea> <br/>
 <div compile="html"></div>
 </div>
 </file>
 <file name="protractor.js" type="protractor">
 it('should auto compile', function() {
 var textarea = $('textarea');
 var output = $('div[compile]');
 // The initial state reads 'Hello Angular'.
 expect(output.getText()).toBe('Hello Angular');
 textarea.clear();
 textarea.sendKeys('{{name}}!');
 expect(output.getText()).toBe('Angular!');
 });
 </file>
 </example>
*" ilk="class" name="$compile">
<scope ilk="namespace" name="directive">
<scope ilk="class" name="Attributes">
<scope doc="Adds the CSS class value specified by the classVal parameter to the element. If animations
are enabled then an animation will be triggered for the class addition.
" ilk="function" name="$addClass" signature="$addClass()" />
<scope doc="Converts an attribute name (e.g. dash/colon/underscore-delimited string, optionally prefixed with `x-` or
`data-`) to its normalized, camelCase form.
* Also there is special case for Moz prefix starting with upper case letter.
* For further information check out the guide on {@link guide/directive#matching-directives Matching Directives}
" ilk="function" name="$normalize" signature="$normalize()" />
<scope doc="Observes an interpolated attribute.
* The observer function will be invoked once during the next `$digest` following
compilation. The observer is then invoked whenever the interpolated value
changes.
" ilk="function" name="$observe" returns="function()" signature="$observe(key) => function()">
<variable citdl="string" doc="Normalized key. (ie ngAttribute) ." ilk="argument" name="key" />
</scope>
<scope doc="Removes the CSS class value specified by the classVal parameter from the element. If
animations are enabled then an animation will be triggered for the class removal.
" ilk="function" name="$removeClass" signature="$removeClass()" />
<scope doc="Set DOM element attribute value.
*" ilk="function" name="$set" signature="$set()" />
<scope doc="Adds and removes the appropriate CSS class values to the element based on the difference
between the new and old CSS class values (specified as newClasses and oldClasses).
" ilk="function" name="$updateClass" signature="$updateClass(newClasses)">
<variable citdl="string" doc="The current CSS className value" ilk="argument" name="newClasses" />
</scope>
<variable name="$attr" />
</scope>
</scope>
</scope>
<scope ilk="class" name="$controller" />
<scope doc="A {@link angular.element jQuery or jqLite} wrapper for the browser's `window.document` object.
" ilk="class" name="$document" />
<scope doc="Any uncaught exception in angular expressions is delegated to this service.
The default implementation simply delegates to `$log.error` which logs it into
the browser console.
* In unit tests, if `angular-mocks.js` is loaded, this service is overridden by
{@link ngMock.$exceptionHandler mock $exceptionHandler} which aids in testing.
* ## Example:
* ```js
angular.module('exceptionOverride', []).factory('$exceptionHandler', function() {
return function(exception, cause) {
exception.message += ' (caused by "' + cause + '")';
throw exception;
};
});
```
* This example will override the normal action of `$exceptionHandler`, to make angular
exceptions fail hard when they happen, instead of just logging to the console.
* <hr />
Note, that code executed in event-listeners (even those registered using jqLite's `on`/`bind`
methods) does not delegate exceptions to the {@link ng.$exceptionHandler $exceptionHandler}
(unless executed during a digest).
* If you wish, you can manually delegate exceptions, e.g.
`try { ... } catch(e) { $exceptionHandler(e); }`
" ilk="class" name="$exceptionHandler" />
<scope doc="Filters are used for formatting data displayed to the user.
* The general syntax in templates is as follows:
* {{ expression [| filter_name[:parameter_value] ... ] }}
" ilk="class" name="$filter" />
<scope doc="The `$http` service is a core Angular service that facilitates communication with the remote
HTTP servers via the browser's [XMLHttpRequest](https://developer.mozilla.org/en/xmlhttprequest)
object or via [JSONP](http://en.wikipedia.org/wiki/JSONP).
* For unit testing applications that use `$http` service, see
{@link ngMock.$httpBackend $httpBackend mock}.
* For a higher level of abstraction, please check out the {@link ngResource.$resource
$resource} service.
* The $http API is based on the {@link ng.$q deferred/promise APIs} exposed by
the $q service. While for simple usage patterns this doesn't matter much, for advanced usage
it is important to familiarize yourself with these APIs and the guarantees they provide.
*
## General usage
The `$http` service is a function which takes a single argument — a {@link $http#usage configuration object} —
that is used to generate an HTTP request and returns a {@link ng.$q promise}.
* ```js
// Simple GET request example:
$http({
method: 'GET',
url: '/someUrl'
}).then(function successCallback(response) {
// this callback will be called asynchronously
// when the response is available
}, function errorCallback(response) {
// called asynchronously if an error occurs
// or server returns response with an error status.
});
```
* The response object has these properties:
* - **data** – `{string|Object}` – The response body transformed with the transform
functions.
- **status** – `{number}` – HTTP status code of the response.
- **headers** – `{function([headerName])}` – Header getter function.
- **config** – `{Object}` – The configuration object that was used to generate the request.
- **statusText** – `{string}` – HTTP status text of the response.
* A response status code between 200 and 299 is considered a success status and
will result in the success callback being called. Note that if the response is a redirect,
XMLHttpRequest will transparently follow it, meaning that the error callback will not be
called for such responses.
*
## Shortcut methods
* Shortcut methods are also available. All shortcut methods require passing in the URL, and
request data must be passed in for POST/PUT requests. An optional config can be passed as the
last argument.
* ```js
$http.get('/someUrl', config).then(successCallback, errorCallback);
$http.post('/someUrl', data, config).then(successCallback, errorCallback);
```
* Complete list of shortcut methods:
* - {@link ng.$http#get $http.get}
- {@link ng.$http#head $http.head}
- {@link ng.$http#post $http.post}
- {@link ng.$http#put $http.put}
- {@link ng.$http#delete $http.delete}
- {@link ng.$http#jsonp $http.jsonp}
- {@link ng.$http#patch $http.patch}
*
## Writing Unit Tests that use $http
When unit testing (using {@link ngMock ngMock}), it is necessary to call
{@link ngMock.$httpBackend#flush $httpBackend.flush()} to flush each pending
request using trained responses.
* ```
$httpBackend.expectGET(...);
$http.get(...);
$httpBackend.flush();
```
* ## Deprecation Notice
<div class="alert alert-danger">
The `$http` legacy promise methods `success` and `error` have been deprecated.
Use the standard `then` method instead.
If {@link $httpProvider#useLegacyPromiseExtensions `$httpProvider.useLegacyPromiseExtensions`} is set to
`false` then these methods will throw {@link $http:legacy `$http/legacy`} error.
</div>
* ## Setting HTTP Headers
* The $http service will automatically add certain HTTP headers to all requests. These defaults
can be fully configured by accessing the `$httpProvider.defaults.headers` configuration
object, which currently contains this default configuration:
* - `$httpProvider.defaults.headers.common` (headers that are common for all requests):
- `Accept: application/json, text/plain, * / *`
- `$httpProvider.defaults.headers.post`: (header defaults for POST requests)
- `Content-Type: application/json`
- `$httpProvider.defaults.headers.put` (header defaults for PUT requests)
- `Content-Type: application/json`
* To add or overwrite these defaults, simply add or remove a property from these configuration
objects. To add headers for an HTTP method other than POST or PUT, simply add a new object
with the lowercased HTTP method name as the key, e.g.
`$httpProvider.defaults.headers.get = { 'My-Header' : 'value' }`.
* The defaults can also be set at runtime via the `$http.defaults` object in the same
fashion. For example:
* ```
module.run(function($http) {
$http.defaults.headers.common.Authorization = 'Basic YmVlcDpib29w'
});
```
* In addition, you can supply a `headers` property in the config object passed when
calling `$http(config)`, which overrides the defaults without changing them globally.
* To explicitly remove a header automatically added via $httpProvider.defaults.headers on a per request basis,
Use the `headers` property, setting the desired header to `undefined`. For example:
* ```js
var req = {
method: 'POST',
url: 'http://example.com',
headers: {
'Content-Type': undefined
},
data: { test: 'test' }
}
* $http(req).then(function(){...}, function(){...});
```
* ## Transforming Requests and Responses
* Both requests and responses can be transformed using transformation functions: `transformRequest`
and `transformResponse`. These properties can be a single function that returns
the transformed value (`function(data, headersGetter, status)`) or an array of such transformation functions,
which allows you to `push` or `unshift` a new transformation function into the transformation chain.
* ### Default Transformations
* The `$httpProvider` provider and `$http` service expose `defaults.transformRequest` and
`defaults.transformResponse` properties. If a request does not provide its own transformations
then these will be applied.
* You can augment or replace the default transformations by modifying these properties by adding to or
replacing the array.
* Angular provides the following default transformations:
* Request transformations (`$httpProvider.defaults.transformRequest` and `$http.defaults.transformRequest`):
* - If the `data` property of the request configuration object contains an object, serialize it
into JSON format.
* Response transformations (`$httpProvider.defaults.transformResponse` and `$http.defaults.transformResponse`):
* - If XSRF prefix is detected, strip it (see Security Considerations section below).
- If JSON response is detected, deserialize it using a JSON parser.
*
### Overriding the Default Transformations Per Request
* If you wish override the request/response transformations only for a single request then provide
`transformRequest` and/or `transformResponse` properties on the configuration object passed
into `$http`.
* Note that if you provide these properties on the config object the default transformations will be
overwritten. If you wish to augment the default transformations then you must include them in your
local transformation array.
* The following code demonstrates adding a new response transformation to be run after the default response
transformations have been run.
* ```js
function appendTransform(defaults, transform) {
* // We can't guarantee that the default transformation is an array
defaults = angular.isArray(defaults) ? defaults : [defaults];
* // Append the new transformation to the defaults
return defaults.concat(transform);
}
* $http({
url: '...',
method: 'GET',
transformResponse: appendTransform($http.defaults.transformResponse, function(value) {
return doTransform(value);
})
});
```
*
## Caching
* To enable caching, set the request configuration `cache` property to `true` (to use default
cache) or to a custom cache object (built with {@link ng.$cacheFactory `$cacheFactory`}).
When the cache is enabled, `$http` stores the response from the server in the specified
cache. The next time the same request is made, the response is served from the cache without
sending a request to the server.
* Note that even if the response is served from cache, delivery of the data is asynchronous in
the same way that real requests are.
* If there are multiple GET requests for the same URL that should be cached using the same
cache, but the cache is not populated yet, only one request to the server will be made and
the remaining requests will be fulfilled using the response from the first request.
* You can change the default cache to a new object (built with
{@link ng.$cacheFactory `$cacheFactory`}) by updating the
{@link ng.$http#defaults `$http.defaults.cache`} property. All requests who set
their `cache` property to `true` will now use this cache object.
* If you set the default cache to `false` then only requests that specify their own custom
cache object will be cached.
* ## Interceptors
* Before you start creating interceptors, be sure to understand the
{@link ng.$q $q and deferred/promise APIs}.
* For purposes of global error handling, authentication, or any kind of synchronous or
asynchronous pre-processing of request or postprocessing of responses, it is desirable to be
able to intercept requests before they are handed to the server and
responses before they are handed over to the application code that
initiated these requests. The interceptors leverage the {@link ng.$q
promise APIs} to fulfill this need for both synchronous and asynchronous pre-processing.
* The interceptors are service factories that are registered with the `$httpProvider` by
adding them to the `$httpProvider.interceptors` array. The factory is called and
injected with dependencies (if specified) and returns the interceptor.
* There are two kinds of interceptors (and two kinds of rejection interceptors):
* * `request`: interceptors get called with a http {@link $http#usage config} object. The function is free to
modify the `config` object or create a new one. The function needs to return the `config`
object directly, or a promise containing the `config` or a new `config` object.
* `requestError`: interceptor gets called when a previous interceptor threw an error or
resolved with a rejection.
* `response`: interceptors get called with http `response` object. The function is free to
modify the `response` object or create a new one. The function needs to return the `response`
object directly, or as a promise containing the `response` or a new `response` object.
* `responseError`: interceptor gets called when a previous interceptor threw an error or
resolved with a rejection.
*
```js
// register the interceptor as a service
$provide.factory('myHttpInterceptor', function($q, dependency1, dependency2) {
return {
// optional method
'request': function(config) {
// do something on success
return config;
},
* // optional method
'requestError': function(rejection) {
// do something on error
if (canRecover(rejection)) {
return responseOrNewPromise
}
return $q.reject(rejection);
},
*
* // optional method
'response': function(response) {
// do something on success
return response;
},
* // optional method
'responseError': function(rejection) {
// do something on error
if (canRecover(rejection)) {
return responseOrNewPromise
}
return $q.reject(rejection);
}
};
});
* $httpProvider.interceptors.push('myHttpInterceptor');
*
// alternatively, register the interceptor via an anonymous factory
$httpProvider.interceptors.push(function($q, dependency1, dependency2) {
return {
'request': function(config) {
// same as above
},
* 'response': function(response) {
// same as above
}
};
});
```
* ## Security Considerations
* When designing web applications, consider security threats from:
* - [JSON vulnerability](http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx)
- [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery)
* Both server and the client must cooperate in order to eliminate these threats. Angular comes
pre-configured with strategies that address these issues, but for this to work backend server
cooperation is required.
* ### JSON Vulnerability Protection
* A [JSON vulnerability](http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx)
allows third party website to turn your JSON resource URL into
[JSONP](http://en.wikipedia.org/wiki/JSONP) request under some conditions. To
counter this your server can prefix all JSON requests with following string `")]}',\n"`.
Angular will automatically strip the prefix before processing it as JSON.
* For example if your server needs to return:
```js
['one','two']
```
* which is vulnerable to attack, your server can return:
```js
)]}',
['one','two']
```
* Angular will strip the prefix, before processing the JSON.
*
### Cross Site Request Forgery (XSRF) Protection
* [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery) is a technique by which
an unauthorized site can gain your user's private data. Angular provides a mechanism
to counter XSRF. When performing XHR requests, the $http service reads a token from a cookie
(by default, `XSRF-TOKEN`) and sets it as an HTTP header (`X-XSRF-TOKEN`). Since only
JavaScript that runs on your domain could read the cookie, your server can be assured that
the XHR came from JavaScript running on your domain. The header will not be set for
cross-domain requests.
* To take advantage of this, your server needs to set a token in a JavaScript readable session
cookie called `XSRF-TOKEN` on the first HTTP GET request. On subsequent XHR requests the
server can verify that the cookie matches `X-XSRF-TOKEN` HTTP header, and therefore be sure
that only JavaScript running on your domain could have sent the request. The token must be
unique for each user and must be verifiable by the server (to prevent the JavaScript from
making up its own tokens). We recommend that the token is a digest of your site's
authentication cookie with a [salt](https://en.wikipedia.org/wiki/Salt_(cryptography&#41;)
for added security.
* The name of the headers can be specified using the xsrfHeaderName and xsrfCookieName
properties of either $httpProvider.defaults at config-time, $http.defaults at run-time,
or the per-request config object.
* In order to prevent collisions in environments where multiple Angular apps share the
same domain or subdomain, we recommend that each application uses unique cookie name.
" ilk="class" name="$http">
<scope doc="Shortcut method to perform `DELETE` request.
" ilk="function" name="delete" returns="HttpPromise" signature="delete(url) => HttpPromise">
<variable citdl="string" doc="Relative or absolute URL specifying the destination of the request" ilk="argument" name="url" />
</scope>
<scope doc="Shortcut method to perform `GET` request.
" ilk="function" name="get" returns="HttpPromise" signature="get(url) => HttpPromise">
<variable citdl="string" doc="Relative or absolute URL specifying the destination of the request" ilk="argument" name="url" />
</scope>
<scope doc="Shortcut method to perform `HEAD` request.
" ilk="function" name="head" returns="HttpPromise" signature="head(url) => HttpPromise">
<variable citdl="string" doc="Relative or absolute URL specifying the destination of the request" ilk="argument" name="url" />
</scope>
<scope doc="Shortcut method to perform `JSONP` request.
" ilk="function" name="jsonp" returns="HttpPromise" signature="jsonp(config) => HttpPromise">
<variable citdl="Object=" doc="Optional configuration object" ilk="argument" name="config" />
</scope>
<scope doc="Shortcut method to perform `PATCH` request.
" ilk="function" name="patch" returns="HttpPromise" signature="patch(url,config) => HttpPromise">
<variable citdl="string" doc="Relative or absolute URL specifying the destination of the request" ilk="argument" name="url" />
<variable citdl="Object=" doc="Optional configuration object" ilk="argument" name="config" />
</scope>
<scope doc="Shortcut method to perform `POST` request.
" ilk="function" name="post" returns="HttpPromise" signature="post(url,config) => HttpPromise">
<variable citdl="string" doc="Relative or absolute URL specifying the destination of the request" ilk="argument" name="url" />
<variable citdl="Object=" doc="Optional configuration object" ilk="argument" name="config" />
</scope>
<scope doc="Shortcut method to perform `PUT` request.
" ilk="function" name="put" returns="HttpPromise" signature="put(url,config) => HttpPromise">
<variable citdl="string" doc="Relative or absolute URL specifying the destination of the request" ilk="argument" name="url" />
<variable citdl="Object=" doc="Optional configuration object" ilk="argument" name="config" />
</scope>
<variable name="defaults" />
</scope>
<scope ilk="class" name="$httpBackend" />
<scope ilk="class" name="$httpParamSerializer" />
<scope ilk="class" name="$httpParamSerializerJQLike" />
<scope ilk="class" name="$injector">
<scope doc="Returns an array of service names which the function is requesting for injection. This API is
used by the injector to determine which services need to be injected into the function when the
function is invoked. There are three ways in which the function can be annotated with the needed
dependencies.
* # Argument names
* The simplest form is to extract the dependencies from the arguments of the function. This is done
by converting the function into a string using `toString()` method and extracting the argument
names.
```js
// Given
function MyController($scope, $route) {
// ...
}
* // Then
expect(injector.annotate(MyController)).toEqual(['$scope', '$route']);
```
* You can disallow this method by using strict injection mode.
* This method does not work with code minification / obfuscation. For this reason the following
annotation strategies are supported.
* # The `$inject` property
* If a function has an `$inject` property and its value is an array of strings, then the strings
represent names of services to be injected into the function.
```js
// Given
var MyController = function(obfuscatedScope, obfuscatedRoute) {
// ...
}
// Define function dependencies
MyController['$inject'] = ['$scope', '$route'];
* // Then
expect(injector.annotate(MyController)).toEqual(['$scope', '$route']);
```
* # The array notation
* It is often desirable to inline Injected functions and that's when setting the `$inject` property
is very inconvenient. In these situations using the array notation to specify the dependencies in
a way that survives minification is a better choice:
* ```js
// We wish to write this (not minification / obfuscation safe)
injector.invoke(function($compile, $rootScope) {
// ...
});
* // We are forced to write break inlining
var tmpFn = function(obfuscatedCompile, obfuscatedRootScope) {
// ...
};
tmpFn.$inject = ['$compile', '$rootScope'];
injector.invoke(tmpFn);
* // To better support inline function the inline annotation is supported
injector.invoke(['$compile', '$rootScope', function(obfCompile, obfRootScope) {
// ...
}]);
* // Therefore
expect(injector.annotate(
['$compile', '$rootScope', function(obfus_$compile, obfus_$rootScope) {}])
).toEqual(['$compile', '$rootScope']);
```
" ilk="function" name="annotate" returns="Array.<string>" signature="annotate() => Array.<string>" />
<scope doc="Return an instance of the service.
" ilk="function" name="get" signature="get(name)">
<variable citdl="string" doc="The name of the instance to retrieve." ilk="argument" name="name" />
</scope>
<scope doc="Allows the user to query if the particular service exists.
" ilk="function" name="has" returns="boolean" signature="has(name) => boolean">
<variable citdl="string" doc="Name of the service to query." ilk="argument" name="name" />
</scope>
<scope doc="Create a new instance of JS type. The method takes a constructor function, invokes the new
operator, and supplies all of the arguments to the constructor function as specified by the
constructor annotation.
" ilk="function" name="instantiate" returns="Object" signature="instantiate(Type) => Object">
<variable citdl="Function" doc="Annotated constructor function." ilk="argument" name="Type" />
</scope>
<scope doc="Invoke the method and supply the method arguments from the `$injector`.
" ilk="function" name="invoke" returns="*" signature="invoke(self) => *">
<variable citdl="Object=" doc="The `this` for the invoked method." ilk="argument" name="self" />
</scope>
</scope>
<scope doc="* Compiles a string with markup into an interpolation function. This service is used by the
HTML {@link ng.$compile $compile} service for data binding. See
{@link ng.$interpolateProvider $interpolateProvider} for configuring the
interpolation markup.
*
```js
var $interpolate = ...; // injected
var exp = $interpolate('Hello {{name | uppercase}}!');
expect(exp({name:'Angular'})).toEqual('Hello ANGULAR!');
```
* `$interpolate` takes an optional fourth argument, `allOrNothing`. If `allOrNothing` is
`true`, the interpolation function will return `undefined` unless all embedded expressions
evaluate to a value other than `undefined`.
* ```js
var $interpolate = ...; // injected
var context = {greeting: 'Hello', name: undefined };
* // default "forgiving" mode
var exp = $interpolate('{{greeting}} {{name}}!');
expect(exp(context)).toEqual('Hello !');
* // "allOrNothing" mode
exp = $interpolate('{{greeting}} {{name}}!', false, null, true);
expect(exp(context)).toBeUndefined();
context.name = 'Angular';
expect(exp(context)).toEqual('Hello Angular!');
```
* `allOrNothing` is useful for interpolating URLs. `ngSrc` and `ngSrcset` use this behavior.
* ####Escaped Interpolation
$interpolate provides a mechanism for escaping interpolation markers. Start and end markers
can be escaped by preceding each of their characters with a REVERSE SOLIDUS U+005C (backslash).
It will be rendered as a regular start/end marker, and will not be interpreted as an expression
or binding.
* This enables web-servers to prevent script injection attacks and defacing attacks, to some
degree, while also enabling code examples to work without relying on the
{@link ng.directive:ngNonBindable ngNonBindable} directive.
* **For security purposes, it is strongly encouraged that web servers escape user-supplied data,
replacing angle brackets (&lt;, &gt;) with &amp;lt; and &amp;gt; respectively, and replacing all
interpolation start/end markers with their escaped counterparts.**
* Escaped interpolation markers are only replaced with the actual interpolation markers in rendered
output when the $interpolate service processes the text. So, for HTML elements interpolated
by {@link ng.$compile $compile}, or otherwise interpolated with the `mustHaveExpression` parameter
set to `true`, the interpolated text must contain an unescaped interpolation expression. As such,
this is typically useful only when user-data is used in rendering a template from the server, or
when otherwise untrusted data is used by a directive.
* <example>
<file name="index.html">
<div ng-init="username='A user'">
<p ng-init="apptitle='Escaping demo'">{{apptitle}}: \{\{ username = "defaced value"; \}\}
</p>
<p><strong>{{username}}</strong> attempts to inject code which will deface the
application, but fails to accomplish their task, because the server has correctly
escaped the interpolation start/end markers with REVERSE SOLIDUS U+005C (backslash)
characters.</p>
<p>Instead, the result of the attempted script injection is visible, and can be removed
from the database by an administrator.</p>
</div>
</file>
</example>
" ilk="class" name="$interpolate">
<scope doc="Symbol to denote the end of expression in the interpolated string. Defaults to `}}`.
* Use {@link ng.$interpolateProvider#endSymbol `$interpolateProvider.endSymbol`} to change
the symbol.
" ilk="function" name="endSymbol" returns="string" signature="endSymbol() => string" />
<scope doc="Symbol to denote the start of expression in the interpolated string. Defaults to `{{`.
* Use {@link ng.$interpolateProvider#startSymbol `$interpolateProvider.startSymbol`} to change
the symbol.
" ilk="function" name="startSymbol" returns="string" signature="startSymbol() => string" />
</scope>
<scope doc="Angular's wrapper for `window.setInterval`. The `fn` function is executed every `delay`
milliseconds.
* The return value of registering an interval function is a promise. This promise will be
notified upon each tick of the interval, and will be resolved after `count` iterations, or
run indefinitely if `count` is not defined. The value of the notification will be the
number of iterations that have run.
To cancel an interval, call `$interval.cancel(promise)`.
* In tests you can use {@link ngMock.$interval#flush `$interval.flush(millis)`} to
move forward by `millis` milliseconds and trigger any functions scheduled to run in that
time.
* <div class="alert alert-warning">
**Note**: Intervals created by this service must be explicitly destroyed when you are finished
with them. In particular they are not automatically destroyed when a controller's scope or a
directive's element are destroyed.
You should take this into consideration and make sure to always cancel the interval at the
appropriate moment. See the example below for more details on how and when to do this.
</div>
" ilk="class" name="$interval">
<scope doc="Cancels a task associated with the `promise`.
" ilk="function" name="cancel" returns="boolean" signature="cancel(promise) => boolean">
<variable citdl="Promise=" doc="returned by the `$interval` function." ilk="argument" name="promise" />
</scope>
</scope>
<scope ilk="class" name="$locale" />
<scope ilk="class" name="$location">
<scope doc="This method is getter only.
* Return full url representation with all segments encoded according to rules specified in
[RFC 3986](http://www.ietf.org/rfc/rfc3986.txt).
*
```js
// given url http://example.com/#/some/path?foo=bar&baz=xoxo
var absUrl = $location.absUrl();
// => "http://example.com/#/some/path?foo=bar&baz=xoxo"
```
" ilk="function" name="absUrl" signature="absUrl()" />
<scope doc="This method is getter / setter.
* Returns the hash fragment when called without any parameters.
* Changes the hash fragment when called with a parameter and returns `$location`.
*
```js
// given url http://example.com/#/some/path?foo=bar&baz=xoxo#hashValue
var hash = $location.hash();
// => "hashValue"
```
" ilk="function" name="hash" signature="hash(hash)">
<variable citdl="(string|number)=" doc="New hash fragment" ilk="argument" name="hash" />
</scope>
<scope doc="This method is getter only.
* Return host of current url.
* Note: compared to the non-angular version `location.host` which returns `hostname:port`, this returns the `hostname` portion only.
*
```js
// given url http://example.com/#/some/path?foo=bar&baz=xoxo
var host = $location.host();
// => "example.com"
* // given url http://user:password@example.com:8080/#/some/path?foo=bar&baz=xoxo
host = $location.host();
// => "example.com"
host = location.host;
// => "example.com:8080"
```
" ilk="function" name="host" signature="host()" />
<scope doc="This method is getter / setter.
* Return path of current url when called without any parameter.
* Change path when called with parameter and return `$location`.
* Note: Path should always begin with forward slash (/), this method will add the forward slash
if it is missing.
*
```js
// given url http://example.com/#/some/path?foo=bar&baz=xoxo
var path = $location.path();
// => "/some/path"
```
" ilk="function" name="path" signature="path(path)">
<variable citdl="(string|number)=" doc="New path" ilk="argument" name="path" />
</scope>
<scope doc="This method is getter only.
* Return port of current url.
*
```js
// given url http://example.com/#/some/path?foo=bar&baz=xoxo
var port = $location.port();
// => 80
```
" ilk="function" name="port" signature="port()" />
<scope doc="This method is getter only.
* Return protocol of current url.
*
```js
// given url http://example.com/#/some/path?foo=bar&baz=xoxo
var protocol = $location.protocol();
// => "http"
```
" ilk="function" name="protocol" signature="protocol()" />
<scope ilk="function" name="replace" signature="replace()" />
<scope doc="This method is getter / setter.
* Return search part (as object) of current url when called without any parameter.
* Change search part when called with parameter and return `$location`.
*
```js
// given url http://example.com/#/some/path?foo=bar&baz=xoxo
var searchObject = $location.search();
// => {foo: 'bar', baz: 'xoxo'}
* // set foo to 'yipee'
$location.search('foo', 'yipee');
// $location.search() => {foo: 'yipee', baz: 'xoxo'}
```
" ilk="function" name="search" signature="search()" />
<scope doc="This method is getter / setter.
* Return the history state object when called without any parameter.
* Change the history state object when called with one parameter and return `$location`.
The state object is later passed to `pushState` or `replaceState`.
* NOTE: This method is supported only in HTML5 mode and only in browsers supporting
the HTML5 History API (i.e. methods `pushState` and `replaceState`). If you need to support
older browsers (like IE9 or Android < 4.0), don't use this method.
" ilk="function" name="state" signature="state(state)">
<variable citdl="object=" doc="State object for pushState or replaceState" ilk="argument" name="state" />
</scope>
<scope doc="This method is getter / setter.
* Return url (e.g. `/path?a=b#hash`) when called without any parameter.
* Change path, search and hash, when called with parameter and return `$location`.
*
```js
// given url http://example.com/#/some/path?foo=bar&baz=xoxo
var url = $location.url();
// => "/some/path?foo=bar&baz=xoxo"
```
" ilk="function" name="url" signature="url(url)">
<variable citdl="string=" doc="New url without base prefix (e.g. `/path?a=b#hash`)" ilk="argument" name="url" />
</scope>
</scope>
<scope doc="Simple service for logging. Default implementation safely writes the message
into the browser's console (if present).
* The main purpose of this service is to simplify debugging and troubleshooting.
* The default is to log `debug` messages. You can use
{@link ng.$logProvider ng.$logProvider#debugEnabled} to change this.
" ilk="class" name="$log">
<scope ilk="function" name="debug" signature="debug()" />
<scope ilk="function" name="error" signature="error()" />
<scope ilk="function" name="info" signature="info()" />
<scope ilk="function" name="log" signature="log()" />
<scope ilk="function" name="warn" signature="warn()" />
</scope>
<scope doc="* Converts Angular {@link guide/expression expression} into a function.
* ```js
var getter = $parse('user.name');
var setter = getter.assign;
var context = {user:{name:'angular'}};
var locals = {user:{name:'local'}};
* expect(getter(context)).toEqual('angular');
setter(context, 'newValue');
expect(context.user.name).toEqual('newValue');
expect(getter(context, locals)).toEqual('local');
```
*" ilk="class" name="$parse" />
<scope ilk="class" name="$provide">
<scope doc="* Register a **constant service**, such as a string, a number, an array, an object or a function,
with the {@link auto.$injector $injector}. Unlike {@link auto.$provide#value value} it can be
injected into a module configuration function (see {@link angular.Module#config}) and it cannot
be overridden by an Angular {@link auto.$provide#decorator decorator}.
" ilk="function" name="constant" returns="Object" signature="constant(name) => Object">
<variable citdl="string" doc="The name of the constant." ilk="argument" name="name" />
</scope>
<scope doc="* Register a **service decorator** with the {@link auto.$injector $injector}. A service decorator
intercepts the creation of a service, allowing it to override or modify the behavior of the
service. The object returned by the decorator may be the original service, or a new service
object which replaces or wraps and delegates to the original service.
" ilk="function" name="decorator" signature="decorator(name)">
<variable citdl="string" doc="The name of the service to decorate." ilk="argument" name="name" />
</scope>
<scope doc="* Register a **service factory**, which will be called to return the service instance.
This is short for registering a service where its provider consists of only a `$get` property,
which is the given service factory function.
You should use {@link auto.$provide#factory $provide.factory(getFn)} if you do not need to
configure your service in a provider.
" ilk="function" name="factory" returns="Object" signature="factory(name) => Object">
<variable citdl="string" doc="The name of the instance." ilk="argument" name="name" />
</scope>
<scope doc="* Register a **provider function** with the {@link auto.$injector $injector}. Provider functions
are constructor functions, whose instances are responsible for "providing" a factory for a
service.
* Service provider names start with the name of the service they provide followed by `Provider`.
For example, the {@link ng.$log $log} service has a provider called
{@link ng.$logProvider $logProvider}.
* Service provider objects can have additional methods which allow configuration of the provider
and its service. Importantly, you can configure what kind of service is created by the `$get`
method, or how that service will act. For example, the {@link ng.$logProvider $logProvider} has a
method {@link ng.$logProvider#debugEnabled debugEnabled}
which lets you specify whether the {@link ng.$log $log} service will log debug messages to the
console or not.
" ilk="function" name="provider" returns="Object" signature="provider() => Object" />
<scope doc="* Register a **service constructor**, which will be invoked with `new` to create the service
instance.
This is short for registering a service where its provider's `$get` property is the service
constructor function that will be used to instantiate the service instance.
* You should use {@link auto.$provide#service $provide.service(class)} if you define your service
as a type/class.
" ilk="function" name="service" returns="Object" signature="service(name) => Object">
<variable citdl="string" doc="The name of the instance." ilk="argument" name="name" />
</scope>
<scope doc="* Register a **value service** with the {@link auto.$injector $injector}, such as a string, a
number, an array, an object or a function. This is short for registering a service where its
provider's `$get` property is a factory function that takes no arguments and returns the **value
service**.
* Value services are similar to constant services, except that they cannot be injected into a
module configuration function (see {@link angular.Module#config}) but they can be overridden by
an Angular
{@link auto.$provide#decorator decorator}.
" ilk="function" name="value" returns="Object" signature="value(name) => Object">
<variable citdl="string" doc="The name of the instance." ilk="argument" name="name" />
</scope>
</scope>
<scope doc="A service that helps you run functions asynchronously, and use their return values (or exceptions)
when they are done processing.
* This is an implementation of promises/deferred objects inspired by
[Kris Kowal's Q](https://github.com/kriskowal/q).
* $q can be used in two fashions --- one which is more similar to Kris Kowal's Q or jQuery's Deferred
implementations, and the other which resembles ES6 promises to some degree.
* # $q constructor
* The streamlined ES6 style promise is essentially just using $q as a constructor which takes a `resolver`
function as the first argument. This is similar to the native Promise implementation from ES6 Harmony,
see [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
* While the constructor-style use is supported, not all of the supporting methods from ES6 Harmony promises are
available yet.
* It can be used like so:
* ```js
// for the purpose of this example let's assume that variables `$q` and `okToGreet`
// are available in the current lexical scope (they could have been injected or passed in).
* function asyncGreet(name) {
// perform some asynchronous operation, resolve or reject the promise when appropriate.
return $q(function(resolve, reject) {
setTimeout(function() {
if (okToGreet(name)) {
resolve('Hello, ' + name + '!');
} else {
reject('Greeting ' + name + ' is not allowed.');
}
}, 1000);
});
}
* var promise = asyncGreet('Robin Hood');
promise.then(function(greeting) {
alert('Success: ' + greeting);
}, function(reason) {
alert('Failed: ' + reason);
});
```
* Note: progress/notify callbacks are not currently supported via the ES6-style interface.
* Note: unlike ES6 behaviour, an exception thrown in the constructor function will NOT implicitly reject the promise.
* However, the more traditional CommonJS-style usage is still available, and documented below.
* [The CommonJS Promise proposal](http://wiki.commonjs.org/wiki/Promises) describes a promise as an
interface for interacting with an object that represents the result of an action that is
performed asynchronously, and may or may not be finished at any given point in time.
* From the perspective of dealing with error handling, deferred and promise APIs are to
asynchronous programming what `try`, `catch` and `throw` keywords are to synchronous programming.
* ```js
// for the purpose of this example let's assume that variables `$q` and `okToGreet`
// are available in the current lexical scope (they could have been injected or passed in).
* function asyncGreet(name) {
var deferred = $q.defer();
* setTimeout(function() {
deferred.notify('About to greet ' + name + '.');
* if (okToGreet(name)) {
deferred.resolve('Hello, ' + name + '!');
} else {
deferred.reject('Greeting ' + name + ' is not allowed.');
}
}, 1000);
* return deferred.promise;
}
* var promise = asyncGreet('Robin Hood');
promise.then(function(greeting) {
alert('Success: ' + greeting);
}, function(reason) {
alert('Failed: ' + reason);
}, function(update) {
alert('Got notification: ' + update);
});
```
* At first it might not be obvious why this extra complexity is worth the trouble. The payoff
comes in the way of guarantees that promise and deferred APIs make, see
https://github.com/kriskowal/uncommonjs/blob/master/promises/specification.md.
* Additionally the promise api allows for composition that is very hard to do with the
traditional callback ([CPS](http://en.wikipedia.org/wiki/Continuation-passing_style)) approach.
For more on this please see the [Q documentation](https://github.com/kriskowal/q) especially the
section on serial or parallel joining of promises.
* # The Deferred API
* A new instance of deferred is constructed by calling `$q.defer()`.
* The purpose of the deferred object is to expose the associated Promise instance as well as APIs
that can be used for signaling the successful or unsuccessful completion, as well as the status
of the task.
* **Methods**
* - `resolve(value)` – resolves the derived promise with the `value`. If the value is a rejection
constructed via `$q.reject`, the promise will be rejected instead.
- `reject(reason)` – rejects the derived promise with the `reason`. This is equivalent to
resolving it with a rejection constructed via `$q.reject`.
- `notify(value)` - provides updates on the status of the promise's execution. This may be called
multiple times before the promise is either resolved or rejected.
* **Properties**
* - promise – `{Promise}` – promise object associated with this deferred.
*
# The Promise API
* A new promise instance is created when a deferred instance is created and can be retrieved by
calling `deferred.promise`.
* The purpose of the promise object is to allow for interested parties to get access to the result
of the deferred task when it completes.
* **Methods**
* - `then(successCallback, errorCallback, notifyCallback)` – regardless of when the promise was or
will be resolved or rejected, `then` calls one of the success or error callbacks asynchronously
as soon as the result is available. The callbacks are called with a single argument: the result
or rejection reason. Additionally, the notify callback may be called zero or more times to
provide a progress indication, before the promise is resolved or rejected.
* This method *returns a new promise* which is resolved or rejected via the return value of the
`successCallback`, `errorCallback` (unless that value is a promise, in which case it is resolved
with the value which is resolved in that promise using
[promise chaining](http://www.html5rocks.com/en/tutorials/es6/promises/#toc-promises-queues)).
It also notifies via the return value of the `notifyCallback` method. The promise cannot be
resolved or rejected from the notifyCallback method.
* - `catch(errorCallback)` – shorthand for `promise.then(null, errorCallback)`
* - `finally(callback, notifyCallback)` – allows you to observe either the fulfillment or rejection of a promise,
but to do so without modifying the final value. This is useful to release resources or do some
clean-up that needs to be done whether the promise was rejected or resolved. See the [full
specification](https://github.com/kriskowal/q/wiki/API-Reference#promisefinallycallback) for
more information.
* # Chaining promises
* Because calling the `then` method of a promise returns a new derived promise, it is easily
possible to create a chain of promises:
* ```js
promiseB = promiseA.then(function(result) {
return result + 1;
});
* // promiseB will be resolved immediately after promiseA is resolved and its value
// will be the result of promiseA incremented by 1
```
* It is possible to create chains of any length and since a promise can be resolved with another
promise (which will defer its resolution further), it is possible to pause/defer resolution of
the promises at any point in the chain. This makes it possible to implement powerful APIs like
$http's response interceptors.
*
# Differences between Kris Kowal's Q and $q
* There are two main differences:
* - $q is integrated with the {@link ng.$rootScope.Scope} Scope model observation
mechanism in angular, which means faster propagation of resolution or rejection into your
models and avoiding unnecessary browser repaints, which would result in flickering UI.
- Q has many more features than $q, but that comes at a cost of bytes. $q is tiny, but contains
all the important functionality needed for common async tasks.
* # Testing
* ```js
it('should simulate promise', inject(function($q, $rootScope) {
var deferred = $q.defer();
var promise = deferred.promise;
var resolvedValue;
* promise.then(function(value) { resolvedValue = value; });
expect(resolvedValue).toBeUndefined();
* // Simulate resolving of promise
deferred.resolve(123);
// Note that the 'then' function does not get called synchronously.
// This is because we want the promise API to always be async, whether or not
// it got called synchronously or asynchronously.
expect(resolvedValue).toBeUndefined();
* // Propagate promise resolution to 'then' functions using $apply().
$rootScope.$apply();
expect(resolvedValue).toEqual(123);
}));
```
" ilk="class" name="$q">
<scope doc="Combines multiple promises into a single promise that is resolved when all of the input
promises are resolved.
" ilk="function" name="all" returns="Promise" signature="all(promises) => Promise">
<variable citdl="Array.<Promise>|Object.<Promise>" doc="An array or hash of promises." ilk="argument" name="promises" />
</scope>
<scope doc="Creates a promise that is resolved as rejected with the specified `reason`. This api should be
used to forward rejection in a chain of promises. If you are dealing with the last promise in
a promise chain, you don't need to worry about it.
* When comparing deferreds/promises to the familiar behavior of try/catch/throw, think of
`reject` as the `throw` keyword in JavaScript. This also means that if you "catch" an error via
a promise error callback and you want to forward the error to the promise derived from the
current promise, you have to "rethrow" the error by returning a rejection constructed via
`reject`.
* ```js
promiseB = promiseA.then(function(result) {
// success: do something and resolve promiseB
// with the old or a new result
return result;
}, function(reason) {
// error: handle the error if possible and
// resolve promiseB with newPromiseOrValue,
// otherwise forward the rejection to promiseB
if (canHandle(reason)) {
// handle the error and recover
return newPromiseOrValue;
}
return $q.reject(reason);
});
```
" ilk="function" name="reject" returns="Promise" signature="reject(reason) => Promise">
<variable citdl="*" doc="Constant, message, exception or an object representing the rejection reason." ilk="argument" name="reason" />
</scope>
<scope doc="Alias of {@link ng.$q#when when} to maintain naming consistency with ES6.
" ilk="function" name="resolve" returns="Promise" signature="resolve(value,errorCallback) => Promise">
<variable citdl="*" doc="Value or a promise" ilk="argument" name="value" />
<variable citdl="Function=" doc="* @param {Function=} progressCallback" ilk="argument" name="errorCallback" />
</scope>
<scope doc="Wraps an object that might be a value or a (3rd party) then-able promise into a $q promise.
This is useful when you are dealing with an object that might or might not be a promise, or if
the promise comes from a source that can't be trusted.
" ilk="function" name="when" returns="Promise" signature="when(value,errorCallback) => Promise">
<variable citdl="*" doc="Value or a promise" ilk="argument" name="value" />
<variable citdl="Function=" doc="* @param {Function=} progressCallback" ilk="argument" name="errorCallback" />
</scope>
</scope>
<scope ilk="class" name="$rootElement" />
<scope ilk="class" name="$rootScope">
<scope doc="A root scope can be retrieved using the {@link ng.$rootScope $rootScope} key from the
{@link auto.$injector $injector}. Child scopes are created using the
{@link ng.$rootScope.Scope#$new $new()} method. (Most scopes are created automatically when
compiled HTML template is executed.) See also the {@link guide/scope Scopes guide} for
an in-depth introduction and usage examples.
*
# Inheritance
A scope can inherit from a parent scope, as in this example:
```js
 var parent = $rootScope;
 var child = parent.$new();

 parent.salutation = "Hello";
 expect(child.salutation).toEqual('Hello');

 child.salutation = "Welcome";
 expect(child.salutation).toEqual('Welcome');
 expect(parent.salutation).toEqual('Hello');
```
* When interacting with `Scope` in tests, additional helper methods are available on the
instances of `Scope` type. See {@link ngMock.$rootScope.Scope ngMock Scope} for additional
details.
*" ilk="class" name="Scope">
<scope doc="`$apply()` is used to execute an expression in angular from outside of the angular
framework. (For example from browser DOM events, setTimeout, XHR or third party libraries).
Because we are calling into the angular framework we need to perform proper scope life
cycle of {@link ng.$exceptionHandler exception handling},
{@link ng.$rootScope.Scope#$digest executing watches}.
* ## Life cycle
* # Pseudo-Code of `$apply()`
```js
 function $apply(expr) {
 try {
 return $eval(expr);
 } catch (e) {
 $exceptionHandler(e);
 } finally {
 $root.$digest();
 }
 }
```
*
Scope's `$apply()` method transitions through the following stages:
* 1. The {@link guide/expression expression} is executed using the
{@link ng.$rootScope.Scope#$eval $eval()} method.
2. Any exceptions from the execution of the expression are forwarded to the
{@link ng.$exceptionHandler $exceptionHandler} service.
3. The {@link ng.$rootScope.Scope#$watch watch} listeners are fired immediately after the
expression was executed using the {@link ng.$rootScope.Scope#$digest $digest()} method.
*" ilk="function" name="$apply" returns="*" signature="$apply() => *" />
<scope doc="Schedule the invocation of $apply to occur at a later time. The actual time difference
varies across browsers, but is typically around ~10 milliseconds.
* This can be used to queue up multiple expressions which need to be evaluated in the same
digest.
" ilk="function" name="$applyAsync" signature="$applyAsync()" />
<scope doc="Dispatches an event `name` downwards to all child scopes (and their children) notifying the
registered {@link ng.$rootScope.Scope#$on} listeners.
* The event life cycle starts at the scope on which `$broadcast` was called. All
{@link ng.$rootScope.Scope#$on listeners} listening for `name` event on this scope get
notified. Afterwards, the event propagates to all direct and indirect scopes of the current
scope and calls all registered listeners along the way. The event cannot be canceled.
* Any exception emitted from the {@link ng.$rootScope.Scope#$on listeners} will be passed
onto the {@link ng.$exceptionHandler $exceptionHandler} service.
" ilk="function" name="$broadcast" signature="$broadcast(name)">
<variable citdl="string" doc="Event name to broadcast." ilk="argument" name="name" />
</scope>
<scope ilk="function" name="$destroy" signature="$destroy()" />
<scope ilk="function" name="$digest" signature="$digest()" />
<scope doc="Dispatches an event `name` upwards through the scope hierarchy notifying the
registered {@link ng.$rootScope.Scope#$on} listeners.
* The event life cycle starts at the scope on which `$emit` was called. All
{@link ng.$rootScope.Scope#$on listeners} listening for `name` event on this scope get
notified. Afterwards, the event traverses upwards toward the root scope and calls all
registered listeners along the way. The event will stop propagating if one of the listeners
cancels it.
* Any exception emitted from the {@link ng.$rootScope.Scope#$on listeners} will be passed
onto the {@link ng.$exceptionHandler $exceptionHandler} service.
" ilk="function" name="$emit" signature="$emit(name)">
<variable citdl="string" doc="Event name to emit." ilk="argument" name="name" />
</scope>
<scope doc="Executes the `expression` on the current scope and returns the result. Any exceptions in
the expression are propagated (uncaught). This is useful when evaluating Angular
expressions.
* # Example
```js
 var scope = ng.$rootScope.Scope();
 scope.a = 1;
 scope.b = 2;

 expect(scope.$eval('a+b')).toEqual(3);
 expect(scope.$eval(function(scope){ return scope.a + scope.b; })).toEqual(3);
```
" ilk="function" name="$eval" returns="*" signature="$eval(locals) => *">
<variable citdl="(object)=" doc="Local variables object, useful for overriding values in scope." ilk="argument" name="locals" />
</scope>
<scope doc="Executes the expression on the current scope at a later point in time.
* The `$evalAsync` makes no guarantees as to when the `expression` will be executed, only
that:
* - it will execute after the function that scheduled the evaluation (preferably before DOM
rendering).
- at least one {@link ng.$rootScope.Scope#$digest $digest cycle} will be performed after
`expression` execution.
* Any exceptions from the execution of the expression are forwarded to the
{@link ng.$exceptionHandler $exceptionHandler} service.
* __Note:__ if this function is called outside of a `$digest` cycle, a new `$digest` cycle
will be scheduled. However, it is encouraged to always call code that changes the model
from within an `$apply` call. That includes code evaluated via `$evalAsync`.
" ilk="function" name="$evalAsync" signature="$evalAsync()" />
<scope doc="Creates a new child {@link ng.$rootScope.Scope scope}.
* The parent scope will propagate the {@link ng.$rootScope.Scope#$digest $digest()} event.
The scope can be removed from the scope hierarchy using {@link ng.$rootScope.Scope#$destroy $destroy()}.
* {@link ng.$rootScope.Scope#$destroy $destroy()} must be called on a scope when it is
desired for the scope and its child scopes to be permanently detached from the parent and
thus stop participating in model change detection and listener notification by invoking.
" ilk="function" name="$new" returns="Object" signature="$new() => Object" />
<scope doc="Listens on events of a given type. See {@link ng.$rootScope.Scope#$emit $emit} for
discussion of event life cycle.
* The event listener function format is: `function(event, args...)`. The `event` object
passed into the listener has the following attributes:
* - `targetScope` - `{Scope}`: the scope on which the event was `$emit`-ed or
`$broadcast`-ed.
- `currentScope` - `{Scope}`: the scope that is currently handling the event. Once the
event propagates through the scope hierarchy, this property is set to null.
- `name` - `{string}`: name of the event.
- `stopPropagation` - `{function=}`: calling `stopPropagation` function will cancel
further event propagation (available only for events that were `$emit`-ed).
- `preventDefault` - `{function}`: calling `preventDefault` sets `defaultPrevented` flag
to true.
- `defaultPrevented` - `{boolean}`: true if `preventDefault` was called.
" ilk="function" name="$on" returns="function()" signature="$on(name) => function()">
<variable citdl="string" doc="Event name to listen on." ilk="argument" name="name" />
</scope>
<scope doc="Registers a `listener` callback to be executed whenever the `watchExpression` changes.
* - The `watchExpression` is called on every call to {@link ng.$rootScope.Scope#$digest
$digest()} and should return the value that will be watched. (`watchExpression` should not change
its value when executed multiple times with the same input because it may be executed multiple
times by {@link ng.$rootScope.Scope#$digest $digest()}. That is, `watchExpression` should be
[idempotent](http://en.wikipedia.org/wiki/Idempotence).
- The `listener` is called only when the value from the current `watchExpression` and the
previous call to `watchExpression` are not equal (with the exception of the initial run,
see below). Inequality is determined according to reference inequality,
[strict comparison](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Comparison_Operators)
via the `!==` Javascript operator, unless `objectEquality == true`
(see next point)
- When `objectEquality == true`, inequality of the `watchExpression` is determined
according to the {@link angular.equals} function. To save the value of the object for
later comparison, the {@link angular.copy} function is used. This therefore means that
watching complex objects will have adverse memory and performance implications.
- The watch `listener` may change the model, which may trigger other `listener`s to fire.
This is achieved by rerunning the watchers until no changes are detected. The rerun
iteration limit is 10 to prevent an infinite loop deadlock.
*
If you want to be notified whenever {@link ng.$rootScope.Scope#$digest $digest} is called,
you can register a `watchExpression` function with no `listener`. (Be prepared for
multiple calls to your `watchExpression` because it will execute multiple times in a
single {@link ng.$rootScope.Scope#$digest $digest} cycle if a change is detected.)
* After a watcher is registered with the scope, the `listener` fn is called asynchronously
(via {@link ng.$rootScope.Scope#$evalAsync $evalAsync}) to initialize the
watcher. In rare cases, this is undesirable because the listener is called when the result
of `watchExpression` didn't change. To detect this scenario within the `listener` fn, you
can compare the `newVal` and `oldVal`. If these two values are identical (`===`) then the
listener was called due to initialization.
*
* # Example
```js
 // let's assume that scope was dependency injected as the $rootScope
 var scope = $rootScope;
 scope.name = 'misko';
 scope.counter = 0;

 expect(scope.counter).toEqual(0);
 scope.$watch('name', function(newValue, oldValue) {
 scope.counter = scope.counter + 1;
 });
 expect(scope.counter).toEqual(0);

 scope.$digest();
 // the listener is always called during the first $digest loop after it was registered
 expect(scope.counter).toEqual(1);

 scope.$digest();
 // but now it will not be called unless the value changes
 expect(scope.counter).toEqual(1);

 scope.name = 'adam';
 scope.$digest();
 expect(scope.counter).toEqual(2);



 // Using a function as a watchExpression
 var food;
 scope.foodCounter = 0;
 expect(scope.foodCounter).toEqual(0);
 scope.$watch(
 // This function returns the value being watched. It is called for each turn of the $digest loop
 function() { return food; },
 // This is the change listener, called when the value returned from the above function changes
 function(newValue, oldValue) {
 if ( newValue !== oldValue ) {
 // Only increment the counter if the value changed
 scope.foodCounter = scope.foodCounter + 1;
 }
 }
 );
 // No digest has been run so the counter will be zero
 expect(scope.foodCounter).toEqual(0);

 // Run the digest but since food has not changed count will still be zero
 scope.$digest();
 expect(scope.foodCounter).toEqual(0);

 // Update food and run digest. Now the counter will increment
 food = 'cheeseburger';
 scope.$digest();
 expect(scope.foodCounter).toEqual(1);
```
*
" ilk="function" name="$watch" returns="function()" signature="$watch() => function()" />
<scope doc="Shallow watches the properties of an object and fires whenever any of the properties change
(for arrays, this implies watching the array items; for object maps, this implies watching
the properties). If a change is detected, the `listener` callback is fired.
* - The `obj` collection is observed via standard $watch operation and is examined on every
call to $digest() to see if any items have been added, removed, or moved.
- The `listener` is called whenever anything within the `obj` has changed. Examples include
adding, removing, and moving items belonging to an object or array.
*
# Example
```js
 $scope.names = ['igor', 'matias', 'misko', 'james'];
 $scope.dataCount = 4;

 $scope.$watchCollection('names', function(newNames, oldNames) {
 $scope.dataCount = newNames.length;
 });

 expect($scope.dataCount).toEqual(4);
 $scope.$digest();

 //still at 4 ... no changes
 expect($scope.dataCount).toEqual(4);

 $scope.names.pop();
 $scope.$digest();

 //now there's been a change
 expect($scope.dataCount).toEqual(3);
```
*" ilk="function" name="$watchCollection" returns="function()" signature="$watchCollection() => function()" />
<scope doc="A variant of {@link ng.$rootScope.Scope#$watch $watch()} where it watches an array of `watchExpressions`.
If any one expression in the collection changes the `listener` is executed.
* - The items in the `watchExpressions` array are observed via standard $watch operation and are examined on every
call to $digest() to see if any items changes.
- The `listener` is called whenever any expression in the `watchExpressions` array changes.
" ilk="function" name="$watchGroup" returns="function()" signature="$watchGroup() => function()" />
<variable name="$id" />
<variable name="$parent" />
<variable name="$root" />
</scope>
</scope>
<scope ilk="class" name="$sce">
<scope doc="Delegates to {@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted`}. As such,
takes the result of a {@link ng.$sce#trustAs `$sce.trustAs`}() call and returns the
originally supplied value if the queried context type is a supertype of the created type.
If this condition isn't satisfied, throws an exception.
" ilk="function" name="getTrusted" returns="*" signature="getTrusted(type) => *">
<variable citdl="string" doc="The kind of context in which this value is to be used." ilk="argument" name="type" />
</scope>
<scope doc="Shorthand method. `$sce.getTrustedCss(value)` →
{@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.CSS, value)`}
" ilk="function" name="getTrustedCss" returns="*" signature="getTrustedCss(value) => *">
<variable citdl="*" doc="The value to pass to `$sce.getTrusted`." ilk="argument" name="value" />
</scope>
<scope doc="Shorthand method. `$sce.getTrustedHtml(value)` →
{@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.HTML, value)`}
" ilk="function" name="getTrustedHtml" returns="*" signature="getTrustedHtml(value) => *">
<variable citdl="*" doc="The value to pass to `$sce.getTrusted`." ilk="argument" name="value" />
</scope>
<scope doc="Shorthand method. `$sce.getTrustedJs(value)` →
{@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.JS, value)`}
" ilk="function" name="getTrustedJs" returns="*" signature="getTrustedJs(value) => *">
<variable citdl="*" doc="The value to pass to `$sce.getTrusted`." ilk="argument" name="value" />
</scope>
<scope doc="Shorthand method. `$sce.getTrustedResourceUrl(value)` →
{@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.RESOURCE_URL, value)`}
" ilk="function" name="getTrustedResourceUrl" returns="*" signature="getTrustedResourceUrl(value) => *">
<variable citdl="*" doc="The value to pass to `$sceDelegate.getTrusted`." ilk="argument" name="value" />
</scope>
<scope doc="Shorthand method. `$sce.getTrustedUrl(value)` →
{@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.URL, value)`}
" ilk="function" name="getTrustedUrl" returns="*" signature="getTrustedUrl(value) => *">
<variable citdl="*" doc="The value to pass to `$sce.getTrusted`." ilk="argument" name="value" />
</scope>
<scope ilk="function" name="isEnabled" signature="isEnabled()" />
<scope doc="Converts Angular {@link guide/expression expression} into a function. This is like {@link
ng.$parse $parse} and is identical when the expression is a literal constant. Otherwise, it
wraps the expression in a call to {@link ng.$sce#getTrusted $sce.getTrusted(*type*,
*result*)}
" ilk="function" name="parseAs" returns="function(context, locals)" signature="parseAs(type) => function(context, locals)">
<variable citdl="string" doc="The kind of SCE context in which this result will be used." ilk="argument" name="type" />
</scope>
<scope doc="Shorthand method. `$sce.parseAsCss(value)` →
{@link ng.$sce#parseAs `$sce.parseAs($sce.CSS, value)`}
" ilk="function" name="parseAsCss" returns="function(context, locals)" signature="parseAsCss(expression) => function(context, locals)">
<variable citdl="string" doc="String expression to compile." ilk="argument" name="expression" />
</scope>
<scope doc="Shorthand method. `$sce.parseAsHtml(expression string)` →
{@link ng.$sce#parseAs `$sce.parseAs($sce.HTML, value)`}
" ilk="function" name="parseAsHtml" returns="function(context, locals)" signature="parseAsHtml(expression) => function(context, locals)">
<variable citdl="string" doc="String expression to compile." ilk="argument" name="expression" />
</scope>
<scope doc="Shorthand method. `$sce.parseAsJs(value)` →
{@link ng.$sce#parseAs `$sce.parseAs($sce.JS, value)`}
" ilk="function" name="parseAsJs" returns="function(context, locals)" signature="parseAsJs(expression) => function(context, locals)">
<variable citdl="string" doc="String expression to compile." ilk="argument" name="expression" />
</scope>
<scope doc="Shorthand method. `$sce.parseAsResourceUrl(value)` →
{@link ng.$sce#parseAs `$sce.parseAs($sce.RESOURCE_URL, value)`}
" ilk="function" name="parseAsResourceUrl" returns="function(context, locals)" signature="parseAsResourceUrl(expression) => function(context, locals)">
<variable citdl="string" doc="String expression to compile." ilk="argument" name="expression" />
</scope>
<scope doc="Shorthand method. `$sce.parseAsUrl(value)` →
{@link ng.$sce#parseAs `$sce.parseAs($sce.URL, value)`}
" ilk="function" name="parseAsUrl" returns="function(context, locals)" signature="parseAsUrl(expression) => function(context, locals)">
<variable citdl="string" doc="String expression to compile." ilk="argument" name="expression" />
</scope>
<scope doc="Delegates to {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}. As such,
returns an object that is trusted by angular for use in specified strict contextual
escaping contexts (such as ng-bind-html, ng-include, any src attribute
interpolation, any dom event binding attribute interpolation such as for onclick, etc.)
that uses the provided value. See * {@link ng.$sce $sce} for enabling strict contextual
escaping.
" ilk="function" name="trustAs" returns="*" signature="trustAs(value) => *">
<variable citdl="*" doc="The value that that should be considered trusted/safe." ilk="argument" name="value" />
</scope>
<scope doc="Shorthand method. `$sce.trustAsHtml(value)` →
{@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.HTML, value)`}
" ilk="function" name="trustAsHtml" returns="*" signature="trustAsHtml(value) => *">
<variable citdl="*" doc="The value to trustAs." ilk="argument" name="value" />
</scope>
<scope doc="Shorthand method. `$sce.trustAsJs(value)` →
{@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.JS, value)`}
" ilk="function" name="trustAsJs" returns="*" signature="trustAsJs(value) => *">
<variable citdl="*" doc="The value to trustAs." ilk="argument" name="value" />
</scope>
<scope doc="Shorthand method. `$sce.trustAsResourceUrl(value)` →
{@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.RESOURCE_URL, value)`}
" ilk="function" name="trustAsResourceUrl" returns="*" signature="trustAsResourceUrl(value) => *">
<variable citdl="*" doc="The value to trustAs." ilk="argument" name="value" />
</scope>
<scope doc="Shorthand method. `$sce.trustAsUrl(value)` →
{@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.URL, value)`}
" ilk="function" name="trustAsUrl" returns="*" signature="trustAsUrl(value) => *">
<variable citdl="*" doc="The value to trustAs." ilk="argument" name="value" />
</scope>
</scope>
<scope ilk="class" name="$sceDelegate">
<scope doc="Takes the result of a {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`} call and
returns the originally supplied value if the queried context type is a supertype of the
created type. If this condition isn't satisfied, throws an exception.
" ilk="function" name="getTrusted" returns="*" signature="getTrusted(type) => *">
<variable citdl="string" doc="The kind of context in which this value is to be used." ilk="argument" name="type" />
</scope>
<scope doc="Returns an object that is trusted by angular for use in specified strict
contextual escaping contexts (such as ng-bind-html, ng-include, any src
attribute interpolation, any dom event binding attribute interpolation
such as for onclick, etc.) that uses the provided value.
See {@link ng.$sce $sce} for enabling strict contextual escaping.
" ilk="function" name="trustAs" returns="*" signature="trustAs(value) => *">
<variable citdl="*" doc="The value that that should be considered trusted/safe." ilk="argument" name="value" />
</scope>
<scope doc="If the passed parameter had been returned by a prior call to {@link ng.$sceDelegate#trustAs
`$sceDelegate.trustAs`}, returns the value that had been passed to {@link
ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}.
* If the passed parameter is not a value that had been returned by {@link
ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}, returns it as-is.
" ilk="function" name="valueOf" returns="*" signature="valueOf() => *" />
</scope>
<scope ilk="class" name="$templateCache" />
<scope doc="The `$templateRequest` service runs security checks then downloads the provided template using
`$http` and, upon success, stores the contents inside of `$templateCache`. If the HTTP request
fails or the response data of the HTTP request is empty, a `$compile` error will be thrown (the
exception can be thwarted by setting the 2nd parameter of the function to true). Note that the
contents of `$templateCache` are trusted, so the call to `$sce.getTrustedUrl(tpl)` is omitted
when `tpl` is of type string and `$templateCache` has the matching entry.
" ilk="class" name="$templateRequest" />
<scope doc="Angular's wrapper for `window.setTimeout`. The `fn` function is wrapped into a try/catch
block and delegates any exceptions to
{@link ng.$exceptionHandler $exceptionHandler} service.
* The return value of calling `$timeout` is a promise, which will be resolved when
the delay has passed and the timeout function, if provided, is executed.
* To cancel a timeout request, call `$timeout.cancel(promise)`.
* In tests you can use {@link ngMock.$timeout `$timeout.flush()`} to
synchronously flush the queue of deferred functions.
* If you only want a promise that will be resolved after some specified delay
then you can call `$timeout` without the `fn` function.
" ilk="class" name="$timeout">
<scope doc="Cancels a task associated with the `promise`. As a result of this, the promise will be
resolved with a rejection.
" ilk="function" name="cancel" returns="boolean" signature="cancel(promise) => boolean">
<variable citdl="Promise=" doc="Promise returned by the `$timeout` function." ilk="argument" name="promise" />
</scope>
</scope>
<scope doc="A reference to the browser's `window` object. While `window`
is globally available in JavaScript, it causes testability problems, because
it is a global variable. In angular we always refer to it through the
`$window` service, so it may be overridden, removed or mocked for testing.
* Expressions, like the one defined for the `ngClick` directive in the example
below, are evaluated with respect to the current scope. Therefore, there is
no risk of inadvertently coding in a dependency on a global value in such an
expression.
" ilk="class" name="$window" />
<scope doc="Factory function used to create XMLHttpRequest objects.
* Replace or decorate this service to create your own custom XMLHttpRequest objects.
* ```
angular.module('myApp', [])
.factory('$xhrFactory', function() {
return function createXhr(method, url) {
return new window.XMLHttpRequest({mozSystem: true});
};
});
```
" ilk="class" name="$xhrFactory" />
<scope ilk="namespace" name="form">
<scope ilk="class" name="FormController">
<scope ilk="function" name="$addControl" signature="$addControl()" />
<scope ilk="function" name="$commitViewValue" signature="$commitViewValue()" />
<scope ilk="function" name="$removeControl" signature="$removeControl()" />
<scope ilk="function" name="$rollbackViewValue" signature="$rollbackViewValue()" />
<scope ilk="function" name="$setDirty" signature="$setDirty()" />
<scope ilk="function" name="$setPristine" signature="$setPristine()" />
<scope ilk="function" name="$setSubmitted" signature="$setSubmitted()" />
<scope ilk="function" name="$setUntouched" signature="$setUntouched()" />
<scope ilk="function" name="$setValidity" signature="$setValidity()" />
</scope>
</scope>
<scope ilk="namespace" name="ngModel">
<scope doc="* `NgModelController` provides API for the {@link ngModel `ngModel`} directive.
The controller contains services for data-binding, validation, CSS updates, and value formatting
and parsing. It purposefully does not contain any logic which deals with DOM rendering or
listening to DOM events.
Such DOM related logic should be provided by other directives which make use of
`NgModelController` for data-binding to control elements.
Angular provides this DOM logic for most {@link input `input`} elements.
At the end of this page you can find a {@link ngModel.NgModelController#custom-control-example
custom control example} that uses `ngModelController` to bind to `contenteditable` elements.
" ilk="class" name="NgModelController">
<scope ilk="function" name="$commitViewValue" signature="$commitViewValue()" />
<scope doc="This is called when we need to determine if the value of an input is empty.
* For instance, the required directive does this to work out if the input has data or not.
* The default `$isEmpty` function checks whether the value is `undefined`, `''`, `null` or `NaN`.
* You can override this for input directives whose concept of being empty is different from the
default. The `checkboxInputType` directive does this because in its case a value of `false`
implies empty.
" ilk="function" name="$isEmpty" returns="boolean" signature="$isEmpty(value) => boolean">
<variable citdl="*" doc="The value of the input to check for emptiness." ilk="argument" name="value" />
</scope>
<scope ilk="function" name="$render" signature="$render()" />
<scope ilk="function" name="$rollbackViewValue" signature="$rollbackViewValue()" />
<scope ilk="function" name="$setDirty" signature="$setDirty()" />
<scope ilk="function" name="$setPristine" signature="$setPristine()" />
<scope ilk="function" name="$setTouched" signature="$setTouched()" />
<scope ilk="function" name="$setUntouched" signature="$setUntouched()" />
<scope doc="Change the validity state, and notify the form.
* This method can be called within $parsers/$formatters or a custom validation implementation.
However, in most cases it should be sufficient to use the `ngModel.$validators` and
`ngModel.$asyncValidators` collections which will call `$setValidity` automatically.
" ilk="function" name="$setValidity" signature="$setValidity()" />
<scope doc="Update the view value.
* This method should be called when a control wants to change the view value; typically,
this is done from within a DOM event handler. For example, the {@link ng.directive:input input}
directive calls it when the value of the input changes and {@link ng.directive:select select}
calls it when an option is selected.
* When `$setViewValue` is called, the new `value` will be staged for committing through the `$parsers`
and `$validators` pipelines. If there are no special {@link ngModelOptions} specified then the staged
value sent directly for processing, finally to be applied to `$modelValue` and then the
**expression** specified in the `ng-model` attribute. Lastly, all the registered change listeners,
in the `$viewChangeListeners` list, are called.
* In case the {@link ng.directive:ngModelOptions ngModelOptions} directive is used with `updateOn`
and the `default` trigger is not listed, all those actions will remain pending until one of the
`updateOn` events is triggered on the DOM element.
All these actions will be debounced if the {@link ng.directive:ngModelOptions ngModelOptions}
directive is used with a custom debounce for this particular event.
Note that a `$digest` is only triggered once the `updateOn` events are fired, or if `debounce`
is specified, once the timer runs out.
* When used with standard inputs, the view value will always be a string (which is in some cases
parsed into another type, such as a `Date` object for `input[date]`.)
However, custom controls might also pass objects to this method. In this case, we should make
a copy of the object before passing it to `$setViewValue`. This is because `ngModel` does not
perform a deep watch of objects, it only looks for a change of identity. If you only change
the property of the object then ngModel will not realise that the object has changed and
will not invoke the `$parsers` and `$validators` pipelines. For this reason, you should
not change properties of the copy once it has been passed to `$setViewValue`.
Otherwise you may cause the model value on the scope to change incorrectly.
* <div class="alert alert-info">
In any case, the value passed to the method should always reflect the current value
of the control. For example, if you are calling `$setViewValue` for an input element,
you should pass the input DOM value. Otherwise, the control and the scope model become
out of sync. It's also important to note that `$setViewValue` does not call `$render` or change
the control's DOM value in any way. If we want to change the control's DOM value
programmatically, we should update the `ngModel` scope expression. Its new value will be
picked up by the model controller, which will run it through the `$formatters`, `$render` it
to update the DOM, and finally call `$validate` on it.
</div>
" ilk="function" name="$setViewValue" signature="$setViewValue(value)">
<variable citdl="*" doc="value from the view." ilk="argument" name="value" />
</scope>
<scope ilk="function" name="$validate" signature="$validate()" />
</scope>
</scope>
<scope ilk="namespace" name="select">
<scope ilk="class" name="SelectController" />
</scope>
<scope ilk="namespace" name="ng">
<scope ilk="class" name="$q">
<scope doc="Creates a `Deferred` object which represents a task which will finish in the future.
" ilk="function" name="defer" returns="Deferred" signature="defer() => Deferred" />
</scope>
</scope>
</scope>
</file>
</codeintel>