Improve this Doc

Migrating an App to a newer version

Minor version releases in AngularJS introduce several breaking changes that may require changes to your application's source code; for instance from 1.0 to 1.2 and from 1.2 to 1.3.

Although we try to avoid breaking changes, there are some cases where it is unavoidable:

Contents

Migrating from 1.4 to 1.5

Angular 1.5 takes a big step towards preparing developers for a smoother transition to Angular 2 in the future. Architecturing your applications using components, multi-slot transclusion, one-way bindings in isolate scopes, using lifecycle hooks in directive controllers and relying on native ES6 features (such as classes and arrow functions) are now all possible with Angular 1.5.

This release includes numerous bug and security fixes, as well as performance improvements to core services, directives, filters and helper functions. Existing applications can start enjoying the benefits of such changes in $compile, $parse, $animate, $animateCss, $sanitize, ngOptions, currencyFilter, numberFilter, copy() (to name but a few) without any change in code.

New features have been added to more than a dozen services, directives and filters across 8 modules. Among them, a few stand out:

Also, notable is the improved support for ES6 features, such as classes and arrow functions. These features are now more reliably detected and correctly handled within the core.

All this goodness doesn't come without a price, though. Below is a list of breaking changes (grouped by module) that need to be taken into account while migrating from 1.4. Fortunately, the majority of them should have a pretty low impact on most applications.

Core

We tried to keep the breaking changes inside the core components to a bare minimum. Still, a few of them were unavoidable.

Services ($parse)

Due to 0ea53503, a new special property, $locals, will be available for accessing the locals from an expression. This is a breaking change, only if a $locals property does already exist (and needs to be referenced) either on the scope or on the locals object. Your expressions should be changed to access such existing properties as this.$locals and $locals.$locals respectively.

Directives (ngOptions)

A fair amount of work has been put into the ngOptions directive, fixing bugs and corner-cases and neutralizing browser quirks. A couple of breaking changes were made in the process:

Due to b71d7c3f, falsy values ('', 0, false and null) are properly recognized as option group identifiers for options passed to ngOptions. Previously, all of these values were ignored and the option was not assigned to any group. undefined is still interpreted as "no group". If you have options with falsy group indentifiers that should still not be assigned to any group, then you must filter the values before passing them to ngOptions, converting falsy values to undefined.

Due to ded25187, ngOptions now explicitly requires ngModel on the same element, thus an error will be thrown if ngModel is not found. Previously, ngOptions would silently fail, which could lead to hard-to-debug errors. This is not expected to have any significant impact on applications, since ngOptions didn't work without ngModel before either. The main difference is that now it will fail with a more informative error message.

Filters (orderBy)

Due to 2a85a634, passing a non-array-like value (other than undefined or null) through the orderBy filter will throw an error. Previously, the input was returned unchanged, which could lead to hard-to-spot bugs and was not consistent with other filters (e.g. filter). Objects considered array-like include: arrays, array subclasses, strings, NodeLists, jqLite/jQuery collections

ngMessages (ngMessage)

Due to 4971ef12, the ngMessage directive is now compiled with a priority of 1, which means directives on the same element as ngMessage with a priority lower than 1 will be applied when ngMessage calls its $transclude function. Previously, they were applied during the initial compile phase and were passed the comment element created by the transclusion of ngMessage. If you have custom directives that relied on the previous behavior, you need to give them a priority of 1 or greater.

ngResource ($resource)

The $resource service underwent a minor internal refactoring to finally solve a long-standing bug preventing requests from being cancelled using promises. Due to the nature of $resource's configuration, it was not possible to follow the $http convention. A new $cancelRequest() method was introduced instead.

Due to 98528be3, using a promise as timeout in $resource is no longer supported and will log a warning. This is hardly expected to affect the behavior of your application, since a promise as timeout didn't work before either, but it will now warn you explicitly when trying to pass one. If you need to be able to cancel pending requests, you can now use the new $cancelRequest() that will be available on $resource instances.

ngRoute (ngView)

Due to 983b0598, a new property will be available on the scope of the route, allowing easy access to the route's resolved values from the view's template. The default name for this property is $resolve. This is a breaking change, only if a $resolve property is already available on the scope, in which case the existing property will be hidden or overwritten. To fix this, you should choose a custom name for this property, that does not collide with other properties on the scope, by specifying the resolveAs property on the route.

ngSanitize ($sanitize, linky)

The HTML sanitizer has been re-implemented using inert documents, increasing security, fixing some corner-cases that were difficult to handle and reducing its size by about 20% (in terms of loc). In order to make it more secure by default, a couple of breaking changes have been introduced:

Due to 181fc567, SVG support in $sanitize is now an opt-in feature (i.e. disabled by default), as it could make an application vulnerable to click-hijacking attacks. If your application relies on it, you can still turn it on with $sanitizeProvider.enableSvg(true), but you extra precautions need to be taken in order to keep your application secure. Read the documentation for more information about the dangers and ways to mitigate them.

