34255 lines · 1.2 MB · JavaScript
RawDownload
         * @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 &amp; 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

Lines 7001–7500 of 34255. Previous lines

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t