diff --git a/CHANGELOG.md b/CHANGELOG.md index b3fbcff12acd..23df2398dc30 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -448,8 +448,8 @@ This in turn affects how dirty checking treats objects that prototypally inherit from `Array` (e.g. MobX observable arrays). AngularJS will now be able to handle these objects better when copying or watching. -### **$sce** due to: - - **[1e9ead](https://github.com/angular/angular.js/commit/1e9eadcd72dbbd5c67dae8328a63e535cfa91ff9)**: handle URL sanitization through the `$sce` service +### **$sce** : + - due to **[1e9ead](https://github.com/angular/angular.js/commit/1e9eadcd72dbbd5c67dae8328a63e535cfa91ff9)**: handle URL sanitization through the `$sce` service If you use `attrs.$set` for URL attributes (a[href] and img[src]) there will no longer be any automated sanitization of the value. This is in line with other @@ -463,6 +463,35 @@ Note that values that have been passed through the `$interpolate` service within `URL` or `MEDIA_URL` will have already been sanitized, so you would not need to sanitize these values again. + - due to **[1e9ead](https://github.com/angular/angular.js/commit/1e9eadcd72dbbd5c67dae8328a63e535cfa91ff9)**: handle URL sanitization through the `$sce` service + +binding `trustAs()` and the short versions (`trustAsResourceUrl()` et al.) to +`ngSrc`, `ngSrcset`, and `ngHref` will now raise an infinite digest error: + +```js + $scope.imgThumbFn = function(id) { + return $sce.trustAsResourceUrl(someService.someUrl(id)); + }; +``` + +```html + +``` +This is because the `$interpolate` service is now responsible for sanitizing +the attribute value, and its watcher receives a new object from `trustAs()` +on every digest. +To migrate, compute the trusted value only when the input value changes: + +```js + $scope.$watch('imgId', function(id) { + $scope.imgThumb = $sce.trustAsResourceUrl(someService.someUrl(id)); + }); +``` + +```html + +``` + ### **orderBy** due to: - **[1d8046](https://github.com/angular/angular.js/commit/1d804645f7656d592c90216a0355b4948807f6b8)**: consider `null` and `undefined` greater than other values diff --git a/docs/content/guide/$location.ngdoc b/docs/content/guide/$location.ngdoc index caf18bb42df1..66f79fab9ac8 100644 --- a/docs/content/guide/$location.ngdoc +++ b/docs/content/guide/$location.ngdoc @@ -3,7 +3,7 @@ @sortOrder 500 @description -# What does it do? +# Using the `$location` service The `$location` service parses the URL in the browser address bar (based on [`window.location`](https://developer.mozilla.org/en/window.location)) and makes the URL available to your application. Changes to the URL in the address bar are reflected into the `$location` service and @@ -76,7 +76,7 @@ the current URL in the browser. It does not cause a full page reload when the browser URL is changed. To reload the page after changing the URL, use the lower-level API, `$window.location.href`. -# General overview of the API +## General overview of the API The `$location` service can behave differently, depending on the configuration that was provided to it when it was instantiated. The default configuration is suitable for many applications, for @@ -85,7 +85,7 @@ others customizing the configuration can enable new features. Once the `$location` service is instantiated, you can interact with it via jQuery-style getter and setter methods that allow you to get or change the current URL in the browser. -## `$location` service configuration +### `$location` service configuration To configure the `$location` service, retrieve the {@link ng.$locationProvider $locationProvider} and set the parameters as follows: @@ -113,12 +113,12 @@ To configure the `$location` service, retrieve the Prefix used for Hashbang URLs (used in Hashbang mode or in legacy browsers in HTML5 mode).
Default: `'!'` -### Example configuration +#### Example configuration ```js $locationProvider.html5Mode(true).hashPrefix('*'); ``` -## Getter and setter methods +### Getter and setter methods `$location` service provides getter methods for read-only parts of the URL (absUrl, protocol, host, port) and getter / setter methods for url, path, search, hash: @@ -137,7 +137,7 @@ change multiple segments in one go, chain setters like this: $location.path('/newValue').search({key: value}); ``` -## Replace method +### Replace method There is a special `replace` method which can be used to tell the $location service that the next time the $location service is synced with the browser, the last history record should be replaced @@ -173,7 +173,7 @@ encoded. `/path?search=a&b=c#hash`. The segments are encoded as well. -# Hashbang and HTML5 Modes +## Hashbang and HTML5 Modes `$location` service has two configuration modes which control the format of the URL in the browser address bar: **Hashbang mode** (the default) and the **HTML5 mode** which is based on using the @@ -221,7 +221,7 @@ facilitate the browser URL change and history management. -## Hashbang mode (default mode) +### Hashbang mode (default mode) In this mode, `$location` uses Hashbang URLs in all browsers. AngularJS also does not intercept and rewrite links in this mode. I.e. links work @@ -229,7 +229,7 @@ as expected and also perform full page reloads when other parts of the url than the hash fragment was changed. -### Example +#### Example ```js it('should show example', function() { @@ -255,7 +255,7 @@ it('should show example', function() { }); ``` -## HTML5 mode +### HTML5 mode In HTML5 mode, the `$location` service getters and setters interact with the browser URL address through the HTML5 history API. This allows for use of regular URL path and search segments, @@ -271,7 +271,7 @@ Note that in this mode, AngularJS intercepts all links (subject to the "Html lin and updates the url in a way that never performs a full page reload. -### Example +#### Example ```js it('should show example', function() { @@ -320,14 +320,14 @@ it('should show example (when browser doesn\'t support HTML5 mode', function() { }); ``` -### Fallback for legacy browsers +#### Fallback for legacy browsers For browsers that support the HTML5 history API, `$location` uses the HTML5 history API to write path and search. If the history API is not supported by a browser, `$location` supplies a Hashbang URL. This frees you from having to worry about whether the browser viewing your app supports the history API or not; the `$location` service makes this transparent to you. -### HTML link rewriting +#### HTML link rewriting When you use HTML5 history API mode, you will not need special hashbang links. All you have to do is specify regular URL links, such as: `link` @@ -361,7 +361,7 @@ Note that [attribute name normalization](guide/directive#normalization) does not `'internalLink'` will **not** match `'internal-link'`. -### Relative links +#### Relative links Be sure to check all relative links, images, scripts etc. AngularJS requires you to specify the url base in the head of your main html file (``) unless `html5Mode.requireBase` @@ -374,14 +374,14 @@ will only change `$location.hash()` and not modify the url otherwise. This is us to anchors on the same page without needing to know on which page the user currently is. -### Server side +#### Server side Using this mode requires URL rewriting on server side, basically you have to rewrite all your links to entry point of your application (e.g. index.html). Requiring a `` tag is also important for this case, as it allows AngularJS to differentiate between the part of the url that is the application base and the path that should be handled by the application. -### Base href constraints +#### Base href constraints The `$location` service is not able to function properly if the current URL is outside the URL given as the base href. This can have subtle confusing consequences... @@ -403,7 +403,7 @@ legacy browsers and hashbang links in modern browser: - Modern browser will rewrite hashbang URLs to regular URLs. - Older browsers will redirect regular URLs to hashbang URLs. -### Example +#### Example Here you can see two `$location` instances that show the difference between **Html5 mode** and **Html5 Fallback mode**. Note that to simulate different levels of browser support, the `$location` instances are connected to @@ -415,7 +415,7 @@ redirect to regular / hashbang url, as this conversion happens only during parsi In these examples we use ``. The inputs represent the address bar of the browser. -#### Browser in HTML5 mode +##### Browser in HTML5 mode
@@ -565,7 +565,7 @@ In these examples we use ``. The inputs represen -#### Browser in HTML5 Fallback mode (Hashbang mode) +##### Browser in HTML5 Fallback mode (Hashbang mode)
@@ -718,15 +718,15 @@ In these examples we use ``. The inputs represen -# Caveats +## Caveats -## Page reload navigation +### Page reload navigation The `$location` service allows you to change only the URL; it does not allow you to reload the page. When you need to change the URL and reload the page or navigate to a different page, please use a lower level API, {@link ng.$window $window.location.href}. -## Using $location outside of the scope life-cycle +### Using $location outside of the scope life-cycle `$location` knows about AngularJS's {@link ng.$rootScope.Scope scope} life-cycle. When a URL changes in the browser it updates the `$location` and calls `$apply` so that all @@ -738,7 +738,7 @@ propagate this change into browser and will notify all the {@link ng.$rootScope. When you want to change the `$location` from outside AngularJS (for example, through a DOM Event or during testing) - you must call `$apply` to propagate the changes. -## $location.path() and ! or / prefixes +### $location.path() and ! or / prefixes A path should always begin with forward slash (`/`); the `$location.path()` setter will add the forward slash if it is missing. @@ -746,22 +746,17 @@ forward slash if it is missing. Note that the `!` prefix in the hashbang mode is not part of `$location.path()`; it is actually `hashPrefix`. -## Crawling your app +### Crawling your app -To allow indexing of your AJAX application, you have to add special meta tag in the head section of -your document: - -```html - -``` - -This will cause crawler bot to request links with `_escaped_fragment_` param so that your server -can recognize the crawler and serve a HTML snapshots. For more information about this technique, -see [Making AJAX Applications -Crawlable](http://code.google.com/web/ajaxcrawling/docs/specification.html). +Most modern search engines are able to crawl AJAX applications with dynamic content, provided all +included resources are available to the crawler bots. +There also exists a special +[AJAX crawling scheme](http://code.google.com/web/ajaxcrawling/docs/specification.html) developed by +Google that allows bots to crawl the static equivalent of a dynamically generated page, +but this schema has been deprecated, and support for it may vary by search engine. -# Testing with the $location service +## Testing with the $location service When using `$location` service during testing, you are outside of the angular's {@link ng.$rootScope.Scope scope} life-cycle. This means it's your responsibility to call `scope.$apply()`. @@ -784,85 +779,6 @@ describe('serviceUnderTest', function() { }); ``` - -# Migrating from earlier AngularJS releases - -In earlier releases of AngularJS, `$location` used `hashPath` or `hashSearch` to process path and -search methods. With this release, the `$location` service processes path and search methods and -then uses the information it obtains to compose hashbang URLs (such as -`http://server.com/#!/path?search=a`), when necessary. - -## Changes to your code - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Navigation inside the appChange to
$location.href = value
$location.hash = value
$location.update(value)
$location.updateHash(value)		$location.path(path).search(search)
$location.hashPath = path$location.path(path)
$location.hashSearch = search$location.search(search)
Navigation outside the app - Use lower level API -
$location.href = value
$location.update(value)		$window.location.href = value
$location[protocol | host | port | path | search]$window.location[protocol | host | port | path | search]
Read access - Change to -
$location.hashPath$location.path()
$location.hashSearch$location.search()
$location.href
$location.protocol
$location.host
$location.port
$location.hash		$location.absUrl()
$location.protocol()
$location.host()
$location.port()
$location.path() + $location.search()
$location.path
$location.search		$window.location.path
$window.location.search
- ## Two-way binding to $location Because `$location` uses getters/setters, you can use `ng-model-options="{ getterSetter: true }"` @@ -884,6 +800,6 @@ angular.module('locationExample', []) -# Related API +## Related API * {@link ng.$location `$location` API} diff --git a/docs/content/guide/migration.ngdoc b/docs/content/guide/migration.ngdoc index 376295665999..e05027a6e558 100644 --- a/docs/content/guide/migration.ngdoc +++ b/docs/content/guide/migration.ngdoc @@ -505,6 +505,36 @@ Note that values that have been passed through the `$interpolate` service within `URL` or `MEDIA_URL` will have already been sanitized, so you would not need to sanitize these values again. +
+ +Due to **[1e9ead](https://github.com/angular/angular.js/commit/1e9eadcd72dbbd5c67dae8328a63e535cfa91ff9)**, +binding {@link ng.$sce#trustAs trustAs()} and the short versions +({@link ng.$sce#trustAsResourceUrl trustAsResourceUrl()} et al.) to +{@link ng.ngSrc}, {@link ng.ngSrcset}, and {@link ng.ngHref} will now raise an infinite digest error: + +```js + $scope.imgThumbFn = function(id) { + return $sce.trustAsResourceUrl(someService.someUrl(id)); + }; +``` + +```html + +``` +This is because {@link ng.$interpolate} is now responsible for sanitizing +the attribute value, and its watcher receives a new object from `trustAs()` +on every digest. +To migrate, compute the trusted value only when the input value changes: + +```js + $scope.$watch('imgId', function(id) { + $scope.imgThumb = $sce.trustAsResourceUrl(someService.someUrl(id)); + }); +``` + +```html + +``` diff --git a/src/ng/compile.js b/src/ng/compile.js index a257c0b5f096..6471240e6692 100644 --- a/src/ng/compile.js +++ b/src/ng/compile.js @@ -1030,8 +1030,7 @@ * * See issue [#2573](https://github.com/angular/angular.js/issues/2573). * - * #### `transclude: element` in the replace template root can have - * unexpected effects + * #### `transclude: element` in the replace template root can have unexpected effects * * When the replace template has a directive at the root node that uses * {@link $compile#-transclude- `transclude: element`}, e.g.