Skip to content

Commit 8148507

Browse files
chrisdavidmillsdomenicSchalk Neethlingwbamberg
authored and
hamishwillee
committed
add docs for the Navigation API (mdn#21960)
* add docs for the Navigation API * Update files/en-us/web/api/navigation_api/index.md Co-authored-by: Domenic Denicola <[email protected]> * Update files/en-us/web/api/navigation_api/index.md Co-authored-by: Domenic Denicola <[email protected]> * Update files/en-us/web/api/navigation_api/index.md Co-authored-by: Domenic Denicola <[email protected]> * updating landing page according to domenics comments * remaining interface pages plus assorted fixes * add all member pages for Navigate * making fixes for domenic review comments * fix macro error * add member pages for NavigationDestination and NavigationHistoryEntry * attempt to fix folder name casing * fix casing issue in directory name * add all remaining pages, fix flaws * adding description of when disposal occurs * Update files/en-us/web/api/navigation_api/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation_api/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation_api/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation_api/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation_api/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation_api/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation_api/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation_api/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation_api/index.md Co-authored-by: wbamberg <[email protected]> * adding fixes for wbamberg comments * adding fixes for wbamberg comments * making fixes for wbamberg comments * Update files/en-us/web/api/navigation/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/updatecurrententry/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/updatecurrententry/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/updatecurrententry/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/updatecurrententry/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/traverseto/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/back/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/cangoback/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/cangoforward/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/currententry/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/forward/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/navigate/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/navigate/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/navigate/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/reload/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/reload/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/transition/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/traverseto/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/navigation/traverseto/index.md Co-authored-by: wbamberg <[email protected]> * fixing linter trailing space errors * add structured-clonable information to navigate() * add structured-clonable information to reload() and updateCurrentEntry() * making fixes in response to wbamberg navigationhistoryentry comments * moooooar fixes for wbamberg comments Co-authored-by: Domenic Denicola <[email protected]> Co-authored-by: Schalk Neethling <[email protected]> Co-authored-by: wbamberg <[email protected]>
1 parent 55753f6 commit 8148507

File tree

56 files changed

+4151
-1
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+4151
-1
lines changed

‎files/en-us/web/api/navigateevent/canintercept/index.md

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: NavigateEvent.canIntercept
3+
slug: Web/API/NavigateEvent/canIntercept
4+
page-type: web-api-instance-property
5+
tags:
6+
- API
7+
- canIntercept
8+
- Experimental
9+
- History
10+
- Navigate
11+
- NavigateEvent
12+
- Navigation
13+
- Navigation API
14+
- Property
15+
- Read-only
16+
- Reference
17+
- Scroll
18+
- Traversal
19+
browser-compat: api.NavigateEvent.canIntercept
20+
---
21+
22+
{{APIRef("Navigation API")}}{{seecompattable}}
23+
24+
The **`canIntercept`** read-only property of the
25+
{{domxref("NavigateEvent")}} interface returns `true` if the navigation can be intercepted and have its URL rewritten, or `false` otherwise
26+
27+
There are several rules around when a navigation can be intercepted. For example:
28+
29+
- You can't intercept cross-origin navigations.
30+
- You can intercept `http` or `https` URLs if only the `path`, `query`, and `fragment` portions of the new URL differ from the current URL.
31+
- You can intercept `file` URLs if only the `query` and `fragment` portions of the new URL differ.
32+
- For other URL types you can intercept the navigation if only the `fragment` portion differs.
33+
34+
See the spec for more explanation on [when a Document can have its URL rewritten](https://html.spec.whatwg.org/multipage/nav-history-apis.html#can-have-its-url-rewritten), including a table of examples.
35+
36+
## Value
37+
38+
A boolean value—`true` if the navigation can be intercepted, `false` if not.
39+
40+
## Examples
41+
42+
```js
43+
navigation.addEventListener("navigate", event => {
44+
// Some navigations, e.g. cross-origin navigations, we
45+
// cannot intercept. Let the browser handle those normally.
46+
if (!event.canIntercept) {
47+
return;
48+
}
49+
50+
// Don't intercept fragment navigations or downloads.
51+
if (event.hashChange || event.downloadRequest !== null) {
52+
return;
53+
}
54+
55+
event.intercept({
56+
handler() {
57+
if (event.formData) {
58+
processFormDataAndUpdateUI(event.formData, event.signal);
59+
} else {
60+
doSinglePageAppNav(event.destination, event.signal);
61+
}
62+
}
63+
});
64+
});
65+
```
66+
67+
## Specifications
68+
69+
{{Specifications}}
70+
71+
## Browser compatibility
72+
73+
{{Compat}}
74+
75+
## See also
76+
77+
- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/)
78+
- [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md)
79+
- Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/)

