* @name $cacheFactory.Cache#info * @kind function * * @description * Retrieve information regarding a particular {@link $cacheFactory.Cache Cache}. * * @returns {object} an object with the following properties: * <ul> * <li>**id**: the id of the cache instance</li> * <li>**size**: the number of entries kept in the cache instance</li> * <li>**...**: any additional properties from the options object when creating the * cache.</li> * </ul> */ info: function() { return extend({}, stats, {size: size}); } }); /** * makes the `entry` the freshEnd of the LRU linked list */ function refresh(entry) { if (entry !== freshEnd) { if (!staleEnd) { staleEnd = entry; } else if (staleEnd === entry) { staleEnd = entry.n; } link(entry.n, entry.p); link(entry, freshEnd); freshEnd = entry; freshEnd.n = null; } } /** * bidirectionally links two entries of the LRU linked list */ function link(nextEntry, prevEntry) { if (nextEntry !== prevEntry) { if (nextEntry) nextEntry.p = prevEntry; //p stands for previous, 'prev' didn't minify if (prevEntry) prevEntry.n = nextEntry; //n stands for next, 'next' didn't minify } } } /** * @ngdoc method * @name $cacheFactory#info * * @description * Get information about all the caches that have been created * * @returns {Object} - key-value map of `cacheId` to the result of calling `cache#info` */ cacheFactory.info = function() { var info = {}; forEach(caches, function(cache, cacheId) { info[cacheId] = cache.info(); }); return info; }; /** * @ngdoc method * @name $cacheFactory#get * * @description * Get access to a cache object by the `cacheId` used when it was created. * * @param {string} cacheId Name or id of a cache to access. * @returns {object} Cache object identified by the cacheId or undefined if no such cache. */ cacheFactory.get = function(cacheId) { return caches[cacheId]; }; return cacheFactory; };} /** * @ngdoc service * @name $templateCache * @this * * @description * `$templateCache` is a {@link $cacheFactory.Cache Cache object} created by the * {@link ng.$cacheFactory $cacheFactory}. * * The first time a template is used, it is loaded in the template cache for quick retrieval. You * can load templates directly into the cache in a `script` tag, by using {@link $templateRequest}, * or by consuming the `$templateCache` service directly. * * Adding via the `script` tag: * * ```html * <script type="text/ng-template" id="templateId.html"> * <p>This is the content of the template</p> * </script> * ``` * * **Note:** the `script` tag containing the template does not need to be included in the `head` of * the document, but it must be a descendent of the {@link ng.$rootElement $rootElement} (e.g. * element with {@link ngApp} attribute), otherwise the template will be ignored. * * Adding via the `$templateCache` service: * * ```js * var myApp = angular.module('myApp', []); * myApp.run(function($templateCache) { * $templateCache.put('templateId.html', 'This is the content of the template'); * }); * ``` * * To retrieve the template later, simply use it in your component: * ```js * myApp.component('myComponent', { * templateUrl: 'templateId.html' * }); * ``` * * or get it via the `$templateCache` service: * ```js * $templateCache.get('templateId.html') * ``` * */function $TemplateCacheProvider() { this.$get = ['$cacheFactory', function($cacheFactory) { return $cacheFactory('templates'); }];} /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Any commits to this file should be reviewed with security in mind. * * Changes to this file can potentially create security vulnerabilities. * * An approval from 2 Core members with history of modifying * * this file is required. * * * * Does the change somehow allow for arbitrary javascript to be executed? * * Or allows for someone to change the prototype of built-in objects? * * Or gives undesired access to variables like document or window? * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* ! VARIABLE/FUNCTION NAMING CONVENTIONS THAT APPLY TO THIS FILE! * * DOM-related variables: * * - "node" - DOM Node * - "element" - DOM Element or Node * - "$node" or "$element" - jqLite-wrapped node or element * * * Compiler related stuff: * * - "linkFn" - linking fn of a single directive * - "nodeLinkFn" - function that aggregates all linking fns for a particular node * - "childLinkFn" - function that aggregates all linking fns for child nodes of a particular node * - "compositeLinkFn" - function that aggregates all linking fns for a compilation root (nodeList) */ /** * @ngdoc service * @name $compile * @kind function * * @description * 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 {@link $compile#directive-definition-object 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 = { * {@link $compile#-priority- priority}: 0, * {@link $compile#-template- template}: '<div></div>', // or // function(tElement, tAttrs) { ... }, * // or * // {@link $compile#-templateurl- templateUrl}: 'directive.html', // or // function(tElement, tAttrs) { ... }, * {@link $compile#-transclude- transclude}: false, * {@link $compile#-restrict- restrict}: 'A', * {@link $compile#-templatenamespace- templateNamespace}: 'html', * {@link $compile#-scope- scope}: false, * {@link $compile#-controller- controller}: function($scope, $element, $attrs, $transclude, otherInjectables) { ... }, * {@link $compile#-controlleras- controllerAs}: 'stringIdentifier', * {@link $compile#-bindtocontroller- bindToController}: false, * {@link $compile#-require- require}: 'siblingDirectiveName', // or // ['^parentDirectiveName', '?optionalDirectiveName', '?^optionalParent'], * {@link $compile#-multielement- multiElement}: false, * {@link $compile#-compile- compile}: function compile(tElement, tAttrs, transclude) { * return { * {@link $compile#pre-linking-function pre}: function preLink(scope, iElement, iAttrs, controller) { ... }, * {@link $compile#post-linking-function post}: function postLink(scope, iElement, iAttrs, controller) { ... } * } * // or * // return function postLink( ... ) { ... } * }, * // or * // {@link $compile#-link- link}: { * // {@link $compile#pre-linking-function pre}: function preLink(scope, iElement, iAttrs, controller) { ... }, * // {@link $compile#post-linking-function post}: function postLink(scope, iElement, iAttrs, controller) { ... } * // } * // or * // {@link $compile#-link- 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) { ... } * }); * ``` * * ### Life-cycle hooks * Directive controllers can provide the following methods that are called by Angular at points in the life-cycle of the * directive: * * `$onInit()` - Called on each controller after all the controllers on an element have been constructed and * had their bindings initialized (and before the pre & post linking functions for the directives on * this element). This is a good place to put initialization code for your controller. * * `$onChanges(changesObj)` - Called whenever one-way (`<`) or interpolation (`@`) bindings are updated. The * `changesObj` is a hash whose keys are the names of the bound properties that have changed, and the values are an * object of the form `{ currentValue, previousValue, isFirstChange() }`. Use this hook to trigger updates within a * component such as cloning the bound value to prevent accidental mutation of the outer value. Note that this will * also be called when your bindings are initialized. * * `$doCheck()` - Called on each turn of the digest cycle. Provides an opportunity to detect and act on * changes. Any actions that you wish to take in response to the changes that you detect must be * invoked from this hook; implementing this has no effect on when `$onChanges` is called. For example, this hook * could be useful if you wish to perform a deep equality check, or to check a Date object, changes to which would not * be detected by Angular's change detector and thus not trigger `$onChanges`. This hook is invoked with no arguments; * if detecting changes, you must store the previous value(s) for comparison to the current values. * * `$onDestroy()` - Called on a controller when its containing scope is destroyed. Use this hook for releasing * external resources, watches and event handlers. Note that components have their `$onDestroy()` hooks called in * the same order as the `$scope.$broadcast` events are triggered, which is top down. This means that parent * components will have their `$onDestroy()` hook called before child components. * * `$postLink()` - Called after this controller's element and its children have been linked. Similar to the post-link * function this hook can be used to set up DOM event handlers and do direct DOM manipulation. * 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. * * #### Comparison with Angular 2 life-cycle hooks * Angular 2 also uses life-cycle hooks for its components. While the Angular 1 life-cycle hooks are similar there are * some differences that you should be aware of, especially when it comes to moving your code from Angular 1 to Angular 2: * * * Angular 1 hooks are prefixed with `$`, such as `$onInit`. Angular 2 hooks are prefixed with `ng`, such as `ngOnInit`. * * Angular 1 hooks can be defined on the controller prototype or added to the controller inside its constructor. * In Angular 2 you can only define hooks on the prototype of the Component class. * * Due to the differences in change-detection, you may get many more calls to `$doCheck` in Angular 1 than you would to * `ngDoCheck` in Angular 2 * * Changes to the model inside `$doCheck` will trigger new turns of the digest loop, which will cause the changes to be * propagated throughout the application. * Angular 2 does not allow the `ngDoCheck` hook to trigger a change outside of the component. It will either throw an * error or do nothing depending upon the state of `enableProdMode()`. * * #### Life-cycle hook examples * * This example shows how you can check for mutations to a Date object even though the identity of the object * has not changed. * * <example name="doCheckDateExample" module="do-check-module"> * <file name="app.js"> * angular.module('do-check-module', []) * .component('app', { * template: * 'Month: <input ng-model="$ctrl.month" ng-change="$ctrl.updateDate()">' + * 'Date: {{ $ctrl.date }}' + * '<test date="$ctrl.date"></test>', * controller: function() { * this.date = new Date(); * this.month = this.date.getMonth(); * this.updateDate = function() { * this.date.setMonth(this.month); * }; * } * }) * .component('test', { * bindings: { date: '<' }, * template: * '<pre>{{ $ctrl.log | json }}</pre>', * controller: function() { * var previousValue; * this.log = []; * this.$doCheck = function() { * var currentValue = this.date && this.date.valueOf(); * if (previousValue !== currentValue) { * this.log.push('doCheck: date mutated: ' + this.date); * previousValue = currentValue; * } * }; * } * }); * </file> * <file name="index.html"> * <app></app> * </file> * </example> * * This example show how you might use `$doCheck` to trigger changes in your component's inputs even if the * actual identity of the component doesn't change. (Be aware that cloning and deep equality checks on large * arrays or objects can have a negative impact on your application performance) * * <example name="doCheckArrayExample" module="do-check-module"> * <file name="index.html"> * <div ng-init="items = []"> * <button ng-click="items.push(items.length)">Add Item</button> * <button ng-click="items = []">Reset Items</button> * <pre>{{ items }}</pre> * <test items="items"></test> * </div> * </file> * <file name="app.js"> * angular.module('do-check-module', []) * .component('test', { * bindings: { items: '<' }, * template: * '<pre>{{ $ctrl.log | json }}</pre>', * controller: function() { * this.log = []; * * this.$doCheck = function() { * if (this.items_ref !== this.items) { * this.log.push('doCheck: items changed'); * this.items_ref = this.items; * } * if (!angular.equals(this.items_clone, this.items)) { * this.log.push('doCheck: items mutated'); * this.items_clone = angular.copy(this.items); * } * }; * } * }); * </file> * </example> * * * ### 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 (default is `false`), 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 behavioral (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 `false`, `true`, or an object: * * * **`false` (default):** 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. * * * **`{...}` (an object hash):** A new "isolate" scope is created for the directive's template. * 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. Note that an isolate scope * directive without a `template` or `templateUrl` will not apply the isolate scope * to its children elements. * * 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 `<my-component * my-attr="hello {{name}}">` and the isolate scope definition `scope: { localName:'@myAttr' }`, * the directive's scope property `localName` will reflect the interpolated value of `hello * {{name}}`. As the `name` attribute changes so will the `localName` property on the directive's * scope. The `name` is read from the parent scope (not the directive's scope). * * * `=` or `=attr` - set up a bidirectional binding between a local scope property and an expression * passed via the attribute `attr`. The expression is evaluated 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 `<my-component my-attr="parentModel">` and the isolate scope definition `scope: { * localModel: '=myAttr' }`, the property `localModel` on the directive's scope will reflect the * value of `parentModel` on the parent scope. Changes to `parentModel` will be reflected in * `localModel` and vice versa. Optional attributes should be marked as such with a question mark: * `=?` or `=?attr`. If the binding expression is non-assignable, or if the attribute isn't * optional and doesn't exist, an exception ({@link error/$compile/nonassign `$compile:nonassign`}) * will be thrown upon discovering changes to the local value, since it will be impossible to sync * them back to the parent scope. By default, the {@link ng.$rootScope.Scope#$watch `$watch`} * method is used for tracking changes, and the equality check is based on object identity. * However, if an object literal or an array literal is passed as the binding expression, the * equality check is done by value (using the {@link angular.equals} function). It's also possible * to watch the evaluated value shallowly with {@link ng.$rootScope.Scope#$watchCollection * `$watchCollection`}: use `=*` or `=*attr` (`=*?` or `=*?attr` if the attribute is optional). * * * `<` or `<attr` - set up a one-way (one-directional) binding between a local scope property and an * expression passed via the attribute `attr`. The expression is evaluated 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. You can also make the binding optional by adding `?`: `<?` or `<?attr`. * * For example, given `<my-component my-attr="parentModel">` and directive definition of * `scope: { localModel:'<myAttr' }`, then the isolated scope property `localModel` will reflect the * value of `parentModel` on the parent scope. Any changes to `parentModel` will be reflected * in `localModel`, but changes in `localModel` will not reflect in `parentModel`. There are however * two caveats: * 1. one-way binding does not copy the value from the parent to the isolate scope, it simply * sets the same value. That means if your bound value is an object, changes to its properties * in the isolated scope will be reflected in the parent scope (because both reference the same object). * 2. one-way binding watches changes to the **identity** of the parent value. That means the * {@link ng.$rootScope.Scope#$watch `$watch`} on the parent value only fires if the reference * to the value has changed. In most cases, this should not be of concern, but can be important * to know if you one-way bind to an object, and then replace that object in the isolated scope. * If you now change a property of the object in your parent scope, the change will not be * propagated to the isolated scope, because the identity of the object on the parent scope * has not changed. Instead you must assign a new object. * * One-way binding is useful if you do not plan to propagate changes to your isolated scope bindings * back to the parent. However, it does not make this completely impossible. * * * `&` 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 `<my-component my-attr="count = count + value">` and the isolate scope definition `scope: { * localFn:'&myAttr' }`, the 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 directivesLines 7001–7500 of 34255. Previous lines Load more
* @name $cacheFactory.Cache#info * @kind function * * @description * Retrieve information regarding a particular {@link $cacheFactory.Cache Cache}. * * @returns {object} an object with the following properties: * <ul> * <li>**id**: the id of the cache instance</li> * <li>**size**: the number of entries kept in the cache instance</li> * <li>**...**: any additional properties from the options object when creating the * cache.</li> * </ul> */ info: function() { return extend({}, stats, {size: size}); } }); /** * makes the `entry` the freshEnd of the LRU linked list */ function refresh(entry) { if (entry !== freshEnd) { if (!staleEnd) { staleEnd = entry; } else if (staleEnd === entry) { staleEnd = entry.n; } link(entry.n, entry.p); link(entry, freshEnd); freshEnd = entry; freshEnd.n = null; } } /** * bidirectionally links two entries of the LRU linked list */ function link(nextEntry, prevEntry) { if (nextEntry !== prevEntry) { if (nextEntry) nextEntry.p = prevEntry; //p stands for previous, 'prev' didn't minify if (prevEntry) prevEntry.n = nextEntry; //n stands for next, 'next' didn't minify } } } /** * @ngdoc method * @name $cacheFactory#info * * @description * Get information about all the caches that have been created * * @returns {Object} - key-value map of `cacheId` to the result of calling `cache#info` */ cacheFactory.info = function() { var info = {}; forEach(caches, function(cache, cacheId) { info[cacheId] = cache.info(); }); return info; }; /** * @ngdoc method * @name $cacheFactory#get * * @description * Get access to a cache object by the `cacheId` used when it was created. * * @param {string} cacheId Name or id of a cache to access. * @returns {object} Cache object identified by the cacheId or undefined if no such cache. */ cacheFactory.get = function(cacheId) { return caches[cacheId]; }; return cacheFactory; }; } /** * @ngdoc service * @name $templateCache * @this * * @description * `$templateCache` is a {@link $cacheFactory.Cache Cache object} created by the * {@link ng.$cacheFactory $cacheFactory}. * * The first time a template is used, it is loaded in the template cache for quick retrieval. You * can load templates directly into the cache in a `script` tag, by using {@link $templateRequest}, * or by consuming the `$templateCache` service directly. * * Adding via the `script` tag: * * ```html * <script type="text/ng-template" id="templateId.html"> * <p>This is the content of the template</p> * </script> * ``` * * **Note:** the `script` tag containing the template does not need to be included in the `head` of * the document, but it must be a descendent of the {@link ng.$rootElement $rootElement} (e.g. * element with {@link ngApp} attribute), otherwise the template will be ignored. * * Adding via the `$templateCache` service: * * ```js * var myApp = angular.module('myApp', []); * myApp.run(function($templateCache) { * $templateCache.put('templateId.html', 'This is the content of the template'); * }); * ``` * * To retrieve the template later, simply use it in your component: * ```js * myApp.component('myComponent', { * templateUrl: 'templateId.html' * }); * ``` * * or get it via the `$templateCache` service: * ```js * $templateCache.get('templateId.html') * ``` * */ function $TemplateCacheProvider() { this.$get = ['$cacheFactory', function($cacheFactory) { return $cacheFactory('templates'); }]; } /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Any commits to this file should be reviewed with security in mind. * * Changes to this file can potentially create security vulnerabilities. * * An approval from 2 Core members with history of modifying * * this file is required. * * * * Does the change somehow allow for arbitrary javascript to be executed? * * Or allows for someone to change the prototype of built-in objects? * * Or gives undesired access to variables like document or window? * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* ! VARIABLE/FUNCTION NAMING CONVENTIONS THAT APPLY TO THIS FILE! * * DOM-related variables: * * - "node" - DOM Node * - "element" - DOM Element or Node * - "$node" or "$element" - jqLite-wrapped node or element * * * Compiler related stuff: * * - "linkFn" - linking fn of a single directive * - "nodeLinkFn" - function that aggregates all linking fns for a particular node * - "childLinkFn" - function that aggregates all linking fns for child nodes of a particular node * - "compositeLinkFn" - function that aggregates all linking fns for a compilation root (nodeList) */ /** * @ngdoc service * @name $compile * @kind function * * @description * 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 {@link $compile#directive-definition-object 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 = { * {@link $compile#-priority- priority}: 0, * {@link $compile#-template- template}: '<div></div>', // or // function(tElement, tAttrs) { ... }, * // or * // {@link $compile#-templateurl- templateUrl}: 'directive.html', // or // function(tElement, tAttrs) { ... }, * {@link $compile#-transclude- transclude}: false, * {@link $compile#-restrict- restrict}: 'A', * {@link $compile#-templatenamespace- templateNamespace}: 'html', * {@link $compile#-scope- scope}: false, * {@link $compile#-controller- controller}: function($scope, $element, $attrs, $transclude, otherInjectables) { ... }, * {@link $compile#-controlleras- controllerAs}: 'stringIdentifier', * {@link $compile#-bindtocontroller- bindToController}: false, * {@link $compile#-require- require}: 'siblingDirectiveName', // or // ['^parentDirectiveName', '?optionalDirectiveName', '?^optionalParent'], * {@link $compile#-multielement- multiElement}: false, * {@link $compile#-compile- compile}: function compile(tElement, tAttrs, transclude) { * return { * {@link $compile#pre-linking-function pre}: function preLink(scope, iElement, iAttrs, controller) { ... }, * {@link $compile#post-linking-function post}: function postLink(scope, iElement, iAttrs, controller) { ... } * } * // or * // return function postLink( ... ) { ... } * }, * // or * // {@link $compile#-link- link}: { * // {@link $compile#pre-linking-function pre}: function preLink(scope, iElement, iAttrs, controller) { ... }, * // {@link $compile#post-linking-function post}: function postLink(scope, iElement, iAttrs, controller) { ... } * // } * // or * // {@link $compile#-link- 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) { ... } * }); * ``` * * ### Life-cycle hooks * Directive controllers can provide the following methods that are called by Angular at points in the life-cycle of the * directive: * * `$onInit()` - Called on each controller after all the controllers on an element have been constructed and * had their bindings initialized (and before the pre & post linking functions for the directives on * this element). This is a good place to put initialization code for your controller. * * `$onChanges(changesObj)` - Called whenever one-way (`<`) or interpolation (`@`) bindings are updated. The * `changesObj` is a hash whose keys are the names of the bound properties that have changed, and the values are an * object of the form `{ currentValue, previousValue, isFirstChange() }`. Use this hook to trigger updates within a * component such as cloning the bound value to prevent accidental mutation of the outer value. Note that this will * also be called when your bindings are initialized. * * `$doCheck()` - Called on each turn of the digest cycle. Provides an opportunity to detect and act on * changes. Any actions that you wish to take in response to the changes that you detect must be * invoked from this hook; implementing this has no effect on when `$onChanges` is called. For example, this hook * could be useful if you wish to perform a deep equality check, or to check a Date object, changes to which would not * be detected by Angular's change detector and thus not trigger `$onChanges`. This hook is invoked with no arguments; * if detecting changes, you must store the previous value(s) for comparison to the current values. * * `$onDestroy()` - Called on a controller when its containing scope is destroyed. Use this hook for releasing * external resources, watches and event handlers. Note that components have their `$onDestroy()` hooks called in * the same order as the `$scope.$broadcast` events are triggered, which is top down. This means that parent * components will have their `$onDestroy()` hook called before child components. * * `$postLink()` - Called after this controller's element and its children have been linked. Similar to the post-link * function this hook can be used to set up DOM event handlers and do direct DOM manipulation. * 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. * * #### Comparison with Angular 2 life-cycle hooks * Angular 2 also uses life-cycle hooks for its components. While the Angular 1 life-cycle hooks are similar there are * some differences that you should be aware of, especially when it comes to moving your code from Angular 1 to Angular 2: * * * Angular 1 hooks are prefixed with `$`, such as `$onInit`. Angular 2 hooks are prefixed with `ng`, such as `ngOnInit`. * * Angular 1 hooks can be defined on the controller prototype or added to the controller inside its constructor. * In Angular 2 you can only define hooks on the prototype of the Component class. * * Due to the differences in change-detection, you may get many more calls to `$doCheck` in Angular 1 than you would to * `ngDoCheck` in Angular 2 * * Changes to the model inside `$doCheck` will trigger new turns of the digest loop, which will cause the changes to be * propagated throughout the application. * Angular 2 does not allow the `ngDoCheck` hook to trigger a change outside of the component. It will either throw an * error or do nothing depending upon the state of `enableProdMode()`. * * #### Life-cycle hook examples * * This example shows how you can check for mutations to a Date object even though the identity of the object * has not changed. * * <example name="doCheckDateExample" module="do-check-module"> * <file name="app.js"> * angular.module('do-check-module', []) * .component('app', { * template: * 'Month: <input ng-model="$ctrl.month" ng-change="$ctrl.updateDate()">' + * 'Date: {{ $ctrl.date }}' + * '<test date="$ctrl.date"></test>', * controller: function() { * this.date = new Date(); * this.month = this.date.getMonth(); * this.updateDate = function() { * this.date.setMonth(this.month); * }; * } * }) * .component('test', { * bindings: { date: '<' }, * template: * '<pre>{{ $ctrl.log | json }}</pre>', * controller: function() { * var previousValue; * this.log = []; * this.$doCheck = function() { * var currentValue = this.date && this.date.valueOf(); * if (previousValue !== currentValue) { * this.log.push('doCheck: date mutated: ' + this.date); * previousValue = currentValue; * } * }; * } * }); * </file> * <file name="index.html"> * <app></app> * </file> * </example> * * This example show how you might use `$doCheck` to trigger changes in your component's inputs even if the * actual identity of the component doesn't change. (Be aware that cloning and deep equality checks on large * arrays or objects can have a negative impact on your application performance) * * <example name="doCheckArrayExample" module="do-check-module"> * <file name="index.html"> * <div ng-init="items = []"> * <button ng-click="items.push(items.length)">Add Item</button> * <button ng-click="items = []">Reset Items</button> * <pre>{{ items }}</pre> * <test items="items"></test> * </div> * </file> * <file name="app.js"> * angular.module('do-check-module', []) * .component('test', { * bindings: { items: '<' }, * template: * '<pre>{{ $ctrl.log | json }}</pre>', * controller: function() { * this.log = []; * * this.$doCheck = function() { * if (this.items_ref !== this.items) { * this.log.push('doCheck: items changed'); * this.items_ref = this.items; * } * if (!angular.equals(this.items_clone, this.items)) { * this.log.push('doCheck: items mutated'); * this.items_clone = angular.copy(this.items); * } * }; * } * }); * </file> * </example> * * * ### 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 (default is `false`), 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 behavioral (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 `false`, `true`, or an object: * * * **`false` (default):** 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. * * * **`{...}` (an object hash):** A new "isolate" scope is created for the directive's template. * 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. Note that an isolate scope * directive without a `template` or `templateUrl` will not apply the isolate scope * to its children elements. * * 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 `<my-component * my-attr="hello {{name}}">` and the isolate scope definition `scope: { localName:'@myAttr' }`, * the directive's scope property `localName` will reflect the interpolated value of `hello * {{name}}`. As the `name` attribute changes so will the `localName` property on the directive's * scope. The `name` is read from the parent scope (not the directive's scope). * * * `=` or `=attr` - set up a bidirectional binding between a local scope property and an expression * passed via the attribute `attr`. The expression is evaluated 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 `<my-component my-attr="parentModel">` and the isolate scope definition `scope: { * localModel: '=myAttr' }`, the property `localModel` on the directive's scope will reflect the * value of `parentModel` on the parent scope. Changes to `parentModel` will be reflected in * `localModel` and vice versa. Optional attributes should be marked as such with a question mark: * `=?` or `=?attr`. If the binding expression is non-assignable, or if the attribute isn't * optional and doesn't exist, an exception ({@link error/$compile/nonassign `$compile:nonassign`}) * will be thrown upon discovering changes to the local value, since it will be impossible to sync * them back to the parent scope. By default, the {@link ng.$rootScope.Scope#$watch `$watch`} * method is used for tracking changes, and the equality check is based on object identity. * However, if an object literal or an array literal is passed as the binding expression, the * equality check is done by value (using the {@link angular.equals} function). It's also possible * to watch the evaluated value shallowly with {@link ng.$rootScope.Scope#$watchCollection * `$watchCollection`}: use `=*` or `=*attr` (`=*?` or `=*?attr` if the attribute is optional). * * * `<` or `<attr` - set up a one-way (one-directional) binding between a local scope property and an * expression passed via the attribute `attr`. The expression is evaluated 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. You can also make the binding optional by adding `?`: `<?` or `<?attr`. * * For example, given `<my-component my-attr="parentModel">` and directive definition of * `scope: { localModel:'<myAttr' }`, then the isolated scope property `localModel` will reflect the * value of `parentModel` on the parent scope. Any changes to `parentModel` will be reflected * in `localModel`, but changes in `localModel` will not reflect in `parentModel`. There are however * two caveats: * 1. one-way binding does not copy the value from the parent to the isolate scope, it simply * sets the same value. That means if your bound value is an object, changes to its properties * in the isolated scope will be reflected in the parent scope (because both reference the same object). * 2. one-way binding watches changes to the **identity** of the parent value. That means the * {@link ng.$rootScope.Scope#$watch `$watch`} on the parent value only fires if the reference * to the value has changed. In most cases, this should not be of concern, but can be important * to know if you one-way bind to an object, and then replace that object in the isolated scope. * If you now change a property of the object in your parent scope, the change will not be * propagated to the isolated scope, because the identity of the object on the parent scope * has not changed. Instead you must assign a new object. * * One-way binding is useful if you do not plan to propagate changes to your isolated scope bindings * back to the parent. However, it does not make this completely impossible. * * * `&` 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 `<my-component my-attr="count = count + value">` and the isolate scope definition `scope: { * localFn:'&myAttr' }`, the 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