Due to 7a668cdd, the $sanitize service will now remove instances of the <use> tag from the content passed to it. This element is used to import external SVG resources, which is a security risk as the $sanitize service does not have access to the resource in order to sanitize it.

Similarly, due to 234053fc, the $sanitize service will now also remove instances of the usemap attribute from any elements passed to it. This attribute is used to reference another element by name or id. Since the name and id attributes are already blacklisted, a sanitized usemap attribute could only reference unsanitized content, which is a security risk.

Due to 98c2db7f, passing a non-string value (other than undefined or null) through the linky filter will throw an error. This is not expected to have any significant impact on applications, since the input was always assumed to be of type 'string', so passing non-string values never worked correctly anyway. The main difference is that now it will fail faster and with a more informative error message.

ngTouch (ngClick)

Due to 0dfc1dfe, the ngClick override directive from the ngTouch module is deprecated and disabled by default. This means that on touch-based devices, users might now experience a 300ms delay before a click event is fired.

If you rely on this directive, you can still enable it using $touchProvider.ngClickOverrideEnabled():

angular.module('myApp').config(function($touchProvider) {
  $touchProvider.ngClickOverrideEnabled(true);
});

Going forward, we recommend using FastClick or perhaps one of the Angular 3rd party touch-related modules that provide similar functionality.

Also note that modern browsers already remove the 300ms delay under some circumstances:

For more info on the topic, you can take a look at this article by Telerik.

Note: This change does not affect the ngSwipe directive.

Migrating from 1.3 to 1.4

Angular 1.4 fixes major animation issues and introduces a new API for ngCookies. Further, there are changes to ngMessages, $compile, ngRepeat, ngOptionsand some fixes to core filters: limitTo and filter.

The reason for the ngAnimate refactor was to fix timing issues and to expose new APIs to allow for developers to construct more versatile animations. We now have access to $animateCss and the many timing-oriented bugs were fixed which results in smoother animations. If animation is something of interest, then please read over the breaking changes below for animations when ngAnimate is used.

ngMessages has been upgraded to allow for dynamic message resolution. This handy feature allows for developers to render error messages with ngMessages that are listed with a directive such as ngRepeat. A great usecase for this involves pulling error message data from a server and then displaying that data via the mechanics of ngMessages. Be sure to read the breaking change involved with ngMessagesInclude to upgrade your template code.

Other changes, such as the ordering of elements with ngRepeat and ngOptions, may also affect the behavior of your application. And be sure to also read up on the changes to $cookies. The migration jump from 1.3 to 1.4 should be relatively straightforward otherwise.

Animation (ngAnimate)

Animations in 1.4 have been refactored internally, but the API has stayed much the same. There are, however, some breaking changes that need to be addressed when upgrading to 1.4.

Due to c8700f04, JavaScript and CSS animations can no longer be run in parallel. With earlier versions of ngAnimate, both CSS and JS animations would be run together when multiple animations were detected. This feature has been removed, however, the same effect, with even more possibilities, can be achieved by injecting $animateCss into a JavaScript-defined animation and creating custom CSS-based animations from there.

By using $animateCss inside of a JavaScript animation in Angular 1.4, we can trigger custom CSS-based animations directly from our JavaScript code.

ngModule.animation('.slide-animation', ['$animateCss', function($animateCss) {
  return {
    enter: function(element, doneFn) {
      // this will trigger a `.ng-enter` and `.ng-enter-active` CSS animation
      var animation = $animateCss(element, {
        event: 'enter'
        // any other CSS-related properties
        //   addClass: 'some-class',
        //   removeClass: 'some-other-class',
        //   from: {},
        //   to: {}
      });

      // make sure to read the ngAnimate docs to understand how this works
      animation.start().done(doneFn);
    }
  }
}]);

Click here to learn how to use $animateCss in your animation code

Due to c8700f04, animation-related callbacks are now fired on $animate.on instead of directly being on the element.

// < 1.4
element.on('$animate:before', function(e, data) {
  if (data.event === 'enter') { ... }
});
element.off('$animate:before', fn);

// 1.4+
$animate.on('enter', element, function(data) {
  //...
});
$animate.off('enter', element, fn);

Due to c8700f04, the function params for $animate.enabled() when an element is used are now flipped. This fix allows the function to act as a getter when a single element param is provided.

// < 1.4
$animate.enabled(false, element);

// 1.4+
$animate.enabled(element, false);

Due to c8700f04, in addition to disabling the children of the element, $animate.enabled(element, false) will now also disable animations on the element itself.

Due to c8700f04, there is no need to call $scope.$apply or $scope.$digest inside of a animation promise callback anymore since the promise is resolved within a digest automatically. (Not to worry, any extra digests will not be run unless the promise is used.)

// < 1.4
$animate.enter(element).then(function() {
  $scope.$apply(function() {
    $scope.explode = true;
  });
});