‎files/en-us/web/api/navigateevent/destination/index.md

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: NavigateEvent.destination
3+
slug: Web/API/NavigateEvent/destination
4+
page-type: web-api-instance-property
5+
tags:
6+
- API
7+
- destination
8+
- Experimental
9+
- History
10+
- Navigate
11+
- NavigateEvent
12+
- Navigation
13+
- Navigation API
14+
- Property
15+
- Read-only
16+
- Reference
17+
- Scroll
18+
- Traversal
19+
browser-compat: api.NavigateEvent.destination
20+
---
21+
22+
{{APIRef("Navigation API")}}{{seecompattable}}
23+
24+
The **`destination`** read-only property of the
25+
{{domxref("NavigateEvent")}} interface returns a {{domxref("NavigationDestination")}} object representing the destination being navigated to.
26+
27+
## Value
28+
29+
A {{domxref("NavigationDestination")}} object.
30+
31+
## Examples
32+
33+
```js
34+
navigation.addEventListener('navigate', (event) => {
35+
// Exit early if this navigation shouldn't be intercepted,
36+
// e.g. if the navigation is cross-origin, or a download request
37+
if (shouldNotIntercept(event)) {
38+
return;
39+
}
40+
41+
const url = new URL(event.destination.url);
42+
43+
if (url.pathname.startsWith('/articles/')) {
44+
event.intercept({
45+
async handler() {
46+
// The URL has already changed, so show a placeholder while
47+
//fetching the new content, such as a spinner or loading page
48+
renderArticlePagePlaceholder();
49+
50+
// Fetch the new content and display when ready
51+
const articleContent = await getArticleContent(url.pathname);
52+
renderArticlePage(articleContent);
53+
},
54+
});
55+
}
56+
});
57+
```
58+
59+
## Specifications
60+
61+
{{Specifications}}
62+
63+
## Browser compatibility
64+
65+
{{Compat}}
66+
67+
## See also
68+
69+
- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/)
70+
- [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md)
71+
- Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/)

‎files/en-us/web/api/navigateevent/downloadrequest/index.md

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: NavigateEvent.downloadRequest
3+
slug: Web/API/NavigateEvent/downloadRequest
4+
page-type: web-api-instance-property
5+
tags:
6+
- API
7+
- downloadRequest
8+
- Experimental
9+
- History
10+
- Navigate
11+
- NavigateEvent
12+
- Navigation
13+
- Navigation API
14+
- Property
15+
- Read-only
16+
- Reference
17+
- Scroll
18+
- Traversal
19+
browser-compat: api.NavigateEvent.downloadRequest
20+
---
21+
22+
{{APIRef("Navigation API")}}{{seecompattable}}
23+
24+
The **`downloadRequest`** read-only property of the
25+
{{domxref("NavigateEvent")}} interface returns the filename of the file requested for download, in the case of a download navigation (e.g. an {{htmlelement("a")}} or {{htmlelement("area")}} element with a `download` attribute), or `null` otherwise.
26+
27+
## Value
28+
29+
A string containing the filename of the file requested for download, or `null`.
30+
31+
## Examples
32+
33+
```js
34+
navigation.addEventListener("navigate", (event) => {
35+
// Some navigations, e.g. cross-origin navigations, we
36+
// cannot intercept. Let the browser handle those normally.
37+
if (!event.canIntercept) {
38+
return;
39+
}
40+
41+
// Don't intercept fragment navigations or downloads.
42+
if (event.hashChange || event.downloadRequest !== null) {
43+
return;
44+
}
45+
46+
event.intercept({
47+
handler() {
48+
if (event.formData) {
49+
processFormDataAndUpdateUI(event.formData, event.signal);
50+
} else {
51+
doSinglePageAppNav(event.destination, event.signal);
52+
}
53+
}
54+
});
55+
});
56+
```
57+
58+
## Specifications
59+
60+
{{Specifications}}
61+
62+
## Browser compatibility
63+
64+
{{Compat}}
65+
66+
## See also
67+
68+
- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/)
69+
- [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md)
70+
- Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/)

