} watchExpressions Array of expressions that will be individually
+ * watched using {@link ng.$rootScope.Scope#$watch $watch()}
+ *
+ * @param {function(newValues, oldValues, scope)} listener Callback called whenever the return value of any
+ * expression in `watchExpressions` changes
+ * The `newValues` array contains the current values of the `watchExpressions`, with the indexes matching
+ * those of `watchExpression`
+ * and the `oldValues` array contains the previous values of the `watchExpressions`, with the indexes matching
+ * those of `watchExpression`
+ * The `scope` refers to the current scope.
+ * @returns {function()} Returns a de-registration function for all listeners.
+ */
+ $watchGroup: function $watchGroup(watchExpressions, listener) {
+ var oldValues = new Array(watchExpressions.length);
+ var newValues = new Array(watchExpressions.length);
+ var deregisterFns = [];
+ var self = this;
+ var changeReactionScheduled = false;
+ var firstRun = true;
+
+ if (!watchExpressions.length) {
+ // No expressions means we call the listener ASAP
+ var shouldCall = true;
+ self.$evalAsync(function () {
+ if (shouldCall) listener(newValues, newValues, self);
+ });
+ return function deregisterWatchGroup() {
+ shouldCall = false;
+ };
+ }
+
+ if (watchExpressions.length === 1) {
+ // Special case size of one
+ return this.$watch(watchExpressions[0], function watchGroupAction(value, oldValue, scope) {
+ newValues[0] = value;
+ oldValues[0] = oldValue;
+ listener(newValues, value === oldValue ? newValues : oldValues, scope);
+ });
+ }
+
+ forEach(watchExpressions, function (expr, i) {
+ var unwatchFn = self.$watch(expr, function watchGroupSubAction(value, oldValue) {
+ newValues[i] = value;
+ oldValues[i] = oldValue;
+ if (!changeReactionScheduled) {
+ changeReactionScheduled = true;
+ self.$evalAsync(watchGroupAction);
+ }
+ });
+ deregisterFns.push(unwatchFn);
});
- return logFn.apply(console, args);
- };
- }
- // we are IE which either doesn't have window.console => this is noop and we do nothing,
- // or we are IE where console.log doesn't have apply so we log at least first 2 args
- return function(arg1, arg2) {
- logFn(arg1, arg2 == null ? '' : arg2);
- };
- }
- }];
-}
+ function watchGroupAction() {
+ changeReactionScheduled = false;
+
+ if (firstRun) {
+ firstRun = false;
+ listener(newValues, newValues, self);
+ } else {
+ listener(newValues, oldValues, self);
+ }
+ }
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
- * 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 likes document or window? *
- * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+ return function deregisterWatchGroup() {
+ while (deregisterFns.length) {
+ deregisterFns.shift()();
+ }
+ };
+ },
-var $parseMinErr = minErr('$parse');
+ /**
+ * @ngdoc method
+ * @name $rootScope.Scope#$watchCollection
+ * @kind function
+ *
+ * @description
+ * 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);
+ * ```
+ *
+ *
+ * @param {string|function(scope)} obj Evaluated as {@link guide/expression expression}. The
+ * expression value should evaluate to an object or an array which is observed on each
+ * {@link ng.$rootScope.Scope#$digest $digest} cycle. Any shallow change within the
+ * collection will trigger a call to the `listener`.
+ *
+ * @param {function(newCollection, oldCollection, scope)} listener a callback function called
+ * when a change is detected.
+ * - The `newCollection` object is the newly modified data obtained from the `obj` expression
+ * - The `oldCollection` object is a copy of the former collection data.
+ * Due to performance considerations, the`oldCollection` value is computed only if the
+ * `listener` function declares two or more arguments.
+ * - The `scope` argument refers to the current scope.
+ *
+ * @returns {function()} Returns a de-registration function for this listener. When the
+ * de-registration function is executed, the internal watch operation is terminated.
+ */
+ $watchCollection: function $watchCollection(obj, listener) {
+ $watchCollectionInterceptor.$stateful = true;
-var objectValueOf = {}.constructor.prototype.valueOf;
+ var self = this;
+ // the current value, updated on each dirty-check run
+ var newValue;
+ // a shallow copy of the newValue from the last dirty-check run,
+ // updated to match newValue during dirty-check run
+ var oldValue;
+ // a shallow copy of the newValue from when the last change happened
+ var veryOldValue;
+ // only track veryOldValue if the listener is asking for it
+ var trackVeryOldValue = listener.length > 1;
+ var changeDetected = 0;
+ var changeDetector = $parse(obj, $watchCollectionInterceptor);
+ var internalArray = [];
+ var internalObject = {};
+ var initRun = true;
+ var oldLength = 0;
+
+ function $watchCollectionInterceptor(_value) {
+ newValue = _value;
+ var newLength, key, bothNaN, newItem, oldItem;
+
+ // If the new value is undefined, then return undefined as the watch may be a one-time watch
+ if (isUndefined(newValue)) return;
-// Sandboxing Angular Expressions
-// ------------------------------
-// Angular expressions are no longer sandboxed. So it is now even easier to access arbitrary JS code by
-// various means such as obtaining a reference to native JS functions like the Function constructor.
-//
-// As an example, consider the following Angular expression:
-//
-// {}.toString.constructor('alert("evil JS code")')
-//
-// It is important to realize that if you create an expression from a string that contains user provided
-// content then it is possible that your application contains a security vulnerability to an XSS style attack.
-//
-// See https://docs.angularjs.org/guide/security
+ if (!isObject(newValue)) {
+ // if primitive
+ if (oldValue !== newValue) {
+ oldValue = newValue;
+ changeDetected++;
+ }
+ } else if (isArrayLike(newValue)) {
+ if (oldValue !== internalArray) {
+ // we are transitioning from something which was not an array into array.
+ oldValue = internalArray;
+ oldLength = oldValue.length = 0;
+ changeDetected++;
+ }
+ newLength = newValue.length;
-function getStringValue(name) {
- // Property names must be strings. This means that non-string objects cannot be used
- // as keys in an object. Any non-string object, including a number, is typecasted
- // into a string via the toString method.
- // -- MDN, https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Property_accessors#Property_names
- //
- // So, to ensure that we are checking the same `name` that JavaScript would use, we cast it
- // to a string. It's not always possible. If `name` is an object and its `toString` method is
- // 'broken' (doesn't return a string, isn't a function, etc.), an error will be thrown:
- //
- // TypeError: Cannot convert object to primitive value
- //
- // For performance reasons, we don't catch this error here and allow it to propagate up the call
- // stack. Note that you'll get the same error in JavaScript if you try to access a property using
- // such a 'broken' object as a key.
- return name + '';
-}
+ if (oldLength !== newLength) {
+ // if lengths do not match we need to trigger change notification
+ changeDetected++;
+ oldValue.length = oldLength = newLength;
+ }
+ // copy the items to oldValue and look for changes.
+ for (var i = 0; i < newLength; i++) {
+ oldItem = oldValue[i];
+ newItem = newValue[i];
+
+ // eslint-disable-next-line no-self-compare
+ bothNaN = oldItem !== oldItem && newItem !== newItem;
+ if (!bothNaN && oldItem !== newItem) {
+ changeDetected++;
+ oldValue[i] = newItem;
+ }
+ }
+ } else {
+ if (oldValue !== internalObject) {
+ // we are transitioning from something which was not an object into object.
+ oldValue = internalObject = {};
+ oldLength = 0;
+ changeDetected++;
+ }
+ // copy the items to oldValue and look for changes.
+ newLength = 0;
+ for (key in newValue) {
+ if (hasOwnProperty.call(newValue, key)) {
+ newLength++;
+ newItem = newValue[key];
+ oldItem = oldValue[key];
+
+ if (key in oldValue) {
+ // eslint-disable-next-line no-self-compare
+ bothNaN = oldItem !== oldItem && newItem !== newItem;
+ if (!bothNaN && oldItem !== newItem) {
+ changeDetected++;
+ oldValue[key] = newItem;
+ }
+ } else {
+ oldLength++;
+ oldValue[key] = newItem;
+ changeDetected++;
+ }
+ }
+ }
+ if (oldLength > newLength) {
+ // we used to have more keys, need to find them and destroy them.
+ changeDetected++;
+ for (key in oldValue) {
+ if (!hasOwnProperty.call(newValue, key)) {
+ oldLength--;
+ delete oldValue[key];
+ }
+ }
+ }
+ }
+ return changeDetected;
+ }
+ function $watchCollectionAction() {
+ if (initRun) {
+ initRun = false;
+ listener(newValue, newValue, self);
+ } else {
+ listener(newValue, veryOldValue, self);
+ }
-var OPERATORS = createMap();
-forEach('+ - * / % === !== == != < > <= >= && || ! = |'.split(' '), function(operator) { OPERATORS[operator] = true; });
-var ESCAPE = {'n':'\n', 'f':'\f', 'r':'\r', 't':'\t', 'v':'\v', '\'':'\'', '"':'"'};
+ // make a copy for the next time a collection is changed
+ if (trackVeryOldValue) {
+ if (!isObject(newValue)) {
+ //primitive
+ veryOldValue = newValue;
+ } else if (isArrayLike(newValue)) {
+ veryOldValue = new Array(newValue.length);
+ for (var i = 0; i < newValue.length; i++) {
+ veryOldValue[i] = newValue[i];
+ }
+ } else {
+ // if object
+ veryOldValue = {};
+ for (var key in newValue) {
+ if (hasOwnProperty.call(newValue, key)) {
+ veryOldValue[key] = newValue[key];
+ }
+ }
+ }
+ }
+ }
+ return this.$watch(changeDetector, $watchCollectionAction);
+ },
-/////////////////////////////////////////
+ /**
+ * @ngdoc method
+ * @name $rootScope.Scope#$digest
+ * @kind function
+ *
+ * @description
+ * Processes all of the {@link ng.$rootScope.Scope#$watch watchers} of the current scope and
+ * its children. Because a {@link ng.$rootScope.Scope#$watch watcher}'s listener can change
+ * the model, the `$digest()` keeps calling the {@link ng.$rootScope.Scope#$watch watchers}
+ * until no more listeners are firing. This means that it is possible to get into an infinite
+ * loop. This function will throw `'Maximum iteration limit exceeded.'` if the number of
+ * iterations exceeds 10.
+ *
+ * Usually, you don't call `$digest()` directly in
+ * {@link ng.directive:ngController controllers} or in
+ * {@link ng.$compileProvider#directive directives}.
+ * Instead, you should call {@link ng.$rootScope.Scope#$apply $apply()} (typically from within
+ * a {@link ng.$compileProvider#directive directive}), which will force a `$digest()`.
+ *
+ * If you want to be notified whenever `$digest()` is called,
+ * you can register a `watchExpression` function with
+ * {@link ng.$rootScope.Scope#$watch $watch()} with no `listener`.
+ *
+ * In unit tests, you may need to call `$digest()` to simulate the scope life cycle.
+ *
+ * # Example
+ * ```js
+ var scope = ...;
+ 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);
+ * ```
+ *
+ */
+ $digest: function $digest() {
+ var watch,
+ value,
+ last,
+ fn,
+ get,
+ watchers,
+ dirty,
+ ttl = TTL,
+ next,
+ current,
+ target = this,
+ watchLog = [],
+ logIdx,
+ asyncTask;
+
+ beginPhase('$digest');
+ // Check for changes to browser url that happened in sync before the call to $digest
+ $browser.$$checkUrlChange();
+
+ if (this === $rootScope && applyAsyncId !== null) {
+ // If this is the root scope, and $applyAsync has scheduled a deferred $apply(), then
+ // cancel the scheduled $apply and flush the queue of expressions to be evaluated.
+ $browser.defer.cancel(applyAsyncId);
+ flushApplyAsync();
+ }
+ lastDirtyWatch = null;
-/**
- * @constructor
- */
-var Lexer = function Lexer(options) {
- this.options = options;
-};
+ do {
+ // "while dirty" loop
+ dirty = false;
+ current = target;
-Lexer.prototype = {
- constructor: Lexer,
+ // It's safe for asyncQueuePosition to be a local variable here because this loop can't
+ // be reentered recursively. Calling $digest from a function passed to $evalAsync would
+ // lead to a '$digest already in progress' error.
+ for (var asyncQueuePosition = 0; asyncQueuePosition < asyncQueue.length; asyncQueuePosition++) {
+ try {
+ asyncTask = asyncQueue[asyncQueuePosition];
+ fn = asyncTask.fn;
+ fn(asyncTask.scope, asyncTask.locals);
+ } catch (e) {
+ $exceptionHandler(e);
+ }
+ lastDirtyWatch = null;
+ }
+ asyncQueue.length = 0;
+
+ traverseScopesLoop: do {
+ // "traverse the scopes" loop
+ if (watchers = current.$$watchers) {
+ // process our watches
+ watchers.$$digestWatchIndex = watchers.length;
+ while (watchers.$$digestWatchIndex--) {
+ try {
+ watch = watchers[watchers.$$digestWatchIndex];
+ // Most common watches are on primitives, in which case we can short
+ // circuit it with === operator, only when === fails do we use .equals
+ if (watch) {
+ get = watch.get;
+ if ((value = get(current)) !== (last = watch.last) && !(watch.eq ? equals(value, last) : isNumberNaN(value) && isNumberNaN(last))) {
+ dirty = true;
+ lastDirtyWatch = watch;
+ watch.last = watch.eq ? copy(value, null) : value;
+ fn = watch.fn;
+ fn(value, last === initWatchVal ? value : last, current);
+ if (ttl < 5) {
+ logIdx = 4 - ttl;
+ if (!watchLog[logIdx]) watchLog[logIdx] = [];
+ watchLog[logIdx].push({
+ msg: isFunction(watch.exp) ? 'fn: ' + (watch.exp.name || watch.exp.toString()) : watch.exp,
+ newVal: value,
+ oldVal: last
+ });
+ }
+ } else if (watch === lastDirtyWatch) {
+ // If the most recently dirty watcher is now clean, short circuit since the remaining watchers
+ // have already been tested.
+ dirty = false;
+ break traverseScopesLoop;
+ }
+ }
+ } catch (e) {
+ $exceptionHandler(e);
+ }
+ }
+ }
- lex: function(text) {
- this.text = text;
- this.index = 0;
- this.tokens = [];
+ // Insanity Warning: scope depth-first traversal
+ // yes, this code is a bit crazy, but it works and we have tests to prove it!
+ // this piece should be kept in sync with the traversal in $broadcast
+ if (!(next = current.$$watchersCount && current.$$childHead || current !== target && current.$$nextSibling)) {
+ while (current !== target && !(next = current.$$nextSibling)) {
+ current = current.$parent;
+ }
+ }
+ } while (current = next);
- while (this.index < this.text.length) {
- var ch = this.text.charAt(this.index);
- if (ch === '"' || ch === '\'') {
- this.readString(ch);
- } else if (this.isNumber(ch) || ch === '.' && this.isNumber(this.peek())) {
- this.readNumber();
- } else if (this.isIdentifierStart(this.peekMultichar())) {
- this.readIdent();
- } else if (this.is(ch, '(){}[].,;:?')) {
- this.tokens.push({index: this.index, text: ch});
- this.index++;
- } else if (this.isWhitespace(ch)) {
- this.index++;
- } else {
- var ch2 = ch + this.peek();
- var ch3 = ch2 + this.peek(2);
- var op1 = OPERATORS[ch];
- var op2 = OPERATORS[ch2];
- var op3 = OPERATORS[ch3];
- if (op1 || op2 || op3) {
- var token = op3 ? ch3 : (op2 ? ch2 : ch);
- this.tokens.push({index: this.index, text: token, operator: true});
- this.index += token.length;
- } else {
- this.throwError('Unexpected next character ', this.index, this.index + 1);
- }
- }
- }
- return this.tokens;
- },
+ // `break traverseScopesLoop;` takes us to here
- is: function(ch, chars) {
- return chars.indexOf(ch) !== -1;
- },
+ if ((dirty || asyncQueue.length) && !ttl--) {
+ clearPhase();
+ throw $rootScopeMinErr('infdig', '{0} $digest() iterations reached. Aborting!\n' + 'Watchers fired in the last 5 iterations: {1}', TTL, watchLog);
+ }
+ } while (dirty || asyncQueue.length);
- peek: function(i) {
- var num = i || 1;
- return (this.index + num < this.text.length) ? this.text.charAt(this.index + num) : false;
- },
+ clearPhase();
- isNumber: function(ch) {
- return ('0' <= ch && ch <= '9') && typeof ch === 'string';
- },
+ // postDigestQueuePosition isn't local here because this loop can be reentered recursively.
+ while (postDigestQueuePosition < postDigestQueue.length) {
+ try {
+ postDigestQueue[postDigestQueuePosition++]();
+ } catch (e) {
+ $exceptionHandler(e);
+ }
+ }
+ postDigestQueue.length = postDigestQueuePosition = 0;
- isWhitespace: function(ch) {
- // IE treats non-breaking space as \u00A0
- return (ch === ' ' || ch === '\r' || ch === '\t' ||
- ch === '\n' || ch === '\v' || ch === '\u00A0');
- },
+ // Check for changes to browser url that happened during the $digest
+ // (for which no event is fired; e.g. via `history.pushState()`)
+ $browser.$$checkUrlChange();
+ },
- isIdentifierStart: function(ch) {
- return this.options.isIdentifierStart ?
- this.options.isIdentifierStart(ch, this.codePointAt(ch)) :
- this.isValidIdentifierStart(ch);
- },
+ /**
+ * @ngdoc event
+ * @name $rootScope.Scope#$destroy
+ * @eventType broadcast on scope being destroyed
+ *
+ * @description
+ * Broadcasted when a scope and its children are being destroyed.
+ *
+ * Note that, in AngularJS, there is also a `$destroy` jQuery event, which can be used to
+ * clean up DOM bindings before an element is removed from the DOM.
+ */
- isValidIdentifierStart: function(ch) {
- return ('a' <= ch && ch <= 'z' ||
- 'A' <= ch && ch <= 'Z' ||
- '_' === ch || ch === '$');
- },
+ /**
+ * @ngdoc method
+ * @name $rootScope.Scope#$destroy
+ * @kind function
+ *
+ * @description
+ * Removes the current scope (and all of its children) from the parent scope. Removal implies
+ * that calls to {@link ng.$rootScope.Scope#$digest $digest()} will no longer
+ * propagate to the current scope and its children. Removal also implies that the current
+ * scope is eligible for garbage collection.
+ *
+ * The `$destroy()` is usually used by directives such as
+ * {@link ng.directive:ngRepeat ngRepeat} for managing the
+ * unrolling of the loop.
+ *
+ * Just before a scope is destroyed, a `$destroy` event is broadcasted on this scope.
+ * Application code can register a `$destroy` event handler that will give it a chance to
+ * perform any necessary cleanup.
+ *
+ * Note that, in AngularJS, there is also a `$destroy` jQuery event, which can be used to
+ * clean up DOM bindings before an element is removed from the DOM.
+ */
+ $destroy: function $destroy() {
+ // We can't destroy a scope that has been already destroyed.
+ if (this.$$destroyed) return;
+ var parent = this.$parent;
- isIdentifierContinue: function(ch) {
- return this.options.isIdentifierContinue ?
- this.options.isIdentifierContinue(ch, this.codePointAt(ch)) :
- this.isValidIdentifierContinue(ch);
- },
+ this.$broadcast('$destroy');
+ this.$$destroyed = true;
- isValidIdentifierContinue: function(ch, cp) {
- return this.isValidIdentifierStart(ch, cp) || this.isNumber(ch);
- },
+ if (this === $rootScope) {
+ //Remove handlers attached to window when $rootScope is removed
+ $browser.$$applicationDestroyed();
+ }
- codePointAt: function(ch) {
- if (ch.length === 1) return ch.charCodeAt(0);
- // eslint-disable-next-line no-bitwise
- return (ch.charCodeAt(0) << 10) + ch.charCodeAt(1) - 0x35FDC00;
- },
+ incrementWatchersCount(this, -this.$$watchersCount);
+ for (var eventName in this.$$listenerCount) {
+ decrementListenerCount(this, this.$$listenerCount[eventName], eventName);
+ }
- peekMultichar: function() {
- var ch = this.text.charAt(this.index);
- var peek = this.peek();
- if (!peek) {
- return ch;
- }
- var cp1 = ch.charCodeAt(0);
- var cp2 = peek.charCodeAt(0);
- if (cp1 >= 0xD800 && cp1 <= 0xDBFF && cp2 >= 0xDC00 && cp2 <= 0xDFFF) {
- return ch + peek;
- }
- return ch;
- },
+ // sever all the references to parent scopes (after this cleanup, the current scope should
+ // not be retained by any of our references and should be eligible for garbage collection)
+ if (parent && parent.$$childHead === this) parent.$$childHead = this.$$nextSibling;
+ if (parent && parent.$$childTail === this) parent.$$childTail = this.$$prevSibling;
+ if (this.$$prevSibling) this.$$prevSibling.$$nextSibling = this.$$nextSibling;
+ if (this.$$nextSibling) this.$$nextSibling.$$prevSibling = this.$$prevSibling;
+
+ // Disable listeners, watchers and apply/digest methods
+ this.$destroy = this.$digest = this.$apply = this.$evalAsync = this.$applyAsync = noop;
+ this.$on = this.$watch = this.$watchGroup = function () {
+ return noop;
+ };
+ this.$$listeners = {};
- isExpOperator: function(ch) {
- return (ch === '-' || ch === '+' || this.isNumber(ch));
- },
+ // Disconnect the next sibling to prevent `cleanUpScope` destroying those too
+ this.$$nextSibling = null;
+ cleanUpScope(this);
+ },
- throwError: function(error, start, end) {
- end = end || this.index;
- var colStr = (isDefined(start)
- ? 's ' + start + '-' + this.index + ' [' + this.text.substring(start, end) + ']'
- : ' ' + end);
- throw $parseMinErr('lexerr', 'Lexer Error: {0} at column{1} in expression [{2}].',
- error, colStr, this.text);
- },
+ /**
+ * @ngdoc method
+ * @name $rootScope.Scope#$eval
+ * @kind function
+ *
+ * @description
+ * 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);
+ * ```
+ *
+ * @param {(string|function())=} expression An angular expression to be executed.
+ *
+ * - `string`: execute using the rules as defined in {@link guide/expression expression}.
+ * - `function(scope)`: execute the function with the current `scope` parameter.
+ *
+ * @param {(object)=} locals Local variables object, useful for overriding values in scope.
+ * @returns {*} The result of evaluating the expression.
+ */
+ $eval: function $eval(expr, locals) {
+ return $parse(expr)(this, locals);
+ },
- readNumber: function() {
- var number = '';
- var start = this.index;
- while (this.index < this.text.length) {
- var ch = lowercase(this.text.charAt(this.index));
- if (ch === '.' || this.isNumber(ch)) {
- number += ch;
- } else {
- var peekCh = this.peek();
- if (ch === 'e' && this.isExpOperator(peekCh)) {
- number += ch;
- } else if (this.isExpOperator(ch) &&
- peekCh && this.isNumber(peekCh) &&
- number.charAt(number.length - 1) === 'e') {
- number += ch;
- } else if (this.isExpOperator(ch) &&
- (!peekCh || !this.isNumber(peekCh)) &&
- number.charAt(number.length - 1) === 'e') {
- this.throwError('Invalid exponent');
- } else {
- break;
- }
- }
- this.index++;
- }
- this.tokens.push({
- index: start,
- text: number,
- constant: true,
- value: Number(number)
- });
- },
+ /**
+ * @ngdoc method
+ * @name $rootScope.Scope#$evalAsync
+ * @kind function
+ *
+ * @description
+ * 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`.
+ *
+ * @param {(string|function())=} expression An angular expression to be executed.
+ *
+ * - `string`: execute using the rules as defined in {@link guide/expression expression}.
+ * - `function(scope)`: execute the function with the current `scope` parameter.
+ *
+ * @param {(object)=} locals Local variables object, useful for overriding values in scope.
+ */
+ $evalAsync: function $evalAsync(expr, locals) {
+ // if we are outside of an $digest loop and this is the first time we are scheduling async
+ // task also schedule async auto-flush
+ if (!$rootScope.$$phase && !asyncQueue.length) {
+ $browser.defer(function () {
+ if (asyncQueue.length) {
+ $rootScope.$digest();
+ }
+ });
+ }
- readIdent: function() {
- var start = this.index;
- this.index += this.peekMultichar().length;
- while (this.index < this.text.length) {
- var ch = this.peekMultichar();
- if (!this.isIdentifierContinue(ch)) {
- break;
- }
- this.index += ch.length;
- }
- this.tokens.push({
- index: start,
- text: this.text.slice(start, this.index),
- identifier: true
- });
- },
+ asyncQueue.push({ scope: this, fn: $parse(expr), locals: locals });
+ },
- readString: function(quote) {
- var start = this.index;
- this.index++;
- var string = '';
- var rawString = quote;
- var escape = false;
- while (this.index < this.text.length) {
- var ch = this.text.charAt(this.index);
- rawString += ch;
- if (escape) {
- if (ch === 'u') {
- var hex = this.text.substring(this.index + 1, this.index + 5);
- if (!hex.match(/[\da-f]{4}/i)) {
- this.throwError('Invalid unicode escape [\\u' + hex + ']');
+ $$postDigest: function $$postDigest(fn) {
+ postDigestQueue.push(fn);
+ },
+
+ /**
+ * @ngdoc method
+ * @name $rootScope.Scope#$apply
+ * @kind function
+ *
+ * @description
+ * `$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.
+ *
+ *
+ * @param {(string|function())=} exp An angular expression to be executed.
+ *
+ * - `string`: execute using the rules as defined in {@link guide/expression expression}.
+ * - `function(scope)`: execute the function with current `scope` parameter.
+ *
+ * @returns {*} The result of evaluating the expression.
+ */
+ $apply: function $apply(expr) {
+ try {
+ beginPhase('$apply');
+ try {
+ return this.$eval(expr);
+ } finally {
+ clearPhase();
+ }
+ } catch (e) {
+ $exceptionHandler(e);
+ } finally {
+ try {
+ $rootScope.$digest();
+ } catch (e) {
+ $exceptionHandler(e);
+ // eslint-disable-next-line no-unsafe-finally
+ throw e;
+ }
}
- this.index += 4;
- string += String.fromCharCode(parseInt(hex, 16));
- } else {
- var rep = ESCAPE[ch];
- string = string + (rep || ch);
- }
- escape = false;
- } else if (ch === '\\') {
- escape = true;
- } else if (ch === quote) {
- this.index++;
- this.tokens.push({
- index: start,
- text: rawString,
- constant: true,
- value: string
- });
- return;
- } else {
- string += ch;
- }
- this.index++;
- }
- this.throwError('Unterminated quote', start);
- }
-};
+ },
-var AST = function AST(lexer, options) {
- this.lexer = lexer;
- this.options = options;
-};
+ /**
+ * @ngdoc method
+ * @name $rootScope.Scope#$applyAsync
+ * @kind function
+ *
+ * @description
+ * 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.
+ *
+ * @param {(string|function())=} exp An angular expression to be executed.
+ *
+ * - `string`: execute using the rules as defined in {@link guide/expression expression}.
+ * - `function(scope)`: execute the function with current `scope` parameter.
+ */
+ $applyAsync: function $applyAsync(expr) {
+ var scope = this;
+ if (expr) {
+ applyAsyncQueue.push($applyAsyncExpression);
+ }
+ expr = $parse(expr);
+ scheduleApplyAsync();
+
+ function $applyAsyncExpression() {
+ scope.$eval(expr);
+ }
+ },
+
+ /**
+ * @ngdoc method
+ * @name $rootScope.Scope#$on
+ * @kind function
+ *
+ * @description
+ * 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.
+ *
+ * @param {string} name Event name to listen on.
+ * @param {function(event, ...args)} listener Function to call when the event is emitted.
+ * @returns {function()} Returns a deregistration function for this listener.
+ */
+ $on: function $on(name, listener) {
+ var namedListeners = this.$$listeners[name];
+ if (!namedListeners) {
+ this.$$listeners[name] = namedListeners = [];
+ }
+ namedListeners.push(listener);
-AST.Program = 'Program';
-AST.ExpressionStatement = 'ExpressionStatement';
-AST.AssignmentExpression = 'AssignmentExpression';
-AST.ConditionalExpression = 'ConditionalExpression';
-AST.LogicalExpression = 'LogicalExpression';
-AST.BinaryExpression = 'BinaryExpression';
-AST.UnaryExpression = 'UnaryExpression';
-AST.CallExpression = 'CallExpression';
-AST.MemberExpression = 'MemberExpression';
-AST.Identifier = 'Identifier';
-AST.Literal = 'Literal';
-AST.ArrayExpression = 'ArrayExpression';
-AST.Property = 'Property';
-AST.ObjectExpression = 'ObjectExpression';
-AST.ThisExpression = 'ThisExpression';
-AST.LocalsExpression = 'LocalsExpression';
+ var current = this;
+ do {
+ if (!current.$$listenerCount[name]) {
+ current.$$listenerCount[name] = 0;
+ }
+ current.$$listenerCount[name]++;
+ } while (current = current.$parent);
-// Internal use only
-AST.NGValueParameter = 'NGValueParameter';
+ var self = this;
+ return function () {
+ var indexOfListener = namedListeners.indexOf(listener);
+ if (indexOfListener !== -1) {
+ namedListeners[indexOfListener] = null;
+ decrementListenerCount(self, 1, name);
+ }
+ };
+ },
-AST.prototype = {
- ast: function(text) {
- this.text = text;
- this.tokens = this.lexer.lex(text);
+ /**
+ * @ngdoc method
+ * @name $rootScope.Scope#$emit
+ * @kind function
+ *
+ * @description
+ * 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.
+ *
+ * @param {string} name Event name to emit.
+ * @param {...*} args Optional one or more arguments which will be passed onto the event listeners.
+ * @return {Object} Event object (see {@link ng.$rootScope.Scope#$on}).
+ */
+ $emit: function $emit(name, args) {
+ var empty = [],
+ namedListeners,
+ scope = this,
+ _stopPropagation = false,
+ event = {
+ name: name,
+ targetScope: scope,
+ stopPropagation: function stopPropagation() {
+ _stopPropagation = true;
+ },
+ preventDefault: function preventDefault() {
+ event.defaultPrevented = true;
+ },
+ defaultPrevented: false
+ },
+ listenerArgs = concat([event], arguments, 1),
+ i,
+ length;
+
+ do {
+ namedListeners = scope.$$listeners[name] || empty;
+ event.currentScope = scope;
+ for (i = 0, length = namedListeners.length; i < length; i++) {
+
+ // if listeners were deregistered, defragment the array
+ if (!namedListeners[i]) {
+ namedListeners.splice(i, 1);
+ i--;
+ length--;
+ continue;
+ }
+ try {
+ //allow all listeners attached to the current scope to run
+ namedListeners[i].apply(null, listenerArgs);
+ } catch (e) {
+ $exceptionHandler(e);
+ }
+ }
+ //if any listener on the current scope stops propagation, prevent bubbling
+ if (_stopPropagation) {
+ event.currentScope = null;
+ return event;
+ }
+ //traverse upwards
+ scope = scope.$parent;
+ } while (scope);
- var value = this.program();
+ event.currentScope = null;
- if (this.tokens.length !== 0) {
- this.throwError('is an unexpected token', this.tokens[0]);
- }
+ return event;
+ },
- return value;
- },
+ /**
+ * @ngdoc method
+ * @name $rootScope.Scope#$broadcast
+ * @kind function
+ *
+ * @description
+ * 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.
+ *
+ * @param {string} name Event name to broadcast.
+ * @param {...*} args Optional one or more arguments which will be passed onto the event listeners.
+ * @return {Object} Event object, see {@link ng.$rootScope.Scope#$on}
+ */
+ $broadcast: function $broadcast(name, args) {
+ var target = this,
+ current = target,
+ next = target,
+ event = {
+ name: name,
+ targetScope: target,
+ preventDefault: function preventDefault() {
+ event.defaultPrevented = true;
+ },
+ defaultPrevented: false
+ };
- program: function() {
- var body = [];
- while (true) {
- if (this.tokens.length > 0 && !this.peek('}', ')', ';', ']'))
- body.push(this.expressionStatement());
- if (!this.expect(';')) {
- return { type: AST.Program, body: body};
- }
- }
- },
+ if (!target.$$listenerCount[name]) return event;
+
+ var listenerArgs = concat([event], arguments, 1),
+ listeners,
+ i,
+ length;
+
+ //down while you can, then up and next sibling or up and next sibling until back at root
+ while (current = next) {
+ event.currentScope = current;
+ listeners = current.$$listeners[name] || [];
+ for (i = 0, length = listeners.length; i < length; i++) {
+ // if listeners were deregistered, defragment the array
+ if (!listeners[i]) {
+ listeners.splice(i, 1);
+ i--;
+ length--;
+ continue;
+ }
- expressionStatement: function() {
- return { type: AST.ExpressionStatement, expression: this.filterChain() };
- },
+ try {
+ listeners[i].apply(null, listenerArgs);
+ } catch (e) {
+ $exceptionHandler(e);
+ }
+ }
- filterChain: function() {
- var left = this.expression();
- while (this.expect('|')) {
- left = this.filter(left);
- }
- return left;
- },
+ // Insanity Warning: scope depth-first traversal
+ // yes, this code is a bit crazy, but it works and we have tests to prove it!
+ // this piece should be kept in sync with the traversal in $digest
+ // (though it differs due to having the extra check for $$listenerCount)
+ if (!(next = current.$$listenerCount[name] && current.$$childHead || current !== target && current.$$nextSibling)) {
+ while (current !== target && !(next = current.$$nextSibling)) {
+ current = current.$parent;
+ }
+ }
+ }
- expression: function() {
- return this.assignment();
- },
+ event.currentScope = null;
+ return event;
+ }
+ };
- assignment: function() {
- var result = this.ternary();
- if (this.expect('=')) {
- if (!isAssignable(result)) {
- throw $parseMinErr('lval', 'Trying to assign a value to a non l-value');
- }
+ var $rootScope = new Scope();
- result = { type: AST.AssignmentExpression, left: result, right: this.assignment(), operator: '='};
- }
- return result;
- },
+ //The internal queues. Expose them on the $rootScope for debugging/testing purposes.
+ var asyncQueue = $rootScope.$$asyncQueue = [];
+ var postDigestQueue = $rootScope.$$postDigestQueue = [];
+ var applyAsyncQueue = $rootScope.$$applyAsyncQueue = [];
- ternary: function() {
- var test = this.logicalOR();
- var alternate;
- var consequent;
- if (this.expect('?')) {
- alternate = this.expression();
- if (this.consume(':')) {
- consequent = this.expression();
- return { type: AST.ConditionalExpression, test: test, alternate: alternate, consequent: consequent};
- }
- }
- return test;
- },
+ var postDigestQueuePosition = 0;
- logicalOR: function() {
- var left = this.logicalAND();
- while (this.expect('||')) {
- left = { type: AST.LogicalExpression, operator: '||', left: left, right: this.logicalAND() };
- }
- return left;
- },
+ return $rootScope;
- logicalAND: function() {
- var left = this.equality();
- while (this.expect('&&')) {
- left = { type: AST.LogicalExpression, operator: '&&', left: left, right: this.equality()};
- }
- return left;
- },
+ function beginPhase(phase) {
+ if ($rootScope.$$phase) {
+ throw $rootScopeMinErr('inprog', '{0} already in progress', $rootScope.$$phase);
+ }
- equality: function() {
- var left = this.relational();
- var token;
- while ((token = this.expect('==','!=','===','!=='))) {
- left = { type: AST.BinaryExpression, operator: token.text, left: left, right: this.relational() };
- }
- return left;
- },
+ $rootScope.$$phase = phase;
+ }
- relational: function() {
- var left = this.additive();
- var token;
- while ((token = this.expect('<', '>', '<=', '>='))) {
- left = { type: AST.BinaryExpression, operator: token.text, left: left, right: this.additive() };
- }
- return left;
- },
+ function clearPhase() {
+ $rootScope.$$phase = null;
+ }
- additive: function() {
- var left = this.multiplicative();
- var token;
- while ((token = this.expect('+','-'))) {
- left = { type: AST.BinaryExpression, operator: token.text, left: left, right: this.multiplicative() };
- }
- return left;
- },
+ function incrementWatchersCount(current, count) {
+ do {
+ current.$$watchersCount += count;
+ } while (current = current.$parent);
+ }
- multiplicative: function() {
- var left = this.unary();
- var token;
- while ((token = this.expect('*','/','%'))) {
- left = { type: AST.BinaryExpression, operator: token.text, left: left, right: this.unary() };
- }
- return left;
- },
+ function decrementListenerCount(current, count, name) {
+ do {
+ current.$$listenerCount[name] -= count;
- unary: function() {
- var token;
- if ((token = this.expect('+', '-', '!'))) {
- return { type: AST.UnaryExpression, operator: token.text, prefix: true, argument: this.unary() };
- } else {
- return this.primary();
- }
- },
+ if (current.$$listenerCount[name] === 0) {
+ delete current.$$listenerCount[name];
+ }
+ } while (current = current.$parent);
+ }
- primary: function() {
- var primary;
- if (this.expect('(')) {
- primary = this.filterChain();
- this.consume(')');
- } else if (this.expect('[')) {
- primary = this.arrayDeclaration();
- } else if (this.expect('{')) {
- primary = this.object();
- } else if (this.selfReferential.hasOwnProperty(this.peek().text)) {
- primary = copy(this.selfReferential[this.consume().text]);
- } else if (this.options.literals.hasOwnProperty(this.peek().text)) {
- primary = { type: AST.Literal, value: this.options.literals[this.consume().text]};
- } else if (this.peek().identifier) {
- primary = this.identifier();
- } else if (this.peek().constant) {
- primary = this.constant();
- } else {
- this.throwError('not a primary expression', this.peek());
- }
+ /**
+ * function used as an initial value for watchers.
+ * because it's unique we can easily tell it apart from other values
+ */
+ function initWatchVal() {}
- var next;
- while ((next = this.expect('(', '[', '.'))) {
- if (next.text === '(') {
- primary = {type: AST.CallExpression, callee: primary, arguments: this.parseArguments() };
- this.consume(')');
- } else if (next.text === '[') {
- primary = { type: AST.MemberExpression, object: primary, property: this.expression(), computed: true };
- this.consume(']');
- } else if (next.text === '.') {
- primary = { type: AST.MemberExpression, object: primary, property: this.identifier(), computed: false };
- } else {
- this.throwError('IMPOSSIBLE');
+ function flushApplyAsync() {
+ while (applyAsyncQueue.length) {
+ try {
+ applyAsyncQueue.shift()();
+ } catch (e) {
+ $exceptionHandler(e);
+ }
+ }
+ applyAsyncId = null;
}
- }
- return primary;
- },
- filter: function(baseExpression) {
- var args = [baseExpression];
- var result = {type: AST.CallExpression, callee: this.identifier(), arguments: args, filter: true};
+ function scheduleApplyAsync() {
+ if (applyAsyncId === null) {
+ applyAsyncId = $browser.defer(function () {
+ $rootScope.$apply(flushApplyAsync);
+ });
+ }
+ }
+ }];
+ }
- while (this.expect(':')) {
- args.push(this.expression());
- }
+ /**
+ * @ngdoc service
+ * @name $rootElement
+ *
+ * @description
+ * The root element of Angular application. This is either the element where {@link
+ * ng.directive:ngApp ngApp} was declared or the element passed into
+ * {@link angular.bootstrap}. The element represents the root element of application. It is also the
+ * location where the application's {@link auto.$injector $injector} service gets
+ * published, and can be retrieved using `$rootElement.injector()`.
+ */
- return result;
- },
+ // the implementation is in angular.bootstrap
- parseArguments: function() {
- var args = [];
- if (this.peekToken().text !== ')') {
- do {
- args.push(this.filterChain());
- } while (this.expect(','));
- }
- return args;
- },
+ /**
+ * @this
+ * @description
+ * Private service to sanitize uris for links and images. Used by $compile and $sanitize.
+ */
+ function $$SanitizeUriProvider() {
+ var aHrefSanitizationWhitelist = /^\s*(https?|ftp|mailto|tel|file):/,
+ imgSrcSanitizationWhitelist = /^\s*((https?|ftp|file|blob):|data:image\/)/;
- identifier: function() {
- var token = this.consume();
- if (!token.identifier) {
- this.throwError('is not a valid identifier', token);
- }
- return { type: AST.Identifier, name: token.text };
- },
+ /**
+ * @description
+ * 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 prevent 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.
+ *
+ * @param {RegExp=} regexp New regexp to whitelist urls with.
+ * @returns {RegExp|ng.$compileProvider} Current RegExp if called without value or self for
+ * chaining otherwise.
+ */
+ this.aHrefSanitizationWhitelist = function (regexp) {
+ if (isDefined(regexp)) {
+ aHrefSanitizationWhitelist = regexp;
+ return this;
+ }
+ return aHrefSanitizationWhitelist;
+ };
- constant: function() {
- // TODO check that it is a constant
- return { type: AST.Literal, value: this.consume().value };
- },
+ /**
+ * @description
+ * 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.
+ *
+ * @param {RegExp=} regexp New regexp to whitelist urls with.
+ * @returns {RegExp|ng.$compileProvider} Current RegExp if called without value or self for
+ * chaining otherwise.
+ */
+ this.imgSrcSanitizationWhitelist = function (regexp) {
+ if (isDefined(regexp)) {
+ imgSrcSanitizationWhitelist = regexp;
+ return this;
+ }
+ return imgSrcSanitizationWhitelist;
+ };
- arrayDeclaration: function() {
- var elements = [];
- if (this.peekToken().text !== ']') {
- do {
- if (this.peek(']')) {
- // Support trailing commas per ES5.1.
- break;
+ this.$get = function () {
+ return function sanitizeUri(uri, isImage) {
+ var regex = isImage ? imgSrcSanitizationWhitelist : aHrefSanitizationWhitelist;
+ var normalizedVal;
+ normalizedVal = urlResolve(uri).href;
+ if (normalizedVal !== '' && !normalizedVal.match(regex)) {
+ return 'unsafe:' + normalizedVal;
}
- elements.push(this.expression());
- } while (this.expect(','));
- }
- this.consume(']');
+ return uri;
+ };
+ };
+ }
- return { type: AST.ArrayExpression, elements: elements };
- },
+ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * 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 likes document or window? *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
- object: function() {
- var properties = [], property;
- if (this.peekToken().text !== '}') {
- do {
- if (this.peek('}')) {
- // Support trailing commas per ES5.1.
- break;
- }
- property = {type: AST.Property, kind: 'init'};
- if (this.peek().constant) {
- property.key = this.constant();
- property.computed = false;
- this.consume(':');
- property.value = this.expression();
- } else if (this.peek().identifier) {
- property.key = this.identifier();
- property.computed = false;
- if (this.peek(':')) {
- this.consume(':');
- property.value = this.expression();
- } else {
- property.value = property.key;
- }
- } else if (this.peek('[')) {
- this.consume('[');
- property.key = this.expression();
- this.consume(']');
- property.computed = true;
- this.consume(':');
- property.value = this.expression();
- } else {
- this.throwError('invalid key', this.peek());
- }
- properties.push(property);
- } while (this.expect(','));
- }
- this.consume('}');
+ /* exported $SceProvider, $SceDelegateProvider */
- return {type: AST.ObjectExpression, properties: properties };
- },
+ var $sceMinErr = minErr('$sce');
- throwError: function(msg, token) {
- throw $parseMinErr('syntax',
- 'Syntax Error: Token \'{0}\' {1} at column {2} of the expression [{3}] starting at [{4}].',
- token.text, msg, (token.index + 1), this.text, this.text.substring(token.index));
- },
+ var SCE_CONTEXTS = {
+ // HTML is used when there's HTML rendered (e.g. ng-bind-html, iframe srcdoc binding).
+ HTML: 'html',
- consume: function(e1) {
- if (this.tokens.length === 0) {
- throw $parseMinErr('ueoe', 'Unexpected end of expression: {0}', this.text);
- }
+ // Style statements or stylesheets. Currently unused in AngularJS.
+ CSS: 'css',
- var token = this.expect(e1);
- if (!token) {
- this.throwError('is unexpected, expecting [' + e1 + ']', this.peek());
- }
- return token;
- },
+ // An URL used in a context where it does not refer to a resource that loads code. Currently
+ // unused in AngularJS.
+ URL: 'url',
- peekToken: function() {
- if (this.tokens.length === 0) {
- throw $parseMinErr('ueoe', 'Unexpected end of expression: {0}', this.text);
- }
- return this.tokens[0];
- },
+ // RESOURCE_URL is a subtype of URL used where the referred-to resource could be interpreted as
+ // code. (e.g. ng-include, script src binding, templateUrl)
+ RESOURCE_URL: 'resourceUrl',
- peek: function(e1, e2, e3, e4) {
- return this.peekAhead(0, e1, e2, e3, e4);
- },
+ // Script. Currently unused in AngularJS.
+ JS: 'js'
+ };
- peekAhead: function(i, e1, e2, e3, e4) {
- if (this.tokens.length > i) {
- var token = this.tokens[i];
- var t = token.text;
- if (t === e1 || t === e2 || t === e3 || t === e4 ||
- (!e1 && !e2 && !e3 && !e4)) {
- return token;
- }
- }
- return false;
- },
+ // Helper functions follow.
- expect: function(e1, e2, e3, e4) {
- var token = this.peek(e1, e2, e3, e4);
- if (token) {
- this.tokens.shift();
- return token;
- }
- return false;
- },
+ var UNDERSCORE_LOWERCASE_REGEXP = /_([a-z])/g;
- selfReferential: {
- 'this': {type: AST.ThisExpression },
- '$locals': {type: AST.LocalsExpression }
+ function snakeToCamel(name) {
+ return name.replace(UNDERSCORE_LOWERCASE_REGEXP, fnCamelCaseReplace);
}
-};
-
-function ifDefined(v, d) {
- return typeof v !== 'undefined' ? v : d;
-}
-
-function plusFn(l, r) {
- if (typeof l === 'undefined') return r;
- if (typeof r === 'undefined') return l;
- return l + r;
-}
-
-function isStateless($filter, filterName) {
- var fn = $filter(filterName);
- return !fn.$stateful;
-}
-function findConstantAndWatchExpressions(ast, $filter) {
- var allConstants;
- var argsToWatch;
- var isStatelessFilter;
- switch (ast.type) {
- case AST.Program:
- allConstants = true;
- forEach(ast.body, function(expr) {
- findConstantAndWatchExpressions(expr.expression, $filter);
- allConstants = allConstants && expr.expression.constant;
- });
- ast.constant = allConstants;
- break;
- case AST.Literal:
- ast.constant = true;
- ast.toWatch = [];
- break;
- case AST.UnaryExpression:
- findConstantAndWatchExpressions(ast.argument, $filter);
- ast.constant = ast.argument.constant;
- ast.toWatch = ast.argument.toWatch;
- break;
- case AST.BinaryExpression:
- findConstantAndWatchExpressions(ast.left, $filter);
- findConstantAndWatchExpressions(ast.right, $filter);
- ast.constant = ast.left.constant && ast.right.constant;
- ast.toWatch = ast.left.toWatch.concat(ast.right.toWatch);
- break;
- case AST.LogicalExpression:
- findConstantAndWatchExpressions(ast.left, $filter);
- findConstantAndWatchExpressions(ast.right, $filter);
- ast.constant = ast.left.constant && ast.right.constant;
- ast.toWatch = ast.constant ? [] : [ast];
- break;
- case AST.ConditionalExpression:
- findConstantAndWatchExpressions(ast.test, $filter);
- findConstantAndWatchExpressions(ast.alternate, $filter);
- findConstantAndWatchExpressions(ast.consequent, $filter);
- ast.constant = ast.test.constant && ast.alternate.constant && ast.consequent.constant;
- ast.toWatch = ast.constant ? [] : [ast];
- break;
- case AST.Identifier:
- ast.constant = false;
- ast.toWatch = [ast];
- break;
- case AST.MemberExpression:
- findConstantAndWatchExpressions(ast.object, $filter);
- if (ast.computed) {
- findConstantAndWatchExpressions(ast.property, $filter);
- }
- ast.constant = ast.object.constant && (!ast.computed || ast.property.constant);
- ast.toWatch = [ast];
- break;
- case AST.CallExpression:
- isStatelessFilter = ast.filter ? isStateless($filter, ast.callee.name) : false;
- allConstants = isStatelessFilter;
- argsToWatch = [];
- forEach(ast.arguments, function(expr) {
- findConstantAndWatchExpressions(expr, $filter);
- allConstants = allConstants && expr.constant;
- if (!expr.constant) {
- argsToWatch.push.apply(argsToWatch, expr.toWatch);
- }
- });
- ast.constant = allConstants;
- ast.toWatch = isStatelessFilter ? argsToWatch : [ast];
- break;
- case AST.AssignmentExpression:
- findConstantAndWatchExpressions(ast.left, $filter);
- findConstantAndWatchExpressions(ast.right, $filter);
- ast.constant = ast.left.constant && ast.right.constant;
- ast.toWatch = [ast];
- break;
- case AST.ArrayExpression:
- allConstants = true;
- argsToWatch = [];
- forEach(ast.elements, function(expr) {
- findConstantAndWatchExpressions(expr, $filter);
- allConstants = allConstants && expr.constant;
- if (!expr.constant) {
- argsToWatch.push.apply(argsToWatch, expr.toWatch);
- }
- });
- ast.constant = allConstants;
- ast.toWatch = argsToWatch;
- break;
- case AST.ObjectExpression:
- allConstants = true;
- argsToWatch = [];
- forEach(ast.properties, function(property) {
- findConstantAndWatchExpressions(property.value, $filter);
- allConstants = allConstants && property.value.constant && !property.computed;
- if (!property.value.constant) {
- argsToWatch.push.apply(argsToWatch, property.value.toWatch);
- }
- if (property.computed) {
- findConstantAndWatchExpressions(property.key, $filter);
- if (!property.key.constant) {
- argsToWatch.push.apply(argsToWatch, property.key.toWatch);
- }
+ function adjustMatcher(matcher) {
+ if (matcher === 'self') {
+ return matcher;
+ } else if (isString(matcher)) {
+ // Strings match exactly except for 2 wildcards - '*' and '**'.
+ // '*' matches any character except those from the set ':/.?&'.
+ // '**' matches any character (like .* in a RegExp).
+ // More than 2 *'s raises an error as it's ill defined.
+ if (matcher.indexOf('***') > -1) {
+ throw $sceMinErr('iwcard', 'Illegal sequence *** in string matcher. String: {0}', matcher);
}
-
- });
- ast.constant = allConstants;
- ast.toWatch = argsToWatch;
- break;
- case AST.ThisExpression:
- ast.constant = false;
- ast.toWatch = [];
- break;
- case AST.LocalsExpression:
- ast.constant = false;
- ast.toWatch = [];
- break;
+ matcher = escapeForRegexp(matcher).replace(/\\\*\\\*/g, '.*').replace(/\\\*/g, '[^:/.?&;]*');
+ return new RegExp('^' + matcher + '$');
+ } else if (isRegExp(matcher)) {
+ // The only other type of matcher allowed is a Regexp.
+ // Match entire URL / disallow partial matches.
+ // Flags are reset (i.e. no global, ignoreCase or multiline)
+ return new RegExp('^' + matcher.source + '$');
+ } else {
+ throw $sceMinErr('imatcher', 'Matchers may only be "self", string patterns or RegExp objects');
+ }
}
-}
-function getInputs(body) {
- if (body.length !== 1) return;
- var lastExpression = body[0].expression;
- var candidate = lastExpression.toWatch;
- if (candidate.length !== 1) return candidate;
- return candidate[0] !== lastExpression ? candidate : undefined;
-}
-
-function isAssignable(ast) {
- return ast.type === AST.Identifier || ast.type === AST.MemberExpression;
-}
-
-function assignableAST(ast) {
- if (ast.body.length === 1 && isAssignable(ast.body[0].expression)) {
- return {type: AST.AssignmentExpression, left: ast.body[0].expression, right: {type: AST.NGValueParameter}, operator: '='};
+ function adjustMatchers(matchers) {
+ var adjustedMatchers = [];
+ if (isDefined(matchers)) {
+ forEach(matchers, function (matcher) {
+ adjustedMatchers.push(adjustMatcher(matcher));
+ });
+ }
+ return adjustedMatchers;
}
-}
-
-function isLiteral(ast) {
- return ast.body.length === 0 ||
- ast.body.length === 1 && (
- ast.body[0].expression.type === AST.Literal ||
- ast.body[0].expression.type === AST.ArrayExpression ||
- ast.body[0].expression.type === AST.ObjectExpression);
-}
-function isConstant(ast) {
- return ast.constant;
-}
+ /**
+ * @ngdoc service
+ * @name $sceDelegate
+ * @kind function
+ *
+ * @description
+ *
+ * `$sceDelegate` is a service that is used by the `$sce` service to provide {@link ng.$sce Strict
+ * Contextual Escaping (SCE)} services to AngularJS.
+ *
+ * For an overview of this service and the functionnality it provides in AngularJS, see the main
+ * page for {@link ng.$sce SCE}. The current page is targeted for developers who need to alter how
+ * SCE works in their application, which shouldn't be needed in most cases.
+ *
+ *
+ * AngularJS strongly relies on contextual escaping for the security of bindings: disabling or
+ * modifying this might cause cross site scripting (XSS) vulnerabilities. For libraries owners,
+ * changes to this service will also influence users, so be extra careful and document your changes.
+ *
+ *
+ * Typically, you would configure or override the {@link ng.$sceDelegate $sceDelegate} instead of
+ * the `$sce` service to customize the way Strict Contextual Escaping works in AngularJS. This is
+ * because, while the `$sce` provides numerous shorthand methods, etc., you really only need to
+ * override 3 core functions (`trustAs`, `getTrusted` and `valueOf`) to replace the way things
+ * work because `$sce` delegates to `$sceDelegate` for these operations.
+ *
+ * Refer {@link ng.$sceDelegateProvider $sceDelegateProvider} to configure this service.
+ *
+ * The default instance of `$sceDelegate` should work out of the box with little pain. While you
+ * can override it completely to change the behavior of `$sce`, the common case would
+ * involve configuring the {@link ng.$sceDelegateProvider $sceDelegateProvider} instead by setting
+ * your own whitelists and blacklists for trusting URLs used for loading AngularJS resources such as
+ * templates. Refer {@link ng.$sceDelegateProvider#resourceUrlWhitelist
+ * $sceDelegateProvider.resourceUrlWhitelist} and {@link
+ * ng.$sceDelegateProvider#resourceUrlBlacklist $sceDelegateProvider.resourceUrlBlacklist}
+ */
-function ASTCompiler($filter) {
- this.$filter = $filter;
-}
+ /**
+ * @ngdoc provider
+ * @name $sceDelegateProvider
+ * @this
+ *
+ * @description
+ *
+ * The `$sceDelegateProvider` provider allows developers to configure the {@link ng.$sceDelegate
+ * $sceDelegate service}, used as a delegate for {@link ng.$sce Strict Contextual Escaping (SCE)}.
+ *
+ * The `$sceDelegateProvider` allows one to get/set the whitelists and blacklists used to ensure
+ * that the URLs used for sourcing AngularJS templates and other script-running URLs are safe (all
+ * places that use the `$sce.RESOURCE_URL` context). See
+ * {@link ng.$sceDelegateProvider#resourceUrlWhitelist $sceDelegateProvider.resourceUrlWhitelist}
+ * and
+ * {@link ng.$sceDelegateProvider#resourceUrlBlacklist $sceDelegateProvider.resourceUrlBlacklist},
+ *
+ * For the general details about this service in Angular, read the main page for {@link ng.$sce
+ * Strict Contextual Escaping (SCE)}.
+ *
+ * **Example**: Consider the following case.
+ *
+ * - your app is hosted at url `http://myapp.example.com/`
+ * - but some of your templates are hosted on other domains you control such as
+ * `http://srv01.assets.example.com/`, `http://srv02.assets.example.com/`, etc.
+ * - and you have an open redirect at `http://myapp.example.com/clickThru?...`.
+ *
+ * Here is what a secure configuration for this scenario might look like:
+ *
+ * ```
+ * angular.module('myApp', []).config(function($sceDelegateProvider) {
+ * $sceDelegateProvider.resourceUrlWhitelist([
+ * // Allow same origin resource loads.
+ * 'self',
+ * // Allow loading from our assets domain. Notice the difference between * and **.
+ * 'http://srv*.assets.example.com/**'
+ * ]);
+ *
+ * // The blacklist overrides the whitelist so the open redirect here is blocked.
+ * $sceDelegateProvider.resourceUrlBlacklist([
+ * 'http://myapp.example.com/clickThru**'
+ * ]);
+ * });
+ * ```
+ * Note that an empty whitelist will block every resource URL from being loaded, and will require
+ * you to manually mark each one as trusted with `$sce.trustAsResourceUrl`. However, templates
+ * requested by {@link ng.$templateRequest $templateRequest} that are present in
+ * {@link ng.$templateCache $templateCache} will not go through this check. If you have a mechanism
+ * to populate your templates in that cache at config time, then it is a good idea to remove 'self'
+ * from that whitelist. This helps to mitigate the security impact of certain types of issues, like
+ * for instance attacker-controlled `ng-includes`.
+ */
-ASTCompiler.prototype = {
- compile: function(ast) {
- var self = this;
- this.state = {
- nextId: 0,
- filters: {},
- fn: {vars: [], body: [], own: {}},
- assign: {vars: [], body: [], own: {}},
- inputs: []
- };
- findConstantAndWatchExpressions(ast, self.$filter);
- var extra = '';
- var assignable;
- this.stage = 'assign';
- if ((assignable = assignableAST(ast))) {
- this.state.computing = 'assign';
- var result = this.nextId();
- this.recurse(assignable, result);
- this.return_(result);
- extra = 'fn.assign=' + this.generateFunction('assign', 's,v,l');
- }
- var toWatch = getInputs(ast.body);
- self.stage = 'inputs';
- forEach(toWatch, function(watch, key) {
- var fnKey = 'fn' + key;
- self.state[fnKey] = {vars: [], body: [], own: {}};
- self.state.computing = fnKey;
- var intoId = self.nextId();
- self.recurse(watch, intoId);
- self.return_(intoId);
- self.state.inputs.push(fnKey);
- watch.watchId = key;
- });
- this.state.computing = 'fn';
- this.stage = 'main';
- this.recurse(ast);
- var fnString =
- // The build and minification steps remove the string "use strict" from the code, but this is done using a regex.
- // This is a workaround for this until we do a better job at only removing the prefix only when we should.
- '"' + this.USE + ' ' + this.STRICT + '";\n' +
- this.filterPrefix() +
- 'var fn=' + this.generateFunction('fn', 's,l,a,i') +
- extra +
- this.watchFns() +
- 'return fn;';
-
- // eslint-disable-next-line no-new-func
- var fn = (new Function('$filter',
- 'getStringValue',
- 'ifDefined',
- 'plus',
- fnString))(
- this.$filter,
- getStringValue,
- ifDefined,
- plusFn);
- this.state = this.stage = undefined;
- return fn;
- },
+ function $SceDelegateProvider() {
+ this.SCE_CONTEXTS = SCE_CONTEXTS;
- USE: 'use',
+ // Resource URLs can also be trusted by policy.
+ var resourceUrlWhitelist = ['self'],
+ resourceUrlBlacklist = [];
- STRICT: 'strict',
+ /**
+ * @ngdoc method
+ * @name $sceDelegateProvider#resourceUrlWhitelist
+ * @kind function
+ *
+ * @param {Array=} whitelist When provided, replaces the resourceUrlWhitelist with the value
+ * provided. This must be an array or null. A snapshot of this array is used so further
+ * changes to the array are ignored.
+ * Follow {@link ng.$sce#resourceUrlPatternItem this link} for a description of the items
+ * allowed in this array.
+ *
+ * @return {Array} The currently set whitelist array.
+ *
+ * @description
+ * Sets/Gets the whitelist of trusted resource URLs.
+ *
+ * The **default value** when no whitelist has been explicitly set is `['self']` allowing only
+ * same origin resource requests.
+ *
+ *
+ * **Note:** the default whitelist of 'self' is not recommended if your app shares its origin
+ * with other apps! It is a good idea to limit it to only your application's directory.
+ *
+ */
+ this.resourceUrlWhitelist = function (value) {
+ if (arguments.length) {
+ resourceUrlWhitelist = adjustMatchers(value);
+ }
+ return resourceUrlWhitelist;
+ };
- watchFns: function() {
- var result = [];
- var fns = this.state.inputs;
- var self = this;
- forEach(fns, function(name) {
- result.push('var ' + name + '=' + self.generateFunction(name, 's'));
- });
- if (fns.length) {
- result.push('fn.inputs=[' + fns.join(',') + '];');
- }
- return result.join('');
- },
+ /**
+ * @ngdoc method
+ * @name $sceDelegateProvider#resourceUrlBlacklist
+ * @kind function
+ *
+ * @param {Array=} blacklist When provided, replaces the resourceUrlBlacklist with the value
+ * provided. This must be an array or null. A snapshot of this array is used so further
+ * changes to the array are ignored.
+ * Follow {@link ng.$sce#resourceUrlPatternItem this link} for a description of the items
+ * allowed in this array.
+ * The typical usage for the blacklist is to **block
+ * [open redirects](http://cwe.mitre.org/data/definitions/601.html)** served by your domain as
+ * these would otherwise be trusted but actually return content from the redirected domain.
+ *
+ * Finally, **the blacklist overrides the whitelist** and has the final say.
+ *
+ * @return {Array} The currently set blacklist array.
+ *
+ * @description
+ * Sets/Gets the blacklist of trusted resource URLs.
+ *
+ * The **default value** when no whitelist has been explicitly set is the empty array (i.e. there
+ * is no blacklist.)
+ */
- generateFunction: function(name, params) {
- return 'function(' + params + '){' +
- this.varsPrefix(name) +
- this.body(name) +
- '};';
- },
+ this.resourceUrlBlacklist = function (value) {
+ if (arguments.length) {
+ resourceUrlBlacklist = adjustMatchers(value);
+ }
+ return resourceUrlBlacklist;
+ };
- filterPrefix: function() {
- var parts = [];
- var self = this;
- forEach(this.state.filters, function(id, filter) {
- parts.push(id + '=$filter(' + self.escape(filter) + ')');
- });
- if (parts.length) return 'var ' + parts.join(',') + ';';
- return '';
- },
+ this.$get = ['$injector', function ($injector) {
- varsPrefix: function(section) {
- return this.state[section].vars.length ? 'var ' + this.state[section].vars.join(',') + ';' : '';
- },
+ var htmlSanitizer = function htmlSanitizer(html) {
+ throw $sceMinErr('unsafe', 'Attempting to use an unsafe value in a safe context.');
+ };
- body: function(section) {
- return this.state[section].body.join('');
- },
+ if ($injector.has('$sanitize')) {
+ htmlSanitizer = $injector.get('$sanitize');
+ }
- recurse: function(ast, intoId, nameId, recursionFn, create, skipWatchIdCheck) {
- var left, right, self = this, args, expression, computed;
- recursionFn = recursionFn || noop;
- if (!skipWatchIdCheck && isDefined(ast.watchId)) {
- intoId = intoId || this.nextId();
- this.if_('i',
- this.lazyAssign(intoId, this.computedMember('i', ast.watchId)),
- this.lazyRecurse(ast, intoId, nameId, recursionFn, create, true)
- );
- return;
- }
- switch (ast.type) {
- case AST.Program:
- forEach(ast.body, function(expression, pos) {
- self.recurse(expression.expression, undefined, undefined, function(expr) { right = expr; });
- if (pos !== ast.body.length - 1) {
- self.current().body.push(right, ';');
+ function matchUrl(matcher, parsedUrl) {
+ if (matcher === 'self') {
+ return urlIsSameOrigin(parsedUrl);
} else {
- self.return_(right);
+ // definitely a regex. See adjustMatchers()
+ return !!matcher.exec(parsedUrl.href);
}
- });
- break;
- case AST.Literal:
- expression = this.escape(ast.value);
- this.assign(intoId, expression);
- recursionFn(intoId || expression);
- break;
- case AST.UnaryExpression:
- this.recurse(ast.argument, undefined, undefined, function(expr) { right = expr; });
- expression = ast.operator + '(' + this.ifDefined(right, 0) + ')';
- this.assign(intoId, expression);
- recursionFn(expression);
- break;
- case AST.BinaryExpression:
- this.recurse(ast.left, undefined, undefined, function(expr) { left = expr; });
- this.recurse(ast.right, undefined, undefined, function(expr) { right = expr; });
- if (ast.operator === '+') {
- expression = this.plus(left, right);
- } else if (ast.operator === '-') {
- expression = this.ifDefined(left, 0) + ast.operator + this.ifDefined(right, 0);
- } else {
- expression = '(' + left + ')' + ast.operator + '(' + right + ')';
}
- this.assign(intoId, expression);
- recursionFn(expression);
- break;
- case AST.LogicalExpression:
- intoId = intoId || this.nextId();
- self.recurse(ast.left, intoId);
- self.if_(ast.operator === '&&' ? intoId : self.not(intoId), self.lazyRecurse(ast.right, intoId));
- recursionFn(intoId);
- break;
- case AST.ConditionalExpression:
- intoId = intoId || this.nextId();
- self.recurse(ast.test, intoId);
- self.if_(intoId, self.lazyRecurse(ast.alternate, intoId), self.lazyRecurse(ast.consequent, intoId));
- recursionFn(intoId);
- break;
- case AST.Identifier:
- intoId = intoId || this.nextId();
- if (nameId) {
- nameId.context = self.stage === 'inputs' ? 's' : this.assign(this.nextId(), this.getHasOwnProperty('l', ast.name) + '?l:s');
- nameId.computed = false;
- nameId.name = ast.name;
- }
- self.if_(self.stage === 'inputs' || self.not(self.getHasOwnProperty('l', ast.name)),
- function() {
- self.if_(self.stage === 'inputs' || 's', function() {
- if (create && create !== 1) {
- self.if_(
- self.isNull(self.nonComputedMember('s', ast.name)),
- self.lazyAssign(self.nonComputedMember('s', ast.name), '{}'));
- }
- self.assign(intoId, self.nonComputedMember('s', ast.name));
- });
- }, intoId && self.lazyAssign(intoId, self.nonComputedMember('l', ast.name))
- );
- recursionFn(intoId);
- break;
- case AST.MemberExpression:
- left = nameId && (nameId.context = this.nextId()) || this.nextId();
- intoId = intoId || this.nextId();
- self.recurse(ast.object, left, undefined, function() {
- self.if_(self.notNull(left), function() {
- if (ast.computed) {
- right = self.nextId();
- self.recurse(ast.property, right);
- self.getStringValue(right);
- if (create && create !== 1) {
- self.if_(self.not(self.computedMember(left, right)), self.lazyAssign(self.computedMember(left, right), '{}'));
- }
- expression = self.computedMember(left, right);
- self.assign(intoId, expression);
- if (nameId) {
- nameId.computed = true;
- nameId.name = right;
- }
- } else {
- if (create && create !== 1) {
- self.if_(self.isNull(self.nonComputedMember(left, ast.property.name)), self.lazyAssign(self.nonComputedMember(left, ast.property.name), '{}'));
- }
- expression = self.nonComputedMember(left, ast.property.name);
- self.assign(intoId, expression);
- if (nameId) {
- nameId.computed = false;
- nameId.name = ast.property.name;
- }
+
+ function isResourceUrlAllowedByPolicy(url) {
+ var parsedUrl = urlResolve(url.toString());
+ var i,
+ n,
+ allowed = false;
+ // Ensure that at least one item from the whitelist allows this url.
+ for (i = 0, n = resourceUrlWhitelist.length; i < n; i++) {
+ if (matchUrl(resourceUrlWhitelist[i], parsedUrl)) {
+ allowed = true;
+ break;
}
- }, function() {
- self.assign(intoId, 'undefined');
- });
- recursionFn(intoId);
- }, !!create);
- break;
- case AST.CallExpression:
- intoId = intoId || this.nextId();
- if (ast.filter) {
- right = self.filter(ast.callee.name);
- args = [];
- forEach(ast.arguments, function(expr) {
- var argument = self.nextId();
- self.recurse(expr, argument);
- args.push(argument);
- });
- expression = right + '(' + args.join(',') + ')';
- self.assign(intoId, expression);
- recursionFn(intoId);
- } else {
- right = self.nextId();
- left = {};
- args = [];
- self.recurse(ast.callee, right, left, function() {
- self.if_(self.notNull(right), function() {
- forEach(ast.arguments, function(expr) {
- self.recurse(expr, ast.constant ? undefined : self.nextId(), undefined, function(argument) {
- args.push(argument);
- });
- });
- if (left.name) {
- expression = self.member(left.context, left.name, left.computed) + '(' + args.join(',') + ')';
- } else {
- expression = right + '(' + args.join(',') + ')';
- }
- self.assign(intoId, expression);
- }, function() {
- self.assign(intoId, 'undefined');
- });
- recursionFn(intoId);
- });
- }
- break;
- case AST.AssignmentExpression:
- right = this.nextId();
- left = {};
- this.recurse(ast.left, undefined, left, function() {
- self.if_(self.notNull(left.context), function() {
- self.recurse(ast.right, right);
- expression = self.member(left.context, left.name, left.computed) + ast.operator + right;
- self.assign(intoId, expression);
- recursionFn(intoId || expression);
- });
- }, 1);
- break;
- case AST.ArrayExpression:
- args = [];
- forEach(ast.elements, function(expr) {
- self.recurse(expr, ast.constant ? undefined : self.nextId(), undefined, function(argument) {
- args.push(argument);
- });
- });
- expression = '[' + args.join(',') + ']';
- this.assign(intoId, expression);
- recursionFn(intoId || expression);
- break;
- case AST.ObjectExpression:
- args = [];
- computed = false;
- forEach(ast.properties, function(property) {
- if (property.computed) {
- computed = true;
}
- });
- if (computed) {
- intoId = intoId || this.nextId();
- this.assign(intoId, '{}');
- forEach(ast.properties, function(property) {
- if (property.computed) {
- left = self.nextId();
- self.recurse(property.key, left);
- } else {
- left = property.key.type === AST.Identifier ?
- property.key.name :
- ('' + property.key.value);
+ if (allowed) {
+ // Ensure that no item from the blacklist blocked this url.
+ for (i = 0, n = resourceUrlBlacklist.length; i < n; i++) {
+ if (matchUrl(resourceUrlBlacklist[i], parsedUrl)) {
+ allowed = false;
+ break;
+ }
}
- right = self.nextId();
- self.recurse(property.value, right);
- self.assign(self.member(intoId, left, property.computed), right);
- });
- } else {
- forEach(ast.properties, function(property) {
- self.recurse(property.value, ast.constant ? undefined : self.nextId(), undefined, function(expr) {
- args.push(self.escape(
- property.key.type === AST.Identifier ? property.key.name :
- ('' + property.key.value)) +
- ':' + expr);
- });
- });
- expression = '{' + args.join(',') + '}';
- this.assign(intoId, expression);
+ }
+ return allowed;
}
- recursionFn(intoId || expression);
- break;
- case AST.ThisExpression:
- this.assign(intoId, 's');
- recursionFn(intoId || 's');
- break;
- case AST.LocalsExpression:
- this.assign(intoId, 'l');
- recursionFn(intoId || 'l');
- break;
- case AST.NGValueParameter:
- this.assign(intoId, 'v');
- recursionFn(intoId || 'v');
- break;
- }
- },
-
- getHasOwnProperty: function(element, property) {
- var key = element + '.' + property;
- var own = this.current().own;
- if (!own.hasOwnProperty(key)) {
- own[key] = this.nextId(false, element + '&&(' + this.escape(property) + ' in ' + element + ')');
- }
- return own[key];
- },
-
- assign: function(id, value) {
- if (!id) return;
- this.current().body.push(id, '=', value, ';');
- return id;
- },
-
- filter: function(filterName) {
- if (!this.state.filters.hasOwnProperty(filterName)) {
- this.state.filters[filterName] = this.nextId(true);
- }
- return this.state.filters[filterName];
- },
- ifDefined: function(id, defaultValue) {
- return 'ifDefined(' + id + ',' + this.escape(defaultValue) + ')';
- },
+ function generateHolderType(Base) {
+ var holderType = function TrustedValueHolderType(trustedValue) {
+ this.$$unwrapTrustedValue = function () {
+ return trustedValue;
+ };
+ };
+ if (Base) {
+ holderType.prototype = new Base();
+ }
+ holderType.prototype.valueOf = function sceValueOf() {
+ return this.$$unwrapTrustedValue();
+ };
+ holderType.prototype.toString = function sceToString() {
+ return this.$$unwrapTrustedValue().toString();
+ };
+ return holderType;
+ }
- plus: function(left, right) {
- return 'plus(' + left + ',' + right + ')';
- },
+ var trustedValueHolderBase = generateHolderType(),
+ byType = {};
- return_: function(id) {
- this.current().body.push('return ', id, ';');
- },
+ byType[SCE_CONTEXTS.HTML] = generateHolderType(trustedValueHolderBase);
+ byType[SCE_CONTEXTS.CSS] = generateHolderType(trustedValueHolderBase);
+ byType[SCE_CONTEXTS.URL] = generateHolderType(trustedValueHolderBase);
+ byType[SCE_CONTEXTS.JS] = generateHolderType(trustedValueHolderBase);
+ byType[SCE_CONTEXTS.RESOURCE_URL] = generateHolderType(byType[SCE_CONTEXTS.URL]);
- if_: function(test, alternate, consequent) {
- if (test === true) {
- alternate();
- } else {
- var body = this.current().body;
- body.push('if(', test, '){');
- alternate();
- body.push('}');
- if (consequent) {
- body.push('else{');
- consequent();
- body.push('}');
+ /**
+ * @ngdoc method
+ * @name $sceDelegate#trustAs
+ *
+ * @description
+ * Returns a trusted representation of the parameter for the specified context. This trusted
+ * object will later on be used as-is, without any security check, by bindings or directives
+ * that require this security context.
+ * For instance, marking a string as trusted for the `$sce.HTML` context will entirely bypass
+ * the potential `$sanitize` call in corresponding `$sce.HTML` bindings or directives, such as
+ * `ng-bind-html`. Note that in most cases you won't need to call this function: if you have the
+ * sanitizer loaded, passing the value itself will render all the HTML that does not pose a
+ * security risk.
+ *
+ * See {@link ng.$sceDelegate#getTrusted getTrusted} for the function that will consume those
+ * trusted values, and {@link ng.$sce $sce} for general documentation about strict contextual
+ * escaping.
+ *
+ * @param {string} type The context in which this value is safe for use, e.g. `$sce.URL`,
+ * `$sce.RESOURCE_URL`, `$sce.HTML`, `$sce.JS` or `$sce.CSS`.
+ *
+ * @param {*} value The value that should be considered trusted.
+ * @return {*} A trusted representation of value, that can be used in the given context.
+ */
+ function trustAs(type, trustedValue) {
+ var Constructor = byType.hasOwnProperty(type) ? byType[type] : null;
+ if (!Constructor) {
+ throw $sceMinErr('icontext', 'Attempted to trust a value in invalid context. Context: {0}; Value: {1}', type, trustedValue);
+ }
+ if (trustedValue === null || isUndefined(trustedValue) || trustedValue === '') {
+ return trustedValue;
+ }
+ // All the current contexts in SCE_CONTEXTS happen to be strings. In order to avoid trusting
+ // mutable objects, we ensure here that the value passed in is actually a string.
+ if (typeof trustedValue !== 'string') {
+ throw $sceMinErr('itype', 'Attempted to trust a non-string value in a content requiring a string: Context: {0}', type);
+ }
+ return new Constructor(trustedValue);
}
- }
- },
-
- not: function(expression) {
- return '!(' + expression + ')';
- },
-
- isNull: function(expression) {
- return expression + '==null';
- },
- notNull: function(expression) {
- return expression + '!=null';
- },
+ /**
+ * @ngdoc method
+ * @name $sceDelegate#valueOf
+ *
+ * @description
+ * 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`}, it must be returned as-is.
+ *
+ * @param {*} value The result of a prior {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}
+ * call or anything else.
+ * @return {*} The `value` that was originally provided to {@link ng.$sceDelegate#trustAs
+ * `$sceDelegate.trustAs`} if `value` is the result of such a call. Otherwise, returns
+ * `value` unchanged.
+ */
+ function valueOf(maybeTrusted) {
+ if (maybeTrusted instanceof trustedValueHolderBase) {
+ return maybeTrusted.$$unwrapTrustedValue();
+ } else {
+ return maybeTrusted;
+ }
+ }
- nonComputedMember: function(left, right) {
- var SAFE_IDENTIFIER = /^[$_a-zA-Z][$_a-zA-Z0-9]*$/;
- var UNSAFE_CHARACTERS = /[^$_a-zA-Z0-9]/g;
- if (SAFE_IDENTIFIER.test(right)) {
- return left + '.' + right;
- } else {
- return left + '["' + right.replace(UNSAFE_CHARACTERS, this.stringEscapeFn) + '"]';
- }
- },
+ /**
+ * @ngdoc method
+ * @name $sceDelegate#getTrusted
+ *
+ * @description
+ * Takes any input, and either returns a value that's safe to use in the specified context, or
+ * throws an exception.
+ *
+ * In practice, there are several cases. When given a string, this function runs checks
+ * and sanitization to make it safe without prior assumptions. When given the result of a {@link
+ * ng.$sceDelegate#trustAs `$sceDelegate.trustAs`} call, it returns the originally supplied
+ * value if that value's context is valid for this call's context. Finally, this function can
+ * also throw when there is no way to turn `maybeTrusted` in a safe value (e.g., no sanitization
+ * is available or possible.)
+ *
+ * @param {string} type The context in which this value is to be used (such as `$sce.HTML`).
+ * @param {*} maybeTrusted The result of a prior {@link ng.$sceDelegate#trustAs
+ * `$sceDelegate.trustAs`} call, or anything else (which will not be considered trusted.)
+ * @return {*} A version of the value that's safe to use in the given context, or throws an
+ * exception if this is impossible.
+ */
+ function getTrusted(type, maybeTrusted) {
+ if (maybeTrusted === null || isUndefined(maybeTrusted) || maybeTrusted === '') {
+ return maybeTrusted;
+ }
+ var constructor = byType.hasOwnProperty(type) ? byType[type] : null;
+ // If maybeTrusted is a trusted class instance or subclass instance, then unwrap and return
+ // as-is.
+ if (constructor && maybeTrusted instanceof constructor) {
+ return maybeTrusted.$$unwrapTrustedValue();
+ }
+ // Otherwise, if we get here, then we may either make it safe, or throw an exception. This
+ // depends on the context: some are sanitizatible (HTML), some use whitelists (RESOURCE_URL),
+ // some are impossible to do (JS). This step isn't implemented for CSS and URL, as AngularJS
+ // has no corresponding sinks.
+ if (type === SCE_CONTEXTS.RESOURCE_URL) {
+ // RESOURCE_URL uses a whitelist.
+ if (isResourceUrlAllowedByPolicy(maybeTrusted)) {
+ return maybeTrusted;
+ } else {
+ throw $sceMinErr('insecurl', 'Blocked loading resource from url not allowed by $sceDelegate policy. URL: {0}', maybeTrusted.toString());
+ }
+ } else if (type === SCE_CONTEXTS.HTML) {
+ // htmlSanitizer throws its own error when no sanitizer is available.
+ return htmlSanitizer(maybeTrusted);
+ }
+ // Default error when the $sce service has no way to make the input safe.
+ throw $sceMinErr('unsafe', 'Attempting to use an unsafe value in a safe context.');
+ }
- computedMember: function(left, right) {
- return left + '[' + right + ']';
- },
+ return { trustAs: trustAs,
+ getTrusted: getTrusted,
+ valueOf: valueOf };
+ }];
+ }
- member: function(left, right, computed) {
- if (computed) return this.computedMember(left, right);
- return this.nonComputedMember(left, right);
- },
+ /**
+ * @ngdoc provider
+ * @name $sceProvider
+ * @this
+ *
+ * @description
+ *
+ * The $sceProvider provider allows developers to configure the {@link ng.$sce $sce} service.
+ * - enable/disable Strict Contextual Escaping (SCE) in a module
+ * - override the default implementation with a custom delegate
+ *
+ * Read more about {@link ng.$sce Strict Contextual Escaping (SCE)}.
+ */
- getStringValue: function(item) {
- this.assign(item, 'getStringValue(' + item + ')');
- },
+ /**
+ * @ngdoc service
+ * @name $sce
+ * @kind function
+ *
+ * @description
+ *
+ * `$sce` is a service that provides Strict Contextual Escaping services to AngularJS.
+ *
+ * # Strict Contextual Escaping
+ *
+ * Strict Contextual Escaping (SCE) is a mode in which AngularJS constrains bindings to only render
+ * trusted values. Its goal is to assist in writing code in a way that (a) is secure by default, and
+ * (b) makes auditing for security vulnerabilities such as XSS, clickjacking, etc. a lot easier.
+ *
+ * ## Overview
+ *
+ * To systematically block XSS security bugs, AngularJS treats all values as untrusted by default in
+ * HTML or sensitive URL bindings. When binding untrusted values, AngularJS will automatically
+ * run security checks on them (sanitizations, whitelists, depending on context), or throw when it
+ * cannot guarantee the security of the result. That behavior depends strongly on contexts: HTML
+ * can be sanitized, but template URLs cannot, for instance.
+ *
+ * To illustrate this, consider the `ng-bind-html` directive. It renders its value directly as HTML:
+ * we call that the *context*. When given an untrusted input, AngularJS will attempt to sanitize it
+ * before rendering if a sanitizer is available, and throw otherwise. To bypass sanitization and
+ * render the input as-is, you will need to mark it as trusted for that context before attempting
+ * to bind it.
+ *
+ * As of version 1.2, AngularJS ships with SCE enabled by default.
+ *
+ * ## In practice
+ *
+ * Here's an example of a binding in a privileged context:
+ *
+ * ```
+ *
+ *
+ * ```
+ *
+ * Notice that `ng-bind-html` is bound to `userHtml` controlled by the user. With SCE
+ * disabled, this application allows the user to render arbitrary HTML into the DIV, which would
+ * be an XSS security bug. In a more realistic example, one may be rendering user comments, blog
+ * articles, etc. via bindings. (HTML is just one example of a context where rendering user
+ * controlled input creates security vulnerabilities.)
+ *
+ * For the case of HTML, you might use a library, either on the client side, or on the server side,
+ * to sanitize unsafe HTML before binding to the value and rendering it in the document.
+ *
+ * How would you ensure that every place that used these types of bindings was bound to a value that
+ * was sanitized by your library (or returned as safe for rendering by your server?) How can you
+ * ensure that you didn't accidentally delete the line that sanitized the value, or renamed some
+ * properties/fields and forgot to update the binding to the sanitized value?
+ *
+ * To be secure by default, AngularJS makes sure bindings go through that sanitization, or
+ * any similar validation process, unless there's a good reason to trust the given value in this
+ * context. That trust is formalized with a function call. This means that as a developer, you
+ * can assume all untrusted bindings are safe. Then, to audit your code for binding security issues,
+ * you just need to ensure the values you mark as trusted indeed are safe - because they were
+ * received from your server, sanitized by your library, etc. You can organize your codebase to
+ * help with this - perhaps allowing only the files in a specific directory to do this.
+ * Ensuring that the internal API exposed by that code doesn't markup arbitrary values as safe then
+ * becomes a more manageable task.
+ *
+ * In the case of AngularJS' SCE service, one uses {@link ng.$sce#trustAs $sce.trustAs}
+ * (and shorthand methods such as {@link ng.$sce#trustAsHtml $sce.trustAsHtml}, etc.) to
+ * build the trusted versions of your values.
+ *
+ * ## How does it work?
+ *
+ * In privileged contexts, directives and code will bind to the result of {@link ng.$sce#getTrusted
+ * $sce.getTrusted(context, value)} rather than to the value directly. Think of this function as
+ * a way to enforce the required security context in your data sink. Directives use {@link
+ * ng.$sce#parseAs $sce.parseAs} rather than `$parse` to watch attribute bindings, which performs
+ * the {@link ng.$sce#getTrusted $sce.getTrusted} behind the scenes on non-constant literals. Also,
+ * when binding without directives, AngularJS will understand the context of your bindings
+ * automatically.
+ *
+ * As an example, {@link ng.directive:ngBindHtml ngBindHtml} uses {@link
+ * ng.$sce#parseAsHtml $sce.parseAsHtml(binding expression)}. Here's the actual code (slightly
+ * simplified):
+ *
+ * ```
+ * var ngBindHtmlDirective = ['$sce', function($sce) {
+ * return function(scope, element, attr) {
+ * scope.$watch($sce.parseAsHtml(attr.ngBindHtml), function(value) {
+ * element.html(value || '');
+ * });
+ * };
+ * }];
+ * ```
+ *
+ * ## Impact on loading templates
+ *
+ * This applies both to the {@link ng.directive:ngInclude `ng-include`} directive as well as
+ * `templateUrl`'s specified by {@link guide/directive directives}.
+ *
+ * By default, Angular only loads templates from the same domain and protocol as the application
+ * document. This is done by calling {@link ng.$sce#getTrustedResourceUrl
+ * $sce.getTrustedResourceUrl} on the template URL. To load templates from other domains and/or
+ * protocols, you may either {@link ng.$sceDelegateProvider#resourceUrlWhitelist whitelist
+ * them} or {@link ng.$sce#trustAsResourceUrl wrap it} into a trusted value.
+ *
+ * *Please note*:
+ * The browser's
+ * [Same Origin Policy](https://code.google.com/p/browsersec/wiki/Part2#Same-origin_policy_for_XMLHttpRequest)
+ * and [Cross-Origin Resource Sharing (CORS)](http://www.w3.org/TR/cors/)
+ * policy apply in addition to this and may further restrict whether the template is successfully
+ * loaded. This means that without the right CORS policy, loading templates from a different domain
+ * won't work on all browsers. Also, loading templates from `file://` URL does not work on some
+ * browsers.
+ *
+ * ## This feels like too much overhead
+ *
+ * It's important to remember that SCE only applies to interpolation expressions.
+ *
+ * If your expressions are constant literals, they're automatically trusted and you don't need to
+ * call `$sce.trustAs` on them (e.g.
+ * `
`) just works. The `$sceDelegate` will
+ * also use the `$sanitize` service if it is available when binding untrusted values to
+ * `$sce.HTML` context. AngularJS provides an implementation in `angular-sanitize.js`, and if you
+ * wish to use it, you will also need to depend on the {@link ngSanitize `ngSanitize`} module in
+ * your application.
+ *
+ * The included {@link ng.$sceDelegate $sceDelegate} comes with sane defaults to allow you to load
+ * templates in `ng-include` from your application's domain without having to even know about SCE.
+ * It blocks loading templates from other domains or loading templates over http from an https
+ * served document. You can change these by setting your own custom {@link
+ * ng.$sceDelegateProvider#resourceUrlWhitelist whitelists} and {@link
+ * ng.$sceDelegateProvider#resourceUrlBlacklist blacklists} for matching such URLs.
+ *
+ * This significantly reduces the overhead. It is far easier to pay the small overhead and have an
+ * application that's secure and can be audited to verify that with much more ease than bolting
+ * security onto an application later.
+ *
+ *
+ * ## What trusted context types are supported?
+ *
+ * | Context | Notes |
+ * |---------------------|----------------|
+ * | `$sce.HTML` | For HTML that's safe to source into the application. The {@link ng.directive:ngBindHtml ngBindHtml} directive uses this context for bindings. If an unsafe value is encountered, and the {@link ngSanitize.$sanitize $sanitize} service is available (implemented by the {@link ngSanitize ngSanitize} module) this will sanitize the value instead of throwing an error. |
+ * | `$sce.CSS` | For CSS that's safe to source into the application. Currently, no bindings require this context. Feel free to use it in your own directives. |
+ * | `$sce.URL` | For URLs that are safe to follow as links. Currently unused (` Note that `$sce.RESOURCE_URL` makes a stronger statement about the URL than `$sce.URL` does (it's not just the URL that matters, but also what is at the end of it), and therefore contexts requiring values trusted for `$sce.RESOURCE_URL` can be used anywhere that values trusted for `$sce.URL` are required. |
+ * | `$sce.JS` | For JavaScript that is safe to execute in your application's context. Currently, no bindings require this context. Feel free to use it in your own directives. |
+ *
+ *
+ * Be aware that `a[href]` and `img[src]` automatically sanitize their URLs and do not pass them
+ * through {@link ng.$sce#getTrusted $sce.getTrusted}. There's no CSS-, URL-, or JS-context bindings
+ * in AngularJS currently, so their corresponding `$sce.trustAs` functions aren't useful yet. This
+ * might evolve.
+ *
+ * ## Format of items in {@link ng.$sceDelegateProvider#resourceUrlWhitelist resourceUrlWhitelist}/{@link ng.$sceDelegateProvider#resourceUrlBlacklist Blacklist}
+ *
+ * Each element in these arrays must be one of the following:
+ *
+ * - **'self'**
+ * - The special **string**, `'self'`, can be used to match against all URLs of the **same
+ * domain** as the application document using the **same protocol**.
+ * - **String** (except the special value `'self'`)
+ * - The string is matched against the full *normalized / absolute URL* of the resource
+ * being tested (substring matches are not good enough.)
+ * - There are exactly **two wildcard sequences** - `*` and `**`. All other characters
+ * match themselves.
+ * - `*`: matches zero or more occurrences of any character other than one of the following 6
+ * characters: '`:`', '`/`', '`.`', '`?`', '`&`' and '`;`'. It's a useful wildcard for use
+ * in a whitelist.
+ * - `**`: matches zero or more occurrences of *any* character. As such, it's not
+ * appropriate for use in a scheme, domain, etc. as it would match too much. (e.g.
+ * http://**.example.com/ would match http://evil.com/?ignore=.example.com/ and that might
+ * not have been the intention.) Its usage at the very end of the path is ok. (e.g.
+ * http://foo.example.com/templates/**).
+ * - **RegExp** (*see caveat below*)
+ * - *Caveat*: While regular expressions are powerful and offer great flexibility, their syntax
+ * (and all the inevitable escaping) makes them *harder to maintain*. It's easy to
+ * accidentally introduce a bug when one updates a complex expression (imho, all regexes should
+ * have good test coverage). For instance, the use of `.` in the regex is correct only in a
+ * small number of cases. A `.` character in the regex used when matching the scheme or a
+ * subdomain could be matched against a `:` or literal `.` that was likely not intended. It
+ * is highly recommended to use the string patterns and only fall back to regular expressions
+ * as a last resort.
+ * - The regular expression must be an instance of RegExp (i.e. not a string.) It is
+ * matched against the **entire** *normalized / absolute URL* of the resource being tested
+ * (even when the RegExp did not have the `^` and `$` codes.) In addition, any flags
+ * present on the RegExp (such as multiline, global, ignoreCase) are ignored.
+ * - If you are generating your JavaScript from some other templating engine (not
+ * recommended, e.g. in issue [#4006](https://github.com/angular/angular.js/issues/4006)),
+ * remember to escape your regular expression (and be aware that you might need more than
+ * one level of escaping depending on your templating engine and the way you interpolated
+ * the value.) Do make use of your platform's escaping mechanism as it might be good
+ * enough before coding your own. E.g. Ruby has
+ * [Regexp.escape(str)](http://www.ruby-doc.org/core-2.0.0/Regexp.html#method-c-escape)
+ * and Python has [re.escape](http://docs.python.org/library/re.html#re.escape).
+ * Javascript lacks a similar built in function for escaping. Take a look at Google
+ * Closure library's [goog.string.regExpEscape(s)](
+ * http://docs.closure-library.googlecode.com/git/closure_goog_string_string.js.source.html#line962).
+ *
+ * Refer {@link ng.$sceDelegateProvider $sceDelegateProvider} for an example.
+ *
+ * ## Show me an example using SCE.
+ *
+ *
+ *
+ *
+ *
+ *
User comments
+ * By default, HTML that isn't explicitly trusted (e.g. Alice's comment) is sanitized when
+ * $sanitize is available. If $sanitize isn't available, this results in an error instead of an
+ * exploit.
+ *
+ *
+ * {{userComment.name}} :
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ * angular.module('mySceApp', ['ngSanitize'])
+ * .controller('AppController', ['$http', '$templateCache', '$sce',
+ * function AppController($http, $templateCache, $sce) {
+ * var self = this;
+ * $http.get('test_data.json', {cache: $templateCache}).then(function(response) {
+ * self.userComments = response.data;
+ * });
+ * self.explicitlyTrustedHtml = $sce.trustAsHtml(
+ * 'Hover over this text. ');
+ * }]);
+ *
+ *
+ *
+ * [
+ * { "name": "Alice",
+ * "htmlComment":
+ * "Is anyone reading this? "
+ * },
+ * { "name": "Bob",
+ * "htmlComment": "Yes! Am I the only other one?"
+ * }
+ * ]
+ *
+ *
+ *
+ * describe('SCE doc demo', function() {
+ * it('should sanitize untrusted values', function() {
+ * expect(element.all(by.css('.htmlComment')).first().getAttribute('innerHTML'))
+ * .toBe('Is anyone reading this? ');
+ * });
+ *
+ * it('should NOT sanitize explicitly trusted values', function() {
+ * expect(element(by.id('explicitlyTrustedHtml')).getAttribute('innerHTML')).toBe(
+ * 'Hover over this text. ');
+ * });
+ * });
+ *
+ *
+ *
+ *
+ *
+ * ## Can I disable SCE completely?
+ *
+ * Yes, you can. However, this is strongly discouraged. SCE gives you a lot of security benefits
+ * for little coding overhead. It will be much harder to take an SCE disabled application and
+ * either secure it on your own or enable SCE at a later stage. It might make sense to disable SCE
+ * for cases where you have a lot of existing code that was written before SCE was introduced and
+ * you're migrating them a module at a time. Also do note that this is an app-wide setting, so if
+ * you are writing a library, you will cause security bugs applications using it.
+ *
+ * That said, here's how you can completely disable SCE:
+ *
+ * ```
+ * angular.module('myAppWithSceDisabledmyApp', []).config(function($sceProvider) {
+ * // Completely disable SCE. For demonstration purposes only!
+ * // Do not use in new projects or libraries.
+ * $sceProvider.enabled(false);
+ * });
+ * ```
+ *
+ */
- lazyRecurse: function(ast, intoId, nameId, recursionFn, create, skipWatchIdCheck) {
- var self = this;
- return function() {
- self.recurse(ast, intoId, nameId, recursionFn, create, skipWatchIdCheck);
- };
- },
+ function $SceProvider() {
+ var enabled = true;
- lazyAssign: function(id, value) {
- var self = this;
- return function() {
- self.assign(id, value);
+ /**
+ * @ngdoc method
+ * @name $sceProvider#enabled
+ * @kind function
+ *
+ * @param {boolean=} value If provided, then enables/disables SCE application-wide.
+ * @return {boolean} True if SCE is enabled, false otherwise.
+ *
+ * @description
+ * Enables/disables SCE and returns the current value.
+ */
+ this.enabled = function (value) {
+ if (arguments.length) {
+ enabled = !!value;
+ }
+ return enabled;
};
- },
-
- stringEscapeRegex: /[^ a-zA-Z0-9]/g,
-
- stringEscapeFn: function(c) {
- return '\\u' + ('0000' + c.charCodeAt(0).toString(16)).slice(-4);
- },
-
- escape: function(value) {
- if (isString(value)) return '\'' + value.replace(this.stringEscapeRegex, this.stringEscapeFn) + '\'';
- if (isNumber(value)) return value.toString();
- if (value === true) return 'true';
- if (value === false) return 'false';
- if (value === null) return 'null';
- if (typeof value === 'undefined') return 'undefined';
-
- throw $parseMinErr('esc', 'IMPOSSIBLE');
- },
- nextId: function(skip, init) {
- var id = 'v' + (this.state.nextId++);
- if (!skip) {
- this.current().vars.push(id + (init ? '=' + init : ''));
- }
- return id;
- },
-
- current: function() {
- return this.state[this.state.computing];
- }
-};
+ /* Design notes on the default implementation for SCE.
+ *
+ * The API contract for the SCE delegate
+ * -------------------------------------
+ * The SCE delegate object must provide the following 3 methods:
+ *
+ * - trustAs(contextEnum, value)
+ * This method is used to tell the SCE service that the provided value is OK to use in the
+ * contexts specified by contextEnum. It must return an object that will be accepted by
+ * getTrusted() for a compatible contextEnum and return this value.
+ *
+ * - valueOf(value)
+ * For values that were not produced by trustAs(), return them as is. For values that were
+ * produced by trustAs(), return the corresponding input value to trustAs. Basically, if
+ * trustAs is wrapping the given values into some type, this operation unwraps it when given
+ * such a value.
+ *
+ * - getTrusted(contextEnum, value)
+ * This function should return the a value that is safe to use in the context specified by
+ * contextEnum or throw and exception otherwise.
+ *
+ * NOTE: This contract deliberately does NOT state that values returned by trustAs() must be
+ * opaque or wrapped in some holder object. That happens to be an implementation detail. For
+ * instance, an implementation could maintain a registry of all trusted objects by context. In
+ * such a case, trustAs() would return the same object that was passed in. getTrusted() would
+ * return the same object passed in if it was found in the registry under a compatible context or
+ * throw an exception otherwise. An implementation might only wrap values some of the time based
+ * on some criteria. getTrusted() might return a value and not throw an exception for special
+ * constants or objects even if not wrapped. All such implementations fulfill this contract.
+ *
+ *
+ * A note on the inheritance model for SCE contexts
+ * ------------------------------------------------
+ * I've used inheritance and made RESOURCE_URL wrapped types a subtype of URL wrapped types. This
+ * is purely an implementation details.
+ *
+ * The contract is simply this:
+ *
+ * getTrusted($sce.RESOURCE_URL, value) succeeding implies that getTrusted($sce.URL, value)
+ * will also succeed.
+ *
+ * Inheritance happens to capture this in a natural way. In some future, we may not use
+ * inheritance anymore. That is OK because no code outside of sce.js and sceSpecs.js would need to
+ * be aware of this detail.
+ */
+ this.$get = ['$parse', '$sceDelegate', function ($parse, $sceDelegate) {
+ // Support: IE 9-11 only
+ // Prereq: Ensure that we're not running in IE<11 quirks mode. In that mode, IE < 11 allow
+ // the "expression(javascript expression)" syntax which is insecure.
+ if (enabled && msie < 8) {
+ throw $sceMinErr('iequirks', 'Strict Contextual Escaping does not support Internet Explorer version < 11 in quirks ' + 'mode. You can fix this by adding the text to the top of your HTML ' + 'document. See http://docs.angularjs.org/api/ng.$sce for more information.');
+ }
-function ASTInterpreter($filter) {
- this.$filter = $filter;
-}
+ var sce = shallowCopy(SCE_CONTEXTS);
-ASTInterpreter.prototype = {
- compile: function(ast) {
- var self = this;
- findConstantAndWatchExpressions(ast, self.$filter);
- var assignable;
- var assign;
- if ((assignable = assignableAST(ast))) {
- assign = this.recurse(assignable);
- }
- var toWatch = getInputs(ast.body);
- var inputs;
- if (toWatch) {
- inputs = [];
- forEach(toWatch, function(watch, key) {
- var input = self.recurse(watch);
- watch.input = input;
- inputs.push(input);
- watch.watchId = key;
- });
- }
- var expressions = [];
- forEach(ast.body, function(expression) {
- expressions.push(self.recurse(expression.expression));
- });
- var fn = ast.body.length === 0 ? noop :
- ast.body.length === 1 ? expressions[0] :
- function(scope, locals) {
- var lastValue;
- forEach(expressions, function(exp) {
- lastValue = exp(scope, locals);
- });
- return lastValue;
- };
- if (assign) {
- fn.assign = function(scope, value, locals) {
- return assign(scope, locals, value);
+ /**
+ * @ngdoc method
+ * @name $sce#isEnabled
+ * @kind function
+ *
+ * @return {Boolean} True if SCE is enabled, false otherwise. If you want to set the value, you
+ * have to do it at module config time on {@link ng.$sceProvider $sceProvider}.
+ *
+ * @description
+ * Returns a boolean indicating if SCE is enabled.
+ */
+ sce.isEnabled = function () {
+ return enabled;
};
- }
- if (inputs) {
- fn.inputs = inputs;
- }
- return fn;
- },
+ sce.trustAs = $sceDelegate.trustAs;
+ sce.getTrusted = $sceDelegate.getTrusted;
+ sce.valueOf = $sceDelegate.valueOf;
- recurse: function(ast, context, create) {
- var left, right, self = this, args;
- if (ast.input) {
- return this.inputs(ast.input, ast.watchId);
- }
- switch (ast.type) {
- case AST.Literal:
- return this.value(ast.value, context);
- case AST.UnaryExpression:
- right = this.recurse(ast.argument);
- return this['unary' + ast.operator](right, context);
- case AST.BinaryExpression:
- left = this.recurse(ast.left);
- right = this.recurse(ast.right);
- return this['binary' + ast.operator](left, right, context);
- case AST.LogicalExpression:
- left = this.recurse(ast.left);
- right = this.recurse(ast.right);
- return this['binary' + ast.operator](left, right, context);
- case AST.ConditionalExpression:
- return this['ternary?:'](
- this.recurse(ast.test),
- this.recurse(ast.alternate),
- this.recurse(ast.consequent),
- context
- );
- case AST.Identifier:
- return self.identifier(ast.name, context, create);
- case AST.MemberExpression:
- left = this.recurse(ast.object, false, !!create);
- if (!ast.computed) {
- right = ast.property.name;
- }
- if (ast.computed) right = this.recurse(ast.property);
- return ast.computed ?
- this.computedMember(left, right, context, create) :
- this.nonComputedMember(left, right, context, create);
- case AST.CallExpression:
- args = [];
- forEach(ast.arguments, function(expr) {
- args.push(self.recurse(expr));
- });
- if (ast.filter) right = this.$filter(ast.callee.name);
- if (!ast.filter) right = this.recurse(ast.callee, true);
- return ast.filter ?
- function(scope, locals, assign, inputs) {
- var values = [];
- for (var i = 0; i < args.length; ++i) {
- values.push(args[i](scope, locals, assign, inputs));
- }
- var value = right.apply(undefined, values, inputs);
- return context ? {context: undefined, name: undefined, value: value} : value;
- } :
- function(scope, locals, assign, inputs) {
- var rhs = right(scope, locals, assign, inputs);
- var value;
- if (rhs.value != null) {
- var values = [];
- for (var i = 0; i < args.length; ++i) {
- values.push(args[i](scope, locals, assign, inputs));
- }
- value = rhs.value.apply(rhs.context, values);
- }
- return context ? {value: value} : value;
+ if (!enabled) {
+ sce.trustAs = sce.getTrusted = function (type, value) {
+ return value;
};
- case AST.AssignmentExpression:
- left = this.recurse(ast.left, true, 1);
- right = this.recurse(ast.right);
- return function(scope, locals, assign, inputs) {
- var lhs = left(scope, locals, assign, inputs);
- var rhs = right(scope, locals, assign, inputs);
- lhs.context[lhs.name] = rhs;
- return context ? {value: rhs} : rhs;
- };
- case AST.ArrayExpression:
- args = [];
- forEach(ast.elements, function(expr) {
- args.push(self.recurse(expr));
- });
- return function(scope, locals, assign, inputs) {
- var value = [];
- for (var i = 0; i < args.length; ++i) {
- value.push(args[i](scope, locals, assign, inputs));
- }
- return context ? {value: value} : value;
- };
- case AST.ObjectExpression:
- args = [];
- forEach(ast.properties, function(property) {
- if (property.computed) {
- args.push({key: self.recurse(property.key),
- computed: true,
- value: self.recurse(property.value)
- });
+ sce.valueOf = identity;
+ }
+
+ /**
+ * @ngdoc method
+ * @name $sce#parseAs
+ *
+ * @description
+ * 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*)}
+ *
+ * @param {string} type The SCE context in which this result will be used.
+ * @param {string} expression String expression to compile.
+ * @return {function(context, locals)} A function which represents the compiled expression:
+ *
+ * * `context` – `{object}` – an object against which any expressions embedded in the
+ * strings are evaluated against (typically a scope object).
+ * * `locals` – `{object=}` – local variables context object, useful for overriding values
+ * in `context`.
+ */
+ sce.parseAs = function sceParseAs(type, expr) {
+ var parsed = $parse(expr);
+ if (parsed.literal && parsed.constant) {
+ return parsed;
} else {
- args.push({key: property.key.type === AST.Identifier ?
- property.key.name :
- ('' + property.key.value),
- computed: false,
- value: self.recurse(property.value)
+ return $parse(expr, function (value) {
+ return sce.getTrusted(type, value);
});
}
- });
- return function(scope, locals, assign, inputs) {
- var value = {};
- for (var i = 0; i < args.length; ++i) {
- if (args[i].computed) {
- value[args[i].key(scope, locals, assign, inputs)] = args[i].value(scope, locals, assign, inputs);
- } else {
- value[args[i].key] = args[i].value(scope, locals, assign, inputs);
- }
- }
- return context ? {value: value} : value;
- };
- case AST.ThisExpression:
- return function(scope) {
- return context ? {value: scope} : scope;
};
- case AST.LocalsExpression:
- return function(scope, locals) {
- return context ? {value: locals} : locals;
- };
- case AST.NGValueParameter:
- return function(scope, locals, assign) {
- return context ? {value: assign} : assign;
- };
- }
- },
- 'unary+': function(argument, context) {
- return function(scope, locals, assign, inputs) {
- var arg = argument(scope, locals, assign, inputs);
- if (isDefined(arg)) {
- arg = +arg;
- } else {
- arg = 0;
- }
- return context ? {value: arg} : arg;
- };
- },
- 'unary-': function(argument, context) {
- return function(scope, locals, assign, inputs) {
- var arg = argument(scope, locals, assign, inputs);
- if (isDefined(arg)) {
- arg = -arg;
- } else {
- arg = -0;
- }
- return context ? {value: arg} : arg;
- };
- },
- 'unary!': function(argument, context) {
- return function(scope, locals, assign, inputs) {
- var arg = !argument(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary+': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- var lhs = left(scope, locals, assign, inputs);
- var rhs = right(scope, locals, assign, inputs);
- var arg = plusFn(lhs, rhs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary-': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- var lhs = left(scope, locals, assign, inputs);
- var rhs = right(scope, locals, assign, inputs);
- var arg = (isDefined(lhs) ? lhs : 0) - (isDefined(rhs) ? rhs : 0);
- return context ? {value: arg} : arg;
- };
- },
- 'binary*': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- var arg = left(scope, locals, assign, inputs) * right(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary/': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- var arg = left(scope, locals, assign, inputs) / right(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary%': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- var arg = left(scope, locals, assign, inputs) % right(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary===': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- var arg = left(scope, locals, assign, inputs) === right(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary!==': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- var arg = left(scope, locals, assign, inputs) !== right(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary==': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- // eslint-disable-next-line eqeqeq
- var arg = left(scope, locals, assign, inputs) == right(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary!=': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- // eslint-disable-next-line eqeqeq
- var arg = left(scope, locals, assign, inputs) != right(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary<': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- var arg = left(scope, locals, assign, inputs) < right(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary>': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- var arg = left(scope, locals, assign, inputs) > right(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary<=': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- var arg = left(scope, locals, assign, inputs) <= right(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary>=': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- var arg = left(scope, locals, assign, inputs) >= right(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary&&': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- var arg = left(scope, locals, assign, inputs) && right(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'binary||': function(left, right, context) {
- return function(scope, locals, assign, inputs) {
- var arg = left(scope, locals, assign, inputs) || right(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- 'ternary?:': function(test, alternate, consequent, context) {
- return function(scope, locals, assign, inputs) {
- var arg = test(scope, locals, assign, inputs) ? alternate(scope, locals, assign, inputs) : consequent(scope, locals, assign, inputs);
- return context ? {value: arg} : arg;
- };
- },
- value: function(value, context) {
- return function() { return context ? {context: undefined, name: undefined, value: value} : value; };
- },
- identifier: function(name, context, create) {
- return function(scope, locals, assign, inputs) {
- var base = locals && (name in locals) ? locals : scope;
- if (create && create !== 1 && base && base[name] == null) {
- base[name] = {};
- }
- var value = base ? base[name] : undefined;
- if (context) {
- return {context: base, name: name, value: value};
- } else {
- return value;
- }
- };
- },
- computedMember: function(left, right, context, create) {
- return function(scope, locals, assign, inputs) {
- var lhs = left(scope, locals, assign, inputs);
- var rhs;
- var value;
- if (lhs != null) {
- rhs = right(scope, locals, assign, inputs);
- rhs = getStringValue(rhs);
- if (create && create !== 1) {
- if (lhs && !(lhs[rhs])) {
- lhs[rhs] = {};
- }
- }
- value = lhs[rhs];
- }
- if (context) {
- return {context: lhs, name: rhs, value: value};
- } else {
- return value;
- }
- };
- },
- nonComputedMember: function(left, right, context, create) {
- return function(scope, locals, assign, inputs) {
- var lhs = left(scope, locals, assign, inputs);
- if (create && create !== 1) {
- if (lhs && lhs[right] == null) {
- lhs[right] = {};
- }
- }
- var value = lhs != null ? lhs[right] : undefined;
- if (context) {
- return {context: lhs, name: right, value: value};
- } else {
- return value;
- }
- };
- },
- inputs: function(input, watchId) {
- return function(scope, value, locals, inputs) {
- if (inputs) return inputs[watchId];
- return input(scope, value, locals);
- };
- }
-};
+ /**
+ * @ngdoc method
+ * @name $sce#trustAs
+ *
+ * @description
+ * Delegates to {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}. As such, returns a
+ * wrapped object that represents your value, and the trust you have in its safety for the given
+ * context. AngularJS can then use that value as-is in bindings of the specified secure context.
+ * This is used in bindings for `ng-bind-html`, `ng-include`, and most `src` attribute
+ * interpolations. See {@link ng.$sce $sce} for strict contextual escaping.
+ *
+ * @param {string} type The context in which this value is safe for use, e.g. `$sce.URL`,
+ * `$sce.RESOURCE_URL`, `$sce.HTML`, `$sce.JS` or `$sce.CSS`.
+ *
+ * @param {*} value The value that that should be considered trusted.
+ * @return {*} A wrapped version of value that can be used as a trusted variant of your `value`
+ * in the context you specified.
+ */
-/**
- * @constructor
- */
-function Parser(lexer, $filter, options) {
- this.ast = new AST(lexer, options);
- this.astCompiler = options.csp ? new ASTInterpreter($filter) :
- new ASTCompiler($filter);
-}
+ /**
+ * @ngdoc method
+ * @name $sce#trustAsHtml
+ *
+ * @description
+ * Shorthand method. `$sce.trustAsHtml(value)` →
+ * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.HTML, value)`}
+ *
+ * @param {*} value The value to mark as trusted for `$sce.HTML` context.
+ * @return {*} A wrapped version of value that can be used as a trusted variant of your `value`
+ * in `$sce.HTML` context (like `ng-bind-html`).
+ */
-Parser.prototype = {
- constructor: Parser,
+ /**
+ * @ngdoc method
+ * @name $sce#trustAsCss
+ *
+ * @description
+ * Shorthand method. `$sce.trustAsCss(value)` →
+ * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.CSS, value)`}
+ *
+ * @param {*} value The value to mark as trusted for `$sce.CSS` context.
+ * @return {*} A wrapped version of value that can be used as a trusted variant
+ * of your `value` in `$sce.CSS` context. This context is currently unused, so there are
+ * almost no reasons to use this function so far.
+ */
- parse: function(text) {
- var ast = this.ast.ast(text);
- var fn = this.astCompiler.compile(ast);
- fn.literal = isLiteral(ast);
- fn.constant = isConstant(ast);
- return fn;
- }
-};
+ /**
+ * @ngdoc method
+ * @name $sce#trustAsUrl
+ *
+ * @description
+ * Shorthand method. `$sce.trustAsUrl(value)` →
+ * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.URL, value)`}
+ *
+ * @param {*} value The value to mark as trusted for `$sce.URL` context.
+ * @return {*} A wrapped version of value that can be used as a trusted variant of your `value`
+ * in `$sce.URL` context. That context is currently unused, so there are almost no reasons
+ * to use this function so far.
+ */
-function getValueOf(value) {
- return isFunction(value.valueOf) ? value.valueOf() : objectValueOf.call(value);
-}
+ /**
+ * @ngdoc method
+ * @name $sce#trustAsResourceUrl
+ *
+ * @description
+ * Shorthand method. `$sce.trustAsResourceUrl(value)` →
+ * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.RESOURCE_URL, value)`}
+ *
+ * @param {*} value The value to mark as trusted for `$sce.RESOURCE_URL` context.
+ * @return {*} A wrapped version of value that can be used as a trusted variant of your `value`
+ * in `$sce.RESOURCE_URL` context (template URLs in `ng-include`, most `src` attribute
+ * bindings, ...)
+ */
-///////////////////////////////////
+ /**
+ * @ngdoc method
+ * @name $sce#trustAsJs
+ *
+ * @description
+ * Shorthand method. `$sce.trustAsJs(value)` →
+ * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.JS, value)`}
+ *
+ * @param {*} value The value to mark as trusted for `$sce.JS` context.
+ * @return {*} A wrapped version of value that can be used as a trusted variant of your `value`
+ * in `$sce.JS` context. That context is currently unused, so there are almost no reasons to
+ * use this function so far.
+ */
-/**
- * @ngdoc service
- * @name $parse
- * @kind function
- *
- * @description
- *
- * 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');
- * ```
- *
- *
- * @param {string} expression String expression to compile.
- * @returns {function(context, locals)} a function which represents the compiled expression:
- *
- * * `context` – `{object}` – an object against which any expressions embedded in the strings
- * are evaluated against (typically a scope object).
- * * `locals` – `{object=}` – local variables context object, useful for overriding values in
- * `context`.
- *
- * The returned function also has the following properties:
- * * `literal` – `{boolean}` – whether the expression's top-level node is a JavaScript
- * literal.
- * * `constant` – `{boolean}` – whether the expression is made entirely of JavaScript
- * constant literals.
- * * `assign` – `{?function(context, value)}` – if the expression is assignable, this will be
- * set to a function to change its value on the given context.
- *
- */
+ /**
+ * @ngdoc method
+ * @name $sce#getTrusted
+ *
+ * @description
+ * Delegates to {@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted`}. As such,
+ * takes any input, and either returns a value that's safe to use in the specified context,
+ * or throws an exception. This function is aware of trusted values created by the `trustAs`
+ * function and its shorthands, and when contexts are appropriate, returns the unwrapped value
+ * as-is. Finally, this function can also throw when there is no way to turn `maybeTrusted` in a
+ * safe value (e.g., no sanitization is available or possible.)
+ *
+ * @param {string} type The context in which this value is to be used.
+ * @param {*} maybeTrusted The result of a prior {@link ng.$sce#trustAs
+ * `$sce.trustAs`} call, or anything else (which will not be considered trusted.)
+ * @return {*} A version of the value that's safe to use in the given context, or throws an
+ * exception if this is impossible.
+ */
+ /**
+ * @ngdoc method
+ * @name $sce#getTrustedHtml
+ *
+ * @description
+ * Shorthand method. `$sce.getTrustedHtml(value)` →
+ * {@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.HTML, value)`}
+ *
+ * @param {*} value The value to pass to `$sce.getTrusted`.
+ * @return {*} The return value of `$sce.getTrusted($sce.HTML, value)`
+ */
-/**
- * @ngdoc provider
- * @name $parseProvider
- * @this
- *
- * @description
- * `$parseProvider` can be used for configuring the default behavior of the {@link ng.$parse $parse}
- * service.
- */
-function $ParseProvider() {
- var cache = createMap();
- var literals = {
- 'true': true,
- 'false': false,
- 'null': null,
- 'undefined': undefined
- };
- var identStart, identContinue;
+ /**
+ * @ngdoc method
+ * @name $sce#getTrustedCss
+ *
+ * @description
+ * Shorthand method. `$sce.getTrustedCss(value)` →
+ * {@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.CSS, value)`}
+ *
+ * @param {*} value The value to pass to `$sce.getTrusted`.
+ * @return {*} The return value of `$sce.getTrusted($sce.CSS, value)`
+ */
- /**
- * @ngdoc method
- * @name $parseProvider#addLiteral
- * @description
- *
- * Configure $parse service to add literal values that will be present as literal at expressions.
- *
- * @param {string} literalName Token for the literal value. The literal name value must be a valid literal name.
- * @param {*} literalValue Value for this literal. All literal values must be primitives or `undefined`.
- *
- **/
- this.addLiteral = function(literalName, literalValue) {
- literals[literalName] = literalValue;
- };
+ /**
+ * @ngdoc method
+ * @name $sce#getTrustedUrl
+ *
+ * @description
+ * Shorthand method. `$sce.getTrustedUrl(value)` →
+ * {@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.URL, value)`}
+ *
+ * @param {*} value The value to pass to `$sce.getTrusted`.
+ * @return {*} The return value of `$sce.getTrusted($sce.URL, value)`
+ */
- /**
- * @ngdoc method
- * @name $parseProvider#setIdentifierFns
- *
- * @description
- *
- * Allows defining the set of characters that are allowed in Angular expressions. The function
- * `identifierStart` will get called to know if a given character is a valid character to be the
- * first character for an identifier. The function `identifierContinue` will get called to know if
- * a given character is a valid character to be a follow-up identifier character. The functions
- * `identifierStart` and `identifierContinue` will receive as arguments the single character to be
- * identifier and the character code point. These arguments will be `string` and `numeric`. Keep in
- * mind that the `string` parameter can be two characters long depending on the character
- * representation. It is expected for the function to return `true` or `false`, whether that
- * character is allowed or not.
- *
- * Since this function will be called extensively, keep the implementation of these functions fast,
- * as the performance of these functions have a direct impact on the expressions parsing speed.
- *
- * @param {function=} identifierStart The function that will decide whether the given character is
- * a valid identifier start character.
- * @param {function=} identifierContinue The function that will decide whether the given character is
- * a valid identifier continue character.
- */
- this.setIdentifierFns = function(identifierStart, identifierContinue) {
- identStart = identifierStart;
- identContinue = identifierContinue;
- return this;
- };
+ /**
+ * @ngdoc method
+ * @name $sce#getTrustedResourceUrl
+ *
+ * @description
+ * Shorthand method. `$sce.getTrustedResourceUrl(value)` →
+ * {@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.RESOURCE_URL, value)`}
+ *
+ * @param {*} value The value to pass to `$sceDelegate.getTrusted`.
+ * @return {*} The return value of `$sce.getTrusted($sce.RESOURCE_URL, value)`
+ */
- this.$get = ['$filter', function($filter) {
- var noUnsafeEval = csp().noUnsafeEval;
- var $parseOptions = {
- csp: noUnsafeEval,
- literals: copy(literals),
- isIdentifierStart: isFunction(identStart) && identStart,
- isIdentifierContinue: isFunction(identContinue) && identContinue
- };
- return $parse;
+ /**
+ * @ngdoc method
+ * @name $sce#getTrustedJs
+ *
+ * @description
+ * Shorthand method. `$sce.getTrustedJs(value)` →
+ * {@link ng.$sceDelegate#getTrusted `$sceDelegate.getTrusted($sce.JS, value)`}
+ *
+ * @param {*} value The value to pass to `$sce.getTrusted`.
+ * @return {*} The return value of `$sce.getTrusted($sce.JS, value)`
+ */
- function $parse(exp, interceptorFn) {
- var parsedExpression, oneTime, cacheKey;
+ /**
+ * @ngdoc method
+ * @name $sce#parseAsHtml
+ *
+ * @description
+ * Shorthand method. `$sce.parseAsHtml(expression string)` →
+ * {@link ng.$sce#parseAs `$sce.parseAs($sce.HTML, value)`}
+ *
+ * @param {string} expression String expression to compile.
+ * @return {function(context, locals)} A function which represents the compiled expression:
+ *
+ * * `context` – `{object}` – an object against which any expressions embedded in the
+ * strings are evaluated against (typically a scope object).
+ * * `locals` – `{object=}` – local variables context object, useful for overriding values
+ * in `context`.
+ */
- switch (typeof exp) {
- case 'string':
- exp = exp.trim();
- cacheKey = exp;
+ /**
+ * @ngdoc method
+ * @name $sce#parseAsCss
+ *
+ * @description
+ * Shorthand method. `$sce.parseAsCss(value)` →
+ * {@link ng.$sce#parseAs `$sce.parseAs($sce.CSS, value)`}
+ *
+ * @param {string} expression String expression to compile.
+ * @return {function(context, locals)} A function which represents the compiled expression:
+ *
+ * * `context` – `{object}` – an object against which any expressions embedded in the
+ * strings are evaluated against (typically a scope object).
+ * * `locals` – `{object=}` – local variables context object, useful for overriding values
+ * in `context`.
+ */
- parsedExpression = cache[cacheKey];
+ /**
+ * @ngdoc method
+ * @name $sce#parseAsUrl
+ *
+ * @description
+ * Shorthand method. `$sce.parseAsUrl(value)` →
+ * {@link ng.$sce#parseAs `$sce.parseAs($sce.URL, value)`}
+ *
+ * @param {string} expression String expression to compile.
+ * @return {function(context, locals)} A function which represents the compiled expression:
+ *
+ * * `context` – `{object}` – an object against which any expressions embedded in the
+ * strings are evaluated against (typically a scope object).
+ * * `locals` – `{object=}` – local variables context object, useful for overriding values
+ * in `context`.
+ */
- if (!parsedExpression) {
- if (exp.charAt(0) === ':' && exp.charAt(1) === ':') {
- oneTime = true;
- exp = exp.substring(2);
- }
- var lexer = new Lexer($parseOptions);
- var parser = new Parser(lexer, $filter, $parseOptions);
- parsedExpression = parser.parse(exp);
- if (parsedExpression.constant) {
- parsedExpression.$$watchDelegate = constantWatchDelegate;
- } else if (oneTime) {
- parsedExpression.oneTime = true;
- parsedExpression.$$watchDelegate = oneTimeWatchDelegate;
- } else if (parsedExpression.inputs) {
- parsedExpression.$$watchDelegate = inputsWatchDelegate;
- }
- cache[cacheKey] = parsedExpression;
- }
- return addInterceptor(parsedExpression, interceptorFn);
+ /**
+ * @ngdoc method
+ * @name $sce#parseAsResourceUrl
+ *
+ * @description
+ * Shorthand method. `$sce.parseAsResourceUrl(value)` →
+ * {@link ng.$sce#parseAs `$sce.parseAs($sce.RESOURCE_URL, value)`}
+ *
+ * @param {string} expression String expression to compile.
+ * @return {function(context, locals)} A function which represents the compiled expression:
+ *
+ * * `context` – `{object}` – an object against which any expressions embedded in the
+ * strings are evaluated against (typically a scope object).
+ * * `locals` – `{object=}` – local variables context object, useful for overriding values
+ * in `context`.
+ */
- case 'function':
- return addInterceptor(exp, interceptorFn);
+ /**
+ * @ngdoc method
+ * @name $sce#parseAsJs
+ *
+ * @description
+ * Shorthand method. `$sce.parseAsJs(value)` →
+ * {@link ng.$sce#parseAs `$sce.parseAs($sce.JS, value)`}
+ *
+ * @param {string} expression String expression to compile.
+ * @return {function(context, locals)} A function which represents the compiled expression:
+ *
+ * * `context` – `{object}` – an object against which any expressions embedded in the
+ * strings are evaluated against (typically a scope object).
+ * * `locals` – `{object=}` – local variables context object, useful for overriding values
+ * in `context`.
+ */
- default:
- return addInterceptor(noop, interceptorFn);
- }
- }
+ // Shorthand delegations.
+ var parse = sce.parseAs,
+ getTrusted = sce.getTrusted,
+ trustAs = sce.trustAs;
- function expressionInputDirtyCheck(newValue, oldValueOfValue, compareObjectIdentity) {
+ forEach(SCE_CONTEXTS, function (enumValue, name) {
+ var lName = lowercase(name);
+ sce[snakeToCamel('parse_as_' + lName)] = function (expr) {
+ return parse(enumValue, expr);
+ };
+ sce[snakeToCamel('get_trusted_' + lName)] = function (value) {
+ return getTrusted(enumValue, value);
+ };
+ sce[snakeToCamel('trust_as_' + lName)] = function (value) {
+ return trustAs(enumValue, value);
+ };
+ });
- if (newValue == null || oldValueOfValue == null) { // null/undefined
- return newValue === oldValueOfValue;
- }
+ return sce;
+ }];
+ }
- if (typeof newValue === 'object') {
+ /* exported $SnifferProvider */
- // attempt to convert the value to a primitive type
- // TODO(docs): add a note to docs that by implementing valueOf even objects and arrays can
- // be cheaply dirty-checked
- newValue = getValueOf(newValue);
+ /**
+ * !!! This is an undocumented "private" service !!!
+ *
+ * @name $sniffer
+ * @requires $window
+ * @requires $document
+ * @this
+ *
+ * @property {boolean} history Does the browser support html5 history api ?
+ * @property {boolean} transitions Does the browser support CSS transition events ?
+ * @property {boolean} animations Does the browser support CSS animation events ?
+ *
+ * @description
+ * This is very simple implementation of testing browser's features.
+ */
+ function $SnifferProvider() {
+ this.$get = ['$window', '$document', function ($window, $document) {
+ var eventSupport = {},
+
+ // Chrome Packaged Apps are not allowed to access `history.pushState`.
+ // If not sandboxed, they can be detected by the presence of `chrome.app.runtime`
+ // (see https://developer.chrome.com/apps/api_index). If sandboxed, they can be detected by
+ // the presence of an extension runtime ID and the absence of other Chrome runtime APIs
+ // (see https://developer.chrome.com/apps/manifest/sandbox).
+ // (NW.js apps have access to Chrome APIs, but do support `history`.)
+ isNw = $window.nw && $window.nw.process,
+ isChromePackagedApp = !isNw && $window.chrome && ($window.chrome.app && $window.chrome.app.runtime || !$window.chrome.app && $window.chrome.runtime && $window.chrome.runtime.id),
+ hasHistoryPushState = !isChromePackagedApp && $window.history && $window.history.pushState,
+ android = toInt((/android (\d+)/.exec(lowercase(($window.navigator || {}).userAgent)) || [])[1]),
+ boxee = /Boxee/i.test(($window.navigator || {}).userAgent),
+ document = $document[0] || {},
+ bodyStyle = document.body && document.body.style,
+ transitions = false,
+ animations = false;
+
+ if (bodyStyle) {
+ // Support: Android <5, Blackberry Browser 10, default Chrome in Android 4.4.x
+ // Mentioned browsers need a -webkit- prefix for transitions & animations.
+ transitions = !!('transition' in bodyStyle || 'webkitTransition' in bodyStyle);
+ animations = !!('animation' in bodyStyle || 'webkitAnimation' in bodyStyle);
+ }
- if (typeof newValue === 'object' && !compareObjectIdentity) {
- // objects/arrays are not supported - deep-watching them would be too expensive
- return false;
- }
+ return {
+ // Android has history.pushState, but it does not update location correctly
+ // so let's not use the history API at all.
+ // http://code.google.com/p/android/issues/detail?id=17471
+ // https://github.com/angular/angular.js/issues/904
+
+ // older webkit browser (533.9) on Boxee box has exactly the same problem as Android has
+ // so let's not use the history API also
+ // We are purposefully using `!(android < 4)` to cover the case when `android` is undefined
+ history: !!(hasHistoryPushState && !(android < 4) && !boxee),
+ hasEvent: function hasEvent(event) {
+ // Support: IE 9-11 only
+ // IE9 implements 'input' event it's so fubared that we rather pretend that it doesn't have
+ // it. In particular the event is not fired when backspace or delete key are pressed or
+ // when cut operation is performed.
+ // IE10+ implements 'input' event but it erroneously fires under various situations,
+ // e.g. when placeholder changes, or a form is focused.
+ if (event === 'input' && msie) return false;
+
+ if (isUndefined(eventSupport[event])) {
+ var divElm = document.createElement('div');
+ eventSupport[event] = 'on' + event in divElm;
+ }
- // fall-through to the primitive equality check
- }
+ return eventSupport[event];
+ },
+ csp: csp(),
+ transitions: transitions,
+ animations: animations,
+ android: android
+ };
+ }];
+ }
- //Primitive or NaN
- // eslint-disable-next-line no-self-compare
- return newValue === oldValueOfValue || (newValue !== newValue && oldValueOfValue !== oldValueOfValue);
- }
+ var $templateRequestMinErr = minErr('$compile');
- function inputsWatchDelegate(scope, listener, objectEquality, parsedExpression, prettyPrintExpression) {
- var inputExpressions = parsedExpression.inputs;
- var lastResult;
+ /**
+ * @ngdoc provider
+ * @name $templateRequestProvider
+ * @this
+ *
+ * @description
+ * Used to configure the options passed to the {@link $http} service when making a template request.
+ *
+ * For example, it can be used for specifying the "Accept" header that is sent to the server, when
+ * requesting a template.
+ */
+ function $TemplateRequestProvider() {
- if (inputExpressions.length === 1) {
- var oldInputValueOf = expressionInputDirtyCheck; // init to something unique so that equals check fails
- inputExpressions = inputExpressions[0];
- return scope.$watch(function expressionInputWatch(scope) {
- var newInputValue = inputExpressions(scope);
- if (!expressionInputDirtyCheck(newInputValue, oldInputValueOf, parsedExpression.literal)) {
- lastResult = parsedExpression(scope, undefined, undefined, [newInputValue]);
- oldInputValueOf = newInputValue && getValueOf(newInputValue);
- }
- return lastResult;
- }, listener, objectEquality, prettyPrintExpression);
- }
+ var httpOptions;
- var oldInputValueOfValues = [];
- var oldInputValues = [];
- for (var i = 0, ii = inputExpressions.length; i < ii; i++) {
- oldInputValueOfValues[i] = expressionInputDirtyCheck; // init to something unique so that equals check fails
- oldInputValues[i] = null;
+ /**
+ * @ngdoc method
+ * @name $templateRequestProvider#httpOptions
+ * @description
+ * The options to be passed to the {@link $http} service when making the request.
+ * You can use this to override options such as the "Accept" header for template requests.
+ *
+ * The {@link $templateRequest} will set the `cache` and the `transformResponse` properties of the
+ * options if not overridden here.
+ *
+ * @param {string=} value new value for the {@link $http} options.
+ * @returns {string|self} Returns the {@link $http} options when used as getter and self if used as setter.
+ */
+ this.httpOptions = function (val) {
+ if (val) {
+ httpOptions = val;
+ return this;
}
+ return httpOptions;
+ };
- return scope.$watch(function expressionInputsWatch(scope) {
- var changed = false;
+ /**
+ * @ngdoc service
+ * @name $templateRequest
+ *
+ * @description
+ * 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.
+ *
+ * If you want to pass custom options to the `$http` service, such as setting the Accept header you
+ * can configure this via {@link $templateRequestProvider#httpOptions}.
+ *
+ * @param {string|TrustedResourceUrl} tpl The HTTP request template URL
+ * @param {boolean=} ignoreRequestError Whether or not to ignore the exception when the request fails or the template is empty
+ *
+ * @return {Promise} a promise for the HTTP response data of the given URL.
+ *
+ * @property {number} totalPendingRequests total amount of pending template requests being downloaded.
+ */
+ this.$get = ['$exceptionHandler', '$templateCache', '$http', '$q', '$sce', function ($exceptionHandler, $templateCache, $http, $q, $sce) {
- for (var i = 0, ii = inputExpressions.length; i < ii; i++) {
- var newInputValue = inputExpressions[i](scope);
- if (changed || (changed = !expressionInputDirtyCheck(newInputValue, oldInputValueOfValues[i], parsedExpression.literal))) {
- oldInputValues[i] = newInputValue;
- oldInputValueOfValues[i] = newInputValue && getValueOf(newInputValue);
- }
- }
+ function handleRequestFn(tpl, ignoreRequestError) {
+ handleRequestFn.totalPendingRequests++;
- if (changed) {
- lastResult = parsedExpression(scope, undefined, undefined, oldInputValues);
+ // We consider the template cache holds only trusted templates, so
+ // there's no need to go through whitelisting again for keys that already
+ // are included in there. This also makes Angular accept any script
+ // directive, no matter its name. However, we still need to unwrap trusted
+ // types.
+ if (!isString(tpl) || isUndefined($templateCache.get(tpl))) {
+ tpl = $sce.getTrustedResourceUrl(tpl);
}
- return lastResult;
- }, listener, objectEquality, prettyPrintExpression);
- }
-
- function oneTimeWatchDelegate(scope, listener, objectEquality, parsedExpression, prettyPrintExpression) {
- var isDone = parsedExpression.literal ? isAllDefined : isDefined;
- var unwatch, lastValue;
- if (parsedExpression.inputs) {
- unwatch = inputsWatchDelegate(scope, oneTimeListener, objectEquality, parsedExpression, prettyPrintExpression);
- } else {
- unwatch = scope.$watch(oneTimeWatch, oneTimeListener, objectEquality);
- }
- return unwatch;
+ var transformResponse = $http.defaults && $http.defaults.transformResponse;
- function oneTimeWatch(scope) {
- return parsedExpression(scope);
- }
- function oneTimeListener(value, old, scope) {
- lastValue = value;
- if (isFunction(listener)) {
- listener(value, old, scope);
- }
- if (isDone(value)) {
- scope.$$postDigest(function() {
- if (isDone(lastValue)) {
- unwatch();
- }
+ if (isArray(transformResponse)) {
+ transformResponse = transformResponse.filter(function (transformer) {
+ return transformer !== defaultHttpResponseTransform;
});
+ } else if (transformResponse === defaultHttpResponseTransform) {
+ transformResponse = null;
}
- }
- }
-
- function isAllDefined(value) {
- var allDefined = true;
- forEach(value, function(val) {
- if (!isDefined(val)) allDefined = false;
- });
- return allDefined;
- }
-
- function constantWatchDelegate(scope, listener, objectEquality, parsedExpression) {
- var unwatch = scope.$watch(function constantWatch(scope) {
- unwatch();
- return parsedExpression(scope);
- }, listener, objectEquality);
- return unwatch;
- }
- function addInterceptor(parsedExpression, interceptorFn) {
- if (!interceptorFn) return parsedExpression;
- var watchDelegate = parsedExpression.$$watchDelegate;
- var useInputs = false;
+ return $http.get(tpl, extend({
+ cache: $templateCache,
+ transformResponse: transformResponse
+ }, httpOptions)).finally(function () {
+ handleRequestFn.totalPendingRequests--;
+ }).then(function (response) {
+ $templateCache.put(tpl, response.data);
+ return response.data;
+ }, handleError);
- var isDone = parsedExpression.literal ? isAllDefined : isDefined;
+ function handleError(resp) {
+ if (!ignoreRequestError) {
+ resp = $templateRequestMinErr('tpload', 'Failed to load template: {0} (HTTP status: {1} {2})', tpl, resp.status, resp.statusText);
- function regularInterceptedExpression(scope, locals, assign, inputs) {
- var value = useInputs && inputs ? inputs[0] : parsedExpression(scope, locals, assign, inputs);
- return interceptorFn(value, scope, locals);
- }
+ $exceptionHandler(resp);
+ }
- function oneTimeInterceptedExpression(scope, locals, assign, inputs) {
- var value = useInputs && inputs ? inputs[0] : parsedExpression(scope, locals, assign, inputs);
- var result = interceptorFn(value, scope, locals);
- // we only return the interceptor's result if the
- // initial value is defined (for bind-once)
- return isDone(value) ? result : value;
+ return $q.reject(resp);
+ }
}
- var fn = parsedExpression.oneTime ? oneTimeInterceptedExpression : regularInterceptedExpression;
-
- // Propogate the literal/oneTime attributes
- fn.literal = parsedExpression.literal;
- fn.oneTime = parsedExpression.oneTime;
+ handleRequestFn.totalPendingRequests = 0;
- // Propagate or create inputs / $$watchDelegates
- useInputs = !parsedExpression.inputs;
- if (watchDelegate && watchDelegate !== inputsWatchDelegate) {
- fn.$$watchDelegate = watchDelegate;
- fn.inputs = parsedExpression.inputs;
- } else if (!interceptorFn.$stateful) {
- // If there is an interceptor, but no watchDelegate then treat the interceptor like
- // we treat filters - it is assumed to be a pure function unless flagged with $stateful
- fn.$$watchDelegate = inputsWatchDelegate;
- fn.inputs = parsedExpression.inputs ? parsedExpression.inputs : [parsedExpression];
- }
+ return handleRequestFn;
+ }];
+ }
- return fn;
- }
- }];
-}
+ /** @this */
+ function $$TestabilityProvider() {
+ this.$get = ['$rootScope', '$browser', '$location', function ($rootScope, $browser, $location) {
-/**
- * @ngdoc service
- * @name $q
- * @requires $rootScope
- *
- * @description
- * A service that helps you run functions asynchronously, and use their return values (or exceptions)
- * when they are done processing.
- *
- * This is a [Promises/A+](https://promisesaplus.com/)-compliant 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 (ES2015) 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,
- * 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 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 behavior, 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. The errorCallback and notifyCallback
- * arguments are optional.
- *
- * - `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);
- * }));
- * ```
- *
- * @param {function(function, function)} resolver Function which is responsible for resolving or
- * rejecting the newly created promise. The first parameter is a function which resolves the
- * promise, the second parameter is a function which rejects the promise.
- *
- * @returns {Promise} The newly created promise.
- */
-/**
- * @ngdoc provider
- * @name $qProvider
- * @this
- *
- * @description
- */
-function $QProvider() {
- var errorOnUnhandledRejections = true;
- this.$get = ['$rootScope', '$exceptionHandler', function($rootScope, $exceptionHandler) {
- return qFactory(function(callback) {
- $rootScope.$evalAsync(callback);
- }, $exceptionHandler, errorOnUnhandledRejections);
- }];
+ /**
+ * @name $testability
+ *
+ * @description
+ * The private $$testability service provides a collection of methods for use when debugging
+ * or by automated test and debugging tools.
+ */
+ var testability = {};
- /**
- * @ngdoc method
- * @name $qProvider#errorOnUnhandledRejections
- * @kind function
- *
- * @description
- * Retrieves or overrides whether to generate an error when a rejected promise is not handled.
- * This feature is enabled by default.
- *
- * @param {boolean=} value Whether to generate an error when a rejected promise is not handled.
- * @returns {boolean|ng.$qProvider} Current value when called without a new value or self for
- * chaining otherwise.
- */
- this.errorOnUnhandledRejections = function(value) {
- if (isDefined(value)) {
- errorOnUnhandledRejections = value;
- return this;
- } else {
- return errorOnUnhandledRejections;
- }
- };
-}
+ /**
+ * @name $$testability#findBindings
+ *
+ * @description
+ * Returns an array of elements that are bound (via ng-bind or {{}})
+ * to expressions matching the input.
+ *
+ * @param {Element} element The element root to search from.
+ * @param {string} expression The binding expression to match.
+ * @param {boolean} opt_exactMatch If true, only returns exact matches
+ * for the expression. Filters and whitespace are ignored.
+ */
+ testability.findBindings = function (element, expression, opt_exactMatch) {
+ var bindings = element.getElementsByClassName('ng-binding');
+ var matches = [];
+ forEach(bindings, function (binding) {
+ var dataBinding = angular.element(binding).data('$binding');
+ if (dataBinding) {
+ forEach(dataBinding, function (bindingName) {
+ if (opt_exactMatch) {
+ var matcher = new RegExp('(^|\\s)' + escapeForRegexp(expression) + '(\\s|\\||$)');
+ if (matcher.test(bindingName)) {
+ matches.push(binding);
+ }
+ } else {
+ if (bindingName.indexOf(expression) !== -1) {
+ matches.push(binding);
+ }
+ }
+ });
+ }
+ });
+ return matches;
+ };
-/** @this */
-function $$QProvider() {
- var errorOnUnhandledRejections = true;
- this.$get = ['$browser', '$exceptionHandler', function($browser, $exceptionHandler) {
- return qFactory(function(callback) {
- $browser.defer(callback);
- }, $exceptionHandler, errorOnUnhandledRejections);
- }];
+ /**
+ * @name $$testability#findModels
+ *
+ * @description
+ * Returns an array of elements that are two-way found via ng-model to
+ * expressions matching the input.
+ *
+ * @param {Element} element The element root to search from.
+ * @param {string} expression The model expression to match.
+ * @param {boolean} opt_exactMatch If true, only returns exact matches
+ * for the expression.
+ */
+ testability.findModels = function (element, expression, opt_exactMatch) {
+ var prefixes = ['ng-', 'data-ng-', 'ng\\:'];
+ for (var p = 0; p < prefixes.length; ++p) {
+ var attributeEquals = opt_exactMatch ? '=' : '*=';
+ var selector = '[' + prefixes[p] + 'model' + attributeEquals + '"' + expression + '"]';
+ var elements = element.querySelectorAll(selector);
+ if (elements.length) {
+ return elements;
+ }
+ }
+ };
- this.errorOnUnhandledRejections = function(value) {
- if (isDefined(value)) {
- errorOnUnhandledRejections = value;
- return this;
- } else {
- return errorOnUnhandledRejections;
- }
- };
-}
+ /**
+ * @name $$testability#getLocation
+ *
+ * @description
+ * Shortcut for getting the location in a browser agnostic way. Returns
+ * the path, search, and hash. (e.g. /path?a=b#hash)
+ */
+ testability.getLocation = function () {
+ return $location.url();
+ };
-/**
- * Constructs a promise manager.
- *
- * @param {function(function)} nextTick Function for executing functions in the next turn.
- * @param {function(...*)} exceptionHandler Function into which unexpected exceptions are passed for
- * debugging purposes.
- @ param {=boolean} errorOnUnhandledRejections Whether an error should be generated on unhandled
- * promises rejections.
- * @returns {object} Promise manager.
- */
-function qFactory(nextTick, exceptionHandler, errorOnUnhandledRejections) {
- var $qMinErr = minErr('$q', TypeError);
- var queueSize = 0;
- var checkQueue = [];
+ /**
+ * @name $$testability#setLocation
+ *
+ * @description
+ * Shortcut for navigating to a location without doing a full page reload.
+ *
+ * @param {string} url The location url (path, search and hash,
+ * e.g. /path?a=b#hash) to go to.
+ */
+ testability.setLocation = function (url) {
+ if (url !== $location.url()) {
+ $location.url(url);
+ $rootScope.$digest();
+ }
+ };
- /**
- * @ngdoc method
- * @name ng.$q#defer
- * @kind function
- *
- * @description
- * Creates a `Deferred` object which represents a task which will finish in the future.
- *
- * @returns {Deferred} Returns a new instance of deferred.
- */
- function defer() {
- return new Deferred();
- }
+ /**
+ * @name $$testability#whenStable
+ *
+ * @description
+ * Calls the callback when $timeout and $http requests are completed.
+ *
+ * @param {function} callback
+ */
+ testability.whenStable = function (callback) {
+ $browser.notifyWhenNoOutstandingRequests(callback);
+ };
- function Deferred() {
- var promise = this.promise = new Promise();
- //Non prototype methods necessary to support unbound execution :/
- this.resolve = function(val) { resolvePromise(promise, val); };
- this.reject = function(reason) { rejectPromise(promise, reason); };
- this.notify = function(progress) { notifyPromise(promise, progress); };
+ return testability;
+ }];
}
+ /** @this */
+ function $TimeoutProvider() {
+ this.$get = ['$rootScope', '$browser', '$q', '$$q', '$exceptionHandler', function ($rootScope, $browser, $q, $$q, $exceptionHandler) {
- function Promise() {
- this.$$state = { status: 0 };
- }
-
- extend(Promise.prototype, {
- then: function(onFulfilled, onRejected, progressBack) {
- if (isUndefined(onFulfilled) && isUndefined(onRejected) && isUndefined(progressBack)) {
- return this;
- }
- var result = new Promise();
+ var deferreds = {};
- this.$$state.pending = this.$$state.pending || [];
- this.$$state.pending.push([result, onFulfilled, onRejected, progressBack]);
- if (this.$$state.status > 0) scheduleProcessQueue(this.$$state);
+ /**
+ * @ngdoc service
+ * @name $timeout
+ *
+ * @description
+ * 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.
+ *
+ * @param {function()=} fn A function, whose execution should be delayed.
+ * @param {number=} [delay=0] Delay in milliseconds.
+ * @param {boolean=} [invokeApply=true] If set to `false` skips model dirty checking, otherwise
+ * will invoke `fn` within the {@link ng.$rootScope.Scope#$apply $apply} block.
+ * @param {...*=} Pass additional parameters to the executed function.
+ * @returns {Promise} Promise that will be resolved when the timeout is reached. The promise
+ * will be resolved with the return value of the `fn` function.
+ *
+ */
+ function timeout(fn, delay, invokeApply) {
+ if (!isFunction(fn)) {
+ invokeApply = delay;
+ delay = fn;
+ fn = noop;
+ }
- return result;
- },
+ var args = sliceArgs(arguments, 3),
+ skipApply = isDefined(invokeApply) && !invokeApply,
+ deferred = (skipApply ? $$q : $q).defer(),
+ promise = deferred.promise,
+ timeoutId;
- 'catch': function(callback) {
- return this.then(null, callback);
- },
+ timeoutId = $browser.defer(function () {
+ try {
+ deferred.resolve(fn.apply(null, args));
+ } catch (e) {
+ deferred.reject(e);
+ $exceptionHandler(e);
+ } finally {
+ delete deferreds[promise.$$timeoutId];
+ }
- 'finally': function(callback, progressBack) {
- return this.then(function(value) {
- return handleCallback(value, resolve, callback);
- }, function(error) {
- return handleCallback(error, reject, callback);
- }, progressBack);
- }
- });
+ if (!skipApply) $rootScope.$apply();
+ }, delay);
- function processQueue(state) {
- var fn, promise, pending;
+ promise.$$timeoutId = timeoutId;
+ deferreds[timeoutId] = deferred;
- pending = state.pending;
- state.processScheduled = false;
- state.pending = undefined;
- try {
- for (var i = 0, ii = pending.length; i < ii; ++i) {
- state.pur = true;
- promise = pending[i][0];
- fn = pending[i][state.status];
- try {
- if (isFunction(fn)) {
- resolvePromise(promise, fn(state.value));
- } else if (state.status === 1) {
- resolvePromise(promise, state.value);
- } else {
- rejectPromise(promise, state.value);
- }
- } catch (e) {
- rejectPromise(promise, e);
- }
- }
- } finally {
- --queueSize;
- if (errorOnUnhandledRejections && queueSize === 0) {
- nextTick(processChecks);
+ return promise;
}
- }
- }
- function processChecks() {
- // eslint-disable-next-line no-unmodified-loop-condition
- while (!queueSize && checkQueue.length) {
- var toCheck = checkQueue.shift();
- if (!toCheck.pur) {
- toCheck.pur = true;
- var errorMessage = 'Possibly unhandled rejection: ' + toDebugString(toCheck.value);
- if (toCheck.value instanceof Error) {
- exceptionHandler(toCheck.value, errorMessage);
- } else {
- exceptionHandler(errorMessage);
+ /**
+ * @ngdoc method
+ * @name $timeout#cancel
+ *
+ * @description
+ * Cancels a task associated with the `promise`. As a result of this, the promise will be
+ * resolved with a rejection.
+ *
+ * @param {Promise=} promise Promise returned by the `$timeout` function.
+ * @returns {boolean} Returns `true` if the task hasn't executed yet and was successfully
+ * canceled.
+ */
+ timeout.cancel = function (promise) {
+ if (promise && promise.$$timeoutId in deferreds) {
+ // Timeout cancels should not report an unhandled promise.
+ deferreds[promise.$$timeoutId].promise.catch(noop);
+ deferreds[promise.$$timeoutId].reject('canceled');
+ delete deferreds[promise.$$timeoutId];
+ return $browser.defer.cancel(promise.$$timeoutId);
}
- }
- }
- }
+ return false;
+ };
- function scheduleProcessQueue(state) {
- if (errorOnUnhandledRejections && !state.pending && state.status === 2 && !state.pur) {
- if (queueSize === 0 && checkQueue.length === 0) {
- nextTick(processChecks);
- }
- checkQueue.push(state);
- }
- if (state.processScheduled || !state.pending) return;
- state.processScheduled = true;
- ++queueSize;
- nextTick(function() { processQueue(state); });
+ return timeout;
+ }];
}
- function resolvePromise(promise, val) {
- if (promise.$$state.status) return;
- if (val === promise) {
- $$reject(promise, $qMinErr(
- 'qcycle',
- 'Expected promise to be resolved with value other than itself \'{0}\'',
- val));
- } else {
- $$resolve(promise, val);
- }
-
- }
+ // NOTE: The usage of window and document instead of $window and $document here is
+ // deliberate. This service depends on the specific behavior of anchor nodes created by the
+ // browser (resolving and parsing URLs) that is unlikely to be provided by mock objects and
+ // cause us to break tests. In addition, when the browser resolves a URL for XHR, it
+ // doesn't know about mocked locations and resolves URLs to the real document - which is
+ // exactly the behavior needed here. There is little value is mocking these out for this
+ // service.
+ var urlParsingNode = window.document.createElement('a');
+ var originUrl = urlResolve(window.location.href);
- function $$resolve(promise, val) {
- var then;
- var done = false;
- try {
- if (isObject(val) || isFunction(val)) then = val.then;
- if (isFunction(then)) {
- promise.$$state.status = -1;
- then.call(val, doResolve, doReject, doNotify);
- } else {
- promise.$$state.value = val;
- promise.$$state.status = 1;
- scheduleProcessQueue(promise.$$state);
- }
- } catch (e) {
- doReject(e);
- }
+ /**
+ *
+ * Implementation Notes for non-IE browsers
+ * ----------------------------------------
+ * Assigning a URL to the href property of an anchor DOM node, even one attached to the DOM,
+ * results both in the normalizing and parsing of the URL. Normalizing means that a relative
+ * URL will be resolved into an absolute URL in the context of the application document.
+ * Parsing means that the anchor node's host, hostname, protocol, port, pathname and related
+ * properties are all populated to reflect the normalized URL. This approach has wide
+ * compatibility - Safari 1+, Mozilla 1+ etc. See
+ * http://www.aptana.com/reference/html/api/HTMLAnchorElement.html
+ *
+ * Implementation Notes for IE
+ * ---------------------------
+ * IE <= 10 normalizes the URL when assigned to the anchor node similar to the other
+ * browsers. However, the parsed components will not be set if the URL assigned did not specify
+ * them. (e.g. if you assign a.href = "foo", then a.protocol, a.host, etc. will be empty.) We
+ * work around that by performing the parsing in a 2nd step by taking a previously normalized
+ * URL (e.g. by assigning to a.href) and assigning it a.href again. This correctly populates the
+ * properties such as protocol, hostname, port, etc.
+ *
+ * References:
+ * http://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement
+ * http://www.aptana.com/reference/html/api/HTMLAnchorElement.html
+ * http://url.spec.whatwg.org/#urlutils
+ * https://github.com/angular/angular.js/pull/2902
+ * http://james.padolsey.com/javascript/parsing-urls-with-the-dom/
+ *
+ * @kind function
+ * @param {string} url The URL to be parsed.
+ * @description Normalizes and parses a URL.
+ * @returns {object} Returns the normalized URL as a dictionary.
+ *
+ * | member name | Description |
+ * |---------------|----------------|
+ * | href | A normalized version of the provided URL if it was not an absolute URL |
+ * | protocol | The protocol including the trailing colon |
+ * | host | The host and port (if the port is non-default) of the normalizedUrl |
+ * | search | The search params, minus the question mark |
+ * | hash | The hash string, minus the hash symbol
+ * | hostname | The hostname
+ * | port | The port, without ":"
+ * | pathname | The pathname, beginning with "/"
+ *
+ */
+ function urlResolve(url) {
+ var href = url;
- function doResolve(val) {
- if (done) return;
- done = true;
- $$resolve(promise, val);
- }
- function doReject(val) {
- if (done) return;
- done = true;
- $$reject(promise, val);
- }
- function doNotify(progress) {
- notifyPromise(promise, progress);
+ // Support: IE 9-11 only
+ if (msie) {
+ // Normalize before parse. Refer Implementation Notes on why this is
+ // done in two steps on IE.
+ urlParsingNode.setAttribute('href', href);
+ href = urlParsingNode.href;
}
- }
- function rejectPromise(promise, reason) {
- if (promise.$$state.status) return;
- $$reject(promise, reason);
- }
+ urlParsingNode.setAttribute('href', href);
- function $$reject(promise, reason) {
- promise.$$state.value = reason;
- promise.$$state.status = 2;
- scheduleProcessQueue(promise.$$state);
+ // urlParsingNode provides the UrlUtils interface - http://url.spec.whatwg.org/#urlutils
+ return {
+ href: urlParsingNode.href,
+ protocol: urlParsingNode.protocol ? urlParsingNode.protocol.replace(/:$/, '') : '',
+ host: urlParsingNode.host,
+ search: urlParsingNode.search ? urlParsingNode.search.replace(/^\?/, '') : '',
+ hash: urlParsingNode.hash ? urlParsingNode.hash.replace(/^#/, '') : '',
+ hostname: urlParsingNode.hostname,
+ port: urlParsingNode.port,
+ pathname: urlParsingNode.pathname.charAt(0) === '/' ? urlParsingNode.pathname : '/' + urlParsingNode.pathname
+ };
}
- function notifyPromise(promise, progress) {
- var callbacks = promise.$$state.pending;
-
- if ((promise.$$state.status <= 0) && callbacks && callbacks.length) {
- nextTick(function() {
- var callback, result;
- for (var i = 0, ii = callbacks.length; i < ii; i++) {
- result = callbacks[i][0];
- callback = callbacks[i][3];
- try {
- notifyPromise(result, isFunction(callback) ? callback(progress) : progress);
- } catch (e) {
- exceptionHandler(e);
- }
- }
- });
- }
+ /**
+ * Parse a request URL and determine whether this is a same-origin request as the application document.
+ *
+ * @param {string|object} requestUrl The url of the request as a string that will be resolved
+ * or a parsed URL object.
+ * @returns {boolean} Whether the request is for the same origin as the application document.
+ */
+ function urlIsSameOrigin(requestUrl) {
+ var parsed = isString(requestUrl) ? urlResolve(requestUrl) : requestUrl;
+ return parsed.protocol === originUrl.protocol && parsed.host === originUrl.host;
}
/**
- * @ngdoc method
- * @name $q#reject
- * @kind function
+ * @ngdoc service
+ * @name $window
+ * @this
*
* @description
- * 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.
+ * 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.
*
- * 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);
- * });
- * ```
+ * 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.
*
- * @param {*} reason Constant, message, exception or an object representing the rejection reason.
- * @returns {Promise} Returns a promise that was already resolved as rejected with the `reason`.
+ * @example
+
+
+
+
+
+ ALERT
+
+
+
+ it('should display the greeting in the input box', function() {
+ element(by.model('greeting')).sendKeys('Hello, E2E Tests');
+ // If we click the button it will block the test runner
+ // element(':button').click();
+ });
+
+
*/
- function reject(reason) {
- var result = new Promise();
- rejectPromise(result, reason);
- return result;
- }
-
- function handleCallback(value, resolver, callback) {
- var callbackOutput = null;
- try {
- if (isFunction(callback)) callbackOutput = callback();
- } catch (e) {
- return reject(e);
- }
- if (isPromiseLike(callbackOutput)) {
- return callbackOutput.then(function() {
- return resolver(value);
- }, reject);
- } else {
- return resolver(value);
- }
+ function $WindowProvider() {
+ this.$get = valueFn(window);
}
/**
- * @ngdoc method
- * @name $q#when
- * @kind function
+ * @name $$cookieReader
+ * @requires $document
*
* @description
- * 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.
- *
- * @param {*} value Value or a promise
- * @param {Function=} successCallback
- * @param {Function=} errorCallback
- * @param {Function=} progressCallback
- * @returns {Promise} Returns a promise of the passed value or promise
+ * This is a private service for reading cookies used by $http and ngCookies
+ *
+ * @return {Object} a key/value map of the current cookies
*/
+ function $$CookieReader($document) {
+ var rawDocument = $document[0] || {};
+ var lastCookies = {};
+ var lastCookieString = '';
+
+ function safeGetCookie(rawDocument) {
+ try {
+ return rawDocument.cookie || '';
+ } catch (e) {
+ return '';
+ }
+ }
+
+ function safeDecodeURIComponent(str) {
+ try {
+ return decodeURIComponent(str);
+ } catch (e) {
+ return str;
+ }
+ }
+
+ return function () {
+ var cookieArray, cookie, i, index, name;
+ var currentCookieString = safeGetCookie(rawDocument);
+
+ if (currentCookieString !== lastCookieString) {
+ lastCookieString = currentCookieString;
+ cookieArray = lastCookieString.split('; ');
+ lastCookies = {};
+
+ for (i = 0; i < cookieArray.length; i++) {
+ cookie = cookieArray[i];
+ index = cookie.indexOf('=');
+ if (index > 0) {
+ //ignore nameless cookies
+ name = safeDecodeURIComponent(cookie.substring(0, index));
+ // the first value that is seen for a cookie is the most
+ // specific one. values for the same cookie name that
+ // follow are for less specific paths.
+ if (isUndefined(lastCookies[name])) {
+ lastCookies[name] = safeDecodeURIComponent(cookie.substring(index + 1));
+ }
+ }
+ }
+ }
+ return lastCookies;
+ };
+ }
+ $$CookieReader.$inject = ['$document'];
- function when(value, callback, errback, progressBack) {
- var result = new Promise();
- resolvePromise(result, value);
- return result.then(callback, errback, progressBack);
+ /** @this */
+ function $$CookieReaderProvider() {
+ this.$get = $$CookieReader;
}
+ /* global currencyFilter: true,
+ dateFilter: true,
+ filterFilter: true,
+ jsonFilter: true,
+ limitToFilter: true,
+ lowercaseFilter: true,
+ numberFilter: true,
+ orderByFilter: true,
+ uppercaseFilter: true,
+ */
+
/**
- * @ngdoc method
- * @name $q#resolve
- * @kind function
- *
+ * @ngdoc provider
+ * @name $filterProvider
* @description
- * Alias of {@link ng.$q#when when} to maintain naming consistency with ES6.
*
- * @param {*} value Value or a promise
- * @param {Function=} successCallback
- * @param {Function=} errorCallback
- * @param {Function=} progressCallback
- * @returns {Promise} Returns a promise of the passed value or promise
+ * Filters are just functions which transform input to an output. However filters need to be
+ * Dependency Injected. To achieve this a filter definition consists of a factory function which is
+ * annotated with dependencies and is responsible for creating a filter function.
+ *
+ *
+ * **Note:** Filter names must be valid angular {@link expression} identifiers, such as `uppercase` or `orderBy`.
+ * Names with special characters, such as hyphens and dots, are not allowed. If you wish to namespace
+ * your filters, then you can use capitalization (`myappSubsectionFilterx`) or underscores
+ * (`myapp_subsection_filterx`).
+ *
+ *
+ * ```js
+ * // Filter registration
+ * function MyModule($provide, $filterProvider) {
+ * // create a service to demonstrate injection (not always needed)
+ * $provide.value('greet', function(name){
+ * return 'Hello ' + name + '!';
+ * });
+ *
+ * // register a filter factory which uses the
+ * // greet service to demonstrate DI.
+ * $filterProvider.register('greet', function(greet){
+ * // return the filter function which uses the greet service
+ * // to generate salutation
+ * return function(text) {
+ * // filters need to be forgiving so check input validity
+ * return text && greet(text) || text;
+ * };
+ * });
+ * }
+ * ```
+ *
+ * The filter function is registered with the `$injector` under the filter name suffix with
+ * `Filter`.
+ *
+ * ```js
+ * it('should be the same instance', inject(
+ * function($filterProvider) {
+ * $filterProvider.register('reverse', function(){
+ * return ...;
+ * });
+ * },
+ * function($filter, reverseFilter) {
+ * expect($filter('reverse')).toBe(reverseFilter);
+ * });
+ * ```
+ *
+ *
+ * For more information about how angular filters work, and how to create your own filters, see
+ * {@link guide/filter Filters} in the Angular Developer Guide.
*/
- var resolve = when;
/**
- * @ngdoc method
- * @name $q#all
+ * @ngdoc service
+ * @name $filter
* @kind function
- *
* @description
- * Combines multiple promises into a single promise that is resolved when all of the input
- * promises are resolved.
- *
- * @param {Array.|Object.} promises An array or hash of promises.
- * @returns {Promise} Returns a single promise that will be resolved with an array/hash of values,
- * each value corresponding to the promise at the same index/key in the `promises` array/hash.
- * If any of the promises is resolved with a rejection, this resulting promise will be rejected
- * with the same rejection value.
- */
-
- function all(promises) {
- var result = new Promise(),
- counter = 0,
- results = isArray(promises) ? [] : {};
-
- forEach(promises, function(promise, key) {
- counter++;
- when(promise).then(function(value) {
- results[key] = value;
- if (!(--counter)) resolvePromise(result, results);
- }, function(reason) {
- rejectPromise(result, reason);
- });
- });
+ * Filters are used for formatting data displayed to the user.
+ *
+ * They can be used in view templates, controllers or services.Angular comes
+ * with a collection of [built-in filters](api/ng/filter), but it is easy to
+ * define your own as well.
+ *
+ * The general syntax in templates is as follows:
+ *
+ * ```html
+ * {{ expression [| filter_name[:parameter_value] ... ] }}
+ * ```
+ *
+ * @param {String} name Name of the filter function to retrieve
+ * @return {Function} the filter function
+ * @example
+
+
+
+
{{ originalText }}
+ {{ filteredText }}
+
+
+
+
+ angular.module('filterExample', [])
+ .controller('MainCtrl', function($scope, $filter) {
+ $scope.originalText = 'hello';
+ $scope.filteredText = $filter('uppercase')($scope.originalText);
+ });
+
+
+ */
+ $FilterProvider.$inject = ['$provide'];
+ /** @this */
+ function $FilterProvider($provide) {
+ var suffix = 'Filter';
- if (counter === 0) {
- resolvePromise(result, results);
+ /**
+ * @ngdoc method
+ * @name $filterProvider#register
+ * @param {string|Object} name Name of the filter function, or an object map of filters where
+ * the keys are the filter names and the values are the filter factories.
+ *
+ *
+ * **Note:** Filter names must be valid angular {@link expression} identifiers, such as `uppercase` or `orderBy`.
+ * Names with special characters, such as hyphens and dots, are not allowed. If you wish to namespace
+ * your filters, then you can use capitalization (`myappSubsectionFilterx`) or underscores
+ * (`myapp_subsection_filterx`).
+ *
+ * @param {Function} factory If the first argument was a string, a factory function for the filter to be registered.
+ * @returns {Object} Registered filter instance, or if a map of filters was provided then a map
+ * of the registered filter instances.
+ */
+ function register(name, factory) {
+ if (isObject(name)) {
+ var filters = {};
+ forEach(name, function (filter, key) {
+ filters[key] = register(key, filter);
+ });
+ return filters;
+ } else {
+ return $provide.factory(name + suffix, factory);
+ }
}
+ this.register = register;
- return result;
+ this.$get = ['$injector', function ($injector) {
+ return function (name) {
+ return $injector.get(name + suffix);
+ };
+ }];
+
+ ////////////////////////////////////////
+
+ /* global
+ currencyFilter: false,
+ dateFilter: false,
+ filterFilter: false,
+ jsonFilter: false,
+ limitToFilter: false,
+ lowercaseFilter: false,
+ numberFilter: false,
+ orderByFilter: false,
+ uppercaseFilter: false
+ */
+
+ register('currency', currencyFilter);
+ register('date', dateFilter);
+ register('filter', filterFilter);
+ register('json', jsonFilter);
+ register('limitTo', limitToFilter);
+ register('lowercase', lowercaseFilter);
+ register('number', numberFilter);
+ register('orderBy', orderByFilter);
+ register('uppercase', uppercaseFilter);
}
/**
- * @ngdoc method
- * @name $q#race
+ * @ngdoc filter
+ * @name filter
* @kind function
*
* @description
- * Returns a promise that resolves or rejects as soon as one of those promises
- * resolves or rejects, with the value or reason from that promise.
+ * Selects a subset of items from `array` and returns it as a new array.
+ *
+ * @param {Array} array The source array.
+ *
+ * **Note**: If the array contains objects that reference themselves, filtering is not possible.
+ *
+ * @param {string|Object|function()} expression The predicate to be used for selecting items from
+ * `array`.
+ *
+ * Can be one of:
+ *
+ * - `string`: The string is used for matching against the contents of the `array`. All strings or
+ * objects with string properties in `array` that match this string will be returned. This also
+ * applies to nested object properties.
+ * The predicate can be negated by prefixing the string with `!`.
+ *
+ * - `Object`: A pattern object can be used to filter specific properties on objects contained
+ * by `array`. For example `{name:"M", phone:"1"}` predicate will return an array of items
+ * which have property `name` containing "M" and property `phone` containing "1". A special
+ * property name (`$` by default) can be used (e.g. as in `{$: "text"}`) to accept a match
+ * against any property of the object or its nested object properties. That's equivalent to the
+ * simple substring match with a `string` as described above. The special property name can be
+ * overwritten, using the `anyPropertyKey` parameter.
+ * The predicate can be negated by prefixing the string with `!`.
+ * For example `{name: "!M"}` predicate will return an array of items which have property `name`
+ * not containing "M".
+ *
+ * Note that a named property will match properties on the same level only, while the special
+ * `$` property will match properties on the same level or deeper. E.g. an array item like
+ * `{name: {first: 'John', last: 'Doe'}}` will **not** be matched by `{name: 'John'}`, but
+ * **will** be matched by `{$: 'John'}`.
+ *
+ * - `function(value, index, array)`: A predicate function can be used to write arbitrary filters.
+ * The function is called for each element of the array, with the element, its index, and
+ * the entire array itself as arguments.
+ *
+ * The final result is an array of those elements that the predicate returned true for.
+ *
+ * @param {function(actual, expected)|true|false} [comparator] Comparator which is used in
+ * determining if values retrieved using `expression` (when it is not a function) should be
+ * considered a match based on the the expected value (from the filter expression) and actual
+ * value (from the object in the array).
+ *
+ * Can be one of:
+ *
+ * - `function(actual, expected)`:
+ * The function will be given the object value and the predicate value to compare and
+ * should return true if both values should be considered equal.
+ *
+ * - `true`: A shorthand for `function(actual, expected) { return angular.equals(actual, expected)}`.
+ * This is essentially strict comparison of expected and actual.
+ *
+ * - `false`: A short hand for a function which will look for a substring match in a case
+ * insensitive way. Primitive values are converted to strings. Objects are not compared against
+ * primitives, unless they have a custom `toString` method (e.g. `Date` objects).
+ *
*
- * @param {Array.|Object.} promises An array or hash of promises.
- * @returns {Promise} a promise that resolves or rejects as soon as one of the `promises`
- * resolves or rejects, with the value or reason from that promise.
+ * Defaults to `false`.
+ *
+ * @param {string} [anyPropertyKey] The special property name that matches against any property.
+ * By default `$`.
+ *
+ * @example
+
+
+
+
+ Search:
+
+ Name Phone
+
+ {{friend.name}}
+ {{friend.phone}}
+
+
+
+ Any:
+ Name only
+ Phone only
+ Equality
+
+ Name Phone
+
+ {{friendObj.name}}
+ {{friendObj.phone}}
+
+
+
+
+ var expectFriendNames = function(expectedNames, key) {
+ element.all(by.repeater(key + ' in friends').column(key + '.name')).then(function(arr) {
+ arr.forEach(function(wd, i) {
+ expect(wd.getText()).toMatch(expectedNames[i]);
+ });
+ });
+ };
+
+ it('should search across all fields when filtering with a string', function() {
+ var searchText = element(by.model('searchText'));
+ searchText.clear();
+ searchText.sendKeys('m');
+ expectFriendNames(['Mary', 'Mike', 'Adam'], 'friend');
+
+ searchText.clear();
+ searchText.sendKeys('76');
+ expectFriendNames(['John', 'Julie'], 'friend');
+ });
+
+ it('should search in specific fields when filtering with a predicate object', function() {
+ var searchAny = element(by.model('search.$'));
+ searchAny.clear();
+ searchAny.sendKeys('i');
+ expectFriendNames(['Mary', 'Mike', 'Julie', 'Juliette'], 'friendObj');
+ });
+ it('should use a equal comparison when comparator is true', function() {
+ var searchName = element(by.model('search.name'));
+ var strict = element(by.model('strict'));
+ searchName.clear();
+ searchName.sendKeys('Julie');
+ strict.click();
+ expectFriendNames(['Julie'], 'friendObj');
+ });
+
+
*/
- function race(promises) {
- var deferred = defer();
+ function filterFilter() {
+ return function (array, expression, comparator, anyPropertyKey) {
+ if (!isArrayLike(array)) {
+ if (array == null) {
+ return array;
+ } else {
+ throw minErr('filter')('notarray', 'Expected array but received: {0}', array);
+ }
+ }
- forEach(promises, function(promise) {
- when(promise).then(deferred.resolve, deferred.reject);
- });
+ anyPropertyKey = anyPropertyKey || '$';
+ var expressionType = getTypeForFilter(expression);
+ var predicateFn;
+ var matchAgainstAnyProp;
- return deferred.promise;
- }
+ switch (expressionType) {
+ case 'function':
+ predicateFn = expression;
+ break;
+ case 'boolean':
+ case 'null':
+ case 'number':
+ case 'string':
+ matchAgainstAnyProp = true;
+ // falls through
+ case 'object':
+ predicateFn = createPredicateFn(expression, comparator, anyPropertyKey, matchAgainstAnyProp);
+ break;
+ default:
+ return array;
+ }
- function $Q(resolver) {
- if (!isFunction(resolver)) {
- throw $qMinErr('norslvr', 'Expected resolverFn, got \'{0}\'', resolver);
- }
+ return Array.prototype.filter.call(array, predicateFn);
+ };
+ }
- var promise = new Promise();
+ // Helper functions for `filterFilter`
+ function createPredicateFn(expression, comparator, anyPropertyKey, matchAgainstAnyProp) {
+ var shouldMatchPrimitives = isObject(expression) && anyPropertyKey in expression;
+ var predicateFn;
- function resolveFn(value) {
- resolvePromise(promise, value);
- }
+ if (comparator === true) {
+ comparator = equals;
+ } else if (!isFunction(comparator)) {
+ comparator = function comparator(actual, expected) {
+ if (isUndefined(actual)) {
+ // No substring matching against `undefined`
+ return false;
+ }
+ if (actual === null || expected === null) {
+ // No substring matching against `null`; only match against `null`
+ return actual === expected;
+ }
+ if (isObject(expected) || isObject(actual) && !hasCustomToString(actual)) {
+ // Should not compare primitives against objects, unless they have custom `toString` method
+ return false;
+ }
- function rejectFn(reason) {
- rejectPromise(promise, reason);
+ actual = lowercase('' + actual);
+ expected = lowercase('' + expected);
+ return actual.indexOf(expected) !== -1;
+ };
}
- resolver(resolveFn, rejectFn);
+ predicateFn = function predicateFn(item) {
+ if (shouldMatchPrimitives && !isObject(item)) {
+ return deepCompare(item, expression[anyPropertyKey], comparator, anyPropertyKey, false);
+ }
+ return deepCompare(item, expression, comparator, anyPropertyKey, matchAgainstAnyProp);
+ };
- return promise;
+ return predicateFn;
}
- // Let's make the instanceof operator work for promises, so that
- // `new $q(fn) instanceof $q` would evaluate to true.
- $Q.prototype = Promise.prototype;
-
- $Q.defer = defer;
- $Q.reject = reject;
- $Q.when = when;
- $Q.resolve = resolve;
- $Q.all = all;
- $Q.race = race;
-
- return $Q;
-}
+ function deepCompare(actual, expected, comparator, anyPropertyKey, matchAgainstAnyProp, dontMatchWholeObject) {
+ var actualType = getTypeForFilter(actual);
+ var expectedType = getTypeForFilter(expected);
-/** @this */
-function $$RAFProvider() { //rAF
- this.$get = ['$window', '$timeout', function($window, $timeout) {
- var requestAnimationFrame = $window.requestAnimationFrame ||
- $window.webkitRequestAnimationFrame;
+ if (expectedType === 'string' && expected.charAt(0) === '!') {
+ return !deepCompare(actual, expected.substring(1), comparator, anyPropertyKey, matchAgainstAnyProp);
+ } else if (isArray(actual)) {
+ // In case `actual` is an array, consider it a match
+ // if ANY of it's items matches `expected`
+ return actual.some(function (item) {
+ return deepCompare(item, expected, comparator, anyPropertyKey, matchAgainstAnyProp);
+ });
+ }
- var cancelAnimationFrame = $window.cancelAnimationFrame ||
- $window.webkitCancelAnimationFrame ||
- $window.webkitCancelRequestAnimationFrame;
+ switch (actualType) {
+ case 'object':
+ var key;
+ if (matchAgainstAnyProp) {
+ for (key in actual) {
+ // Under certain, rare, circumstances, key may not be a string and `charAt` will be undefined
+ // See: https://github.com/angular/angular.js/issues/15644
+ if (key.charAt && key.charAt(0) !== '$' && deepCompare(actual[key], expected, comparator, anyPropertyKey, true)) {
+ return true;
+ }
+ }
+ return dontMatchWholeObject ? false : deepCompare(actual, expected, comparator, anyPropertyKey, false);
+ } else if (expectedType === 'object') {
+ for (key in expected) {
+ var expectedVal = expected[key];
+ if (isFunction(expectedVal) || isUndefined(expectedVal)) {
+ continue;
+ }
- var rafSupported = !!requestAnimationFrame;
- var raf = rafSupported
- ? function(fn) {
- var id = requestAnimationFrame(fn);
- return function() {
- cancelAnimationFrame(id);
- };
+ var matchAnyProperty = key === anyPropertyKey;
+ var actualVal = matchAnyProperty ? actual : actual[key];
+ if (!deepCompare(actualVal, expectedVal, comparator, anyPropertyKey, matchAnyProperty, matchAnyProperty)) {
+ return false;
+ }
+ }
+ return true;
+ } else {
+ return comparator(actual, expected);
}
- : function(fn) {
- var timer = $timeout(fn, 16.66, false); // 1000 / 60 = 16.666
- return function() {
- $timeout.cancel(timer);
- };
- };
-
- raf.supported = rafSupported;
+ case 'function':
+ return false;
+ default:
+ return comparator(actual, expected);
+ }
+ }
- return raf;
- }];
-}
+ // Used for easily differentiating between `null` and actual `object`
+ function getTypeForFilter(val) {
+ return val === null ? 'null' : typeof val === 'undefined' ? 'undefined' : _typeof(val);
+ }
-/**
- * DESIGN NOTES
- *
- * The design decisions behind the scope are heavily favored for speed and memory consumption.
- *
- * The typical use of scope is to watch the expressions, which most of the time return the same
- * value as last time so we optimize the operation.
- *
- * Closures construction is expensive in terms of speed as well as memory:
- * - No closures, instead use prototypical inheritance for API
- * - Internal state needs to be stored on scope directly, which means that private state is
- * exposed as $$____ properties
- *
- * Loop operations are optimized by using while(count--) { ... }
- * - This means that in order to keep the same order of execution as addition we have to add
- * items to the array at the beginning (unshift) instead of at the end (push)
- *
- * Child scopes are created and removed often
- * - Using an array would be slow since inserts in the middle are expensive; so we use linked lists
- *
- * There are fewer watches than observers. This is why you don't want the observer to be implemented
- * in the same way as watch. Watch requires return of the initialization function which is expensive
- * to construct.
- */
+ var MAX_DIGITS = 22;
+ var DECIMAL_SEP = '.';
+ var ZERO_CHAR = '0';
+ /**
+ * @ngdoc filter
+ * @name currency
+ * @kind function
+ *
+ * @description
+ * Formats a number as a currency (ie $1,234.56). When no currency symbol is provided, default
+ * symbol for current locale is used.
+ *
+ * @param {number} amount Input to filter.
+ * @param {string=} symbol Currency symbol or identifier to be displayed.
+ * @param {number=} fractionSize Number of decimal places to round the amount to, defaults to default max fraction size for current locale
+ * @returns {string} Formatted number.
+ *
+ *
+ * @example
+
+
+
+
+
+ default currency symbol ($): {{amount | currency}}
+ custom currency identifier (USD$): {{amount | currency:"USD$"}}
+ no fractions (0): {{amount | currency:"USD$":0}}
+
+
+
+ it('should init with 1234.56', function() {
+ expect(element(by.id('currency-default')).getText()).toBe('$1,234.56');
+ expect(element(by.id('currency-custom')).getText()).toBe('USD$1,234.56');
+ expect(element(by.id('currency-no-fractions')).getText()).toBe('USD$1,235');
+ });
+ it('should update', function() {
+ if (browser.params.browser === 'safari') {
+ // Safari does not understand the minus key. See
+ // https://github.com/angular/protractor/issues/481
+ return;
+ }
+ element(by.model('amount')).clear();
+ element(by.model('amount')).sendKeys('-1234');
+ expect(element(by.id('currency-default')).getText()).toBe('-$1,234.00');
+ expect(element(by.id('currency-custom')).getText()).toBe('-USD$1,234.00');
+ expect(element(by.id('currency-no-fractions')).getText()).toBe('-USD$1,234');
+ });
+
+
+ */
+ currencyFilter.$inject = ['$locale'];
+ function currencyFilter($locale) {
+ var formats = $locale.NUMBER_FORMATS;
+ return function (amount, currencySymbol, fractionSize) {
+ if (isUndefined(currencySymbol)) {
+ currencySymbol = formats.CURRENCY_SYM;
+ }
-/**
- * @ngdoc provider
- * @name $rootScopeProvider
- * @description
- *
- * Provider for the $rootScope service.
- */
+ if (isUndefined(fractionSize)) {
+ fractionSize = formats.PATTERNS[1].maxFrac;
+ }
-/**
- * @ngdoc method
- * @name $rootScopeProvider#digestTtl
- * @description
- *
- * 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.
- *
- * @param {number} limit The number of digest iterations.
- */
+ // if null or undefined pass it through
+ return amount == null ? amount : formatNumber(amount, formats.PATTERNS[1], formats.GROUP_SEP, formats.DECIMAL_SEP, fractionSize).replace(/\u00A4/g, currencySymbol);
+ };
+ }
+ /**
+ * @ngdoc filter
+ * @name number
+ * @kind function
+ *
+ * @description
+ * Formats a number as text.
+ *
+ * If the input is null or undefined, it will just be returned.
+ * If the input is infinite (Infinity or -Infinity), the Infinity symbol '∞' or '-∞' is returned, respectively.
+ * If the input is not a number an empty string is returned.
+ *
+ *
+ * @param {number|string} number Number to format.
+ * @param {(number|string)=} fractionSize Number of decimal places to round the number to.
+ * If this is not provided then the fraction size is computed from the current locale's number
+ * formatting pattern. In the case of the default locale, it will be 3.
+ * @returns {string} Number rounded to `fractionSize` appropriately formatted based on the current
+ * locale (e.g., in the en_US locale it will have "." as the decimal separator and
+ * include "," group separators after each third digit).
+ *
+ * @example
+
+
+
+
+ Enter number:
+ Default formatting: {{val | number}}
+ No fractions: {{val | number:0}}
+ Negative number: {{-val | number:4}}
+
+
+
+ it('should format numbers', function() {
+ expect(element(by.id('number-default')).getText()).toBe('1,234.568');
+ expect(element(by.binding('val | number:0')).getText()).toBe('1,235');
+ expect(element(by.binding('-val | number:4')).getText()).toBe('-1,234.5679');
+ });
+
+ it('should update', function() {
+ element(by.model('val')).clear();
+ element(by.model('val')).sendKeys('3374.333');
+ expect(element(by.id('number-default')).getText()).toBe('3,374.333');
+ expect(element(by.binding('val | number:0')).getText()).toBe('3,374');
+ expect(element(by.binding('-val | number:4')).getText()).toBe('-3,374.3330');
+ });
+
+
+ */
+ numberFilter.$inject = ['$locale'];
+ function numberFilter($locale) {
+ var formats = $locale.NUMBER_FORMATS;
+ return function (number, fractionSize) {
-/**
- * @ngdoc service
- * @name $rootScope
- * @this
- *
- * @description
- *
- * Every application has a single root {@link ng.$rootScope.Scope scope}.
- * All other scopes are descendant scopes of the root scope. Scopes provide separation
- * between the model and the view, via a mechanism for watching the model for changes.
- * They also provide event emission/broadcast and subscription facility. See the
- * {@link guide/scope developer guide on scopes}.
- */
-function $RootScopeProvider() {
- var TTL = 10;
- var $rootScopeMinErr = minErr('$rootScope');
- var lastDirtyWatch = null;
- var applyAsyncId = null;
+ // if null or undefined pass it through
+ return number == null ? number : formatNumber(number, formats.PATTERNS[0], formats.GROUP_SEP, formats.DECIMAL_SEP, fractionSize);
+ };
+ }
- this.digestTtl = function(value) {
- if (arguments.length) {
- TTL = value;
- }
- return TTL;
- };
+ /**
+ * Parse a number (as a string) into three components that can be used
+ * for formatting the number.
+ *
+ * (Significant bits of this parse algorithm came from https://github.com/MikeMcl/big.js/)
+ *
+ * @param {string} numStr The number to parse
+ * @return {object} An object describing this number, containing the following keys:
+ * - d : an array of digits containing leading zeros as necessary
+ * - i : the number of the digits in `d` that are to the left of the decimal point
+ * - e : the exponent for numbers that would need more than `MAX_DIGITS` digits in `d`
+ *
+ */
+ function parse(numStr) {
+ var exponent = 0,
+ digits,
+ numberOfIntegerDigits;
+ var i, j, zeros;
- function createChildScopeClass(parent) {
- function ChildScope() {
- this.$$watchers = this.$$nextSibling =
- this.$$childHead = this.$$childTail = null;
- this.$$listeners = {};
- this.$$listenerCount = {};
- this.$$watchersCount = 0;
- this.$id = nextUid();
- this.$$ChildScope = null;
+ // Decimal point?
+ if ((numberOfIntegerDigits = numStr.indexOf(DECIMAL_SEP)) > -1) {
+ numStr = numStr.replace(DECIMAL_SEP, '');
}
- ChildScope.prototype = parent;
- return ChildScope;
- }
-
- this.$get = ['$exceptionHandler', '$parse', '$browser',
- function($exceptionHandler, $parse, $browser) {
- function destroyChildScope($event) {
- $event.currentScope.$$destroyed = true;
+ // Exponential form?
+ if ((i = numStr.search(/e/i)) > 0) {
+ // Work out the exponent.
+ if (numberOfIntegerDigits < 0) numberOfIntegerDigits = i;
+ numberOfIntegerDigits += +numStr.slice(i + 1);
+ numStr = numStr.substring(0, i);
+ } else if (numberOfIntegerDigits < 0) {
+ // There was no decimal point or exponent so it is an integer.
+ numberOfIntegerDigits = numStr.length;
}
- function cleanUpScope($scope) {
+ // Count the number of leading zeros.
+ for (i = 0; numStr.charAt(i) === ZERO_CHAR; i++) {/* empty */}
- // Support: IE 9 only
- if (msie === 9) {
- // There is a memory leak in IE9 if all child scopes are not disconnected
- // completely when a scope is destroyed. So this code will recurse up through
- // all this scopes children
- //
- // See issue https://github.com/angular/angular.js/issues/10706
- if ($scope.$$childHead) {
- cleanUpScope($scope.$$childHead);
- }
- if ($scope.$$nextSibling) {
- cleanUpScope($scope.$$nextSibling);
- }
+ if (i === (zeros = numStr.length)) {
+ // The digits are all zero.
+ digits = [0];
+ numberOfIntegerDigits = 1;
+ } else {
+ // Count the number of trailing zeros
+ zeros--;
+ while (numStr.charAt(zeros) === ZERO_CHAR) {
+ zeros--;
+ } // Trailing zeros are insignificant so ignore them
+ numberOfIntegerDigits -= i;
+ digits = [];
+ // Convert string to array of digits without leading/trailing zeros.
+ for (j = 0; i <= zeros; i++, j++) {
+ digits[j] = +numStr.charAt(i);
}
-
- // The code below works around IE9 and V8's memory leaks
- //
- // See:
- // - https://code.google.com/p/v8/issues/detail?id=2073#c26
- // - https://github.com/angular/angular.js/issues/6794#issuecomment-38648909
- // - https://github.com/angular/angular.js/issues/1313#issuecomment-10378451
-
- $scope.$parent = $scope.$$nextSibling = $scope.$$prevSibling = $scope.$$childHead =
- $scope.$$childTail = $scope.$root = $scope.$$watchers = null;
}
- /**
- * @ngdoc type
- * @name $rootScope.Scope
- *
- * @description
- * 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.
- *
- *
- * @param {Object.=} providers Map of service factory which need to be
- * provided for the current scope. Defaults to {@link ng}.
- * @param {Object.=} instanceCache Provides pre-instantiated services which should
- * append/override services provided by `providers`. This is handy
- * when unit-testing and having the need to override a default
- * service.
- * @returns {Object} Newly created scope.
- *
- */
- function Scope() {
- this.$id = nextUid();
- this.$$phase = this.$parent = this.$$watchers =
- this.$$nextSibling = this.$$prevSibling =
- this.$$childHead = this.$$childTail = null;
- this.$root = this;
- this.$$destroyed = false;
- this.$$listeners = {};
- this.$$listenerCount = {};
- this.$$watchersCount = 0;
- this.$$isolateBindings = null;
+ // If the number overflows the maximum allowed digits then use an exponent.
+ if (numberOfIntegerDigits > MAX_DIGITS) {
+ digits = digits.splice(0, MAX_DIGITS - 1);
+ exponent = numberOfIntegerDigits - 1;
+ numberOfIntegerDigits = 1;
}
- /**
- * @ngdoc property
- * @name $rootScope.Scope#$id
- *
- * @description
- * Unique scope ID (monotonically increasing) useful for debugging.
- */
-
- /**
- * @ngdoc property
- * @name $rootScope.Scope#$parent
- *
- * @description
- * Reference to the parent scope.
- */
-
- /**
- * @ngdoc property
- * @name $rootScope.Scope#$root
- *
- * @description
- * Reference to the root scope.
- */
+ return { d: digits, e: exponent, i: numberOfIntegerDigits };
+ }
- Scope.prototype = {
- constructor: Scope,
- /**
- * @ngdoc method
- * @name $rootScope.Scope#$new
- * @kind function
- *
- * @description
- * 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.
- *
- * @param {boolean} isolate If true, then the scope does not prototypically inherit from the
- * parent scope. The scope is isolated, as it can not see parent scope properties.
- * When creating widgets, it is useful for the widget to not accidentally read parent
- * state.
- *
- * @param {Scope} [parent=this] The {@link ng.$rootScope.Scope `Scope`} that will be the `$parent`
- * of the newly created scope. Defaults to `this` scope if not provided.
- * This is used when creating a transclude scope to correctly place it
- * in the scope hierarchy while maintaining the correct prototypical
- * inheritance.
- *
- * @returns {Object} The newly created child scope.
- *
- */
- $new: function(isolate, parent) {
- var child;
+ /**
+ * Round the parsed number to the specified number of decimal places
+ * This function changed the parsedNumber in-place
+ */
+ function roundNumber(parsedNumber, fractionSize, minFrac, maxFrac) {
+ var digits = parsedNumber.d;
+ var fractionLen = digits.length - parsedNumber.i;
- parent = parent || this;
+ // determine fractionSize if it is not specified; `+fractionSize` converts it to a number
+ fractionSize = isUndefined(fractionSize) ? Math.min(Math.max(minFrac, fractionLen), maxFrac) : +fractionSize;
- if (isolate) {
- child = new Scope();
- child.$root = this.$root;
- } else {
- // Only create a child scope class if somebody asks for one,
- // but cache it to allow the VM to optimize lookups.
- if (!this.$$ChildScope) {
- this.$$ChildScope = createChildScopeClass(this);
- }
- child = new this.$$ChildScope();
- }
- child.$parent = parent;
- child.$$prevSibling = parent.$$childTail;
- if (parent.$$childHead) {
- parent.$$childTail.$$nextSibling = child;
- parent.$$childTail = child;
- } else {
- parent.$$childHead = parent.$$childTail = child;
- }
+ // The index of the digit to where rounding is to occur
+ var roundAt = fractionSize + parsedNumber.i;
+ var digit = digits[roundAt];
- // When the new scope is not isolated or we inherit from `this`, and
- // the parent scope is destroyed, the property `$$destroyed` is inherited
- // prototypically. In all other cases, this property needs to be set
- // when the parent scope is destroyed.
- // The listener needs to be added after the parent is set
- if (isolate || parent !== this) child.$on('$destroy', destroyChildScope);
+ if (roundAt > 0) {
+ // Drop fractional digits beyond `roundAt`
+ digits.splice(Math.max(parsedNumber.i, roundAt));
- return child;
- },
+ // Set non-fractional digits beyond `roundAt` to 0
+ for (var j = roundAt; j < digits.length; j++) {
+ digits[j] = 0;
+ }
+ } else {
+ // We rounded to zero so reset the parsedNumber
+ fractionLen = Math.max(0, fractionLen);
+ parsedNumber.i = 1;
+ digits.length = Math.max(1, roundAt = fractionSize + 1);
+ digits[0] = 0;
+ for (var i = 1; i < roundAt; i++) {
+ digits[i] = 0;
+ }
+ }
- /**
- * @ngdoc method
- * @name $rootScope.Scope#$watch
- * @kind function
- *
- * @description
- * 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.
- * - This should not be used to watch for changes in objects that are
- * or contain [File](https://developer.mozilla.org/docs/Web/API/File) objects due to limitations with {@link angular.copy `angular.copy`}.
- * - 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);
+ if (digit >= 5) {
+ if (roundAt - 1 < 0) {
+ for (var k = 0; k > roundAt; k--) {
+ digits.unshift(0);
+ parsedNumber.i++;
+ }
+ digits.unshift(1);
+ parsedNumber.i++;
+ } else {
+ digits[roundAt - 1]++;
+ }
+ }
- // Run the digest but since food has not changed count will still be zero
- scope.$digest();
- expect(scope.foodCounter).toEqual(0);
+ // Pad out with zeros to get the required fraction length
+ for (; fractionLen < Math.max(0, fractionSize); fractionLen++) {
+ digits.push(0);
+ } // Do any carrying, e.g. a digit was rounded up to 10
+ var carry = digits.reduceRight(function (carry, d, i, digits) {
+ d = d + carry;
+ digits[i] = d % 10;
+ return Math.floor(d / 10);
+ }, 0);
+ if (carry) {
+ digits.unshift(carry);
+ parsedNumber.i++;
+ }
+ }
- // Update food and run digest. Now the counter will increment
- food = 'cheeseburger';
- scope.$digest();
- expect(scope.foodCounter).toEqual(1);
+ /**
+ * Format a number into a string
+ * @param {number} number The number to format
+ * @param {{
+ * minFrac, // the minimum number of digits required in the fraction part of the number
+ * maxFrac, // the maximum number of digits required in the fraction part of the number
+ * gSize, // number of digits in each group of separated digits
+ * lgSize, // number of digits in the last group of digits before the decimal separator
+ * negPre, // the string to go in front of a negative number (e.g. `-` or `(`))
+ * posPre, // the string to go in front of a positive number
+ * negSuf, // the string to go after a negative number (e.g. `)`)
+ * posSuf // the string to go after a positive number
+ * }} pattern
+ * @param {string} groupSep The string to separate groups of number (e.g. `,`)
+ * @param {string} decimalSep The string to act as the decimal separator (e.g. `.`)
+ * @param {[type]} fractionSize The size of the fractional part of the number
+ * @return {string} The number formatted as a string
+ */
+ function formatNumber(number, pattern, groupSep, decimalSep, fractionSize) {
- * ```
- *
- *
- *
- * @param {(function()|string)} watchExpression Expression that is evaluated on each
- * {@link ng.$rootScope.Scope#$digest $digest} cycle. A change in the return value triggers
- * a call to the `listener`.
- *
- * - `string`: Evaluated as {@link guide/expression expression}
- * - `function(scope)`: called with current `scope` as a parameter.
- * @param {function(newVal, oldVal, scope)} listener Callback called whenever the value
- * of `watchExpression` changes.
- *
- * - `newVal` contains the current value of the `watchExpression`
- * - `oldVal` contains the previous value of the `watchExpression`
- * - `scope` refers to the current scope
- * @param {boolean=} [objectEquality=false] Compare for object equality using {@link angular.equals} instead of
- * comparing for reference equality.
- * @returns {function()} Returns a deregistration function for this listener.
- */
- $watch: function(watchExp, listener, objectEquality, prettyPrintExpression) {
- var get = $parse(watchExp);
-
- if (get.$$watchDelegate) {
- return get.$$watchDelegate(this, listener, objectEquality, get, watchExp);
- }
- var scope = this,
- array = scope.$$watchers,
- watcher = {
- fn: listener,
- last: initWatchVal,
- get: get,
- exp: prettyPrintExpression || watchExp,
- eq: !!objectEquality
- };
+ if (!(isString(number) || isNumber(number)) || isNaN(number)) return '';
- lastDirtyWatch = null;
+ var isInfinity = !isFinite(number);
+ var isZero = false;
+ var numStr = Math.abs(number) + '',
+ formattedText = '',
+ parsedNumber;
- if (!isFunction(listener)) {
- watcher.fn = noop;
- }
+ if (isInfinity) {
+ formattedText = '\u221E';
+ } else {
+ parsedNumber = parse(numStr);
- if (!array) {
- array = scope.$$watchers = [];
- array.$$digestWatchIndex = -1;
- }
- // we use unshift since we use a while loop in $digest for speed.
- // the while loop reads in reverse order.
- array.unshift(watcher);
- array.$$digestWatchIndex++;
- incrementWatchersCount(this, 1);
+ roundNumber(parsedNumber, fractionSize, pattern.minFrac, pattern.maxFrac);
- return function deregisterWatch() {
- var index = arrayRemove(array, watcher);
- if (index >= 0) {
- incrementWatchersCount(scope, -1);
- if (index < array.$$digestWatchIndex) {
- array.$$digestWatchIndex--;
- }
- }
- lastDirtyWatch = null;
- };
- },
+ var digits = parsedNumber.d;
+ var integerLen = parsedNumber.i;
+ var exponent = parsedNumber.e;
+ var decimals = [];
+ isZero = digits.reduce(function (isZero, d) {
+ return isZero && !d;
+ }, true);
- /**
- * @ngdoc method
- * @name $rootScope.Scope#$watchGroup
- * @kind function
- *
- * @description
- * 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 the standard `$watch` operation. Their return
- * values are examined for changes on every call to `$digest`.
- * - The `listener` is called whenever any expression in the `watchExpressions` array changes.
- *
- * @param {Array.} watchExpressions Array of expressions that will be individually
- * watched using {@link ng.$rootScope.Scope#$watch $watch()}
- *
- * @param {function(newValues, oldValues, scope)} listener Callback called whenever the return value of any
- * expression in `watchExpressions` changes
- * The `newValues` array contains the current values of the `watchExpressions`, with the indexes matching
- * those of `watchExpression`
- * and the `oldValues` array contains the previous values of the `watchExpressions`, with the indexes matching
- * those of `watchExpression`
- * The `scope` refers to the current scope.
- * @returns {function()} Returns a de-registration function for all listeners.
- */
- $watchGroup: function(watchExpressions, listener) {
- var oldValues = new Array(watchExpressions.length);
- var newValues = new Array(watchExpressions.length);
- var deregisterFns = [];
- var self = this;
- var changeReactionScheduled = false;
- var firstRun = true;
-
- if (!watchExpressions.length) {
- // No expressions means we call the listener ASAP
- var shouldCall = true;
- self.$evalAsync(function() {
- if (shouldCall) listener(newValues, newValues, self);
- });
- return function deregisterWatchGroup() {
- shouldCall = false;
- };
- }
+ // pad zeros for small numbers
+ while (integerLen < 0) {
+ digits.unshift(0);
+ integerLen++;
+ }
- if (watchExpressions.length === 1) {
- // Special case size of one
- return this.$watch(watchExpressions[0], function watchGroupAction(value, oldValue, scope) {
- newValues[0] = value;
- oldValues[0] = oldValue;
- listener(newValues, (value === oldValue) ? newValues : oldValues, scope);
- });
- }
+ // extract decimals digits
+ if (integerLen > 0) {
+ decimals = digits.splice(integerLen, digits.length);
+ } else {
+ decimals = digits;
+ digits = [0];
+ }
- forEach(watchExpressions, function(expr, i) {
- var unwatchFn = self.$watch(expr, function watchGroupSubAction(value, oldValue) {
- newValues[i] = value;
- oldValues[i] = oldValue;
- if (!changeReactionScheduled) {
- changeReactionScheduled = true;
- self.$evalAsync(watchGroupAction);
- }
- });
- deregisterFns.push(unwatchFn);
- });
+ // format the integer digits with grouping separators
+ var groups = [];
+ if (digits.length >= pattern.lgSize) {
+ groups.unshift(digits.splice(-pattern.lgSize, digits.length).join(''));
+ }
+ while (digits.length > pattern.gSize) {
+ groups.unshift(digits.splice(-pattern.gSize, digits.length).join(''));
+ }
+ if (digits.length) {
+ groups.unshift(digits.join(''));
+ }
+ formattedText = groups.join(groupSep);
- function watchGroupAction() {
- changeReactionScheduled = false;
+ // append the decimal digits
+ if (decimals.length) {
+ formattedText += decimalSep + decimals.join('');
+ }
- if (firstRun) {
- firstRun = false;
- listener(newValues, newValues, self);
- } else {
- listener(newValues, oldValues, self);
- }
- }
+ if (exponent) {
+ formattedText += 'e+' + exponent;
+ }
+ }
+ if (number < 0 && !isZero) {
+ return pattern.negPre + formattedText + pattern.negSuf;
+ } else {
+ return pattern.posPre + formattedText + pattern.posSuf;
+ }
+ }
- return function deregisterWatchGroup() {
- while (deregisterFns.length) {
- deregisterFns.shift()();
- }
- };
- },
+ function padNumber(num, digits, trim, negWrap) {
+ var neg = '';
+ if (num < 0 || negWrap && num <= 0) {
+ if (negWrap) {
+ num = -num + 1;
+ } else {
+ num = -num;
+ neg = '-';
+ }
+ }
+ num = '' + num;
+ while (num.length < digits) {
+ num = ZERO_CHAR + num;
+ }if (trim) {
+ num = num.substr(num.length - digits);
+ }
+ return neg + num;
+ }
+ function dateGetter(name, size, offset, trim, negWrap) {
+ offset = offset || 0;
+ return function (date) {
+ var value = date['get' + name]();
+ if (offset > 0 || value > -offset) {
+ value += offset;
+ }
+ if (value === 0 && offset === -12) value = 12;
+ return padNumber(value, size, trim, negWrap);
+ };
+ }
- /**
- * @ngdoc method
- * @name $rootScope.Scope#$watchCollection
- * @kind function
- *
- * @description
- * 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;
+ function dateStrGetter(name, shortForm, standAlone) {
+ return function (date, formats) {
+ var value = date['get' + name]();
+ var propPrefix = (standAlone ? 'STANDALONE' : '') + (shortForm ? 'SHORT' : '');
+ var get = uppercase(propPrefix + name);
- $scope.$watchCollection('names', function(newNames, oldNames) {
- $scope.dataCount = newNames.length;
- });
+ return formats[get][value];
+ };
+ }
- expect($scope.dataCount).toEqual(4);
- $scope.$digest();
+ function timeZoneGetter(date, formats, offset) {
+ var zone = -1 * offset;
+ var paddedZone = zone >= 0 ? '+' : '';
- //still at 4 ... no changes
- expect($scope.dataCount).toEqual(4);
+ paddedZone += padNumber(Math[zone > 0 ? 'floor' : 'ceil'](zone / 60), 2) + padNumber(Math.abs(zone % 60), 2);
- $scope.names.pop();
- $scope.$digest();
+ return paddedZone;
+ }
- //now there's been a change
- expect($scope.dataCount).toEqual(3);
- * ```
- *
- *
- * @param {string|function(scope)} obj Evaluated as {@link guide/expression expression}. The
- * expression value should evaluate to an object or an array which is observed on each
- * {@link ng.$rootScope.Scope#$digest $digest} cycle. Any shallow change within the
- * collection will trigger a call to the `listener`.
- *
- * @param {function(newCollection, oldCollection, scope)} listener a callback function called
- * when a change is detected.
- * - The `newCollection` object is the newly modified data obtained from the `obj` expression
- * - The `oldCollection` object is a copy of the former collection data.
- * Due to performance considerations, the`oldCollection` value is computed only if the
- * `listener` function declares two or more arguments.
- * - The `scope` argument refers to the current scope.
- *
- * @returns {function()} Returns a de-registration function for this listener. When the
- * de-registration function is executed, the internal watch operation is terminated.
- */
- $watchCollection: function(obj, listener) {
- $watchCollectionInterceptor.$stateful = true;
-
- var self = this;
- // the current value, updated on each dirty-check run
- var newValue;
- // a shallow copy of the newValue from the last dirty-check run,
- // updated to match newValue during dirty-check run
- var oldValue;
- // a shallow copy of the newValue from when the last change happened
- var veryOldValue;
- // only track veryOldValue if the listener is asking for it
- var trackVeryOldValue = (listener.length > 1);
- var changeDetected = 0;
- var changeDetector = $parse(obj, $watchCollectionInterceptor);
- var internalArray = [];
- var internalObject = {};
- var initRun = true;
- var oldLength = 0;
-
- function $watchCollectionInterceptor(_value) {
- newValue = _value;
- var newLength, key, bothNaN, newItem, oldItem;
-
- // If the new value is undefined, then return undefined as the watch may be a one-time watch
- if (isUndefined(newValue)) return;
-
- if (!isObject(newValue)) { // if primitive
- if (oldValue !== newValue) {
- oldValue = newValue;
- changeDetected++;
- }
- } else if (isArrayLike(newValue)) {
- if (oldValue !== internalArray) {
- // we are transitioning from something which was not an array into array.
- oldValue = internalArray;
- oldLength = oldValue.length = 0;
- changeDetected++;
- }
+ function getFirstThursdayOfYear(year) {
+ // 0 = index of January
+ var dayOfWeekOnFirst = new Date(year, 0, 1).getDay();
+ // 4 = index of Thursday (+1 to account for 1st = 5)
+ // 11 = index of *next* Thursday (+1 account for 1st = 12)
+ return new Date(year, 0, (dayOfWeekOnFirst <= 4 ? 5 : 12) - dayOfWeekOnFirst);
+ }
- newLength = newValue.length;
+ function getThursdayThisWeek(datetime) {
+ return new Date(datetime.getFullYear(), datetime.getMonth(),
+ // 4 = index of Thursday
+ datetime.getDate() + (4 - datetime.getDay()));
+ }
- if (oldLength !== newLength) {
- // if lengths do not match we need to trigger change notification
- changeDetected++;
- oldValue.length = oldLength = newLength;
- }
- // copy the items to oldValue and look for changes.
- for (var i = 0; i < newLength; i++) {
- oldItem = oldValue[i];
- newItem = newValue[i];
-
- // eslint-disable-next-line no-self-compare
- bothNaN = (oldItem !== oldItem) && (newItem !== newItem);
- if (!bothNaN && (oldItem !== newItem)) {
- changeDetected++;
- oldValue[i] = newItem;
- }
- }
- } else {
- if (oldValue !== internalObject) {
- // we are transitioning from something which was not an object into object.
- oldValue = internalObject = {};
- oldLength = 0;
- changeDetected++;
- }
- // copy the items to oldValue and look for changes.
- newLength = 0;
- for (key in newValue) {
- if (hasOwnProperty.call(newValue, key)) {
- newLength++;
- newItem = newValue[key];
- oldItem = oldValue[key];
-
- if (key in oldValue) {
- // eslint-disable-next-line no-self-compare
- bothNaN = (oldItem !== oldItem) && (newItem !== newItem);
- if (!bothNaN && (oldItem !== newItem)) {
- changeDetected++;
- oldValue[key] = newItem;
- }
- } else {
- oldLength++;
- oldValue[key] = newItem;
- changeDetected++;
- }
- }
- }
- if (oldLength > newLength) {
- // we used to have more keys, need to find them and destroy them.
- changeDetected++;
- for (key in oldValue) {
- if (!hasOwnProperty.call(newValue, key)) {
- oldLength--;
- delete oldValue[key];
- }
- }
- }
- }
- return changeDetected;
- }
+ function weekGetter(size) {
+ return function (date) {
+ var firstThurs = getFirstThursdayOfYear(date.getFullYear()),
+ thisThurs = getThursdayThisWeek(date);
- function $watchCollectionAction() {
- if (initRun) {
- initRun = false;
- listener(newValue, newValue, self);
- } else {
- listener(newValue, veryOldValue, self);
- }
+ var diff = +thisThurs - +firstThurs,
+ result = 1 + Math.round(diff / 6.048e8); // 6.048e8 ms per week
- // make a copy for the next time a collection is changed
- if (trackVeryOldValue) {
- if (!isObject(newValue)) {
- //primitive
- veryOldValue = newValue;
- } else if (isArrayLike(newValue)) {
- veryOldValue = new Array(newValue.length);
- for (var i = 0; i < newValue.length; i++) {
- veryOldValue[i] = newValue[i];
- }
- } else { // if object
- veryOldValue = {};
- for (var key in newValue) {
- if (hasOwnProperty.call(newValue, key)) {
- veryOldValue[key] = newValue[key];
- }
- }
- }
- }
- }
+ return padNumber(result, size);
+ };
+ }
- return this.$watch(changeDetector, $watchCollectionAction);
- },
+ function ampmGetter(date, formats) {
+ return date.getHours() < 12 ? formats.AMPMS[0] : formats.AMPMS[1];
+ }
- /**
- * @ngdoc method
- * @name $rootScope.Scope#$digest
- * @kind function
- *
- * @description
- * Processes all of the {@link ng.$rootScope.Scope#$watch watchers} of the current scope and
- * its children. Because a {@link ng.$rootScope.Scope#$watch watcher}'s listener can change
- * the model, the `$digest()` keeps calling the {@link ng.$rootScope.Scope#$watch watchers}
- * until no more listeners are firing. This means that it is possible to get into an infinite
- * loop. This function will throw `'Maximum iteration limit exceeded.'` if the number of
- * iterations exceeds 10.
- *
- * Usually, you don't call `$digest()` directly in
- * {@link ng.directive:ngController controllers} or in
- * {@link ng.$compileProvider#directive directives}.
- * Instead, you should call {@link ng.$rootScope.Scope#$apply $apply()} (typically from within
- * a {@link ng.$compileProvider#directive directive}), which will force a `$digest()`.
- *
- * If you want to be notified whenever `$digest()` is called,
- * you can register a `watchExpression` function with
- * {@link ng.$rootScope.Scope#$watch $watch()} with no `listener`.
- *
- * In unit tests, you may need to call `$digest()` to simulate the scope life cycle.
- *
- * # Example
- * ```js
- var scope = ...;
- scope.name = 'misko';
- scope.counter = 0;
+ function eraGetter(date, formats) {
+ return date.getFullYear() <= 0 ? formats.ERAS[0] : formats.ERAS[1];
+ }
- expect(scope.counter).toEqual(0);
- scope.$watch('name', function(newValue, oldValue) {
- scope.counter = scope.counter + 1;
- });
- expect(scope.counter).toEqual(0);
+ function longEraGetter(date, formats) {
+ return date.getFullYear() <= 0 ? formats.ERANAMES[0] : formats.ERANAMES[1];
+ }
- scope.$digest();
- // the listener is always called during the first $digest loop after it was registered
- expect(scope.counter).toEqual(1);
+ var DATE_FORMATS = {
+ yyyy: dateGetter('FullYear', 4, 0, false, true),
+ yy: dateGetter('FullYear', 2, 0, true, true),
+ y: dateGetter('FullYear', 1, 0, false, true),
+ MMMM: dateStrGetter('Month'),
+ MMM: dateStrGetter('Month', true),
+ MM: dateGetter('Month', 2, 1),
+ M: dateGetter('Month', 1, 1),
+ LLLL: dateStrGetter('Month', false, true),
+ dd: dateGetter('Date', 2),
+ d: dateGetter('Date', 1),
+ HH: dateGetter('Hours', 2),
+ H: dateGetter('Hours', 1),
+ hh: dateGetter('Hours', 2, -12),
+ h: dateGetter('Hours', 1, -12),
+ mm: dateGetter('Minutes', 2),
+ m: dateGetter('Minutes', 1),
+ ss: dateGetter('Seconds', 2),
+ s: dateGetter('Seconds', 1),
+ // while ISO 8601 requires fractions to be prefixed with `.` or `,`
+ // we can be just safely rely on using `sss` since we currently don't support single or two digit fractions
+ sss: dateGetter('Milliseconds', 3),
+ EEEE: dateStrGetter('Day'),
+ EEE: dateStrGetter('Day', true),
+ a: ampmGetter,
+ Z: timeZoneGetter,
+ ww: weekGetter(2),
+ w: weekGetter(1),
+ G: eraGetter,
+ GG: eraGetter,
+ GGG: eraGetter,
+ GGGG: longEraGetter
+ };
- scope.$digest();
- // but now it will not be called unless the value changes
- expect(scope.counter).toEqual(1);
+ var DATE_FORMATS_SPLIT = /((?:[^yMLdHhmsaZEwG']+)|(?:'(?:[^']|'')*')|(?:E+|y+|M+|L+|d+|H+|h+|m+|s+|a|Z|G+|w+))([\s\S]*)/,
+ NUMBER_STRING = /^-?\d+$/;
- scope.name = 'adam';
- scope.$digest();
- expect(scope.counter).toEqual(2);
- * ```
- *
- */
- $digest: function() {
- var watch, value, last, fn, get,
- watchers,
- dirty, ttl = TTL,
- next, current, target = this,
- watchLog = [],
- logIdx, asyncTask;
-
- beginPhase('$digest');
- // Check for changes to browser url that happened in sync before the call to $digest
- $browser.$$checkUrlChange();
-
- if (this === $rootScope && applyAsyncId !== null) {
- // If this is the root scope, and $applyAsync has scheduled a deferred $apply(), then
- // cancel the scheduled $apply and flush the queue of expressions to be evaluated.
- $browser.defer.cancel(applyAsyncId);
- flushApplyAsync();
- }
-
- lastDirtyWatch = null;
-
- do { // "while dirty" loop
- dirty = false;
- current = target;
-
- // It's safe for asyncQueuePosition to be a local variable here because this loop can't
- // be reentered recursively. Calling $digest from a function passed to $evalAsync would
- // lead to a '$digest already in progress' error.
- for (var asyncQueuePosition = 0; asyncQueuePosition < asyncQueue.length; asyncQueuePosition++) {
- try {
- asyncTask = asyncQueue[asyncQueuePosition];
- fn = asyncTask.fn;
- fn(asyncTask.scope, asyncTask.locals);
- } catch (e) {
- $exceptionHandler(e);
- }
- lastDirtyWatch = null;
- }
- asyncQueue.length = 0;
-
- traverseScopesLoop:
- do { // "traverse the scopes" loop
- if ((watchers = current.$$watchers)) {
- // process our watches
- watchers.$$digestWatchIndex = watchers.length;
- while (watchers.$$digestWatchIndex--) {
- try {
- watch = watchers[watchers.$$digestWatchIndex];
- // Most common watches are on primitives, in which case we can short
- // circuit it with === operator, only when === fails do we use .equals
- if (watch) {
- get = watch.get;
- if ((value = get(current)) !== (last = watch.last) &&
- !(watch.eq
- ? equals(value, last)
- : (isNumberNaN(value) && isNumberNaN(last)))) {
- dirty = true;
- lastDirtyWatch = watch;
- watch.last = watch.eq ? copy(value, null) : value;
- fn = watch.fn;
- fn(value, ((last === initWatchVal) ? value : last), current);
- if (ttl < 5) {
- logIdx = 4 - ttl;
- if (!watchLog[logIdx]) watchLog[logIdx] = [];
- watchLog[logIdx].push({
- msg: isFunction(watch.exp) ? 'fn: ' + (watch.exp.name || watch.exp.toString()) : watch.exp,
- newVal: value,
- oldVal: last
- });
- }
- } else if (watch === lastDirtyWatch) {
- // If the most recently dirty watcher is now clean, short circuit since the remaining watchers
- // have already been tested.
- dirty = false;
- break traverseScopesLoop;
- }
- }
- } catch (e) {
- $exceptionHandler(e);
- }
- }
- }
+ /**
+ * @ngdoc filter
+ * @name date
+ * @kind function
+ *
+ * @description
+ * Formats `date` to a string based on the requested `format`.
+ *
+ * `format` string can be composed of the following elements:
+ *
+ * * `'yyyy'`: 4 digit representation of year (e.g. AD 1 => 0001, AD 2010 => 2010)
+ * * `'yy'`: 2 digit representation of year, padded (00-99). (e.g. AD 2001 => 01, AD 2010 => 10)
+ * * `'y'`: 1 digit representation of year, e.g. (AD 1 => 1, AD 199 => 199)
+ * * `'MMMM'`: Month in year (January-December)
+ * * `'MMM'`: Month in year (Jan-Dec)
+ * * `'MM'`: Month in year, padded (01-12)
+ * * `'M'`: Month in year (1-12)
+ * * `'LLLL'`: Stand-alone month in year (January-December)
+ * * `'dd'`: Day in month, padded (01-31)
+ * * `'d'`: Day in month (1-31)
+ * * `'EEEE'`: Day in Week,(Sunday-Saturday)
+ * * `'EEE'`: Day in Week, (Sun-Sat)
+ * * `'HH'`: Hour in day, padded (00-23)
+ * * `'H'`: Hour in day (0-23)
+ * * `'hh'`: Hour in AM/PM, padded (01-12)
+ * * `'h'`: Hour in AM/PM, (1-12)
+ * * `'mm'`: Minute in hour, padded (00-59)
+ * * `'m'`: Minute in hour (0-59)
+ * * `'ss'`: Second in minute, padded (00-59)
+ * * `'s'`: Second in minute (0-59)
+ * * `'sss'`: Millisecond in second, padded (000-999)
+ * * `'a'`: AM/PM marker
+ * * `'Z'`: 4 digit (+sign) representation of the timezone offset (-1200-+1200)
+ * * `'ww'`: Week of year, padded (00-53). Week 01 is the week with the first Thursday of the year
+ * * `'w'`: Week of year (0-53). Week 1 is the week with the first Thursday of the year
+ * * `'G'`, `'GG'`, `'GGG'`: The abbreviated form of the era string (e.g. 'AD')
+ * * `'GGGG'`: The long form of the era string (e.g. 'Anno Domini')
+ *
+ * `format` string can also be one of the following predefined
+ * {@link guide/i18n localizable formats}:
+ *
+ * * `'medium'`: equivalent to `'MMM d, y h:mm:ss a'` for en_US locale
+ * (e.g. Sep 3, 2010 12:05:08 PM)
+ * * `'short'`: equivalent to `'M/d/yy h:mm a'` for en_US locale (e.g. 9/3/10 12:05 PM)
+ * * `'fullDate'`: equivalent to `'EEEE, MMMM d, y'` for en_US locale
+ * (e.g. Friday, September 3, 2010)
+ * * `'longDate'`: equivalent to `'MMMM d, y'` for en_US locale (e.g. September 3, 2010)
+ * * `'mediumDate'`: equivalent to `'MMM d, y'` for en_US locale (e.g. Sep 3, 2010)
+ * * `'shortDate'`: equivalent to `'M/d/yy'` for en_US locale (e.g. 9/3/10)
+ * * `'mediumTime'`: equivalent to `'h:mm:ss a'` for en_US locale (e.g. 12:05:08 PM)
+ * * `'shortTime'`: equivalent to `'h:mm a'` for en_US locale (e.g. 12:05 PM)
+ *
+ * `format` string can contain literal values. These need to be escaped by surrounding with single quotes (e.g.
+ * `"h 'in the morning'"`). In order to output a single quote, escape it - i.e., two single quotes in a sequence
+ * (e.g. `"h 'o''clock'"`).
+ *
+ * Any other characters in the `format` string will be output as-is.
+ *
+ * @param {(Date|number|string)} date Date to format either as Date object, milliseconds (string or
+ * number) or various ISO 8601 datetime string formats (e.g. yyyy-MM-ddTHH:mm:ss.sssZ and its
+ * shorter versions like yyyy-MM-ddTHH:mmZ, yyyy-MM-dd or yyyyMMddTHHmmssZ). If no timezone is
+ * specified in the string input, the time is considered to be in the local timezone.
+ * @param {string=} format Formatting rules (see Description). If not specified,
+ * `mediumDate` is used.
+ * @param {string=} timezone Timezone to be used for formatting. It understands UTC/GMT and the
+ * continental US time zone abbreviations, but for general use, use a time zone offset, for
+ * example, `'+0430'` (4 hours, 30 minutes east of the Greenwich meridian)
+ * If not specified, the timezone of the browser will be used.
+ * @returns {string} Formatted string or the input if input is not recognized as date/millis.
+ *
+ * @example
+
+
+ {{1288323623006 | date:'medium'}} :
+ {{1288323623006 | date:'medium'}}
+ {{1288323623006 | date:'yyyy-MM-dd HH:mm:ss Z'}} :
+ {{1288323623006 | date:'yyyy-MM-dd HH:mm:ss Z'}}
+ {{1288323623006 | date:'MM/dd/yyyy @ h:mma'}} :
+ {{'1288323623006' | date:'MM/dd/yyyy @ h:mma'}}
+ {{1288323623006 | date:"MM/dd/yyyy 'at' h:mma"}} :
+ {{'1288323623006' | date:"MM/dd/yyyy 'at' h:mma"}}
+
+
+ it('should format date', function() {
+ expect(element(by.binding("1288323623006 | date:'medium'")).getText()).
+ toMatch(/Oct 2\d, 2010 \d{1,2}:\d{2}:\d{2} (AM|PM)/);
+ expect(element(by.binding("1288323623006 | date:'yyyy-MM-dd HH:mm:ss Z'")).getText()).
+ toMatch(/2010-10-2\d \d{2}:\d{2}:\d{2} (-|\+)?\d{4}/);
+ expect(element(by.binding("'1288323623006' | date:'MM/dd/yyyy @ h:mma'")).getText()).
+ toMatch(/10\/2\d\/2010 @ \d{1,2}:\d{2}(AM|PM)/);
+ expect(element(by.binding("'1288323623006' | date:\"MM/dd/yyyy 'at' h:mma\"")).getText()).
+ toMatch(/10\/2\d\/2010 at \d{1,2}:\d{2}(AM|PM)/);
+ });
+
+
+ */
+ dateFilter.$inject = ['$locale'];
+ function dateFilter($locale) {
- // Insanity Warning: scope depth-first traversal
- // yes, this code is a bit crazy, but it works and we have tests to prove it!
- // this piece should be kept in sync with the traversal in $broadcast
- if (!(next = ((current.$$watchersCount && current.$$childHead) ||
- (current !== target && current.$$nextSibling)))) {
- while (current !== target && !(next = current.$$nextSibling)) {
- current = current.$parent;
- }
- }
- } while ((current = next));
+ var R_ISO8601_STR = /^(\d{4})-?(\d\d)-?(\d\d)(?:T(\d\d)(?::?(\d\d)(?::?(\d\d)(?:\.(\d+))?)?)?(Z|([+-])(\d\d):?(\d\d))?)?$/;
+ // 1 2 3 4 5 6 7 8 9 10 11
+ function jsonStringToDate(string) {
+ var match;
+ if (match = string.match(R_ISO8601_STR)) {
+ var date = new Date(0),
+ tzHour = 0,
+ tzMin = 0,
+ dateSetter = match[8] ? date.setUTCFullYear : date.setFullYear,
+ timeSetter = match[8] ? date.setUTCHours : date.setHours;
- // `break traverseScopesLoop;` takes us to here
+ if (match[9]) {
+ tzHour = toInt(match[9] + match[10]);
+ tzMin = toInt(match[9] + match[11]);
+ }
+ dateSetter.call(date, toInt(match[1]), toInt(match[2]) - 1, toInt(match[3]));
+ var h = toInt(match[4] || 0) - tzHour;
+ var m = toInt(match[5] || 0) - tzMin;
+ var s = toInt(match[6] || 0);
+ var ms = Math.round(parseFloat('0.' + (match[7] || 0)) * 1000);
+ timeSetter.call(date, h, m, s, ms);
+ return date;
+ }
+ return string;
+ }
- if ((dirty || asyncQueue.length) && !(ttl--)) {
- clearPhase();
- throw $rootScopeMinErr('infdig',
- '{0} $digest() iterations reached. Aborting!\n' +
- 'Watchers fired in the last 5 iterations: {1}',
- TTL, watchLog);
- }
+ return function (date, format, timezone) {
+ var text = '',
+ parts = [],
+ fn,
+ match;
- } while (dirty || asyncQueue.length);
+ format = format || 'mediumDate';
+ format = $locale.DATETIME_FORMATS[format] || format;
+ if (isString(date)) {
+ date = NUMBER_STRING.test(date) ? toInt(date) : jsonStringToDate(date);
+ }
- clearPhase();
+ if (isNumber(date)) {
+ date = new Date(date);
+ }
- // postDigestQueuePosition isn't local here because this loop can be reentered recursively.
- while (postDigestQueuePosition < postDigestQueue.length) {
- try {
- postDigestQueue[postDigestQueuePosition++]();
- } catch (e) {
- $exceptionHandler(e);
- }
+ if (!isDate(date) || !isFinite(date.getTime())) {
+ return date;
+ }
+
+ while (format) {
+ match = DATE_FORMATS_SPLIT.exec(format);
+ if (match) {
+ parts = concat(parts, match, 1);
+ format = parts.pop();
+ } else {
+ parts.push(format);
+ format = null;
}
- postDigestQueue.length = postDigestQueuePosition = 0;
+ }
- // Check for changes to browser url that happened during the $digest
- // (for which no event is fired; e.g. via `history.pushState()`)
- $browser.$$checkUrlChange();
- },
+ var dateTimezoneOffset = date.getTimezoneOffset();
+ if (timezone) {
+ dateTimezoneOffset = timezoneToOffset(timezone, dateTimezoneOffset);
+ date = convertTimezoneToLocal(date, timezone, true);
+ }
+ forEach(parts, function (value) {
+ fn = DATE_FORMATS[value];
+ text += fn ? fn(date, $locale.DATETIME_FORMATS, dateTimezoneOffset) : value === '\'\'' ? '\'' : value.replace(/(^'|'$)/g, '').replace(/''/g, '\'');
+ });
+ return text;
+ };
+ }
- /**
- * @ngdoc event
- * @name $rootScope.Scope#$destroy
- * @eventType broadcast on scope being destroyed
- *
- * @description
- * Broadcasted when a scope and its children are being destroyed.
- *
- * Note that, in AngularJS, there is also a `$destroy` jQuery event, which can be used to
- * clean up DOM bindings before an element is removed from the DOM.
- */
+ /**
+ * @ngdoc filter
+ * @name json
+ * @kind function
+ *
+ * @description
+ * Allows you to convert a JavaScript object into JSON string.
+ *
+ * This filter is mostly useful for debugging. When using the double curly {{value}} notation
+ * the binding is automatically converted to JSON.
+ *
+ * @param {*} object Any JavaScript object (including arrays and primitive types) to filter.
+ * @param {number=} spacing The number of spaces to use per indentation, defaults to 2.
+ * @returns {string} JSON string.
+ *
+ *
+ * @example
+
+
+ {{ {'name':'value'} | json }}
+ {{ {'name':'value'} | json:4 }}
+
+
+ it('should jsonify filtered objects', function() {
+ expect(element(by.id('default-spacing')).getText()).toMatch(/\{\n {2}"name": ?"value"\n}/);
+ expect(element(by.id('custom-spacing')).getText()).toMatch(/\{\n {4}"name": ?"value"\n}/);
+ });
+
+
+ *
+ */
+ function jsonFilter() {
+ return function (object, spacing) {
+ if (isUndefined(spacing)) {
+ spacing = 2;
+ }
+ return toJson(object, spacing);
+ };
+ }
- /**
- * @ngdoc method
- * @name $rootScope.Scope#$destroy
- * @kind function
- *
- * @description
- * Removes the current scope (and all of its children) from the parent scope. Removal implies
- * that calls to {@link ng.$rootScope.Scope#$digest $digest()} will no longer
- * propagate to the current scope and its children. Removal also implies that the current
- * scope is eligible for garbage collection.
- *
- * The `$destroy()` is usually used by directives such as
- * {@link ng.directive:ngRepeat ngRepeat} for managing the
- * unrolling of the loop.
- *
- * Just before a scope is destroyed, a `$destroy` event is broadcasted on this scope.
- * Application code can register a `$destroy` event handler that will give it a chance to
- * perform any necessary cleanup.
- *
- * Note that, in AngularJS, there is also a `$destroy` jQuery event, which can be used to
- * clean up DOM bindings before an element is removed from the DOM.
- */
- $destroy: function() {
- // We can't destroy a scope that has been already destroyed.
- if (this.$$destroyed) return;
- var parent = this.$parent;
+ /**
+ * @ngdoc filter
+ * @name lowercase
+ * @kind function
+ * @description
+ * Converts string to lowercase.
+ * @see angular.lowercase
+ */
+ var lowercaseFilter = valueFn(lowercase);
- this.$broadcast('$destroy');
- this.$$destroyed = true;
+ /**
+ * @ngdoc filter
+ * @name uppercase
+ * @kind function
+ * @description
+ * Converts string to uppercase.
+ * @see angular.uppercase
+ */
+ var uppercaseFilter = valueFn(uppercase);
- if (this === $rootScope) {
- //Remove handlers attached to window when $rootScope is removed
- $browser.$$applicationDestroyed();
- }
+ /**
+ * @ngdoc filter
+ * @name limitTo
+ * @kind function
+ *
+ * @description
+ * Creates a new array or string containing only a specified number of elements. The elements are
+ * taken from either the beginning or the end of the source array, string or number, as specified by
+ * the value and sign (positive or negative) of `limit`. Other array-like objects are also supported
+ * (e.g. array subclasses, NodeLists, jqLite/jQuery collections etc). If a number is used as input,
+ * it is converted to a string.
+ *
+ * @param {Array|ArrayLike|string|number} input - Array/array-like, string or number to be limited.
+ * @param {string|number} limit - The length of the returned array or string. If the `limit` number
+ * is positive, `limit` number of items from the beginning of the source array/string are copied.
+ * If the number is negative, `limit` number of items from the end of the source array/string
+ * are copied. The `limit` will be trimmed if it exceeds `array.length`. If `limit` is undefined,
+ * the input will be returned unchanged.
+ * @param {(string|number)=} begin - Index at which to begin limitation. As a negative index,
+ * `begin` indicates an offset from the end of `input`. Defaults to `0`.
+ * @returns {Array|string} A new sub-array or substring of length `limit` or less if the input had
+ * less than `limit` elements.
+ *
+ * @example
+
+
+
+
+
+ Limit {{numbers}} to:
+
+
+
Output numbers: {{ numbers | limitTo:numLimit }}
+
+ Limit {{letters}} to:
+
+
+
Output letters: {{ letters | limitTo:letterLimit }}
+
+ Limit {{longNumber}} to:
+
+
+
Output long number: {{ longNumber | limitTo:longNumberLimit }}
+
+
+
+ var numLimitInput = element(by.model('numLimit'));
+ var letterLimitInput = element(by.model('letterLimit'));
+ var longNumberLimitInput = element(by.model('longNumberLimit'));
+ var limitedNumbers = element(by.binding('numbers | limitTo:numLimit'));
+ var limitedLetters = element(by.binding('letters | limitTo:letterLimit'));
+ var limitedLongNumber = element(by.binding('longNumber | limitTo:longNumberLimit'));
+
+ it('should limit the number array to first three items', function() {
+ expect(numLimitInput.getAttribute('value')).toBe('3');
+ expect(letterLimitInput.getAttribute('value')).toBe('3');
+ expect(longNumberLimitInput.getAttribute('value')).toBe('3');
+ expect(limitedNumbers.getText()).toEqual('Output numbers: [1,2,3]');
+ expect(limitedLetters.getText()).toEqual('Output letters: abc');
+ expect(limitedLongNumber.getText()).toEqual('Output long number: 234');
+ });
+
+ // There is a bug in safari and protractor that doesn't like the minus key
+ // it('should update the output when -3 is entered', function() {
+ // numLimitInput.clear();
+ // numLimitInput.sendKeys('-3');
+ // letterLimitInput.clear();
+ // letterLimitInput.sendKeys('-3');
+ // longNumberLimitInput.clear();
+ // longNumberLimitInput.sendKeys('-3');
+ // expect(limitedNumbers.getText()).toEqual('Output numbers: [7,8,9]');
+ // expect(limitedLetters.getText()).toEqual('Output letters: ghi');
+ // expect(limitedLongNumber.getText()).toEqual('Output long number: 342');
+ // });
+
+ it('should not exceed the maximum size of input array', function() {
+ numLimitInput.clear();
+ numLimitInput.sendKeys('100');
+ letterLimitInput.clear();
+ letterLimitInput.sendKeys('100');
+ longNumberLimitInput.clear();
+ longNumberLimitInput.sendKeys('100');
+ expect(limitedNumbers.getText()).toEqual('Output numbers: [1,2,3,4,5,6,7,8,9]');
+ expect(limitedLetters.getText()).toEqual('Output letters: abcdefghi');
+ expect(limitedLongNumber.getText()).toEqual('Output long number: 2345432342');
+ });
+
+
+ */
+ function limitToFilter() {
+ return function (input, limit, begin) {
+ if (Math.abs(Number(limit)) === Infinity) {
+ limit = Number(limit);
+ } else {
+ limit = toInt(limit);
+ }
+ if (isNumberNaN(limit)) return input;
- incrementWatchersCount(this, -this.$$watchersCount);
- for (var eventName in this.$$listenerCount) {
- decrementListenerCount(this, this.$$listenerCount[eventName], eventName);
- }
+ if (isNumber(input)) input = input.toString();
+ if (!isArrayLike(input)) return input;
- // sever all the references to parent scopes (after this cleanup, the current scope should
- // not be retained by any of our references and should be eligible for garbage collection)
- if (parent && parent.$$childHead === this) parent.$$childHead = this.$$nextSibling;
- if (parent && parent.$$childTail === this) parent.$$childTail = this.$$prevSibling;
- if (this.$$prevSibling) this.$$prevSibling.$$nextSibling = this.$$nextSibling;
- if (this.$$nextSibling) this.$$nextSibling.$$prevSibling = this.$$prevSibling;
+ begin = !begin || isNaN(begin) ? 0 : toInt(begin);
+ begin = begin < 0 ? Math.max(0, input.length + begin) : begin;
- // Disable listeners, watchers and apply/digest methods
- this.$destroy = this.$digest = this.$apply = this.$evalAsync = this.$applyAsync = noop;
- this.$on = this.$watch = this.$watchGroup = function() { return noop; };
- this.$$listeners = {};
+ if (limit >= 0) {
+ return sliceFn(input, begin, begin + limit);
+ } else {
+ if (begin === 0) {
+ return sliceFn(input, limit, input.length);
+ } else {
+ return sliceFn(input, Math.max(0, begin + limit), begin);
+ }
+ }
+ };
+ }
- // Disconnect the next sibling to prevent `cleanUpScope` destroying those too
- this.$$nextSibling = null;
- cleanUpScope(this);
- },
+ function sliceFn(input, begin, end) {
+ if (isString(input)) return input.slice(begin, end);
- /**
- * @ngdoc method
- * @name $rootScope.Scope#$eval
- * @kind function
- *
- * @description
- * 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;
+ return slice.call(input, begin, end);
+ }
- expect(scope.$eval('a+b')).toEqual(3);
- expect(scope.$eval(function(scope){ return scope.a + scope.b; })).toEqual(3);
- * ```
- *
- * @param {(string|function())=} expression An angular expression to be executed.
- *
- * - `string`: execute using the rules as defined in {@link guide/expression expression}.
- * - `function(scope)`: execute the function with the current `scope` parameter.
- *
- * @param {(object)=} locals Local variables object, useful for overriding values in scope.
- * @returns {*} The result of evaluating the expression.
- */
- $eval: function(expr, locals) {
- return $parse(expr)(this, locals);
- },
+ /**
+ * @ngdoc filter
+ * @name orderBy
+ * @kind function
+ *
+ * @description
+ * Returns an array containing the items from the specified `collection`, ordered by a `comparator`
+ * function based on the values computed using the `expression` predicate.
+ *
+ * For example, `[{id: 'foo'}, {id: 'bar'}] | orderBy:'id'` would result in
+ * `[{id: 'bar'}, {id: 'foo'}]`.
+ *
+ * The `collection` can be an Array or array-like object (e.g. NodeList, jQuery object, TypedArray,
+ * String, etc).
+ *
+ * The `expression` can be a single predicate, or a list of predicates each serving as a tie-breaker
+ * for the preceding one. The `expression` is evaluated against each item and the output is used
+ * for comparing with other items.
+ *
+ * You can change the sorting order by setting `reverse` to `true`. By default, items are sorted in
+ * ascending order.
+ *
+ * The comparison is done using the `comparator` function. If none is specified, a default, built-in
+ * comparator is used (see below for details - in a nutshell, it compares numbers numerically and
+ * strings alphabetically).
+ *
+ * ### Under the hood
+ *
+ * Ordering the specified `collection` happens in two phases:
+ *
+ * 1. All items are passed through the predicate (or predicates), and the returned values are saved
+ * along with their type (`string`, `number` etc). For example, an item `{label: 'foo'}`, passed
+ * through a predicate that extracts the value of the `label` property, would be transformed to:
+ * ```
+ * {
+ * value: 'foo',
+ * type: 'string',
+ * index: ...
+ * }
+ * ```
+ * 2. The comparator function is used to sort the items, based on the derived values, types and
+ * indices.
+ *
+ * If you use a custom comparator, it will be called with pairs of objects of the form
+ * `{value: ..., type: '...', index: ...}` and is expected to return `0` if the objects are equal
+ * (as far as the comparator is concerned), `-1` if the 1st one should be ranked higher than the
+ * second, or `1` otherwise.
+ *
+ * In order to ensure that the sorting will be deterministic across platforms, if none of the
+ * specified predicates can distinguish between two items, `orderBy` will automatically introduce a
+ * dummy predicate that returns the item's index as `value`.
+ * (If you are using a custom comparator, make sure it can handle this predicate as well.)
+ *
+ * Finally, in an attempt to simplify things, if a predicate returns an object as the extracted
+ * value for an item, `orderBy` will try to convert that object to a primitive value, before passing
+ * it to the comparator. The following rules govern the conversion:
+ *
+ * 1. If the object has a `valueOf()` method that returns a primitive, its return value will be
+ * used instead.
+ * (If the object has a `valueOf()` method that returns another object, then the returned object
+ * will be used in subsequent steps.)
+ * 2. If the object has a custom `toString()` method (i.e. not the one inherited from `Object`) that
+ * returns a primitive, its return value will be used instead.
+ * (If the object has a `toString()` method that returns another object, then the returned object
+ * will be used in subsequent steps.)
+ * 3. No conversion; the object itself is used.
+ *
+ * ### The default comparator
+ *
+ * The default, built-in comparator should be sufficient for most usecases. In short, it compares
+ * numbers numerically, strings alphabetically (and case-insensitively), for objects falls back to
+ * using their index in the original collection, and sorts values of different types by type.
+ *
+ * More specifically, it follows these steps to determine the relative order of items:
+ *
+ * 1. If the compared values are of different types, compare the types themselves alphabetically.
+ * 2. If both values are of type `string`, compare them alphabetically in a case- and
+ * locale-insensitive way.
+ * 3. If both values are objects, compare their indices instead.
+ * 4. Otherwise, return:
+ * - `0`, if the values are equal (by strict equality comparison, i.e. using `===`).
+ * - `-1`, if the 1st value is "less than" the 2nd value (compared using the `<` operator).
+ * - `1`, otherwise.
+ *
+ * **Note:** If you notice numbers not being sorted as expected, make sure they are actually being
+ * saved as numbers and not strings.
+ * **Note:** For the purpose of sorting, `null` values are treated as the string `'null'` (i.e.
+ * `type: 'string'`, `value: 'null'`). This may cause unexpected sort order relative to
+ * other values.
+ *
+ * @param {Array|ArrayLike} collection - The collection (array or array-like object) to sort.
+ * @param {(Function|string|Array.)=} expression - A predicate (or list of
+ * predicates) to be used by the comparator to determine the order of elements.
+ *
+ * Can be one of:
+ *
+ * - `Function`: A getter function. This function will be called with each item as argument and
+ * the return value will be used for sorting.
+ * - `string`: An Angular expression. This expression will be evaluated against each item and the
+ * result will be used for sorting. For example, use `'label'` to sort by a property called
+ * `label` or `'label.substring(0, 3)'` to sort by the first 3 characters of the `label`
+ * property.
+ * (The result of a constant expression is interpreted as a property name to be used for
+ * comparison. For example, use `'"special name"'` (note the extra pair of quotes) to sort by a
+ * property called `special name`.)
+ * An expression can be optionally prefixed with `+` or `-` to control the sorting direction,
+ * ascending or descending. For example, `'+label'` or `'-label'`. If no property is provided,
+ * (e.g. `'+'` or `'-'`), the collection element itself is used in comparisons.
+ * - `Array`: An array of function and/or string predicates. If a predicate cannot determine the
+ * relative order of two items, the next predicate is used as a tie-breaker.
+ *
+ * **Note:** If the predicate is missing or empty then it defaults to `'+'`.
+ *
+ * @param {boolean=} reverse - If `true`, reverse the sorting order.
+ * @param {(Function)=} comparator - The comparator function used to determine the relative order of
+ * value pairs. If omitted, the built-in comparator will be used.
+ *
+ * @returns {Array} - The sorted array.
+ *
+ *
+ * @example
+ * ### Ordering a table with `ngRepeat`
+ *
+ * The example below demonstrates a simple {@link ngRepeat ngRepeat}, where the data is sorted by
+ * age in descending order (expression is set to `'-age'`). The `comparator` is not set, which means
+ * it defaults to the built-in comparator.
+ *
+
+
+
+
+
+ Name
+ Phone Number
+ Age
+
+
+ {{friend.name}}
+ {{friend.phone}}
+ {{friend.age}}
+
+
+
+
+
+ angular.module('orderByExample1', [])
+ .controller('ExampleController', ['$scope', function($scope) {
+ $scope.friends = [
+ {name: 'John', phone: '555-1212', age: 10},
+ {name: 'Mary', phone: '555-9876', age: 19},
+ {name: 'Mike', phone: '555-4321', age: 21},
+ {name: 'Adam', phone: '555-5678', age: 35},
+ {name: 'Julie', phone: '555-8765', age: 29}
+ ];
+ }]);
+
+
+ .friends {
+ border-collapse: collapse;
+ }
+
+ .friends th {
+ border-bottom: 1px solid;
+ }
+ .friends td, .friends th {
+ border-left: 1px solid;
+ padding: 5px 10px;
+ }
+ .friends td:first-child, .friends th:first-child {
+ border-left: none;
+ }
+
+
+ // Element locators
+ var names = element.all(by.repeater('friends').column('friend.name'));
+
+ it('should sort friends by age in reverse order', function() {
+ expect(names.get(0).getText()).toBe('Adam');
+ expect(names.get(1).getText()).toBe('Julie');
+ expect(names.get(2).getText()).toBe('Mike');
+ expect(names.get(3).getText()).toBe('Mary');
+ expect(names.get(4).getText()).toBe('John');
+ });
+
+
+ *
+ *
+ * @example
+ * ### Changing parameters dynamically
+ *
+ * All parameters can be changed dynamically. The next example shows how you can make the columns of
+ * a table sortable, by binding the `expression` and `reverse` parameters to scope properties.
+ *
+
+
+
+
Sort by = {{propertyName}}; reverse = {{reverse}}
+
+
Set to unsorted
+
+
+
+
+ Name
+
+
+
+ Phone Number
+
+
+
+ Age
+
+
+
+
+ {{friend.name}}
+ {{friend.phone}}
+ {{friend.age}}
+
+
+
+
+
+ angular.module('orderByExample2', [])
+ .controller('ExampleController', ['$scope', function($scope) {
+ var friends = [
+ {name: 'John', phone: '555-1212', age: 10},
+ {name: 'Mary', phone: '555-9876', age: 19},
+ {name: 'Mike', phone: '555-4321', age: 21},
+ {name: 'Adam', phone: '555-5678', age: 35},
+ {name: 'Julie', phone: '555-8765', age: 29}
+ ];
+
+ $scope.propertyName = 'age';
+ $scope.reverse = true;
+ $scope.friends = friends;
+
+ $scope.sortBy = function(propertyName) {
+ $scope.reverse = ($scope.propertyName === propertyName) ? !$scope.reverse : false;
+ $scope.propertyName = propertyName;
+ };
+ }]);
+
+
+ .friends {
+ border-collapse: collapse;
+ }
+
+ .friends th {
+ border-bottom: 1px solid;
+ }
+ .friends td, .friends th {
+ border-left: 1px solid;
+ padding: 5px 10px;
+ }
+ .friends td:first-child, .friends th:first-child {
+ border-left: none;
+ }
+
+ .sortorder:after {
+ content: '\25b2'; // BLACK UP-POINTING TRIANGLE
+ }
+ .sortorder.reverse:after {
+ content: '\25bc'; // BLACK DOWN-POINTING TRIANGLE
+ }
+
+
+ // Element locators
+ var unsortButton = element(by.partialButtonText('unsorted'));
+ var nameHeader = element(by.partialButtonText('Name'));
+ var phoneHeader = element(by.partialButtonText('Phone'));
+ var ageHeader = element(by.partialButtonText('Age'));
+ var firstName = element(by.repeater('friends').column('friend.name').row(0));
+ var lastName = element(by.repeater('friends').column('friend.name').row(4));
+
+ it('should sort friends by some property, when clicking on the column header', function() {
+ expect(firstName.getText()).toBe('Adam');
+ expect(lastName.getText()).toBe('John');
+
+ phoneHeader.click();
+ expect(firstName.getText()).toBe('John');
+ expect(lastName.getText()).toBe('Mary');
+
+ nameHeader.click();
+ expect(firstName.getText()).toBe('Adam');
+ expect(lastName.getText()).toBe('Mike');
+
+ ageHeader.click();
+ expect(firstName.getText()).toBe('John');
+ expect(lastName.getText()).toBe('Adam');
+ });
+
+ it('should sort friends in reverse order, when clicking on the same column', function() {
+ expect(firstName.getText()).toBe('Adam');
+ expect(lastName.getText()).toBe('John');
+
+ ageHeader.click();
+ expect(firstName.getText()).toBe('John');
+ expect(lastName.getText()).toBe('Adam');
+
+ ageHeader.click();
+ expect(firstName.getText()).toBe('Adam');
+ expect(lastName.getText()).toBe('John');
+ });
+
+ it('should restore the original order, when clicking "Set to unsorted"', function() {
+ expect(firstName.getText()).toBe('Adam');
+ expect(lastName.getText()).toBe('John');
+
+ unsortButton.click();
+ expect(firstName.getText()).toBe('John');
+ expect(lastName.getText()).toBe('Julie');
+ });
+
+
+ *
+ *
+ * @example
+ * ### Using `orderBy` inside a controller
+ *
+ * It is also possible to call the `orderBy` filter manually, by injecting `orderByFilter`, and
+ * calling it with the desired parameters. (Alternatively, you could inject the `$filter` factory
+ * and retrieve the `orderBy` filter with `$filter('orderBy')`.)
+ *
+
+
+
+
Sort by = {{propertyName}}; reverse = {{reverse}}
+
+
Set to unsorted
+
+
+
+
+ Name
+
+
+
+ Phone Number
+
+
+
+ Age
+
+
+
+
+ {{friend.name}}
+ {{friend.phone}}
+ {{friend.age}}
+
+
+
+
+
+ angular.module('orderByExample3', [])
+ .controller('ExampleController', ['$scope', 'orderByFilter', function($scope, orderBy) {
+ var friends = [
+ {name: 'John', phone: '555-1212', age: 10},
+ {name: 'Mary', phone: '555-9876', age: 19},
+ {name: 'Mike', phone: '555-4321', age: 21},
+ {name: 'Adam', phone: '555-5678', age: 35},
+ {name: 'Julie', phone: '555-8765', age: 29}
+ ];
+
+ $scope.propertyName = 'age';
+ $scope.reverse = true;
+ $scope.friends = orderBy(friends, $scope.propertyName, $scope.reverse);
+
+ $scope.sortBy = function(propertyName) {
+ $scope.reverse = (propertyName !== null && $scope.propertyName === propertyName)
+ ? !$scope.reverse : false;
+ $scope.propertyName = propertyName;
+ $scope.friends = orderBy(friends, $scope.propertyName, $scope.reverse);
+ };
+ }]);
+
+
+ .friends {
+ border-collapse: collapse;
+ }
+
+ .friends th {
+ border-bottom: 1px solid;
+ }
+ .friends td, .friends th {
+ border-left: 1px solid;
+ padding: 5px 10px;
+ }
+ .friends td:first-child, .friends th:first-child {
+ border-left: none;
+ }
+
+ .sortorder:after {
+ content: '\25b2'; // BLACK UP-POINTING TRIANGLE
+ }
+ .sortorder.reverse:after {
+ content: '\25bc'; // BLACK DOWN-POINTING TRIANGLE
+ }
+
+
+ // Element locators
+ var unsortButton = element(by.partialButtonText('unsorted'));
+ var nameHeader = element(by.partialButtonText('Name'));
+ var phoneHeader = element(by.partialButtonText('Phone'));
+ var ageHeader = element(by.partialButtonText('Age'));
+ var firstName = element(by.repeater('friends').column('friend.name').row(0));
+ var lastName = element(by.repeater('friends').column('friend.name').row(4));
+
+ it('should sort friends by some property, when clicking on the column header', function() {
+ expect(firstName.getText()).toBe('Adam');
+ expect(lastName.getText()).toBe('John');
+
+ phoneHeader.click();
+ expect(firstName.getText()).toBe('John');
+ expect(lastName.getText()).toBe('Mary');
+
+ nameHeader.click();
+ expect(firstName.getText()).toBe('Adam');
+ expect(lastName.getText()).toBe('Mike');
+
+ ageHeader.click();
+ expect(firstName.getText()).toBe('John');
+ expect(lastName.getText()).toBe('Adam');
+ });
+
+ it('should sort friends in reverse order, when clicking on the same column', function() {
+ expect(firstName.getText()).toBe('Adam');
+ expect(lastName.getText()).toBe('John');
+
+ ageHeader.click();
+ expect(firstName.getText()).toBe('John');
+ expect(lastName.getText()).toBe('Adam');
+
+ ageHeader.click();
+ expect(firstName.getText()).toBe('Adam');
+ expect(lastName.getText()).toBe('John');
+ });
+
+ it('should restore the original order, when clicking "Set to unsorted"', function() {
+ expect(firstName.getText()).toBe('Adam');
+ expect(lastName.getText()).toBe('John');
+
+ unsortButton.click();
+ expect(firstName.getText()).toBe('John');
+ expect(lastName.getText()).toBe('Julie');
+ });
+
+
+ *
+ *
+ * @example
+ * ### Using a custom comparator
+ *
+ * If you have very specific requirements about the way items are sorted, you can pass your own
+ * comparator function. For example, you might need to compare some strings in a locale-sensitive
+ * way. (When specifying a custom comparator, you also need to pass a value for the `reverse`
+ * argument - passing `false` retains the default sorting order, i.e. ascending.)
+ *
+
+
+
+
+
Locale-sensitive Comparator
+
+
+ Name
+ Favorite Letter
+
+
+ {{friend.name}}
+ {{friend.favoriteLetter}}
+
+
+
+
+
Default Comparator
+
+
+ Name
+ Favorite Letter
+
+
+ {{friend.name}}
+ {{friend.favoriteLetter}}
+
+
+
+
+
+
+ angular.module('orderByExample4', [])
+ .controller('ExampleController', ['$scope', function($scope) {
+ $scope.friends = [
+ {name: 'John', favoriteLetter: 'Ä'},
+ {name: 'Mary', favoriteLetter: 'Ü'},
+ {name: 'Mike', favoriteLetter: 'Ö'},
+ {name: 'Adam', favoriteLetter: 'H'},
+ {name: 'Julie', favoriteLetter: 'Z'}
+ ];
+
+ $scope.localeSensitiveComparator = function(v1, v2) {
+ // If we don't get strings, just compare by index
+ if (v1.type !== 'string' || v2.type !== 'string') {
+ return (v1.index < v2.index) ? -1 : 1;
+ }
+
+ // Compare strings alphabetically, taking locale into account
+ return v1.value.localeCompare(v2.value);
+ };
+ }]);
+
+
+ .friends-container {
+ display: inline-block;
+ margin: 0 30px;
+ }
+
+ .friends {
+ border-collapse: collapse;
+ }
+
+ .friends th {
+ border-bottom: 1px solid;
+ }
+ .friends td, .friends th {
+ border-left: 1px solid;
+ padding: 5px 10px;
+ }
+ .friends td:first-child, .friends th:first-child {
+ border-left: none;
+ }
+
+
+ // Element locators
+ var container = element(by.css('.custom-comparator'));
+ var names = container.all(by.repeater('friends').column('friend.name'));
+
+ it('should sort friends by favorite letter (in correct alphabetical order)', function() {
+ expect(names.get(0).getText()).toBe('John');
+ expect(names.get(1).getText()).toBe('Adam');
+ expect(names.get(2).getText()).toBe('Mike');
+ expect(names.get(3).getText()).toBe('Mary');
+ expect(names.get(4).getText()).toBe('Julie');
+ });
+
+
+ *
+ */
+ orderByFilter.$inject = ['$parse'];
+ function orderByFilter($parse) {
+ return function (array, sortPredicate, reverseOrder, compareFn) {
- /**
- * @ngdoc method
- * @name $rootScope.Scope#$evalAsync
- * @kind function
- *
- * @description
- * 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`.
- *
- * @param {(string|function())=} expression An angular expression to be executed.
- *
- * - `string`: execute using the rules as defined in {@link guide/expression expression}.
- * - `function(scope)`: execute the function with the current `scope` parameter.
- *
- * @param {(object)=} locals Local variables object, useful for overriding values in scope.
- */
- $evalAsync: function(expr, locals) {
- // if we are outside of an $digest loop and this is the first time we are scheduling async
- // task also schedule async auto-flush
- if (!$rootScope.$$phase && !asyncQueue.length) {
- $browser.defer(function() {
- if (asyncQueue.length) {
- $rootScope.$digest();
- }
- });
- }
+ if (array == null) return array;
+ if (!isArrayLike(array)) {
+ throw minErr('orderBy')('notarray', 'Expected array but received: {0}', array);
+ }
- asyncQueue.push({scope: this, fn: $parse(expr), locals: locals});
- },
+ if (!isArray(sortPredicate)) {
+ sortPredicate = [sortPredicate];
+ }
+ if (sortPredicate.length === 0) {
+ sortPredicate = ['+'];
+ }
- $$postDigest: function(fn) {
- postDigestQueue.push(fn);
- },
+ var predicates = processPredicates(sortPredicate);
- /**
- * @ngdoc method
- * @name $rootScope.Scope#$apply
- * @kind function
- *
- * @description
- * `$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.
- *
- *
- * @param {(string|function())=} exp An angular expression to be executed.
- *
- * - `string`: execute using the rules as defined in {@link guide/expression expression}.
- * - `function(scope)`: execute the function with current `scope` parameter.
- *
- * @returns {*} The result of evaluating the expression.
- */
- $apply: function(expr) {
- try {
- beginPhase('$apply');
- try {
- return this.$eval(expr);
- } finally {
- clearPhase();
- }
- } catch (e) {
- $exceptionHandler(e);
- } finally {
- try {
- $rootScope.$digest();
- } catch (e) {
- $exceptionHandler(e);
- // eslint-disable-next-line no-unsafe-finally
- throw e;
- }
- }
- },
+ var descending = reverseOrder ? -1 : 1;
- /**
- * @ngdoc method
- * @name $rootScope.Scope#$applyAsync
- * @kind function
- *
- * @description
- * 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.
- *
- * @param {(string|function())=} exp An angular expression to be executed.
- *
- * - `string`: execute using the rules as defined in {@link guide/expression expression}.
- * - `function(scope)`: execute the function with current `scope` parameter.
- */
- $applyAsync: function(expr) {
- var scope = this;
- if (expr) {
- applyAsyncQueue.push($applyAsyncExpression);
- }
- expr = $parse(expr);
- scheduleApplyAsync();
+ // Define the `compare()` function. Use a default comparator if none is specified.
+ var compare = isFunction(compareFn) ? compareFn : defaultCompare;
- function $applyAsyncExpression() {
- scope.$eval(expr);
- }
- },
+ // The next three lines are a version of a Swartzian Transform idiom from Perl
+ // (sometimes called the Decorate-Sort-Undecorate idiom)
+ // See https://en.wikipedia.org/wiki/Schwartzian_transform
+ var compareValues = Array.prototype.map.call(array, getComparisonObject);
+ compareValues.sort(doComparison);
+ array = compareValues.map(function (item) {
+ return item.value;
+ });
- /**
- * @ngdoc method
- * @name $rootScope.Scope#$on
- * @kind function
- *
- * @description
- * 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.
- *
- * @param {string} name Event name to listen on.
- * @param {function(event, ...args)} listener Function to call when the event is emitted.
- * @returns {function()} Returns a deregistration function for this listener.
- */
- $on: function(name, listener) {
- var namedListeners = this.$$listeners[name];
- if (!namedListeners) {
- this.$$listeners[name] = namedListeners = [];
- }
- namedListeners.push(listener);
+ return array;
- var current = this;
- do {
- if (!current.$$listenerCount[name]) {
- current.$$listenerCount[name] = 0;
- }
- current.$$listenerCount[name]++;
- } while ((current = current.$parent));
-
- var self = this;
- return function() {
- var indexOfListener = namedListeners.indexOf(listener);
- if (indexOfListener !== -1) {
- namedListeners[indexOfListener] = null;
- decrementListenerCount(self, 1, name);
- }
+ function getComparisonObject(value, index) {
+ // NOTE: We are adding an extra `tieBreaker` value based on the element's index.
+ // This will be used to keep the sort stable when none of the input predicates can
+ // distinguish between two elements.
+ return {
+ value: value,
+ tieBreaker: { value: index, type: 'number', index: index },
+ predicateValues: predicates.map(function (predicate) {
+ return getPredicateValue(predicate.get(value), index);
+ })
};
- },
-
-
- /**
- * @ngdoc method
- * @name $rootScope.Scope#$emit
- * @kind function
- *
- * @description
- * 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.
- *
- * @param {string} name Event name to emit.
- * @param {...*} args Optional one or more arguments which will be passed onto the event listeners.
- * @return {Object} Event object (see {@link ng.$rootScope.Scope#$on}).
- */
- $emit: function(name, args) {
- var empty = [],
- namedListeners,
- scope = this,
- stopPropagation = false,
- event = {
- name: name,
- targetScope: scope,
- stopPropagation: function() {stopPropagation = true;},
- preventDefault: function() {
- event.defaultPrevented = true;
- },
- defaultPrevented: false
- },
- listenerArgs = concat([event], arguments, 1),
- i, length;
-
- do {
- namedListeners = scope.$$listeners[name] || empty;
- event.currentScope = scope;
- for (i = 0, length = namedListeners.length; i < length; i++) {
+ }
- // if listeners were deregistered, defragment the array
- if (!namedListeners[i]) {
- namedListeners.splice(i, 1);
- i--;
- length--;
- continue;
- }
- try {
- //allow all listeners attached to the current scope to run
- namedListeners[i].apply(null, listenerArgs);
- } catch (e) {
- $exceptionHandler(e);
- }
- }
- //if any listener on the current scope stops propagation, prevent bubbling
- if (stopPropagation) {
- event.currentScope = null;
- return event;
+ function doComparison(v1, v2) {
+ for (var i = 0, ii = predicates.length; i < ii; i++) {
+ var result = compare(v1.predicateValues[i], v2.predicateValues[i]);
+ if (result) {
+ return result * predicates[i].descending * descending;
}
- //traverse upwards
- scope = scope.$parent;
- } while (scope);
-
- event.currentScope = null;
-
- return event;
- },
-
-
- /**
- * @ngdoc method
- * @name $rootScope.Scope#$broadcast
- * @kind function
- *
- * @description
- * 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.
- *
- * @param {string} name Event name to broadcast.
- * @param {...*} args Optional one or more arguments which will be passed onto the event listeners.
- * @return {Object} Event object, see {@link ng.$rootScope.Scope#$on}
- */
- $broadcast: function(name, args) {
- var target = this,
- current = target,
- next = target,
- event = {
- name: name,
- targetScope: target,
- preventDefault: function() {
- event.defaultPrevented = true;
- },
- defaultPrevented: false
- };
-
- if (!target.$$listenerCount[name]) return event;
-
- var listenerArgs = concat([event], arguments, 1),
- listeners, i, length;
+ }
- //down while you can, then up and next sibling or up and next sibling until back at root
- while ((current = next)) {
- event.currentScope = current;
- listeners = current.$$listeners[name] || [];
- for (i = 0, length = listeners.length; i < length; i++) {
- // if listeners were deregistered, defragment the array
- if (!listeners[i]) {
- listeners.splice(i, 1);
- i--;
- length--;
- continue;
- }
+ return compare(v1.tieBreaker, v2.tieBreaker) * descending;
+ }
+ };
- try {
- listeners[i].apply(null, listenerArgs);
- } catch (e) {
- $exceptionHandler(e);
- }
+ function processPredicates(sortPredicates) {
+ return sortPredicates.map(function (predicate) {
+ var descending = 1,
+ get = identity;
+
+ if (isFunction(predicate)) {
+ get = predicate;
+ } else if (isString(predicate)) {
+ if (predicate.charAt(0) === '+' || predicate.charAt(0) === '-') {
+ descending = predicate.charAt(0) === '-' ? -1 : 1;
+ predicate = predicate.substring(1);
}
-
- // Insanity Warning: scope depth-first traversal
- // yes, this code is a bit crazy, but it works and we have tests to prove it!
- // this piece should be kept in sync with the traversal in $digest
- // (though it differs due to having the extra check for $$listenerCount)
- if (!(next = ((current.$$listenerCount[name] && current.$$childHead) ||
- (current !== target && current.$$nextSibling)))) {
- while (current !== target && !(next = current.$$nextSibling)) {
- current = current.$parent;
+ if (predicate !== '') {
+ get = $parse(predicate);
+ if (get.constant) {
+ var key = get();
+ get = function get(value) {
+ return value[key];
+ };
}
}
}
+ return { get: get, descending: descending };
+ });
+ }
- event.currentScope = null;
- return event;
+ function isPrimitive(value) {
+ switch (typeof value === 'undefined' ? 'undefined' : _typeof(value)) {
+ case 'number': /* falls through */
+ case 'boolean': /* falls through */
+ case 'string':
+ return true;
+ default:
+ return false;
}
- };
-
- var $rootScope = new Scope();
-
- //The internal queues. Expose them on the $rootScope for debugging/testing purposes.
- var asyncQueue = $rootScope.$$asyncQueue = [];
- var postDigestQueue = $rootScope.$$postDigestQueue = [];
- var applyAsyncQueue = $rootScope.$$applyAsyncQueue = [];
-
- var postDigestQueuePosition = 0;
-
- return $rootScope;
-
+ }
- function beginPhase(phase) {
- if ($rootScope.$$phase) {
- throw $rootScopeMinErr('inprog', '{0} already in progress', $rootScope.$$phase);
+ function objectValue(value) {
+ // If `valueOf` is a valid function use that
+ if (isFunction(value.valueOf)) {
+ value = value.valueOf();
+ if (isPrimitive(value)) return value;
+ }
+ // If `toString` is a valid function and not the one from `Object.prototype` use that
+ if (hasCustomToString(value)) {
+ value = value.toString();
+ if (isPrimitive(value)) return value;
}
- $rootScope.$$phase = phase;
+ return value;
}
- function clearPhase() {
- $rootScope.$$phase = null;
+ function getPredicateValue(value, index) {
+ var type = typeof value === 'undefined' ? 'undefined' : _typeof(value);
+ if (value === null) {
+ type = 'string';
+ value = 'null';
+ } else if (type === 'object') {
+ value = objectValue(value);
+ }
+ return { value: value, type: type, index: index };
}
- function incrementWatchersCount(current, count) {
- do {
- current.$$watchersCount += count;
- } while ((current = current.$parent));
- }
+ function defaultCompare(v1, v2) {
+ var result = 0;
+ var type1 = v1.type;
+ var type2 = v2.type;
- function decrementListenerCount(current, count, name) {
- do {
- current.$$listenerCount[name] -= count;
+ if (type1 === type2) {
+ var value1 = v1.value;
+ var value2 = v2.value;
- if (current.$$listenerCount[name] === 0) {
- delete current.$$listenerCount[name];
+ if (type1 === 'string') {
+ // Compare strings case-insensitively
+ value1 = value1.toLowerCase();
+ value2 = value2.toLowerCase();
+ } else if (type1 === 'object') {
+ // For basic objects, use the position of the object
+ // in the collection instead of the value
+ if (isObject(value1)) value1 = v1.index;
+ if (isObject(value2)) value2 = v2.index;
}
- } while ((current = current.$parent));
- }
-
- /**
- * function used as an initial value for watchers.
- * because it's unique we can easily tell it apart from other values
- */
- function initWatchVal() {}
- function flushApplyAsync() {
- while (applyAsyncQueue.length) {
- try {
- applyAsyncQueue.shift()();
- } catch (e) {
- $exceptionHandler(e);
+ if (value1 !== value2) {
+ result = value1 < value2 ? -1 : 1;
}
+ } else {
+ result = type1 < type2 ? -1 : 1;
}
- applyAsyncId = null;
- }
- function scheduleApplyAsync() {
- if (applyAsyncId === null) {
- applyAsyncId = $browser.defer(function() {
- $rootScope.$apply(flushApplyAsync);
- });
- }
+ return result;
}
- }];
-}
-
-/**
- * @ngdoc service
- * @name $rootElement
- *
- * @description
- * The root element of Angular application. This is either the element where {@link
- * ng.directive:ngApp ngApp} was declared or the element passed into
- * {@link angular.bootstrap}. The element represents the root element of application. It is also the
- * location where the application's {@link auto.$injector $injector} service gets
- * published, and can be retrieved using `$rootElement.injector()`.
- */
-
+ }
-// the implementation is in angular.bootstrap
+ function ngDirective(directive) {
+ if (isFunction(directive)) {
+ directive = {
+ link: directive
+ };
+ }
+ directive.restrict = directive.restrict || 'AC';
+ return valueFn(directive);
+ }
-/**
- * @this
- * @description
- * Private service to sanitize uris for links and images. Used by $compile and $sanitize.
- */
-function $$SanitizeUriProvider() {
- var aHrefSanitizationWhitelist = /^\s*(https?|ftp|mailto|tel|file):/,
- imgSrcSanitizationWhitelist = /^\s*((https?|ftp|file|blob):|data:image\/)/;
+ /**
+ * @ngdoc directive
+ * @name a
+ * @restrict E
+ *
+ * @description
+ * Modifies the default behavior of the html a tag so that the default action is prevented when
+ * the href attribute is empty.
+ *
+ * For dynamically creating `href` attributes for a tags, see the {@link ng.ngHref `ngHref`} directive.
+ */
+ var htmlAnchorDirective = valueFn({
+ restrict: 'E',
+ compile: function compile(element, attr) {
+ if (!attr.href && !attr.xlinkHref) {
+ return function (scope, element) {
+ // If the linked element is not an anchor tag anymore, do nothing
+ if (element[0].nodeName.toLowerCase() !== 'a') return;
+
+ // SVGAElement does not use the href attribute, but rather the 'xlinkHref' attribute.
+ var href = toString.call(element.prop('href')) === '[object SVGAnimatedString]' ? 'xlink:href' : 'href';
+ element.on('click', function (event) {
+ // if we have no href url, then don't navigate anywhere.
+ if (!element.attr(href)) {
+ event.preventDefault();
+ }
+ });
+ };
+ }
+ }
+ });
/**
+ * @ngdoc directive
+ * @name ngHref
+ * @restrict A
+ * @priority 99
+ *
* @description
- * Retrieves or overrides the default regular expression that is used for whitelisting of safe
- * urls during a[href] sanitization.
+ * Using Angular markup like `{{hash}}` in an href attribute will
+ * make the link go to the wrong URL if the user clicks it before
+ * Angular has a chance to replace the `{{hash}}` markup with its
+ * value. Until Angular replaces the markup the link will be broken
+ * and will most likely return a 404 error. The `ngHref` directive
+ * solves this problem.
+ *
+ * The wrong way to write it:
+ * ```html
+ * link1
+ * ```
*
- * The sanitization is a security measure aimed at prevent XSS attacks via html links.
+ * The correct way to write it:
+ * ```html
+ * link1
+ * ```
*
- * 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.
+ * @element A
+ * @param {template} ngHref any string which can contain `{{}}` markup.
*
- * @param {RegExp=} regexp New regexp to whitelist urls with.
- * @returns {RegExp|ng.$compileProvider} Current RegExp if called without value or self for
- * chaining otherwise.
+ * @example
+ * This example shows various combinations of `href`, `ng-href` and `ng-click` attributes
+ * in links and their different behaviors:
+
+
+
+ link 1 (link, don't reload)
+ link 2 (link, don't reload)
+ link 3 (link, reload!)
+ anchor (link, don't reload)
+ anchor (no link)
+ link (link, change location)
+
+
+ it('should execute ng-click but not reload when href without value', function() {
+ element(by.id('link-1')).click();
+ expect(element(by.model('value')).getAttribute('value')).toEqual('1');
+ expect(element(by.id('link-1')).getAttribute('href')).toBe('');
+ });
+
+ it('should execute ng-click but not reload when href empty string', function() {
+ element(by.id('link-2')).click();
+ expect(element(by.model('value')).getAttribute('value')).toEqual('2');
+ expect(element(by.id('link-2')).getAttribute('href')).toBe('');
+ });
+
+ it('should execute ng-click and change url when ng-href specified', function() {
+ expect(element(by.id('link-3')).getAttribute('href')).toMatch(/\/123$/);
+
+ element(by.id('link-3')).click();
+
+ // At this point, we navigate away from an Angular page, so we need
+ // to use browser.driver to get the base webdriver.
+
+ browser.wait(function() {
+ return browser.driver.getCurrentUrl().then(function(url) {
+ return url.match(/\/123$/);
+ });
+ }, 5000, 'page should navigate to /123');
+ });
+
+ it('should execute ng-click but not reload when href empty string and name specified', function() {
+ element(by.id('link-4')).click();
+ expect(element(by.model('value')).getAttribute('value')).toEqual('4');
+ expect(element(by.id('link-4')).getAttribute('href')).toBe('');
+ });
+
+ it('should execute ng-click but not reload when no href but name specified', function() {
+ element(by.id('link-5')).click();
+ expect(element(by.model('value')).getAttribute('value')).toEqual('5');
+ expect(element(by.id('link-5')).getAttribute('href')).toBe(null);
+ });
+
+ it('should only change url when only ng-href', function() {
+ element(by.model('value')).clear();
+ element(by.model('value')).sendKeys('6');
+ expect(element(by.id('link-6')).getAttribute('href')).toMatch(/\/6$/);
+
+ element(by.id('link-6')).click();
+
+ // At this point, we navigate away from an Angular page, so we need
+ // to use browser.driver to get the base webdriver.
+ browser.wait(function() {
+ return browser.driver.getCurrentUrl().then(function(url) {
+ return url.match(/\/6$/);
+ });
+ }, 5000, 'page should navigate to /6');
+ });
+
+
*/
- this.aHrefSanitizationWhitelist = function(regexp) {
- if (isDefined(regexp)) {
- aHrefSanitizationWhitelist = regexp;
- return this;
- }
- return aHrefSanitizationWhitelist;
- };
-
/**
+ * @ngdoc directive
+ * @name ngSrc
+ * @restrict A
+ * @priority 99
+ *
* @description
- * Retrieves or overrides the default regular expression that is used for whitelisting of safe
- * urls during img[src] sanitization.
+ * Using Angular markup like `{{hash}}` in a `src` attribute doesn't
+ * work right: The browser will fetch from the URL with the literal
+ * text `{{hash}}` until Angular replaces the expression inside
+ * `{{hash}}`. The `ngSrc` directive solves this problem.
*
- * The sanitization is a security measure aimed at prevent XSS attacks via html links.
+ * The buggy way to write it:
+ * ```html
+ *
+ * ```
*
- * 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.
+ * The correct way to write it:
+ * ```html
+ *
+ * ```
*
- * @param {RegExp=} regexp New regexp to whitelist urls with.
- * @returns {RegExp|ng.$compileProvider} Current RegExp if called without value or self for
- * chaining otherwise.
+ * @element IMG
+ * @param {template} ngSrc any string which can contain `{{}}` markup.
*/
- this.imgSrcSanitizationWhitelist = function(regexp) {
- if (isDefined(regexp)) {
- imgSrcSanitizationWhitelist = regexp;
- return this;
- }
- return imgSrcSanitizationWhitelist;
- };
-
- this.$get = function() {
- return function sanitizeUri(uri, isImage) {
- var regex = isImage ? imgSrcSanitizationWhitelist : aHrefSanitizationWhitelist;
- var normalizedVal;
- normalizedVal = urlResolve(uri).href;
- if (normalizedVal !== '' && !normalizedVal.match(regex)) {
- return 'unsafe:' + normalizedVal;
- }
- return uri;
- };
- };
-}
-
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
- * 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 likes document or window? *
- * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-
-/* exported $SceProvider, $SceDelegateProvider */
-
-var $sceMinErr = minErr('$sce');
-
-var SCE_CONTEXTS = {
- // HTML is used when there's HTML rendered (e.g. ng-bind-html, iframe srcdoc binding).
- HTML: 'html',
-
- // Style statements or stylesheets. Currently unused in AngularJS.
- CSS: 'css',
-
- // An URL used in a context where it does not refer to a resource that loads code. Currently
- // unused in AngularJS.
- URL: 'url',
-
- // RESOURCE_URL is a subtype of URL used where the referred-to resource could be interpreted as
- // code. (e.g. ng-include, script src binding, templateUrl)
- RESOURCE_URL: 'resourceUrl',
-
- // Script. Currently unused in AngularJS.
- JS: 'js'
-};
-
-// Helper functions follow.
-
-var UNDERSCORE_LOWERCASE_REGEXP = /_([a-z])/g;
-
-function snakeToCamel(name) {
- return name
- .replace(UNDERSCORE_LOWERCASE_REGEXP, fnCamelCaseReplace);
-}
-
-function adjustMatcher(matcher) {
- if (matcher === 'self') {
- return matcher;
- } else if (isString(matcher)) {
- // Strings match exactly except for 2 wildcards - '*' and '**'.
- // '*' matches any character except those from the set ':/.?&'.
- // '**' matches any character (like .* in a RegExp).
- // More than 2 *'s raises an error as it's ill defined.
- if (matcher.indexOf('***') > -1) {
- throw $sceMinErr('iwcard',
- 'Illegal sequence *** in string matcher. String: {0}', matcher);
- }
- matcher = escapeForRegexp(matcher).
- replace(/\\\*\\\*/g, '.*').
- replace(/\\\*/g, '[^:/.?&;]*');
- return new RegExp('^' + matcher + '$');
- } else if (isRegExp(matcher)) {
- // The only other type of matcher allowed is a Regexp.
- // Match entire URL / disallow partial matches.
- // Flags are reset (i.e. no global, ignoreCase or multiline)
- return new RegExp('^' + matcher.source + '$');
- } else {
- throw $sceMinErr('imatcher',
- 'Matchers may only be "self", string patterns or RegExp objects');
- }
-}
-
-
-function adjustMatchers(matchers) {
- var adjustedMatchers = [];
- if (isDefined(matchers)) {
- forEach(matchers, function(matcher) {
- adjustedMatchers.push(adjustMatcher(matcher));
- });
- }
- return adjustedMatchers;
-}
-
-
-/**
- * @ngdoc service
- * @name $sceDelegate
- * @kind function
- *
- * @description
- *
- * `$sceDelegate` is a service that is used by the `$sce` service to provide {@link ng.$sce Strict
- * Contextual Escaping (SCE)} services to AngularJS.
- *
- * For an overview of this service and the functionnality it provides in AngularJS, see the main
- * page for {@link ng.$sce SCE}. The current page is targeted for developers who need to alter how
- * SCE works in their application, which shouldn't be needed in most cases.
- *
- *
- * AngularJS strongly relies on contextual escaping for the security of bindings: disabling or
- * modifying this might cause cross site scripting (XSS) vulnerabilities. For libraries owners,
- * changes to this service will also influence users, so be extra careful and document your changes.
- *
- *
- * Typically, you would configure or override the {@link ng.$sceDelegate $sceDelegate} instead of
- * the `$sce` service to customize the way Strict Contextual Escaping works in AngularJS. This is
- * because, while the `$sce` provides numerous shorthand methods, etc., you really only need to
- * override 3 core functions (`trustAs`, `getTrusted` and `valueOf`) to replace the way things
- * work because `$sce` delegates to `$sceDelegate` for these operations.
- *
- * Refer {@link ng.$sceDelegateProvider $sceDelegateProvider} to configure this service.
- *
- * The default instance of `$sceDelegate` should work out of the box with little pain. While you
- * can override it completely to change the behavior of `$sce`, the common case would
- * involve configuring the {@link ng.$sceDelegateProvider $sceDelegateProvider} instead by setting
- * your own whitelists and blacklists for trusting URLs used for loading AngularJS resources such as
- * templates. Refer {@link ng.$sceDelegateProvider#resourceUrlWhitelist
- * $sceDelegateProvider.resourceUrlWhitelist} and {@link
- * ng.$sceDelegateProvider#resourceUrlBlacklist $sceDelegateProvider.resourceUrlBlacklist}
- */
-/**
- * @ngdoc provider
- * @name $sceDelegateProvider
- * @this
- *
- * @description
- *
- * The `$sceDelegateProvider` provider allows developers to configure the {@link ng.$sceDelegate
- * $sceDelegate service}, used as a delegate for {@link ng.$sce Strict Contextual Escaping (SCE)}.
- *
- * The `$sceDelegateProvider` allows one to get/set the whitelists and blacklists used to ensure
- * that the URLs used for sourcing AngularJS templates and other script-running URLs are safe (all
- * places that use the `$sce.RESOURCE_URL` context). See
- * {@link ng.$sceDelegateProvider#resourceUrlWhitelist $sceDelegateProvider.resourceUrlWhitelist}
- * and
- * {@link ng.$sceDelegateProvider#resourceUrlBlacklist $sceDelegateProvider.resourceUrlBlacklist},
- *
- * For the general details about this service in Angular, read the main page for {@link ng.$sce
- * Strict Contextual Escaping (SCE)}.
- *
- * **Example**: Consider the following case.
- *
- * - your app is hosted at url `http://myapp.example.com/`
- * - but some of your templates are hosted on other domains you control such as
- * `http://srv01.assets.example.com/`, `http://srv02.assets.example.com/`, etc.
- * - and you have an open redirect at `http://myapp.example.com/clickThru?...`.
- *
- * Here is what a secure configuration for this scenario might look like:
- *
- * ```
- * angular.module('myApp', []).config(function($sceDelegateProvider) {
- * $sceDelegateProvider.resourceUrlWhitelist([
- * // Allow same origin resource loads.
- * 'self',
- * // Allow loading from our assets domain. Notice the difference between * and **.
- * 'http://srv*.assets.example.com/**'
- * ]);
- *
- * // The blacklist overrides the whitelist so the open redirect here is blocked.
- * $sceDelegateProvider.resourceUrlBlacklist([
- * 'http://myapp.example.com/clickThru**'
- * ]);
- * });
- * ```
- * Note that an empty whitelist will block every resource URL from being loaded, and will require
- * you to manually mark each one as trusted with `$sce.trustAsResourceUrl`. However, templates
- * requested by {@link ng.$templateRequest $templateRequest} that are present in
- * {@link ng.$templateCache $templateCache} will not go through this check. If you have a mechanism
- * to populate your templates in that cache at config time, then it is a good idea to remove 'self'
- * from that whitelist. This helps to mitigate the security impact of certain types of issues, like
- * for instance attacker-controlled `ng-includes`.
- */
+ /**
+ * @ngdoc directive
+ * @name ngSrcset
+ * @restrict A
+ * @priority 99
+ *
+ * @description
+ * Using Angular markup like `{{hash}}` in a `srcset` attribute doesn't
+ * work right: The browser will fetch from the URL with the literal
+ * text `{{hash}}` until Angular replaces the expression inside
+ * `{{hash}}`. The `ngSrcset` directive solves this problem.
+ *
+ * The buggy way to write it:
+ * ```html
+ *
+ * ```
+ *
+ * The correct way to write it:
+ * ```html
+ *
+ * ```
+ *
+ * @element IMG
+ * @param {template} ngSrcset any string which can contain `{{}}` markup.
+ */
-function $SceDelegateProvider() {
- this.SCE_CONTEXTS = SCE_CONTEXTS;
+ /**
+ * @ngdoc directive
+ * @name ngDisabled
+ * @restrict A
+ * @priority 100
+ *
+ * @description
+ *
+ * This directive sets the `disabled` attribute on the element (typically a form control,
+ * e.g. `input`, `button`, `select` etc.) if the
+ * {@link guide/expression expression} inside `ngDisabled` evaluates to truthy.
+ *
+ * A special directive is necessary because we cannot use interpolation inside the `disabled`
+ * attribute. See the {@link guide/interpolation interpolation guide} for more info.
+ *
+ * @example
+
+
+ Click me to toggle:
+ Button
+
+
+ it('should toggle button', function() {
+ expect(element(by.css('button')).getAttribute('disabled')).toBeFalsy();
+ element(by.model('checked')).click();
+ expect(element(by.css('button')).getAttribute('disabled')).toBeTruthy();
+ });
+
+
+ *
+ * @element INPUT
+ * @param {expression} ngDisabled If the {@link guide/expression expression} is truthy,
+ * then the `disabled` attribute will be set on the element
+ */
- // Resource URLs can also be trusted by policy.
- var resourceUrlWhitelist = ['self'],
- resourceUrlBlacklist = [];
+ /**
+ * @ngdoc directive
+ * @name ngChecked
+ * @restrict A
+ * @priority 100
+ *
+ * @description
+ * Sets the `checked` attribute on the element, if the expression inside `ngChecked` is truthy.
+ *
+ * Note that this directive should not be used together with {@link ngModel `ngModel`},
+ * as this can lead to unexpected behavior.
+ *
+ * A special directive is necessary because we cannot use interpolation inside the `checked`
+ * attribute. See the {@link guide/interpolation interpolation guide} for more info.
+ *
+ * @example
+
+
+ Check me to check both:
+
+
+
+ it('should check both checkBoxes', function() {
+ expect(element(by.id('checkSlave')).getAttribute('checked')).toBeFalsy();
+ element(by.model('master')).click();
+ expect(element(by.id('checkSlave')).getAttribute('checked')).toBeTruthy();
+ });
+
+
+ *
+ * @element INPUT
+ * @param {expression} ngChecked If the {@link guide/expression expression} is truthy,
+ * then the `checked` attribute will be set on the element
+ */
/**
- * @ngdoc method
- * @name $sceDelegateProvider#resourceUrlWhitelist
- * @kind function
+ * @ngdoc directive
+ * @name ngReadonly
+ * @restrict A
+ * @priority 100
+ *
+ * @description
+ *
+ * Sets the `readonly` attribute on the element, if the expression inside `ngReadonly` is truthy.
+ * Note that `readonly` applies only to `input` elements with specific types. [See the input docs on
+ * MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-readonly) for more information.
*
- * @param {Array=} whitelist When provided, replaces the resourceUrlWhitelist with the value
- * provided. This must be an array or null. A snapshot of this array is used so further
- * changes to the array are ignored.
- * Follow {@link ng.$sce#resourceUrlPatternItem this link} for a description of the items
- * allowed in this array.
+ * A special directive is necessary because we cannot use interpolation inside the `readonly`
+ * attribute. See the {@link guide/interpolation interpolation guide} for more info.
+ *
+ * @example
+
+
+ Check me to make text readonly:
+
+
+
+ it('should toggle readonly attr', function() {
+ expect(element(by.css('[type="text"]')).getAttribute('readonly')).toBeFalsy();
+ element(by.model('checked')).click();
+ expect(element(by.css('[type="text"]')).getAttribute('readonly')).toBeTruthy();
+ });
+
+
*
- * @return {Array} The currently set whitelist array.
+ * @element INPUT
+ * @param {expression} ngReadonly If the {@link guide/expression expression} is truthy,
+ * then special attribute "readonly" will be set on the element
+ */
+
+ /**
+ * @ngdoc directive
+ * @name ngSelected
+ * @restrict A
+ * @priority 100
*
* @description
- * Sets/Gets the whitelist of trusted resource URLs.
*
- * The **default value** when no whitelist has been explicitly set is `['self']` allowing only
- * same origin resource requests.
+ * Sets the `selected` attribute on the element, if the expression inside `ngSelected` is truthy.
+ *
+ * A special directive is necessary because we cannot use interpolation inside the `selected`
+ * attribute. See the {@link guide/interpolation interpolation guide} for more info.
*
*
- * **Note:** the default whitelist of 'self' is not recommended if your app shares its origin
- * with other apps! It is a good idea to limit it to only your application's directory.
+ * **Note:** `ngSelected` does not interact with the `select` and `ngModel` directives, it only
+ * sets the `selected` attribute on the element. If you are using `ngModel` on the select, you
+ * should not use `ngSelected` on the options, as `ngModel` will set the select value and
+ * selected options.
*
+ *
+ * @example
+
+
+ Check me to select:
+
+ Hello!
+ Greetings!
+
+
+
+ it('should select Greetings!', function() {
+ expect(element(by.id('greet')).getAttribute('selected')).toBeFalsy();
+ element(by.model('selected')).click();
+ expect(element(by.id('greet')).getAttribute('selected')).toBeTruthy();
+ });
+
+
+ *
+ * @element OPTION
+ * @param {expression} ngSelected If the {@link guide/expression expression} is truthy,
+ * then special attribute "selected" will be set on the element
*/
- this.resourceUrlWhitelist = function(value) {
- if (arguments.length) {
- resourceUrlWhitelist = adjustMatchers(value);
- }
- return resourceUrlWhitelist;
- };
/**
- * @ngdoc method
- * @name $sceDelegateProvider#resourceUrlBlacklist
- * @kind function
+ * @ngdoc directive
+ * @name ngOpen
+ * @restrict A
+ * @priority 100
+ *
+ * @description
*
- * @param {Array=} blacklist When provided, replaces the resourceUrlBlacklist with the value
- * provided. This must be an array or null. A snapshot of this array is used so further
- * changes to the array are ignored.
- * Follow {@link ng.$sce#resourceUrlPatternItem this link} for a description of the items
- * allowed in this array.
- * The typical usage for the blacklist is to **block
- * [open redirects](http://cwe.mitre.org/data/definitions/601.html)** served by your domain as
- * these would otherwise be trusted but actually return content from the redirected domain.
- *
- * Finally, **the blacklist overrides the whitelist** and has the final say.
+ * Sets the `open` attribute on the element, if the expression inside `ngOpen` is truthy.
*
- * @return {Array} The currently set blacklist array.
+ * A special directive is necessary because we cannot use interpolation inside the `open`
+ * attribute. See the {@link guide/interpolation interpolation guide} for more info.
*
- * @description
- * Sets/Gets the blacklist of trusted resource URLs.
+ * ## A note about browser compatibility
+ *
+ * Edge, Firefox, and Internet Explorer do not support the `details` element, it is
+ * recommended to use {@link ng.ngShow} and {@link ng.ngHide} instead.
+ *
+ * @example
+
+
+ Check me check multiple:
+
+ Show/Hide me
+
+
+
+ it('should toggle open', function() {
+ expect(element(by.id('details')).getAttribute('open')).toBeFalsy();
+ element(by.model('open')).click();
+ expect(element(by.id('details')).getAttribute('open')).toBeTruthy();
+ });
+
+
*
- * The **default value** when no whitelist has been explicitly set is the empty array (i.e. there
- * is no blacklist.)
+ * @element DETAILS
+ * @param {expression} ngOpen If the {@link guide/expression expression} is truthy,
+ * then special attribute "open" will be set on the element
*/
- this.resourceUrlBlacklist = function(value) {
- if (arguments.length) {
- resourceUrlBlacklist = adjustMatchers(value);
- }
- return resourceUrlBlacklist;
- };
+ var ngAttributeAliasDirectives = {};
- this.$get = ['$injector', function($injector) {
-
- var htmlSanitizer = function htmlSanitizer(html) {
- throw $sceMinErr('unsafe', 'Attempting to use an unsafe value in a safe context.');
- };
+ // boolean attrs are evaluated
+ forEach(BOOLEAN_ATTR, function (propName, attrName) {
+ // binding to multiple is not supported
+ if (propName === 'multiple') return;
- if ($injector.has('$sanitize')) {
- htmlSanitizer = $injector.get('$sanitize');
+ function defaultLinkFn(scope, element, attr) {
+ scope.$watch(attr[normalized], function ngBooleanAttrWatchAction(value) {
+ attr.$set(attrName, !!value);
+ });
}
+ var normalized = directiveNormalize('ng-' + attrName);
+ var linkFn = defaultLinkFn;
- function matchUrl(matcher, parsedUrl) {
- if (matcher === 'self') {
- return urlIsSameOrigin(parsedUrl);
- } else {
- // definitely a regex. See adjustMatchers()
- return !!matcher.exec(parsedUrl.href);
- }
- }
-
- function isResourceUrlAllowedByPolicy(url) {
- var parsedUrl = urlResolve(url.toString());
- var i, n, allowed = false;
- // Ensure that at least one item from the whitelist allows this url.
- for (i = 0, n = resourceUrlWhitelist.length; i < n; i++) {
- if (matchUrl(resourceUrlWhitelist[i], parsedUrl)) {
- allowed = true;
- break;
- }
- }
- if (allowed) {
- // Ensure that no item from the blacklist blocked this url.
- for (i = 0, n = resourceUrlBlacklist.length; i < n; i++) {
- if (matchUrl(resourceUrlBlacklist[i], parsedUrl)) {
- allowed = false;
- break;
- }
+ if (propName === 'checked') {
+ linkFn = function linkFn(scope, element, attr) {
+ // ensuring ngChecked doesn't interfere with ngModel when both are set on the same input
+ if (attr.ngModel !== attr[normalized]) {
+ defaultLinkFn(scope, element, attr);
}
- }
- return allowed;
- }
-
- function generateHolderType(Base) {
- var holderType = function TrustedValueHolderType(trustedValue) {
- this.$$unwrapTrustedValue = function() {
- return trustedValue;
- };
};
- if (Base) {
- holderType.prototype = new Base();
- }
- holderType.prototype.valueOf = function sceValueOf() {
- return this.$$unwrapTrustedValue();
- };
- holderType.prototype.toString = function sceToString() {
- return this.$$unwrapTrustedValue().toString();
- };
- return holderType;
}
- var trustedValueHolderBase = generateHolderType(),
- byType = {};
-
- byType[SCE_CONTEXTS.HTML] = generateHolderType(trustedValueHolderBase);
- byType[SCE_CONTEXTS.CSS] = generateHolderType(trustedValueHolderBase);
- byType[SCE_CONTEXTS.URL] = generateHolderType(trustedValueHolderBase);
- byType[SCE_CONTEXTS.JS] = generateHolderType(trustedValueHolderBase);
- byType[SCE_CONTEXTS.RESOURCE_URL] = generateHolderType(byType[SCE_CONTEXTS.URL]);
-
- /**
- * @ngdoc method
- * @name $sceDelegate#trustAs
- *
- * @description
- * Returns a trusted representation of the parameter for the specified context. This trusted
- * object will later on be used as-is, without any security check, by bindings or directives
- * that require this security context.
- * For instance, marking a string as trusted for the `$sce.HTML` context will entirely bypass
- * the potential `$sanitize` call in corresponding `$sce.HTML` bindings or directives, such as
- * `ng-bind-html`. Note that in most cases you won't need to call this function: if you have the
- * sanitizer loaded, passing the value itself will render all the HTML that does not pose a
- * security risk.
- *
- * See {@link ng.$sceDelegate#getTrusted getTrusted} for the function that will consume those
- * trusted values, and {@link ng.$sce $sce} for general documentation about strict contextual
- * escaping.
- *
- * @param {string} type The context in which this value is safe for use, e.g. `$sce.URL`,
- * `$sce.RESOURCE_URL`, `$sce.HTML`, `$sce.JS` or `$sce.CSS`.
- *
- * @param {*} value The value that should be considered trusted.
- * @return {*} A trusted representation of value, that can be used in the given context.
- */
- function trustAs(type, trustedValue) {
- var Constructor = (byType.hasOwnProperty(type) ? byType[type] : null);
- if (!Constructor) {
- throw $sceMinErr('icontext',
- 'Attempted to trust a value in invalid context. Context: {0}; Value: {1}',
- type, trustedValue);
- }
- if (trustedValue === null || isUndefined(trustedValue) || trustedValue === '') {
- return trustedValue;
- }
- // All the current contexts in SCE_CONTEXTS happen to be strings. In order to avoid trusting
- // mutable objects, we ensure here that the value passed in is actually a string.
- if (typeof trustedValue !== 'string') {
- throw $sceMinErr('itype',
- 'Attempted to trust a non-string value in a content requiring a string: Context: {0}',
- type);
- }
- return new Constructor(trustedValue);
- }
+ ngAttributeAliasDirectives[normalized] = function () {
+ return {
+ restrict: 'A',
+ priority: 100,
+ link: linkFn
+ };
+ };
+ });
- /**
- * @ngdoc method
- * @name $sceDelegate#valueOf
- *
- * @description
- * 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`}, it must be returned as-is.
- *
- * @param {*} value The result of a prior {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}
- * call or anything else.
- * @return {*} The `value` that was originally provided to {@link ng.$sceDelegate#trustAs
- * `$sceDelegate.trustAs`} if `value` is the result of such a call. Otherwise, returns
- * `value` unchanged.
- */
- function valueOf(maybeTrusted) {
- if (maybeTrusted instanceof trustedValueHolderBase) {
- return maybeTrusted.$$unwrapTrustedValue();
- } else {
- return maybeTrusted;
- }
- }
+ // aliased input attrs are evaluated
+ forEach(ALIASED_ATTR, function (htmlAttr, ngAttr) {
+ ngAttributeAliasDirectives[ngAttr] = function () {
+ return {
+ priority: 100,
+ link: function link(scope, element, attr) {
+ //special case ngPattern when a literal regular expression value
+ //is used as the expression (this way we don't have to watch anything).
+ if (ngAttr === 'ngPattern' && attr.ngPattern.charAt(0) === '/') {
+ var match = attr.ngPattern.match(REGEX_STRING_REGEXP);
+ if (match) {
+ attr.$set('ngPattern', new RegExp(match[1], match[2]));
+ return;
+ }
+ }
- /**
- * @ngdoc method
- * @name $sceDelegate#getTrusted
- *
- * @description
- * Takes any input, and either returns a value that's safe to use in the specified context, or
- * throws an exception.
- *
- * In practice, there are several cases. When given a string, this function runs checks
- * and sanitization to make it safe without prior assumptions. When given the result of a {@link
- * ng.$sceDelegate#trustAs `$sceDelegate.trustAs`} call, it returns the originally supplied
- * value if that value's context is valid for this call's context. Finally, this function can
- * also throw when there is no way to turn `maybeTrusted` in a safe value (e.g., no sanitization
- * is available or possible.)
- *
- * @param {string} type The context in which this value is to be used (such as `$sce.HTML`).
- * @param {*} maybeTrusted The result of a prior {@link ng.$sceDelegate#trustAs
- * `$sceDelegate.trustAs`} call, or anything else (which will not be considered trusted.)
- * @return {*} A version of the value that's safe to use in the given context, or throws an
- * exception if this is impossible.
- */
- function getTrusted(type, maybeTrusted) {
- if (maybeTrusted === null || isUndefined(maybeTrusted) || maybeTrusted === '') {
- return maybeTrusted;
- }
- var constructor = (byType.hasOwnProperty(type) ? byType[type] : null);
- // If maybeTrusted is a trusted class instance or subclass instance, then unwrap and return
- // as-is.
- if (constructor && maybeTrusted instanceof constructor) {
- return maybeTrusted.$$unwrapTrustedValue();
- }
- // Otherwise, if we get here, then we may either make it safe, or throw an exception. This
- // depends on the context: some are sanitizatible (HTML), some use whitelists (RESOURCE_URL),
- // some are impossible to do (JS). This step isn't implemented for CSS and URL, as AngularJS
- // has no corresponding sinks.
- if (type === SCE_CONTEXTS.RESOURCE_URL) {
- // RESOURCE_URL uses a whitelist.
- if (isResourceUrlAllowedByPolicy(maybeTrusted)) {
- return maybeTrusted;
- } else {
- throw $sceMinErr('insecurl',
- 'Blocked loading resource from url not allowed by $sceDelegate policy. URL: {0}',
- maybeTrusted.toString());
+ scope.$watch(attr[ngAttr], function ngAttrAliasWatchAction(value) {
+ attr.$set(ngAttr, value);
+ });
}
- } else if (type === SCE_CONTEXTS.HTML) {
- // htmlSanitizer throws its own error when no sanitizer is available.
- return htmlSanitizer(maybeTrusted);
- }
- // Default error when the $sce service has no way to make the input safe.
- throw $sceMinErr('unsafe', 'Attempting to use an unsafe value in a safe context.');
- }
-
- return { trustAs: trustAs,
- getTrusted: getTrusted,
- valueOf: valueOf };
- }];
-}
-
+ };
+ };
+ });
-/**
- * @ngdoc provider
- * @name $sceProvider
- * @this
- *
- * @description
- *
- * The $sceProvider provider allows developers to configure the {@link ng.$sce $sce} service.
- * - enable/disable Strict Contextual Escaping (SCE) in a module
- * - override the default implementation with a custom delegate
- *
- * Read more about {@link ng.$sce Strict Contextual Escaping (SCE)}.
- */
+ // ng-src, ng-srcset, ng-href are interpolated
+ forEach(['src', 'srcset', 'href'], function (attrName) {
+ var normalized = directiveNormalize('ng-' + attrName);
+ ngAttributeAliasDirectives[normalized] = function () {
+ return {
+ priority: 99, // it needs to run after the attributes are interpolated
+ link: function link(scope, element, attr) {
+ var propName = attrName,
+ name = attrName;
+
+ if (attrName === 'href' && toString.call(element.prop('href')) === '[object SVGAnimatedString]') {
+ name = 'xlinkHref';
+ attr.$attr[name] = 'xlink:href';
+ propName = null;
+ }
-/**
- * @ngdoc service
- * @name $sce
- * @kind function
- *
- * @description
- *
- * `$sce` is a service that provides Strict Contextual Escaping services to AngularJS.
- *
- * # Strict Contextual Escaping
- *
- * Strict Contextual Escaping (SCE) is a mode in which AngularJS constrains bindings to only render
- * trusted values. Its goal is to assist in writing code in a way that (a) is secure by default, and
- * (b) makes auditing for security vulnerabilities such as XSS, clickjacking, etc. a lot easier.
- *
- * ## Overview
- *
- * To systematically block XSS security bugs, AngularJS treats all values as untrusted by default in
- * HTML or sensitive URL bindings. When binding untrusted values, AngularJS will automatically
- * run security checks on them (sanitizations, whitelists, depending on context), or throw when it
- * cannot guarantee the security of the result. That behavior depends strongly on contexts: HTML
- * can be sanitized, but template URLs cannot, for instance.
- *
- * To illustrate this, consider the `ng-bind-html` directive. It renders its value directly as HTML:
- * we call that the *context*. When given an untrusted input, AngularJS will attempt to sanitize it
- * before rendering if a sanitizer is available, and throw otherwise. To bypass sanitization and
- * render the input as-is, you will need to mark it as trusted for that context before attempting
- * to bind it.
- *
- * As of version 1.2, AngularJS ships with SCE enabled by default.
- *
- * ## In practice
- *
- * Here's an example of a binding in a privileged context:
- *
- * ```
- *
- *
- * ```
- *
- * Notice that `ng-bind-html` is bound to `userHtml` controlled by the user. With SCE
- * disabled, this application allows the user to render arbitrary HTML into the DIV, which would
- * be an XSS security bug. In a more realistic example, one may be rendering user comments, blog
- * articles, etc. via bindings. (HTML is just one example of a context where rendering user
- * controlled input creates security vulnerabilities.)
- *
- * For the case of HTML, you might use a library, either on the client side, or on the server side,
- * to sanitize unsafe HTML before binding to the value and rendering it in the document.
- *
- * How would you ensure that every place that used these types of bindings was bound to a value that
- * was sanitized by your library (or returned as safe for rendering by your server?) How can you
- * ensure that you didn't accidentally delete the line that sanitized the value, or renamed some
- * properties/fields and forgot to update the binding to the sanitized value?
- *
- * To be secure by default, AngularJS makes sure bindings go through that sanitization, or
- * any similar validation process, unless there's a good reason to trust the given value in this
- * context. That trust is formalized with a function call. This means that as a developer, you
- * can assume all untrusted bindings are safe. Then, to audit your code for binding security issues,
- * you just need to ensure the values you mark as trusted indeed are safe - because they were
- * received from your server, sanitized by your library, etc. You can organize your codebase to
- * help with this - perhaps allowing only the files in a specific directory to do this.
- * Ensuring that the internal API exposed by that code doesn't markup arbitrary values as safe then
- * becomes a more manageable task.
- *
- * In the case of AngularJS' SCE service, one uses {@link ng.$sce#trustAs $sce.trustAs}
- * (and shorthand methods such as {@link ng.$sce#trustAsHtml $sce.trustAsHtml}, etc.) to
- * build the trusted versions of your values.
- *
- * ## How does it work?
- *
- * In privileged contexts, directives and code will bind to the result of {@link ng.$sce#getTrusted
- * $sce.getTrusted(context, value)} rather than to the value directly. Think of this function as
- * a way to enforce the required security context in your data sink. Directives use {@link
- * ng.$sce#parseAs $sce.parseAs} rather than `$parse` to watch attribute bindings, which performs
- * the {@link ng.$sce#getTrusted $sce.getTrusted} behind the scenes on non-constant literals. Also,
- * when binding without directives, AngularJS will understand the context of your bindings
- * automatically.
- *
- * As an example, {@link ng.directive:ngBindHtml ngBindHtml} uses {@link
- * ng.$sce#parseAsHtml $sce.parseAsHtml(binding expression)}. Here's the actual code (slightly
- * simplified):
- *
- * ```
- * var ngBindHtmlDirective = ['$sce', function($sce) {
- * return function(scope, element, attr) {
- * scope.$watch($sce.parseAsHtml(attr.ngBindHtml), function(value) {
- * element.html(value || '');
- * });
- * };
- * }];
- * ```
- *
- * ## Impact on loading templates
- *
- * This applies both to the {@link ng.directive:ngInclude `ng-include`} directive as well as
- * `templateUrl`'s specified by {@link guide/directive directives}.
- *
- * By default, Angular only loads templates from the same domain and protocol as the application
- * document. This is done by calling {@link ng.$sce#getTrustedResourceUrl
- * $sce.getTrustedResourceUrl} on the template URL. To load templates from other domains and/or
- * protocols, you may either {@link ng.$sceDelegateProvider#resourceUrlWhitelist whitelist
- * them} or {@link ng.$sce#trustAsResourceUrl wrap it} into a trusted value.
- *
- * *Please note*:
- * The browser's
- * [Same Origin Policy](https://code.google.com/p/browsersec/wiki/Part2#Same-origin_policy_for_XMLHttpRequest)
- * and [Cross-Origin Resource Sharing (CORS)](http://www.w3.org/TR/cors/)
- * policy apply in addition to this and may further restrict whether the template is successfully
- * loaded. This means that without the right CORS policy, loading templates from a different domain
- * won't work on all browsers. Also, loading templates from `file://` URL does not work on some
- * browsers.
- *
- * ## This feels like too much overhead
- *
- * It's important to remember that SCE only applies to interpolation expressions.
- *
- * If your expressions are constant literals, they're automatically trusted and you don't need to
- * call `$sce.trustAs` on them (e.g.
- * `
`) just works. The `$sceDelegate` will
- * also use the `$sanitize` service if it is available when binding untrusted values to
- * `$sce.HTML` context. AngularJS provides an implementation in `angular-sanitize.js`, and if you
- * wish to use it, you will also need to depend on the {@link ngSanitize `ngSanitize`} module in
- * your application.
- *
- * The included {@link ng.$sceDelegate $sceDelegate} comes with sane defaults to allow you to load
- * templates in `ng-include` from your application's domain without having to even know about SCE.
- * It blocks loading templates from other domains or loading templates over http from an https
- * served document. You can change these by setting your own custom {@link
- * ng.$sceDelegateProvider#resourceUrlWhitelist whitelists} and {@link
- * ng.$sceDelegateProvider#resourceUrlBlacklist blacklists} for matching such URLs.
- *
- * This significantly reduces the overhead. It is far easier to pay the small overhead and have an
- * application that's secure and can be audited to verify that with much more ease than bolting
- * security onto an application later.
- *
- *
- * ## What trusted context types are supported?
- *
- * | Context | Notes |
- * |---------------------|----------------|
- * | `$sce.HTML` | For HTML that's safe to source into the application. The {@link ng.directive:ngBindHtml ngBindHtml} directive uses this context for bindings. If an unsafe value is encountered, and the {@link ngSanitize.$sanitize $sanitize} service is available (implemented by the {@link ngSanitize ngSanitize} module) this will sanitize the value instead of throwing an error. |
- * | `$sce.CSS` | For CSS that's safe to source into the application. Currently, no bindings require this context. Feel free to use it in your own directives. |
- * | `$sce.URL` | For URLs that are safe to follow as links. Currently unused (` Note that `$sce.RESOURCE_URL` makes a stronger statement about the URL than `$sce.URL` does (it's not just the URL that matters, but also what is at the end of it), and therefore contexts requiring values trusted for `$sce.RESOURCE_URL` can be used anywhere that values trusted for `$sce.URL` are required. |
- * | `$sce.JS` | For JavaScript that is safe to execute in your application's context. Currently, no bindings require this context. Feel free to use it in your own directives. |
- *
- *
- * Be aware that `a[href]` and `img[src]` automatically sanitize their URLs and do not pass them
- * through {@link ng.$sce#getTrusted $sce.getTrusted}. There's no CSS-, URL-, or JS-context bindings
- * in AngularJS currently, so their corresponding `$sce.trustAs` functions aren't useful yet. This
- * might evolve.
- *
- * ## Format of items in {@link ng.$sceDelegateProvider#resourceUrlWhitelist resourceUrlWhitelist}/{@link ng.$sceDelegateProvider#resourceUrlBlacklist Blacklist}
- *
- * Each element in these arrays must be one of the following:
- *
- * - **'self'**
- * - The special **string**, `'self'`, can be used to match against all URLs of the **same
- * domain** as the application document using the **same protocol**.
- * - **String** (except the special value `'self'`)
- * - The string is matched against the full *normalized / absolute URL* of the resource
- * being tested (substring matches are not good enough.)
- * - There are exactly **two wildcard sequences** - `*` and `**`. All other characters
- * match themselves.
- * - `*`: matches zero or more occurrences of any character other than one of the following 6
- * characters: '`:`', '`/`', '`.`', '`?`', '`&`' and '`;`'. It's a useful wildcard for use
- * in a whitelist.
- * - `**`: matches zero or more occurrences of *any* character. As such, it's not
- * appropriate for use in a scheme, domain, etc. as it would match too much. (e.g.
- * http://**.example.com/ would match http://evil.com/?ignore=.example.com/ and that might
- * not have been the intention.) Its usage at the very end of the path is ok. (e.g.
- * http://foo.example.com/templates/**).
- * - **RegExp** (*see caveat below*)
- * - *Caveat*: While regular expressions are powerful and offer great flexibility, their syntax
- * (and all the inevitable escaping) makes them *harder to maintain*. It's easy to
- * accidentally introduce a bug when one updates a complex expression (imho, all regexes should
- * have good test coverage). For instance, the use of `.` in the regex is correct only in a
- * small number of cases. A `.` character in the regex used when matching the scheme or a
- * subdomain could be matched against a `:` or literal `.` that was likely not intended. It
- * is highly recommended to use the string patterns and only fall back to regular expressions
- * as a last resort.
- * - The regular expression must be an instance of RegExp (i.e. not a string.) It is
- * matched against the **entire** *normalized / absolute URL* of the resource being tested
- * (even when the RegExp did not have the `^` and `$` codes.) In addition, any flags
- * present on the RegExp (such as multiline, global, ignoreCase) are ignored.
- * - If you are generating your JavaScript from some other templating engine (not
- * recommended, e.g. in issue [#4006](https://github.com/angular/angular.js/issues/4006)),
- * remember to escape your regular expression (and be aware that you might need more than
- * one level of escaping depending on your templating engine and the way you interpolated
- * the value.) Do make use of your platform's escaping mechanism as it might be good
- * enough before coding your own. E.g. Ruby has
- * [Regexp.escape(str)](http://www.ruby-doc.org/core-2.0.0/Regexp.html#method-c-escape)
- * and Python has [re.escape](http://docs.python.org/library/re.html#re.escape).
- * Javascript lacks a similar built in function for escaping. Take a look at Google
- * Closure library's [goog.string.regExpEscape(s)](
- * http://docs.closure-library.googlecode.com/git/closure_goog_string_string.js.source.html#line962).
- *
- * Refer {@link ng.$sceDelegateProvider $sceDelegateProvider} for an example.
- *
- * ## Show me an example using SCE.
- *
- *
- *
- *
- *
- *
User comments
- * By default, HTML that isn't explicitly trusted (e.g. Alice's comment) is sanitized when
- * $sanitize is available. If $sanitize isn't available, this results in an error instead of an
- * exploit.
- *
- *
- * {{userComment.name}} :
- *
- *
- *
- *
- *
- *
- *
- *
- * angular.module('mySceApp', ['ngSanitize'])
- * .controller('AppController', ['$http', '$templateCache', '$sce',
- * function AppController($http, $templateCache, $sce) {
- * var self = this;
- * $http.get('test_data.json', {cache: $templateCache}).then(function(response) {
- * self.userComments = response.data;
- * });
- * self.explicitlyTrustedHtml = $sce.trustAsHtml(
- * 'Hover over this text. ');
- * }]);
- *
- *
- *
- * [
- * { "name": "Alice",
- * "htmlComment":
- * "Is anyone reading this? "
- * },
- * { "name": "Bob",
- * "htmlComment": "Yes! Am I the only other one?"
- * }
- * ]
- *
- *
- *
- * describe('SCE doc demo', function() {
- * it('should sanitize untrusted values', function() {
- * expect(element.all(by.css('.htmlComment')).first().getAttribute('innerHTML'))
- * .toBe('Is anyone reading this? ');
- * });
- *
- * it('should NOT sanitize explicitly trusted values', function() {
- * expect(element(by.id('explicitlyTrustedHtml')).getAttribute('innerHTML')).toBe(
- * 'Hover over this text. ');
- * });
- * });
- *
- *
- *
- *
- *
- * ## Can I disable SCE completely?
- *
- * Yes, you can. However, this is strongly discouraged. SCE gives you a lot of security benefits
- * for little coding overhead. It will be much harder to take an SCE disabled application and
- * either secure it on your own or enable SCE at a later stage. It might make sense to disable SCE
- * for cases where you have a lot of existing code that was written before SCE was introduced and
- * you're migrating them a module at a time. Also do note that this is an app-wide setting, so if
- * you are writing a library, you will cause security bugs applications using it.
- *
- * That said, here's how you can completely disable SCE:
- *
- * ```
- * angular.module('myAppWithSceDisabledmyApp', []).config(function($sceProvider) {
- * // Completely disable SCE. For demonstration purposes only!
- * // Do not use in new projects or libraries.
- * $sceProvider.enabled(false);
- * });
- * ```
- *
- */
+ attr.$observe(normalized, function (value) {
+ if (!value) {
+ if (attrName === 'href') {
+ attr.$set(name, null);
+ }
+ return;
+ }
-function $SceProvider() {
- var enabled = true;
+ attr.$set(name, value);
- /**
- * @ngdoc method
- * @name $sceProvider#enabled
- * @kind function
- *
- * @param {boolean=} value If provided, then enables/disables SCE application-wide.
- * @return {boolean} True if SCE is enabled, false otherwise.
- *
- * @description
- * Enables/disables SCE and returns the current value.
+ // Support: IE 9-11 only
+ // On IE, if "ng:src" directive declaration is used and "src" attribute doesn't exist
+ // then calling element.setAttribute('src', 'foo') doesn't do anything, so we need
+ // to set the property as well to achieve the desired effect.
+ // We use attr[attrName] value since $set can sanitize the url.
+ if (msie && propName) element.prop(propName, attr[name]);
+ });
+ }
+ };
+ };
+ });
+
+ /* global -nullFormCtrl, -PENDING_CLASS, -SUBMITTED_CLASS
*/
- this.enabled = function(value) {
- if (arguments.length) {
- enabled = !!value;
- }
- return enabled;
- };
+ var nullFormCtrl = {
+ $addControl: noop,
+ $$renameControl: nullFormRenameControl,
+ $removeControl: noop,
+ $setValidity: noop,
+ $setDirty: noop,
+ $setPristine: noop,
+ $setSubmitted: noop
+ },
+ PENDING_CLASS = 'ng-pending',
+ SUBMITTED_CLASS = 'ng-submitted';
+ function nullFormRenameControl(control, name) {
+ control.$name = name;
+ }
- /* Design notes on the default implementation for SCE.
- *
- * The API contract for the SCE delegate
- * -------------------------------------
- * The SCE delegate object must provide the following 3 methods:
- *
- * - trustAs(contextEnum, value)
- * This method is used to tell the SCE service that the provided value is OK to use in the
- * contexts specified by contextEnum. It must return an object that will be accepted by
- * getTrusted() for a compatible contextEnum and return this value.
+ /**
+ * @ngdoc type
+ * @name form.FormController
*
- * - valueOf(value)
- * For values that were not produced by trustAs(), return them as is. For values that were
- * produced by trustAs(), return the corresponding input value to trustAs. Basically, if
- * trustAs is wrapping the given values into some type, this operation unwraps it when given
- * such a value.
+ * @property {boolean} $pristine True if user has not interacted with the form yet.
+ * @property {boolean} $dirty True if user has already interacted with the form.
+ * @property {boolean} $valid True if all of the containing forms and controls are valid.
+ * @property {boolean} $invalid True if at least one containing control or form is invalid.
+ * @property {boolean} $pending True if at least one containing control or form is pending.
+ * @property {boolean} $submitted True if user has submitted the form even if its invalid.
*
- * - getTrusted(contextEnum, value)
- * This function should return the a value that is safe to use in the context specified by
- * contextEnum or throw and exception otherwise.
+ * @property {Object} $error Is an object hash, containing references to controls or
+ * forms with failing validators, where:
*
- * NOTE: This contract deliberately does NOT state that values returned by trustAs() must be
- * opaque or wrapped in some holder object. That happens to be an implementation detail. For
- * instance, an implementation could maintain a registry of all trusted objects by context. In
- * such a case, trustAs() would return the same object that was passed in. getTrusted() would
- * return the same object passed in if it was found in the registry under a compatible context or
- * throw an exception otherwise. An implementation might only wrap values some of the time based
- * on some criteria. getTrusted() might return a value and not throw an exception for special
- * constants or objects even if not wrapped. All such implementations fulfill this contract.
+ * - keys are validation tokens (error names),
+ * - values are arrays of controls or forms that have a failing validator for given error name.
*
+ * Built-in validation tokens:
*
- * A note on the inheritance model for SCE contexts
- * ------------------------------------------------
- * I've used inheritance and made RESOURCE_URL wrapped types a subtype of URL wrapped types. This
- * is purely an implementation details.
+ * - `email`
+ * - `max`
+ * - `maxlength`
+ * - `min`
+ * - `minlength`
+ * - `number`
+ * - `pattern`
+ * - `required`
+ * - `url`
+ * - `date`
+ * - `datetimelocal`
+ * - `time`
+ * - `week`
+ * - `month`
*
- * The contract is simply this:
+ * @description
+ * `FormController` keeps track of all its controls and nested forms as well as the state of them,
+ * such as being valid/invalid or dirty/pristine.
*
- * getTrusted($sce.RESOURCE_URL, value) succeeding implies that getTrusted($sce.URL, value)
- * will also succeed.
+ * Each {@link ng.directive:form form} directive creates an instance
+ * of `FormController`.
*
- * Inheritance happens to capture this in a natural way. In some future, we may not use
- * inheritance anymore. That is OK because no code outside of sce.js and sceSpecs.js would need to
- * be aware of this detail.
*/
+ //asks for $scope to fool the BC controller module
+ FormController.$inject = ['$element', '$attrs', '$scope', '$animate', '$interpolate'];
+ function FormController($element, $attrs, $scope, $animate, $interpolate) {
+ this.$$controls = [];
+
+ // init state
+ this.$error = {};
+ this.$$success = {};
+ this.$pending = undefined;
+ this.$name = $interpolate($attrs.name || $attrs.ngForm || '')($scope);
+ this.$dirty = false;
+ this.$pristine = true;
+ this.$valid = true;
+ this.$invalid = false;
+ this.$submitted = false;
+ this.$$parentForm = nullFormCtrl;
- this.$get = ['$parse', '$sceDelegate', function(
- $parse, $sceDelegate) {
- // Support: IE 9-11 only
- // Prereq: Ensure that we're not running in IE<11 quirks mode. In that mode, IE < 11 allow
- // the "expression(javascript expression)" syntax which is insecure.
- if (enabled && msie < 8) {
- throw $sceMinErr('iequirks',
- 'Strict Contextual Escaping does not support Internet Explorer version < 11 in quirks ' +
- 'mode. You can fix this by adding the text to the top of your HTML ' +
- 'document. See http://docs.angularjs.org/api/ng.$sce for more information.');
- }
+ this.$$element = $element;
+ this.$$animate = $animate;
- var sce = shallowCopy(SCE_CONTEXTS);
+ setupValidity(this);
+ }
+ FormController.prototype = {
/**
* @ngdoc method
- * @name $sce#isEnabled
- * @kind function
- *
- * @return {Boolean} True if SCE is enabled, false otherwise. If you want to set the value, you
- * have to do it at module config time on {@link ng.$sceProvider $sceProvider}.
+ * @name form.FormController#$rollbackViewValue
*
* @description
- * Returns a boolean indicating if SCE is enabled.
+ * Rollback all form controls pending updates to the `$modelValue`.
+ *
+ * Updates may be pending by a debounced event or because the input is waiting for a some future
+ * event defined in `ng-model-options`. This method is typically needed by the reset button of
+ * a form that uses `ng-model-options` to pend updates.
*/
- sce.isEnabled = function() {
- return enabled;
- };
- sce.trustAs = $sceDelegate.trustAs;
- sce.getTrusted = $sceDelegate.getTrusted;
- sce.valueOf = $sceDelegate.valueOf;
+ $rollbackViewValue: function $rollbackViewValue() {
+ forEach(this.$$controls, function (control) {
+ control.$rollbackViewValue();
+ });
+ },
- if (!enabled) {
- sce.trustAs = sce.getTrusted = function(type, value) { return value; };
- sce.valueOf = identity;
- }
+ /**
+ * @ngdoc method
+ * @name form.FormController#$commitViewValue
+ *
+ * @description
+ * Commit all form controls pending updates to the `$modelValue`.
+ *
+ * Updates may be pending by a debounced event or because the input is waiting for a some future
+ * event defined in `ng-model-options`. This method is rarely needed as `NgModelController`
+ * usually handles calling this in response to input events.
+ */
+ $commitViewValue: function $commitViewValue() {
+ forEach(this.$$controls, function (control) {
+ control.$commitViewValue();
+ });
+ },
/**
* @ngdoc method
- * @name $sce#parseAs
+ * @name form.FormController#$addControl
+ * @param {object} control control object, either a {@link form.FormController} or an
+ * {@link ngModel.NgModelController}
*
* @description
- * 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*)}
+ * Register a control with the form. Input elements using ngModelController do this automatically
+ * when they are linked.
+ *
+ * Note that the current state of the control will not be reflected on the new parent form. This
+ * is not an issue with normal use, as freshly compiled and linked controls are in a `$pristine`
+ * state.
*
- * @param {string} type The SCE context in which this result will be used.
- * @param {string} expression String expression to compile.
- * @return {function(context, locals)} A function which represents the compiled expression:
+ * However, if the method is used programmatically, for example by adding dynamically created controls,
+ * or controls that have been previously removed without destroying their corresponding DOM element,
+ * it's the developers responsibility to make sure the current state propagates to the parent form.
*
- * * `context` – `{object}` – an object against which any expressions embedded in the
- * strings are evaluated against (typically a scope object).
- * * `locals` – `{object=}` – local variables context object, useful for overriding values
- * in `context`.
+ * For example, if an input control is added that is already `$dirty` and has `$error` properties,
+ * calling `$setDirty()` and `$validate()` afterwards will propagate the state to the parent form.
*/
- sce.parseAs = function sceParseAs(type, expr) {
- var parsed = $parse(expr);
- if (parsed.literal && parsed.constant) {
- return parsed;
- } else {
- return $parse(expr, function(value) {
- return sce.getTrusted(type, value);
- });
+ $addControl: function $addControl(control) {
+ // Breaking change - before, inputs whose name was "hasOwnProperty" were quietly ignored
+ // and not added to the scope. Now we throw an error.
+ assertNotHasOwnProperty(control.$name, 'input');
+ this.$$controls.push(control);
+
+ if (control.$name) {
+ this[control.$name] = control;
}
- };
+
+ control.$$parentForm = this;
+ },
+
+ // Private API: rename a form control
+ $$renameControl: function $$renameControl(control, newName) {
+ var oldName = control.$name;
+
+ if (this[oldName] === control) {
+ delete this[oldName];
+ }
+ this[newName] = control;
+ control.$name = newName;
+ },
/**
* @ngdoc method
- * @name $sce#trustAs
+ * @name form.FormController#$removeControl
+ * @param {object} control control object, either a {@link form.FormController} or an
+ * {@link ngModel.NgModelController}
*
* @description
- * Delegates to {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs`}. As such, returns a
- * wrapped object that represents your value, and the trust you have in its safety for the given
- * context. AngularJS can then use that value as-is in bindings of the specified secure context.
- * This is used in bindings for `ng-bind-html`, `ng-include`, and most `src` attribute
- * interpolations. See {@link ng.$sce $sce} for strict contextual escaping.
+ * Deregister a control from the form.
*
- * @param {string} type The context in which this value is safe for use, e.g. `$sce.URL`,
- * `$sce.RESOURCE_URL`, `$sce.HTML`, `$sce.JS` or `$sce.CSS`.
+ * Input elements using ngModelController do this automatically when they are destroyed.
*
- * @param {*} value The value that that should be considered trusted.
- * @return {*} A wrapped version of value that can be used as a trusted variant of your `value`
- * in the context you specified.
+ * Note that only the removed control's validation state (`$errors`etc.) will be removed from the
+ * form. `$dirty`, `$submitted` states will not be changed, because the expected behavior can be
+ * different from case to case. For example, removing the only `$dirty` control from a form may or
+ * may not mean that the form is still `$dirty`.
*/
+ $removeControl: function $removeControl(control) {
+ if (control.$name && this[control.$name] === control) {
+ delete this[control.$name];
+ }
+ forEach(this.$pending, function (value, name) {
+ // eslint-disable-next-line no-invalid-this
+ this.$setValidity(name, null, control);
+ }, this);
+ forEach(this.$error, function (value, name) {
+ // eslint-disable-next-line no-invalid-this
+ this.$setValidity(name, null, control);
+ }, this);
+ forEach(this.$$success, function (value, name) {
+ // eslint-disable-next-line no-invalid-this
+ this.$setValidity(name, null, control);
+ }, this);
+
+ arrayRemove(this.$$controls, control);
+ control.$$parentForm = nullFormCtrl;
+ },
/**
* @ngdoc method
- * @name $sce#trustAsHtml
+ * @name form.FormController#$setDirty
*
* @description
- * Shorthand method. `$sce.trustAsHtml(value)` →
- * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.HTML, value)`}
+ * Sets the form to a dirty state.
*
- * @param {*} value The value to mark as trusted for `$sce.HTML` context.
- * @return {*} A wrapped version of value that can be used as a trusted variant of your `value`
- * in `$sce.HTML` context (like `ng-bind-html`).
+ * This method can be called to add the 'ng-dirty' class and set the form to a dirty
+ * state (ng-dirty class). This method will also propagate to parent forms.
*/
+ $setDirty: function $setDirty() {
+ this.$$animate.removeClass(this.$$element, PRISTINE_CLASS);
+ this.$$animate.addClass(this.$$element, DIRTY_CLASS);
+ this.$dirty = true;
+ this.$pristine = false;
+ this.$$parentForm.$setDirty();
+ },
/**
* @ngdoc method
- * @name $sce#trustAsCss
+ * @name form.FormController#$setPristine
*
* @description
- * Shorthand method. `$sce.trustAsCss(value)` →
- * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.CSS, value)`}
+ * Sets the form to its pristine state.
+ *
+ * This method sets the form's `$pristine` state to true, the `$dirty` state to false, removes
+ * the `ng-dirty` class and adds the `ng-pristine` class. Additionally, it sets the `$submitted`
+ * state to false.
*
- * @param {*} value The value to mark as trusted for `$sce.CSS` context.
- * @return {*} A wrapped version of value that can be used as a trusted variant
- * of your `value` in `$sce.CSS` context. This context is currently unused, so there are
- * almost no reasons to use this function so far.
+ * This method will also propagate to all the controls contained in this form.
+ *
+ * Setting a form back to a pristine state is often useful when we want to 'reuse' a form after
+ * saving or resetting it.
*/
+ $setPristine: function $setPristine() {
+ this.$$animate.setClass(this.$$element, PRISTINE_CLASS, DIRTY_CLASS + ' ' + SUBMITTED_CLASS);
+ this.$dirty = false;
+ this.$pristine = true;
+ this.$submitted = false;
+ forEach(this.$$controls, function (control) {
+ control.$setPristine();
+ });
+ },
/**
* @ngdoc method
- * @name $sce#trustAsUrl
+ * @name form.FormController#$setUntouched
*
* @description
- * Shorthand method. `$sce.trustAsUrl(value)` →
- * {@link ng.$sceDelegate#trustAs `$sceDelegate.trustAs($sce.URL, value)`}
+ * Sets the form to its untouched state.
+ *
+ * This method can be called to remove the 'ng-touched' class and set the form controls to their
+ * untouched state (ng-untouched class).
*
- * @param {*} value The value to mark as trusted for `$sce.URL` context.
- * @return {*} A wrapped version of value that can be used as a trusted variant of your `value`
- * in `$sce.URL` context. That context is currently unused, so there are almost no reasons
- * to use this function so far.
+ * Setting a form controls back to their untouched state is often useful when setting the form
+ * back to its pristine state.
*/
+ $setUntouched: function $setUntouched() {
+ forEach(this.$$controls, function (control) {
+ control.$setUntouched();
+ });
+ },
/**
* @ngdoc method
- * @name $sce#trustAsResourceUrl
+ * @name form.FormController#$setSubmitted
+ *
+ * @description
+ * Sets the form to its submitted state.
+ */
+ $setSubmitted: function $setSubmitted() {
+ this.$$animate.addClass(this.$$element, SUBMITTED_CLASS);
+ this.$submitted = true;
+ this.$$parentForm.$setSubmitted();
+ }
+ };
+
+ /**
+ * @ngdoc method
+ * @name form.FormController#$setValidity
+ *
+ * @description
+ * Sets the validity of a form control.
+ *
+ * This method will also propagate to parent forms.
+ */
+ addSetValidityMethod({
+ clazz: FormController,
+ set: function set(object, property, controller) {
+ var list = object[property];
+ if (!list) {
+ object[property] = [controller];
+ } else {
+ var index = list.indexOf(controller);
+ if (index === -1) {
+ list.push(controller);
+ }
+ }
+ },
+ unset: function unset(object, property, controller) {
+ var list = object[property];
+ if (!list) {
+ return;
+ }
+ arrayRemove(list, controller);
+ if (list.length === 0) {
+ delete object[property];
+ }
+ }
+ });
+
+ /**
+ * @ngdoc directive
+ * @name ngForm
+ * @restrict EAC
+ *
+ * @description
+ * Nestable alias of {@link ng.directive:form `form`} directive. HTML
+ * does not allow nesting of form elements. It is useful to nest forms, for example if the validity of a
+ * sub-group of controls needs to be determined.
+ *
+ * Note: the purpose of `ngForm` is to group controls,
+ * but not to be a replacement for the `