// 1.4+
$animate.enter(element).then(function() {
  $scope.explode = true;
});

Due to c8700f04, when an enter, leave or move animation is triggered then it will always end any pending or active parent class based animations (animations triggered via ngClass) in order to ensure that any CSS styles are resolved in time.

Forms (ngMessages, ngOptions, select)

ngMessages

The ngMessages module has also been subject to an internal refactor to allow it to be more flexible and compatible with dynamic message data. The ngMessage directive now supports a new attribute called ng-message-exp which will evaluate an expression and will keep track of that expression as it changes in order to re-evaluate the listed messages.

Click here to learn more about dynamic ng-messages

There is only one breaking change. Please consider the following when including remote message templates via ng-messages-include:

Due to c9a4421f, the ngMessagesInclude attribute has now been removed and cannot be used in the same element containing the ngMessages directive. Instead, ngMessagesInclude is to be used on its own element inline with other inline messages situated as children within the ngMessages container directive.

<!-- AngularJS 1.3.x -->
<div ng-messages="model.$error" ng-messages-include="remote.html">
  <div ng-message="required">Your message is required</div>
</div>

<!-- AngularJS 1.4.x -->
<div ng-messages="model.$error">
  <div ng-message="required">Your message is required</div>
  <div ng-messages-include="remote.html"></div>
</div>

Depending on where the ngMessagesInclude directive is placed it will be prioritized inline with the other messages before and after it.

Also due to c9a4421f, it is no longer possible to use interpolation inside the ngMessages attribute expression. This technique is generally not recommended, and can easily break when a directive implementation changes. In cases where a simple expression is not possible, you can delegate accessing the object to a function:

<div ng-messages="ctrl.form['field_{{$index}}'].$error">...</div>

would become

<div ng-messages="ctrl.getMessages($index)">...</div>

where ctrl.getMessages()

ctrl.getMessages = function($index) {
  return ctrl.form['field_' + $index].$error;
}

ngOptions

The ngOptions directive has also been refactored and as a result some long-standing bugs have been fixed. The breaking changes are comparatively minor and should not affect most applications.

Due to 7fda214c, when ngOptions renders the option values within the DOM, the resulting HTML code is different. Normally this should not affect your application at all, however, if your code relies on inspecting the value property of <option> elements (that ngOptions generates) then be sure to read the details.

Due to 7fda214c, when iterating over an object's properties using the (key, value) in obj syntax the order of the elements used to be sorted alphabetically. This was an artificial attempt to create a deterministic ordering since browsers don't guarantee the order. But in practice this is not what people want and so this change iterates over properties in the order they are returned by Object.keys(obj), which is almost always the order in which the properties were defined.

Also due to 7fda214c, setting the ngOptions attribute expression after the element is compiled, will no longer trigger the ngOptions behavior. This worked previously because the ngOptions logic was part of the select directive, while it is now implemented in the ngOptions directive itself.

select

Due to 7fda214c, the select directive will now use strict comparison of the ngModel scope value against option values to determine which option is selected. This means non-string scope values (such as Number or Boolean) will not be matched against equivalent option strings (such as the strings "123", "true" or "false").

In Angular 1.3.x, setting scope.x = 200 would select the option with the value 200 in the following select:

<select ng-model="x">
  <option value="100">100</option>
  <option value="200">200</option>
</select>

In Angular 1.4.x, the 'unknown option' will be selected.

To remedy this, you can initialize the model as a string: scope.x = '200', or if you want to keep the model as a Number, you can do the conversion via $formatters and $parsers on ngModel:

ngModelCtrl.$parsers.push(function(value) {
  return parseInt(value, 10); // Convert option value to number
});

ngModelCtrl.$formatters.push(function(value) {
  return value.toString(); // Convert scope value to string
});

Templating (ngRepeat, $compile)

ngRepeat

Due to c260e738, previously, the order of items when using ngRepeat to iterate over object properties was guaranteed to be consistent by sorting the keys into alphabetic order.

Now, the order of the items is browser dependent based on the order returned from iterating over the object using the for key in obj syntax.

It seems that browsers generally follow the strategy of providing keys in the order in which they were defined, although there are exceptions when keys are deleted and reinstated. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/delete#Cross-browser_issues

The best approach is to convert Objects into Arrays by a filter such as https://github.com/petebacondarwin/angular-toArrayFilter or some other mechanism, and then sort them manually in the order you need.

$compile

Due to 6a38dbfd, previously, '&' expressions would always set up a function in the isolate scope. Now, if the binding is marked as optional and the attribute is not specified, no function will be added to the isolate scope.

Due to 62d514b, returning an object from a controller constructor function will now override the scope. Views that use the controllerAs method will no longer get the this reference, but the returned object.

Cookies (ngCookies)