‎files/en-us/web/api/navigateevent/formdata/index.md

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: NavigateEvent.formData
3+
slug: Web/API/NavigateEvent/formData
4+
page-type: web-api-instance-property
5+
tags:
6+
- API
7+
- Experimental
8+
- formData
9+
- History
10+
- Navigate
11+
- NavigateEvent
12+
- Navigation
13+
- Navigation API
14+
- Property
15+
- Read-only
16+
- Reference
17+
- Scroll
18+
- Traversal
19+
browser-compat: api.NavigateEvent.formData
20+
---
21+
22+
{{APIRef("Navigation API")}}{{seecompattable}}
23+
24+
The **`formData`** read-only property of the
25+
{{domxref("NavigateEvent")}} interface returns the {{domxref("FormData")}} object representing the submitted data in the case of a [`POST`](/en-US/docs/Web/HTTP/Methods/POST) form submission, or `null` otherwise.
26+
27+
## Value
28+
29+
A {{domxref("FormData")}} object, or `null`.
30+
31+
## Examples
32+
33+
```js
34+
navigation.addEventListener("navigate", (event) => {
35+
// Some navigations, e.g. cross-origin navigations, we
36+
// cannot intercept. Let the browser handle those normally.
37+
if (!event.canIntercept) {
38+
return;
39+
}
40+
41+
// Don't intercept fragment navigations or downloads.
42+
if (event.hashChange || event.downloadRequest !== null) {
43+
return;
44+
}
45+
46+
event.intercept({
47+
handler() {
48+
if (event.formData) {
49+
processFormDataAndUpdateUI(event.formData, event.signal);
50+
} else {
51+
doSinglePageAppNav(event.destination, event.signal);
52+
}
53+
}
54+
});
55+
});
56+
```
57+
58+
## Specifications
59+
60+
{{Specifications}}
61+
62+
## Browser compatibility
63+
64+
{{Compat}}
65+
66+
## See also
67+
68+
- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/)
69+
- [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md)
70+
- Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/)

‎files/en-us/web/api/navigateevent/hashchange/index.md

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: NavigateEvent.hashChange
3+
slug: Web/API/NavigateEvent/hashChange
4+
page-type: web-api-instance-property
5+
tags:
6+
- API
7+
- Experimental
8+
- hashChange
9+
- History
10+
- Navigate
11+
- NavigateEvent
12+
- Navigation
13+
- Navigation API
14+
- Property
15+
- Read-only
16+
- Reference
17+
- Scroll
18+
- Traversal
19+
browser-compat: api.NavigateEvent.hashChange
20+
---
21+
22+
{{APIRef("Navigation API")}}{{seecompattable}}
23+
24+
The **`hashChange`** read-only property of the
25+
{{domxref("NavigateEvent")}} interface returns `true` if the navigation is a fragment navigation (i.e. to a fragment identifier in the same document), or `false` otherwise.
26+
27+
## Value
28+
29+
A boolean value—`true` if the navigation is a fragment navigation, `false` if not.
30+
31+
## Examples
32+
33+
```js
34+
navigation.addEventListener("navigate", (event) => {
35+
// Some navigations, e.g. cross-origin navigations, we
36+
// cannot intercept. Let the browser handle those normally.
37+
if (!event.canIntercept) {
38+
return;
39+
}
40+
41+
// Don't intercept fragment navigations or downloads.
42+
if (event.hashChange || event.downloadRequest !== null) {
43+
return;
44+
}
45+
46+
event.intercept({
47+
handler() {
48+
if (event.formData) {
49+
processFormDataAndUpdateUI(event.formData, event.signal);
50+
} else {
51+
doSinglePageAppNav(event.destination, event.signal);
52+
}
53+
}
54+
});
55+
});
56+
```
57+
58+
## Specifications
59+
60+
{{Specifications}}
61+
62+
## Browser compatibility
63+
64+
{{Compat}}
65+
66+
## See also
67+
68+
- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/)
69+
- [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md)
70+
- Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/)

0 commit comments

Comments
 (0)