From ae2cdeb2de418bfc59e70cc1885c818864088c57 Mon Sep 17 00:00:00 2001 From: Brian Ford Date: Thu, 7 Nov 2013 10:16:50 -0800 Subject: docs(guide/migration): add migration guide --- docs/content/guide/migration.ngdoc | 651 +++++++++++++++++++++++++++++++++++++ 1 file changed, 651 insertions(+) create mode 100644 docs/content/guide/migration.ngdoc (limited to 'docs/content/guide') diff --git a/docs/content/guide/migration.ngdoc b/docs/content/guide/migration.ngdoc new file mode 100644 index 00000000..ebcadc5e --- /dev/null +++ b/docs/content/guide/migration.ngdoc @@ -0,0 +1,651 @@ +@ngdoc overview +@name Migrating from 1.0 to 1.2 +@description + + +AngularJS version 1.2 introduces several breaking changes that will may require changes to your +application's source code. + +Although we try to avoid breaking changes, there are some cases where it is unavoidable. +AngularJS 1.2 has undergone a thourough security review to make applications safer by default, +which has driven many of these changes. Several new features, especially animations, would not +be possible without a few changes. Finally, some outstanding bugs were best fixed by changing +an existing API. + +
+

**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](https://github.com/angular/angular.js/blob/master/CHANGELOG.md) 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: + +```html + +``` + +```javascript +var myApp = angular.module('myApp', ['someOtherModule']); +``` + +After: + +```html + + +``` + +```javascript +var myApp = angular.module('myApp', ['ngRoute', 'someOtherModule']); +``` + +See [5599b55b](https://github.com/angular/angular.js/commit/5599b55b04788c2e327d7551a4a699d75516dd21). + + +## Templates no longer automatically unwrap promises + +`$parse` and templates in general will no longer automatically unwrap promises. + +Before: + +```javascript +$scope.foo = $http({method: 'GET', url: '/someUrl'}); +``` + +```html +

{{foo}}

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

{{foo}}

+``` + +This feature has been deprecated. If absolutely needed, it can be reenabled for now via the +`$parseProvider.unwrapPromises(true)` API. + +See [5dc35b52](https://github.com/angular/angular.js/commit/5dc35b527b3c99f6544b8cb52e93c6510d3ac577), +[b6a37d11](https://github.com/angular/angular.js/commit/b6a37d112b3e1478f4d14a5f82faabf700443748). + + +## Syntax for named wildcard parameters changed in `$route` + +To migrate the code, follow the example below. Here, `*highlight` becomes `:highlight*` + +Before: + +```javascript +$routeProvider.when('/Book1/:book/Chapter/:chapter/*highlight/edit', + {controller: noop, templateUrl: 'Chapter.html'}); +``` + +After: + +```javascript +$routeProvider.when('/Book1/:book/Chapter/:chapter/:highlight*/edit', + {controller: noop, templateUrl: 'Chapter.html'}); +``` + +See [04cebcc1](https://github.com/angular/angular.js/commit/04cebcc133c8b433a3ac5f72ed19f3631778142b). + + +## You can only bind one expression to `*[src]` or `*[ng-src]` + +With the exception of `` and `` elements, you cannot bind more than one expression to the +`src` 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. + + + + + + + + + + + + + + + + + + + + + +
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: + +```javascript +scope.baseUrl = 'page'; +scope.a = 1; +scope.b = 2; +``` + +```html + +