Due to 38fbe3ee, $cookies will no longer expose properties that represent the current browser cookie values. $cookies no longer polls the browser for changes to the cookies and no longer copies cookie values onto the $cookies object.

This was changed because the polling is expensive and caused issues with the $cookies properties not synchronizing correctly with the actual browser cookie values (The reason the polling was originally added was to allow communication between different tabs, but there are better ways to do this today, for example localStorage.)

The new API on $cookies is as follows:

You must explictly use the methods above in order to access cookie data. This also means that you can no longer watch the properties on $cookies to detect changes that occur on the browsers cookies.

This feature is generally only needed if a 3rd party library was programmatically changing the cookies at runtime. If you rely on this then you must either write code that can react to the 3rd party library making the changes to cookies or implement your own polling mechanism.

DEPRECATION NOTICE

$cookieStore is now deprecated as all the useful logic has been moved to $cookies, to which $cookieStore now simply delegates calls.

Server Requests ($http)

Due to 5da1256, transformRequest functions can no longer modify request headers.

Before this commit transformRequest could modify request headers, ex.:

function requestTransform(data, headers) {
    headers = angular.extend(headers(), {
      'X-MY_HEADER': 'abcd'
    });
  }
  return angular.toJson(data);
}

This behavior was unintended and undocumented, so the change should affect very few applications. If one needs to dynamically add / remove headers it should be done in a header function, for example:

$http.get(url, {
  headers: {
    'X-MY_HEADER': function(config) {
      return 'abcd'; //you've got access to a request config object to specify header value dynamically
    }
  }
})

Filters (filter, limitTo)

filter filter

Due to cea8e751, the filter filter will throw an error when used with a non-array. Beforehand it would silently return an empty array.

If necessary, this can be worked around by converting an object to an array, using a filter such as https://github.com/petebacondarwin/angular-toArrayFilter.

limitTo filter

Due to a3c3bf33, the limitTo filter has changed behavior when the provided limit value is invalid. Now, instead of returning empty object/array, it returns unchanged input.

Migrating from 1.2 to 1.3

Controllers

Due to 3f2232b5, $controller will no longer look for controllers on window. The old behavior of looking on window for controllers was originally intended for use in examples, demos, and toy apps. We found that allowing global controller functions encouraged poor practices, so we resolved to disable this behavior by default.

To migrate, register your controllers with modules rather than exposing them as globals:

Before:

function MyController() {
  // ...
}

After:

angular.module('myApp', []).controller('MyController', [function() {
  // ...
}]);

Although it's not recommended, you can re-enable the old behavior like this:

angular.module('myModule').config(['$controllerProvider', function($controllerProvider) {
  // this option might be handy for migrating old apps, but please don't use it
  // in new ones!
  $controllerProvider.allowGlobals();
}]);

Angular Expression Parsing ($parse + $interpolate)

You can no longer invoke .bind, .call or .apply on a function in angular expressions. This is to disallow changing the behaviour of existing functions in an unforeseen fashion.

The (deprecated) proto property does not work inside angular expressions anymore.

This prevents the use of {define,lookup}{Getter,Setter} inside angular expressions. If you really need them for some reason, please wrap/bind them to make them less dangerous, then make them available through the scope object.

This prevents the use of Object inside angular expressions. If you need Object.keys, make it accessible in the scope.

Miscellaneous Angular helpers

This changes angular.copy so that it applies the prototype of the original object to the copied object. Previously, angular.copy would copy properties of the original object's prototype chain directly onto the copied object.

This means that if you iterate over only the copied object's hasOwnProperty properties, it will no longer contain the properties from the prototype. This is actually much more reasonable behaviour and it is unlikely that applications are actually relying on this.

If this behaviour is relied upon, in an app, then one should simply iterate over all the properties on the object (and its inherited properties) and not filter them with hasOwnProperty.

Be aware that this change also uses a feature that is not compatible with IE8. If you need this to work on IE8 then you would need to provide a polyfill for Object.create and Object.getPrototypeOf.

This change also makes our forEach behave more like Array#forEach.

jqLite / JQuery

Angular HTML Compiler ($compile)

The isolated scope of a component directive no longer leaks into the template that contains the instance of the directive. This means that you can no longer access the isolated scope from attributes on the element where the isolated directive is defined.

See https://github.com/angular/angular.js/issues/10236 for an example.

Requesting isolate scope and any other scope on a single element is an error. Before this change, the compiler let two directives request a child scope and an isolate scope if the compiler applied them in the order of non-isolate scope directive followed by isolate scope directive.

Now the compiler will error regardless of the order.

If you find that your code is now throwing a $compile:multidir error, check that you do not have directives on the same element that are trying to request both an isolate and a non-isolate scope and fix your code.

Before:

directive('directiveName', function() {
  return {
    link: function(scope, elm, attr) {
      var observer = attr.$observe('someAttr', function(value) {
        console.log(value);
      });
    }
  };
});

After:

directive('directiveName', function() {
  return {
    link: function(scope, elm, attr) {
      var observer = function(value) {
        console.log(value);
      };

      attr.$observe('someAttr', observer);
    }
  };
});

<my-dir></my-dir>

// Link function for directive myDir
link: function(scope, element, attr) {
  attr.$observe('myAttr', function(newVal) {
    scope.myValue = newVal ? newVal : 'myDefaultValue';
  })
}

Instead, check if the attribute is set before registering the observer:

link: function(scope, element, attr) {
  if (attr.myAttr) {
    // register the observer
  } else {
    // set the default
  }
}

Forms, Inputs and ngModel

If an expression is used on ng-pattern (such as ng-pattern="exp") or on the pattern attribute (something like on pattern="{{ exp }}") and the expression itself evaluates to a string then the validator will not parse the string as a literal regular expression object (a value like /abc/i). Instead, the entire string will be created as the regular expression to test against. This means that any expression flags will not be placed on the RegExp object. To get around this limitation, use a regular expression object as the value for the expression.

//before
$scope.exp = '/abc/i';

//after
$scope.exp = /abc/i;

This commit changes the API on NgModelController, both semantically and in terms of adding and renaming methods.

To migrate code that used $cancelUpdate() follow the example below:

Before:

$scope.resetWithCancel = function (e) {
  if (e.keyCode == 27) {
    $scope.myForm.myInput1.$cancelUpdate();
    $scope.myValue = '';
  }
};

After:

$scope.resetWithCancel = function (e) {
  if (e.keyCode == 27) {
    $scope.myForm.myInput1.$rollbackViewValue();
    $scope.myValue = '';
  }
}

Scopes and Digests ($scope)

Server Requests ($http, $resource)

Previously, it was possible to register a response interceptor like so:

// register the interceptor as a service
$provide.factory('myHttpInterceptor', function($q, dependency1, dependency2) {
  return function(promise) {
    return promise.then(function(response) {
      // do something on success
      return response;
    }, function(response) {
      // do something on error
      if (canRecover(response)) {
        return responseOrNewPromise
      }
      return $q.reject(response);
    });
  }
});

$httpProvider.responseInterceptors.push('myHttpInterceptor');

Now, one must use the newer API introduced in v1.1.4 (4ae46814), like so:

$provide.factory('myHttpInterceptor', function($q) {
  return {
    response: function(response) {
      // do something on success
      return response;
    },
    responseError: function(response) {
      // do something on error
      if (canRecover(response)) {
        return responseOrNewPromise
      }
      return $q.reject(response);
    }
  };
});

$httpProvider.interceptors.push('myHttpInterceptor');

More details on the new interceptors API (which has been around as of v1.1.4) can be found at interceptors

Modules and Injector ($inject)

Previously, config blocks would be able to control behaviour of provider registration, due to being invoked prior to provider registration. Now, provider registration always occurs prior to configuration for a given module, and therefore config blocks are not able to have any control over a providers registration.

Example:

Previously, the following:

angular.module('foo', [])
.provider('$rootProvider', function() {
  this.$get = function() { ... }
})
.config(function($rootProvider) {
  $rootProvider.dependentMode = "B";
})
.provider('$dependentProvider', function($rootProvider) {
   if ($rootProvider.dependentMode === "A") {
     this.$get = function() {
      // Special mode!
     }
   } else {
     this.$get = function() {
       // something else
     }
  }
});

would have "worked", meaning behaviour of the config block between the registration of "$rootProvider" and "$dependentProvider" would have actually accomplished something and changed the behaviour of the app. This is no longer possible within a single module.

Animation (ngAnimate)

To update existing code, change all instances of $animate.enter() or $animate.move() from:

$animate.enter(element, parent);

to:

$animate.enter(element, parent, angular.element(parent[0].lastChild));

Before:

.animated.my-class-add {
  opacity:0;
  transition:0.5s linear all;
}
.animated.my-class-add.my-class-add-active {
  opacity:1;
}

After:

.animated.my-class-add {
  transition:0s linear all;
  opacity:0;
}
.animated.my-class-add.my-class-add-active {
  transition:0.5s linear all;
  opacity:1;
}

Please view the documentation for ngAnimate for more info.

Testing

by.binding(descriptor) no longer allows using the surrounding interpolation markers in the descriptor (the default interpolation markers are {{}}). Previously, these were optional.

Before:

var el = element(by.binding('{{foo}}'));

After:

var el = element(by.binding('foo'));

Prefixes ng_ and x-ng- are no longer allowed for models. Use ng-model.

by.repeater cannot find elements by row and column which are not children of the row. For example, if your template is

<div ng-repeat="foo in foos">{{foo.name}}</div>

Before:

var el = element(by.repeater('foo in foos').row(2).column('foo.name'))

After:

You may either enclose {{foo.name}} in a child element

<div ng-repeat="foo in foos"><span>{{foo.name}}</span></div>

or simply use:

