Skip to content

Update upstream #158

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 5, 2018
Merged

Update upstream #158

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7920f71
docs(*): fix headlines
Narretz Jul 1, 2018
3ad07ea
docs(guide/Using Location): change / remove obsolete information
Narretz Jul 1, 2018
74726b4
docs(changelog, guide/Migration): add info about $sce BC in 1.7
Narretz Jul 4, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 31 additions & 2 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
<img ng-src="{{imgThumbFn(imgId)}}">
```
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
<img ng-src="{{imgThumb}}">
```

### **orderBy** due to:
- **[1d8046](https://github.com/angular/angular.js/commit/1d804645f7656d592c90216a0355b4948807f6b8)**: consider `null` and `undefined` greater than other values

Expand Down
148 changes: 32 additions & 116 deletions docs/content/guide/$location.ngdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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).<br />
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:
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -221,15 +221,15 @@ facilitate the browser URL change and history management.
</tbody>
</table>

## 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
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() {
Expand All @@ -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,
Expand All @@ -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() {
Expand Down Expand Up @@ -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: `<a href="/some?foo=bar">link</a>`
Expand Down Expand Up @@ -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 (`<base href="/my-base/index.html">`) unless `html5Mode.requireBase`
Expand All @@ -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 `<base>` 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...
Expand All @@ -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
Expand All @@ -415,7 +415,7 @@ redirect to regular / hashbang url, as this conversion happens only during parsi

In these examples we use `<base href="/base/index.html" />`. The inputs represent the address bar of the browser.

#### Browser in HTML5 mode
##### Browser in HTML5 mode
<example module="html5-mode" name="location-html5-mode">
<file name="index.html">
<div ng-controller="LocationController">
Expand Down Expand Up @@ -565,7 +565,7 @@ In these examples we use `<base href="/base/index.html" />`. The inputs represen

</example>

#### Browser in HTML5 Fallback mode (Hashbang mode)
##### Browser in HTML5 Fallback mode (Hashbang mode)
<example module="hashbang-mode" name="location-hashbang-mode">
<file name="index.html">
<div ng-controller="LocationController">
Expand Down Expand Up @@ -718,15 +718,15 @@ In these examples we use `<base href="/base/index.html" />`. The inputs represen

</example>

# 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
Expand All @@ -738,30 +738,25 @@ 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.

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
<meta name="fragment" content="!" />
```

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()`.
Expand All @@ -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

<table class="table">
<thead>
<tr class="head">
<th>Navigation inside the app</th>
<th>Change to</th>
</tr>
</thead>

<tbody>
<tr>
<td>$location.href = value<br />$location.hash = value<br />$location.update(value)<br
/>$location.updateHash(value)</td>
<td>$location.path(path).search(search)</td>
</tr>

<tr>
<td>$location.hashPath = path</td>
<td>$location.path(path)</td>
</tr>

<tr>
<td>$location.hashSearch = search</td>
<td>$location.search(search)</td>
</tr>

<tr class="head">
<th>Navigation outside the app</td>
<th>Use lower level API</td>
</tr>

<tr>
<td>$location.href = value<br />$location.update(value)</td>
<td>$window.location.href = value</td>
</tr>

<tr>
<td>$location[protocol | host | port | path | search]</td>
<td>$window.location[protocol | host | port | path | search]</td>
</tr>

<tr class="head">
<th>Read access</td>
<th>Change to</td>
</tr>

<tr>
<td>$location.hashPath</td>
<td>$location.path()</td>
</tr>

<tr>
<td>$location.hashSearch</td>
<td>$location.search()</td>
</tr>

<tr>
<td>$location.href<br />$location.protocol<br />$location.host<br />$location.port<br
/>$location.hash</td>
<td>$location.absUrl()<br />$location.protocol()<br />$location.host()<br />$location.port()<br
/>$location.path() + $location.search()</td>
</tr>

<tr>
<td>$location.path<br />$location.search</td>
<td>$window.location.path<br />$window.location.search</td>
</tr>
</tbody>
</table>

## Two-way binding to $location

Because `$location` uses getters/setters, you can use `ng-model-options="{ getterSetter: true }"`
Expand All @@ -884,6 +800,6 @@ angular.module('locationExample', [])
</file>
</example>

# Related API
## Related API

* {@link ng.$location `$location` API}
Loading