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.
$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.
$parseProvider.unwrapPromises
$parseProvider.logPromiseWarnings
$interpolate: due to 88c2193c,
the function returned by $interpolate
no longer has a .parts
array set on it.
Instead it has two arrays:
.expressions
, an array of the expressions in the
interpolated text. The expressions are parsed with
$parse
, with an extra layer converting them to strings
when computed.separators
, an array of strings representing the
separations between interpolations in the text.
This array is always 1 item longer than the
.expressions
array for easy merging with itThis 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.
If you expected toJson
to strip these types of properties before, you will have to
manually do this yourself now.
detach()
method does not trigger the $destroy
event.
If you want to destroy Angular data attached to the element, use remove()
.$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.
replace
flag for defining directives that
replace the element that they are on will be removed in the next major angular version.
This feature has difficult semantics (e.g. how attributes are merged) and leads to more
problems compared to what it solves. Also, with Web Components it is normal to have
custom elements in the DOM.attr.$observe
no longer returns the observer function, but a
deregistration function instead. To migrate the code follow the example below: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);
}
};
});
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.
$setViewValue(value)
-
This method still changes the $viewValue
but does not immediately commit this
change through to the $modelValue
as it did previously.
Now the value is committed only when a trigger specified in an associated
ngModelOptions
directive occurs. If ngModelOptions
also has a debounce
delay
specified for the trigger then the change will also be debounced before being
committed.
In most cases this should not have a significant impact on how NgModelController
is used: If updateOn
includes default
then $setViewValue
will trigger
a (potentially debounced) commit immediately.$cancelUpdate()
- is renamed to $rollbackViewValue()
and has the same meaning,
which is to revert the current $viewValue
back to the $lastCommittedViewValue
,
to cancel any pending debounced updates and to re-render the input.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 = '';
}
}
Date
object as model (46bd6dc8,
#5864)$scope
)$broadcast
and $emit
will now reset the currentScope
property of the event to
null once the event finished propagating. If any code depends on asynchronously accessing their
currentScope
property, it should be migrated to use targetScope
instead. All of these cases
should be considered programming bugs.$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
$resource: due to d3c50c84,
If you expected $resource
to strip these types of properties before,
you will have to manually do this yourself now.
$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.
ngAnimate
)$animate
will no longer default the after parameter to the last element of the parent
container. Instead, when after is not specified, the new element will be inserted as the
first child of the parent container.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));
due to 1bebe36a,
Any class-based animation code that makes use of transitions
and uses the setup CSS classes (such as class-add and class-remove) must now
provide a empty transition value to ensure that its styling is applied right
away. In other words if your animation code is expecting any styling to be
applied that is defined in the setup class then it will not be applied
"instantly" unless a transition:0s none
value is present in the styling
for that CSS class. This situation is only the case if a transition is already
present on the base CSS class once the animation kicks off.
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.
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))
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.
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.
$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.
$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.
*[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.
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.
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.
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.
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 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.
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.
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
now supports multiple keys with the
same value provided that the values are stored in an array.
Before this change:
parseKeyValue
only took the last key overwriting all the previous keys.toKeyValue
joined the keys together in a comma delimited string.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.
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.
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.
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.
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.
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.
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.
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.
scope
propertyIf 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.
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
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:
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:
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.
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.
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.
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.