var el = element(by.repeater('foo in foos').row(2))

Internet Explorer 8

Migrating from 1.0 to 1.2

Note: AngularJS versions 1.1.x are considered "experimental" with breaking changes between minor releases. Version 1.2 is the result of several versions on the 1.1 branch, and has a stable API.

If you have an application on 1.1 and want to migrate it to 1.2, everything in the guide below should still apply, but you may want to consult the changelog as well.

ngRoute has been moved into its own module

Just like ngResource, ngRoute is now its own module.

Applications that use $route, ngView, and/or $routeParams will now need to load an angular-route.js file and have their application's module dependency on the ngRoute module.

Before:

<script src="angular.js"></script>

var myApp = angular.module('myApp', ['someOtherModule']);

After:

<script src="angular.js"></script>
<script src="angular-route.js"></script>

var myApp = angular.module('myApp', ['ngRoute', 'someOtherModule']);

See 5599b55b.

Templates no longer automatically unwrap promises

$parse and templates in general will no longer automatically unwrap promises.

Before:

$scope.foo = $http({method: 'GET', url: '/someUrl'});

<p>{{foo}}</p>

After:

$http({method: 'GET', url: '/someUrl'})
.success(function(data) {
  $scope.foo = data;
});

<p>{{foo}}</p>

This feature has been deprecated. If absolutely needed, it can be reenabled for now via the $parseProvider.unwrapPromises(true) API.

See 5dc35b52, b6a37d11.

Syntax for named wildcard parameters changed in $route

To migrate the code, follow the example below. Here, *highlight becomes :highlight*

Before:

$routeProvider.when('/Book1/:book/Chapter/:chapter/*highlight/edit',
{controller: noop, templateUrl: 'Chapter.html'});

After:

$routeProvider.when('/Book1/:book/Chapter/:chapter/:highlight*/edit',
{controller: noop, templateUrl: 'Chapter.html'});

See 04cebcc1.

You can only bind one expression to *[src], *[ng-src] or action

With the exception of <a> and <img> elements, you cannot bind more than one expression to the src or action attribute of elements.

This is one of several improvements to security introduces by Angular 1.2.

Concatenating expressions makes it hard to understand whether some combination of concatenated values are unsafe to use and potentially subject to XSS vulnerabilities. To simplify the task of auditing for XSS issues, we now require that a single expression be used for *[src/ng-src] bindings such as bindings for iframe[src], object[src], etc. In addition, this requirement is enforced for form tags with action attributes.

Examples
<img src="{{a}}/{{b}}"> ok
<iframe src="{{a}}/{{b}}"></iframe> bad
<iframe src="{{a}}"></iframe> ok

To migrate your code, you can combine multiple expressions using a method attached to your scope.

Before:

scope.baseUrl = 'page';
scope.a = 1;
scope.b = 2;

<!-- Are a and b properly escaped here? Is baseUrl controlled by user? -->
<iframe src="{{baseUrl}}?a={{a}&b={{b}}">

After:

var baseUrl = "page";
scope.getIframeSrc = function() {

  // One should think about their particular case and sanitize accordingly
  var qs = ["a", "b"].map(function(value, name) {
      return encodeURIComponent(name) + "=" +
             encodeURIComponent(value);
    }).join("&");

  // `baseUrl` isn't exposed to a user's control, so we don't have to worry about escaping it.
  return baseUrl + "?" + qs;
};

<iframe src="{{getIframeSrc()}}">

See 38deedd6.

Interpolations inside DOM event handlers are now disallowed

DOM event handlers execute arbitrary Javascript code. Using an interpolation for such handlers means that the interpolated value is a JS string that is evaluated. Storing or generating such strings is error prone and leads to XSS vulnerabilities. On the other hand, ngClick and other Angular specific event handlers evaluate Angular expressions in non-window (Scope) context which makes them much safer.

To migrate the code follow the example below:

Before:

JS:   scope.foo = 'alert(1)';
HTML: <div onclick="{{foo}}">

After:

JS:   scope.foo = function() { alert(1); }
HTML: <div ng-click="foo()">

See 39841f2e.

Directives cannot end with -start or -end

This change was necessary to enable multi-element directives. The best fix is to rename existing directives so that they don't end with these suffixes.

See e46100f7.

In $q, promise.always has been renamed promise.finally

The reason for this change is to align $q with the Q promise library, despite the fact that this makes it a bit more difficult to use with non-ES5 browsers, like IE8.

finally also goes well together with the catch API that was added to $q recently and is part of the DOM promises standard.

To migrate the code follow the example below.

Before:

$http.get('/foo').always(doSomething);

After:

$http.get('/foo').finally(doSomething);

Or for IE8-compatible code:

$http.get('/foo')['finally'](doSomething);

See f078762d.

ngMobile is now ngTouch

Many touch-enabled devices are not mobile devices, so we decided to rename this module to better reflect its concerns.

