add docs for the Navigation API (#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]>
mdn · Nov 20, 2022 · f12a6b6 · f12a6b6
1 parent 0bc4a84
commit f12a6b6
Show file tree

Hide file tree

Showing 56 changed files with 4,151 additions and 1 deletion.
diff --git a/files/en-us/web/api/navigateevent/canintercept/index.md b/files/en-us/web/api/navigateevent/canintercept/index.md
@@ -0,0 +1,79 @@
+---
+title: NavigateEvent.canIntercept
+slug: Web/API/NavigateEvent/canIntercept
+page-type: web-api-instance-property
+tags:
+  - API
+  - canIntercept
+  - Experimental
+  - History
+  - Navigate
+  - NavigateEvent
+  - Navigation
+  - Navigation API
+  - Property
+  - Read-only
+  - Reference
+  - Scroll
+  - Traversal
+browser-compat: api.NavigateEvent.canIntercept
+---
+
+{{APIRef("Navigation API")}}{{seecompattable}}
+
+The **`canIntercept`** read-only property of the
+{{domxref("NavigateEvent")}} interface returns `true` if the navigation can be intercepted and have its URL rewritten, or `false` otherwise
+
+There are several rules around when a navigation can be intercepted. For example:
+
+- You can't intercept cross-origin navigations.
+- You can intercept `http` or `https` URLs if only the `path`, `query`, and `fragment` portions of the new URL differ from the current URL.
+- You can intercept `file` URLs if only the `query` and `fragment` portions of the new URL differ.
+- For other URL types you can intercept the navigation if only the `fragment` portion differs.
+
+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.
+
+## Value
+
+A boolean value—`true` if the navigation can be intercepted, `false` if not.
+
+## Examples
+
+```js
+navigation.addEventListener("navigate", event => {
+  // Some navigations, e.g. cross-origin navigations, we
+  // cannot intercept. Let the browser handle those normally.
+  if (!event.canIntercept) {
+    return;
+  }
+
+  // Don't intercept fragment navigations or downloads.
+  if (event.hashChange || event.downloadRequest !== null) {
+    return;
+  }
+
+  event.intercept({
+    handler() {
+      if (event.formData) {
+        processFormDataAndUpdateUI(event.formData, event.signal);
+      } else {
+        doSinglePageAppNav(event.destination, event.signal);
+      }
+    }
+  });
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/)
+- [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md)
+- Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/)
diff --git a/files/en-us/web/api/navigateevent/destination/index.md b/files/en-us/web/api/navigateevent/destination/index.md
@@ -0,0 +1,71 @@
+---
+title: NavigateEvent.destination
+slug: Web/API/NavigateEvent/destination
+page-type: web-api-instance-property
+tags:
+  - API
+  - destination
+  - Experimental
+  - History
+  - Navigate
+  - NavigateEvent
+  - Navigation
+  - Navigation API
+  - Property
+  - Read-only
+  - Reference
+  - Scroll
+  - Traversal
+browser-compat: api.NavigateEvent.destination
+---
+
+{{APIRef("Navigation API")}}{{seecompattable}}
+
+The **`destination`** read-only property of the
+{{domxref("NavigateEvent")}} interface returns a {{domxref("NavigationDestination")}} object representing the destination being navigated to.
+
+## Value
+
+A {{domxref("NavigationDestination")}} object.
+
+## Examples
+
+```js
+navigation.addEventListener('navigate', (event) => {
+  // Exit early if this navigation shouldn't be intercepted, 
+  // e.g. if the navigation is cross-origin, or a download request
+  if (shouldNotIntercept(event)) {
+    return;
+  }
+
+  const url = new URL(event.destination.url);
+
+  if (url.pathname.startsWith('/articles/')) {
+    event.intercept({
+      async handler() {
+        // The URL has already changed, so show a placeholder while
+        //fetching the new content, such as a spinner or loading page
+        renderArticlePagePlaceholder();
+
+        // Fetch the new content and display when ready
+        const articleContent = await getArticleContent(url.pathname);
+        renderArticlePage(articleContent);
+      },
+    });
+  }
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/)
+- [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md)
+- Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/)
diff --git a/files/en-us/web/api/navigateevent/downloadrequest/index.md b/files/en-us/web/api/navigateevent/downloadrequest/index.md
@@ -0,0 +1,70 @@
+---
+title: NavigateEvent.downloadRequest
+slug: Web/API/NavigateEvent/downloadRequest
+page-type: web-api-instance-property
+tags:
+  - API
+  - downloadRequest
+  - Experimental
+  - History
+  - Navigate
+  - NavigateEvent
+  - Navigation
+  - Navigation API
+  - Property
+  - Read-only
+  - Reference
+  - Scroll
+  - Traversal
+browser-compat: api.NavigateEvent.downloadRequest
+---
+
+{{APIRef("Navigation API")}}{{seecompattable}}
+
+The **`downloadRequest`** read-only property of the
+{{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.
+
+## Value
+
+A string containing the filename of the file requested for download, or `null`.
+
+## Examples
+
+```js
+navigation.addEventListener("navigate", (event) => {
+  // Some navigations, e.g. cross-origin navigations, we
+  // cannot intercept. Let the browser handle those normally.
+  if (!event.canIntercept) {
+    return;
+  }
+
+  // Don't intercept fragment navigations or downloads.
+  if (event.hashChange || event.downloadRequest !== null) {
+    return;
+  }
+
+  event.intercept({
+    handler() {
+      if (event.formData) {
+        processFormDataAndUpdateUI(event.formData, event.signal);
+      } else {
+        doSinglePageAppNav(event.destination, event.signal);
+      }
+    }
+  });
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/)
+- [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md)
+- Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/)
diff --git a/files/en-us/web/api/navigateevent/formdata/index.md b/files/en-us/web/api/navigateevent/formdata/index.md
@@ -0,0 +1,70 @@
+---
+title: NavigateEvent.formData
+slug: Web/API/NavigateEvent/formData
+page-type: web-api-instance-property
+tags:
+  - API
+  - Experimental
+  - formData
+  - History
+  - Navigate
+  - NavigateEvent
+  - Navigation
+  - Navigation API
+  - Property
+  - Read-only
+  - Reference
+  - Scroll
+  - Traversal
+browser-compat: api.NavigateEvent.formData
+---
+
+{{APIRef("Navigation API")}}{{seecompattable}}
+
+The **`formData`** read-only property of the
+{{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.
+
+## Value
+
+A {{domxref("FormData")}} object, or `null`.
+
+## Examples
+
+```js
+navigation.addEventListener("navigate", (event) => {
+  // Some navigations, e.g. cross-origin navigations, we
+  // cannot intercept. Let the browser handle those normally.
+  if (!event.canIntercept) {
+    return;
+  }
+
+  // Don't intercept fragment navigations or downloads.
+  if (event.hashChange || event.downloadRequest !== null) {
+    return;
+  }
+
+  event.intercept({
+    handler() {
+      if (event.formData) {
+        processFormDataAndUpdateUI(event.formData, event.signal);
+      } else {
+        doSinglePageAppNav(event.destination, event.signal);
+      }
+    }
+  });
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/)
+- [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md)
+- Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/)
diff --git a/files/en-us/web/api/navigateevent/hashchange/index.md b/files/en-us/web/api/navigateevent/hashchange/index.md
@@ -0,0 +1,70 @@
+---
+title: NavigateEvent.hashChange
+slug: Web/API/NavigateEvent/hashChange
+page-type: web-api-instance-property
+tags:
+  - API
+  - Experimental
+  - hashChange
+  - History
+  - Navigate
+  - NavigateEvent
+  - Navigation
+  - Navigation API
+  - Property
+  - Read-only
+  - Reference
+  - Scroll
+  - Traversal
+browser-compat: api.NavigateEvent.hashChange
+---
+
+{{APIRef("Navigation API")}}{{seecompattable}}
+
+The **`hashChange`** read-only property of the
+{{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.
+
+## Value
+
+A boolean value—`true` if the navigation is a fragment navigation, `false` if not.
+
+## Examples
+
+```js
+navigation.addEventListener("navigate", (event) => {
+  // Some navigations, e.g. cross-origin navigations, we
+  // cannot intercept. Let the browser handle those normally.
+  if (!event.canIntercept) {
+    return;
+  }
+
+  // Don't intercept fragment navigations or downloads.
+  if (event.hashChange || event.downloadRequest !== null) {
+    return;
+  }
+
+  event.intercept({
+    handler() {
+      if (event.formData) {
+        processFormDataAndUpdateUI(event.formData, event.signal);
+      } else {
+        doSinglePageAppNav(event.destination, event.signal);
+      }
+    }
+  });
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/)
+- [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md)
+- Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/)