To migrate, replace all references to ngMobile with ngTouch and angular-mobile.js with angular-touch.js.

See 94ec84e7.

resource.$then has been removed

Resource instances do not have a $then function anymore. Use the $promise.then instead.

Before:

Resource.query().$then(callback);

After:

Resource.query().$promise.then(callback);

See 05772e15.

Resource methods return the promise

Methods of a resource instance return the promise rather than the instance itself.

Before:

resource.$save().chaining = true;

After:

resource.$save();
resource.chaining = true;

See 05772e15.

Resource promises are resolved with the resource instance

On success, the resource promise is resolved with the resource instance rather than HTTP response object.

Use interceptor API to access the HTTP response object.

Before:

Resource.query().$then(function(response) {...});

After:

var Resource = $resource('/url', {}, {
  get: {
    method: 'get',
    interceptor: {
      response: function(response) {
        // expose response
        return response;
      }
    }
  }
});

See 05772e15.

$location.search supports multiple keys

$location.search now supports multiple keys with the same value provided that the values are stored in an array.

Before this change:

This was deemed buggy behavior. If your server relied on this behavior then either the server should be fixed, or a simple serialization of the array should be done on the client before passing it to $location.

See 80739409.

ngBindHtmlUnsafe has been removed and replaced by ngBindHtml

ngBindHtml provides ngBindHtmlUnsafe like behavior (evaluate an expression and innerHTML the result into the DOM) when bound to the result of $sce.trustAsHtml(string). When bound to a plain string, the string is sanitized via $sanitize before being innerHTML'd. If the $sanitize service isn't available (ngSanitize module is not loaded) and the bound expression evaluates to a value that is not trusted an exception is thrown.

When using this directive you can either include ngSanitize in your module's dependencies (See the example at the ngBindHtml reference) or use the $sce service to set the value as trusted.

See dae69473.

Form names that are expressions are evaluated

If you have form names that will evaluate as an expression:

<form name="ctrl.form">

And if you are accessing the form from your controller:

Before:

function($scope) {
  $scope['ctrl.form'] // form controller instance
}

After:

function($scope) {
  $scope.ctrl.form // form controller instance
}

This makes it possible to access a form from a controller using the new "controller as" syntax. Supporting the previous behavior offers no benefit.

See 8ea802a1.

hasOwnProperty disallowed as an input name

Inputs with name equal to hasOwnProperty are not allowed inside form or ngForm directives.

Before, inputs whose name was "hasOwnProperty" were quietly ignored and not added to the scope. Now a badname exception is thrown. Using "hasOwnProperty" for an input name would be very unusual and bad practice. To migrate, change your input name.

See 7a586e5c.

The order of postLink fn is now mirror opposite of the order in which corresponding preLinking and compile functions execute.

Previously the compile/link fns executed in order, sorted by priority:

# Step Old Sort Order New Sort Order
1 Compile Fns High → Low
2 Compile child nodes
3 PreLink Fns High → Low
4 Link child nodes
5 PostLink Fns High → Low Low → High

"High → Low" here refers to the priority option of a directive.

Very few directives in practice rely on the order of postLinking functions (unlike on the order of compile functions), so in the rare case of this change affecting an existing directive, it might be necessary to convert it to a preLinking function or give it negative priority.

You can look at the diff of this commit to see how an internal attribute interpolation directive was adjusted.

See 31f190d4.

Directive priority

the priority of ngRepeat, ngSwitchWhen, ngIf, ngInclude and ngView has changed. This could affect directives that explicitly specify their priority.

In order to make ngRepeat, ngSwitchWhen, ngIf, ngInclude and ngView work together in all common scenarios their directives are being adjusted to achieve the following precedence:

Directive Old Priority New Priority
ngRepeat 1000 1000
ngSwitchWhen 500 800
ngIf 1000 600
ngInclude 1000 400
ngView 1000 400

See b7af76b4.

ngScenario

browserTrigger now uses an eventData object instead of direct parameters for mouse events. To migrate, place the keys,x and y parameters inside of an object and place that as the third parameter for the browserTrigger function.

See 28f56a38.

ngInclude and ngView replace its entire element on update

Previously ngInclude and ngView only updated its element's content. Now these directives will recreate the element every time a new content is included.

This ensures that a single rootElement for all the included contents always exists, which makes definition of css styles for animations much easier.

See 7d69d52a, aa2133ad.

URLs are now sanitized against a whitelist

A whitelist configured via $compileProvider can be used to configure what URLs are considered safe. By default all common protocol prefixes are whitelisted including data: URIs with mime types image/*. This change shouldn't impact apps that don't contain malicious image links.

See 1adf29af, 3e39ac7e.

Isolate scope only exposed to directives with scope property

If you declare a scope option on a directive, that directive will have an isolate scope. In Angular 1.0, if a directive with an isolate scope is used on an element, all directives on that same element have access to the same isolate scope. For example, say we have the following directives:

// This directive declares an isolate scope.
.directive('isolateScope', function() {
  return {
    scope: {},
    link: function($scope) {
      console.log('one = ' + $scope.$id);
    }
  };
})

// This directive does not.
.directive('nonIsolateScope', function() {
  return {
    link: function($scope) {
      console.log('two = ' + $scope.$id);
    }
  };
});

Now what happens if we use both directives on the same element?

<div isolate-scope non-isolate-scope></div>

In Angular 1.0, the nonIsolateScope directive will have access to the isolateScope directive’s scope. The log statements will print the same id, because the scope is the same. But in Angular 1.2, the nonIsolateScope will not use the same scope as isolateScope. Instead, it will inherit the parent scope. The log statements will print different id’s.

If your code depends on the Angular 1.0 behavior (non-isolate directive needs to access state from within the isolate scope), change the isolate directive to use scope locals to pass these explicitly:

Before

<input ng-model="$parent.value" ng-isolate>

.directive('ngIsolate', function() {
  return {
    scope: {},
    template: '{{value}}'
  };
});

After

<input ng-model="value" ng-isolate>

.directive('ngIsolate', function() {
  return {
    scope: {value: '=ngModel'},
    template: '{{value}}
  };
});

See 909cabd3, #1924 and #2500.

Change to interpolation priority

Previously, the interpolation priority was -100 in 1.2.0-rc.2, and 100 before 1.2.0-rc.2. Before this change the binding was setup in the post-linking phase.

Now the attribute interpolation (binding) executes as a directive with priority 100 and the binding is set up in the pre-linking phase.

See 79223eae, #4525, #4528, and #4649

Underscore-prefixed/suffixed properties are non-bindable

Reverted: This breaking change has been reverted in 1.2.1, and so can be ignored if you're using version 1.2.1 or higher

This change introduces the notion of "private" properties (properties whose names begin and/or end with an underscore) on the scope chain. These properties will not be available to Angular expressions (i.e. {{ }} interpolation in templates and strings passed to $parse) They are freely available to JavaScript code (as before).

Motivation

Angular expressions execute in a limited context. They do not have direct access to the global scope, window, document or the Function constructor. However, they have direct access to names/properties on the scope chain. It has been a long standing best practice to keep sensitive APIs outside of the scope chain (in a closure or your controller.) That's easier said than done for two reasons:

  1. JavaScript does not have a notion of private properties so if you need someone on the scope chain for JavaScript use, you also expose it to Angular expressions
  2. The new controller as syntax that's now in increased usage exposes the entire controller on the scope chain greatly increasing the exposed surface.

Though Angular expressions are written and controlled by the developer, they:

  1. Typically deal with user input
  2. Don't get the kind of test coverage that JavaScript code would

This commit provides a way, via a naming convention, to allow restricting properties from controllers/scopes. This means Angular expressions can access only those properties that are actually needed by the expressions.

See 3d6a89e8.

You cannot bind to select[multiple]

Switching between select[single] and select[multiple] has always been odd due to browser quirks. This feature never worked with two-way data-binding so it's not expected that anyone is using it.

If you are interested in properly adding this feature, please submit a pull request on Github.

See d87fa004.

Uncommon region-specific local files were removed from i18n

AngularJS uses the Google Closure library's locale files. The following locales were removed from Closure, so Angular is not able to continue to support them:

chr, cy, el-polyton, en-zz, fr-rw, fr-sn, fr-td, fr-tg, haw, it-ch, ln-cg, mo, ms-bn, nl-aw, nl-be, pt-ao, pt-gw, pt-mz, pt-st, ro-md, ru-md, ru-ua, sr-cyrl-ba, sr-cyrl-me, sr-cyrl, sr-latn-ba, sr-latn-me, sr-latn, sr-rs, sv-fi, sw-ke, ta-lk, tl-ph, ur-in, zh-hans-hk, zh-hans-mo, zh-hans-sg, zh-hans, zh-hant-hk, zh-hant-mo, zh-hant-tw, zh-hant

Although these locales were removed from the official AngularJS repository, you can continue to load and use your copy of the locale file provided that you maintain it yourself.

See 6382e21f.

Services can now return functions

Previously, the service constructor only returned objects regardless of whether a function was returned.

Now, $injector.instantiate (and thus $provide.service) behaves the same as the native new operator and allows functions to be returned as a service.

If using a JavaScript preprocessor it's quite possible when upgrading that services could start behaving incorrectly. Make sure your services return the correct type wanted.

Coffeescript example

myApp.service 'applicationSrvc', ->
@something = "value"
@someFunct = ->
  "something else"

pre 1.2 this service would return the whole object as the service.

post 1.2 this service returns someFunct as the value of the service

you would need to change this services to

myApp.service 'applicationSrvc', ->
@something = "value"
@someFunct = ->
  "something else"
return

to continue to return the complete instance.

See c22adbf1.