add docs for the Navigation API #21960
Conversation
chrisdavidmills
requested review from
Elchi3 and
dipikabh
and removed request for
a team
|
|
||
| > **Note:** In this context "transition" refers to the transition between one history entry and another. It isn't related to CSS transitions. | ||
|
|
||
| > **Note:** You can also call {{domxref("Event.preventDefault", "preventDefault()")}} to stop the navigation entirely. |
There was a problem hiding this comment.
Note that canceling traversals is not yet implemented anywhere, although we've updated the explainer and spec since we have an implementation in progress. I'm not sure whether that's necessary to mention here, or elsewhere, or not at all.
There was a problem hiding this comment.
I've updated it to
Note: In future implementations you will be able to call {{domxref("Event.preventDefault", "preventDefault()")}} to stop the navigation entirely. This is specced out, but not currently implemented anywhere.
We can always update it when the implementation lands. Let me know.
There was a problem hiding this comment.
Ah, sorry, it's a bit more subtle than that. Canceling (most) push/reload/replace navigations is possible today. It's the traverse navigations which are still a future feature.
You can see the diff, which represents what's not possible yet but will be soon, in WICG/navigation-api@a430943
There was a problem hiding this comment.
Ah! I see. I've updated it again, to
Note: You can also call {{domxref("Event.preventDefault", "preventDefault()")}} to stop the navigation entirely in most cases. This works today for most push, reload, and replace navigations; cancellation of traverse navigations is not yet implemented.
I'll keep it simple for now here, and then link to your explainer text when it is published.
Co-authored-by: Domenic Denicola <[email protected]>
Co-authored-by: Domenic Denicola <[email protected]>
Co-authored-by: Domenic Denicola <[email protected]>
|
@domenic all interface landing pages now created; see preview URLs in #21960 (comment). |
|
@domenic thanks for all the great review comments. I've answered them all, and added all the member pages for the |
…lls/content into add-navigation-api-ref-docs
|
This pull request has merge conflicts that must be resolved before it can be merged. |
Co-authored-by: wbamberg <[email protected]>
Co-authored-by: wbamberg <[email protected]>
Co-authored-by: wbamberg <[email protected]>
Co-authored-by: wbamberg <[email protected]>
Co-authored-by: wbamberg <[email protected]>
Co-authored-by: wbamberg <[email protected]>
Co-authored-by: wbamberg <[email protected]>
Co-authored-by: wbamberg <[email protected]>
Co-authored-by: wbamberg <[email protected]>
| function initHomeBtn() { | ||
| // Get the key of the first loaded entry | ||
| // so the user can always go back to this view. | ||
| const {key} = navigation.currentEntry; | ||
| backToHomeButton.onclick = () => { | ||
| navigation.traverseTo(key); | ||
| } | ||
| } | ||
|
|
||
| navigation.addEventListener("navigate", event => { | ||
| event.intercept({ | ||
| async handler() { | ||
| // Handle single-page navigations | ||
| } | ||
| }); | ||
| }); | ||
|
|
||
| async function handleNavigate(url) { | ||
|
|
||
| // Navigate to a different view, but the button will always work. | ||
| await navigation.navigate(url).finished; | ||
|
|
||
| // ... | ||
| } |
There was a problem hiding this comment.
Yes, this is clearer (to me anyway). FWIW you don't need this bit:
async function handleNavigate(url) {
// Navigate to a different view, but the button will always work.
await navigation.navigate(url).finished;
// ...
}...because navigate will intercept normal links as well, as it does in the demo. You could put the comment // Navigate to a different view, but the button will always work. just in the intercept handler:
| function initHomeBtn() { | |
| // Get the key of the first loaded entry | |
| // so the user can always go back to this view. | |
| const {key} = navigation.currentEntry; | |
| backToHomeButton.onclick = () => { | |
| navigation.traverseTo(key); | |
| } | |
| } | |
| navigation.addEventListener("navigate", event => { | |
| event.intercept({ | |
| async handler() { | |
| // Handle single-page navigations | |
| } | |
| }); | |
| }); | |
| async function handleNavigate(url) { | |
| // Navigate to a different view, but the button will always work. | |
| await navigation.navigate(url).finished; | |
| // ... | |
| } | |
| function initHomeBtn() { | |
| // Get the key of the first loaded entry | |
| // so the user can always go back to this view. | |
| const {key} = navigation.currentEntry; | |
| backToHomeButton.onclick = () => { | |
| navigation.traverseTo(key); | |
| } | |
| } | |
| // Intercept navigate events, such as link clicks, and | |
| // replace them with single-page navigations | |
| navigation.addEventListener("navigate", event => { | |
| event.intercept({ | |
| async handler() { | |
| // Navigate to a different view, | |
| // but the "home" button will always work. | |
| } | |
| }); | |
| }); |
...just a suggestion though
There was a problem hiding this comment.
Good call; I've updated these examples to use your listing suggestion. Thanks Will!
| {{APIRef("Navigation API")}}{{seecompattable}} | ||
|
|
||
| The **`canIntercept`** read-only property of the | ||
| {{domxref("NavigateEvent")}} interface returns `true` if the navigation can be intercepted, or `false` otherwise (e.g. you can't intercept a cross-origin navigation). |
There was a problem hiding this comment.
(e.g. you can't intercept a cross-origin navigation)
I think it would be helpful to explain this a little more. Whenever I see an explanation that's only "e.g." I think, well this is an example, but what are the other cases?
The spec says:
Generally speaking, this will be true whenever the current Document can have its URL rewritten to the destination URL, except for cross-document back/forward navigations, where it will always be false.
I don't like "Generally speaking" there, but at least "can have its URL rewritten" seems to have a clear definition: https://html.spec.whatwg.org/multipage/nav-history-apis.html#can-have-its-url-rewritten. For "except for cross-document back/forward navigations, where it will always be false" I did find this on cross-document navigation: https://chromium.googlesource.com/chromium/src/+/main/docs/navigation_concepts.md#same_document-and-cross_document-navigations , which is presented as a Chromium thing but that seems comprehensible.
So could we say something like:
A navigation can be intercepted in the following circumstances:
- For
httpandhttpsURLs, only thepath,query, andfragmentportions of the new URL may differ from the current URL.- For
fileURLs, only thequeryandfragmentportions of the new URL may differ from the current URL.- For all other schemes, only the
fragmentportion of the new URL may differ from the current URL.See when a
Documentcan have its URL rewritten.An exception is for back/forward navigations in which the existing
documentis replaced with a new one (these are also called cross-document navigations). These navigations can never be intercepted.
?
There was a problem hiding this comment.
The full explanation for this case goes beyond this, and requires reading the whole table at https://github.com/wicg/navigation-api#appendix-types-of-navigations . That's why the non-normative (for web developers) part of the spec uses the vague phrase "generally speaking", because it's too complex to summarize quickly.
There was a problem hiding this comment.
FWIW As a reader the normative information is what I want first; a general summary that will apply for most circumstances - because most of the time I'm reading for the gist.
But I would absolutely also want more precision on the most common cases as @wbamberg has done for http, https and file. If it can't be cannonical as a list, I'd note that "there are a number of other cases listed in the specification, covering X, Y, Z".
There was a problem hiding this comment.
I've rewritten this to provide some examples, using some of Will's text, but I've also linked out to the spec for full information. This is one of those cases in which I don't think it's worth trying to repeat the full explanation on MDN. I think most web devs won't need it.
| {{APIRef("Navigation API")}}{{seecompattable}} | ||
|
|
||
| The **`info`** read-only property of the | ||
| {{domxref("NavigateEvent")}} interface returns the `info` data value passed by the initiating navigation operation (e.g. {{domxref("Navigation.back()")}}, or {{domxref("Navigation.navigate()")}}), or `undefined` if no `info` data was passed. |
There was a problem hiding this comment.
Spec says null? https://wicg.github.io/navigation-api/#dom-navigateevent-info .Although actually the spec says it is null if the event did not come from navigate():
An arbitrary JavaScript value passed via navigation APIs that initiated this navigation, or null if the navigation was initiated by the user or via a non-navigation API.
I couldn't see what is specced if it did come from navigate() but no info was passed.
There was a problem hiding this comment.
Sorry, that part of the spec is wrong; it's undefined. I'm working on fixing it as part of whatwg/html#8502
There was a problem hiding this comment.
Yeah, I think I read undefined in the explainer somewhere. I've updated the syntax section to match, as that said false ;-)
| - {{domxref("NavigateEvent.hashChange", "hashChange")}} {{ReadOnlyInline}} | ||
| - : Returns `true` if the navigation is a fragment navigation (i.e. to a fragment identifier in the same document), or `false` otherwise. | ||
| - {{domxref("NavigateEvent.info", "info")}} {{ReadOnlyInline}} | ||
| - : Returns the `info` data value passed by the initiating navigation operation (e.g. {{domxref("Navigation.back()")}}, or {{domxref("Navigation.navigate()")}}), or `undefined` if no `info` data was passed. |
There was a problem hiding this comment.
null?
An arbitrary JavaScript value passed via navigation APIs that initiated this navigation, or null if the navigation was initiated by the user or via a non-navigation API.
(https://wicg.github.io/navigation-api/#dom-navigateevent-info)
There was a problem hiding this comment.
See previous comment.
| {{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` form submission, or `null` otherwise. |
There was a problem hiding this comment.
| {{domxref("NavigateEvent")}} interface returns the {{domxref("FormData")}} object representing the submitted data in the case of a `POST` form submission, or `null` otherwise. | |
| {{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. |
There was a problem hiding this comment.
Thanks; I've updated this.
|
|
||
| {{APIRef("Navigation API")}}{{seecompattable}} | ||
|
|
||
| The **`NavigateEvent`** interface of the {{domxref("Navigation API", "Navigation API", "", "nocode")}} is the event object for the {{domxref("Navigation/navigate_event", "navigate")}} event, which fires when [any type of navigation](https://github.com/WICG/navigation-api#appendix-types-of-navigations) is initiated (this includes usage of {{domxref("History API", "History API", "", "nocode")}} features like {{domxref("History.go()")}}). `NavigateEvent` provides access to information about that navigation, and allows developers to intercept and control the navigation handling. |
There was a problem hiding this comment.
As before we should IMO document "any type of navigation" on MDN.
There was a problem hiding this comment.
Perhaps, but I'd like to do this as part of a future PR
|
|
||
| ### Return value | ||
|
|
||
| `undefined`. |
There was a problem hiding this comment.
| `undefined`. | |
| None (`undefined`). |
| // User submitted a POST form to a same-domain URL | ||
| // (If canIntercept is false, the event is just informative: | ||
| // you can't intercept this request, although you could | ||
| // likely still call .preventDefault() to stop it completely). |
There was a problem hiding this comment.
Not sure about "likely" here. Can I stop uninterceptable requests?
There was a problem hiding this comment.
Often, yes. See the full table at https://github.com/wicg/navigation-api#appendix-types-of-navigations to know what situations canIntercept (can call intercept()) is true, vs. cancelable (can call preventDefault()) is true.
|
|
||
| ### Handling scrolling using `scroll()` | ||
|
|
||
| ```js |
There was a problem hiding this comment.
As for https://pr21960.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/NavigateEvent#handling_scrolling_using_scroll, it would be great to have a sentence or two explaining this.
|
|
||
| ## Examples | ||
|
|
||
| The general idea here is that the `signal` property can be passed to an associated {{domxref("fetch()")}} operation so that if the navigation is cancelled, it can be safely aborted, avoiding wasting bandwidth on fetches that are no longer needed. |
There was a problem hiding this comment.
| The general idea here is that the `signal` property can be passed to an associated {{domxref("fetch()")}} operation so that if the navigation is cancelled, it can be safely aborted, avoiding wasting bandwidth on fetches that are no longer needed. | |
| The general idea here is that the `signal` property can be passed to an associated {{domxref("fetch()")}} operation so that if the navigation is cancelled, the `fetch` operation can be safely aborted, avoiding wasting bandwidth on fetches that are no longer needed. |
("it" is ambiguous here)
There was a problem hiding this comment.
Good call; updated.
| The **`userInitiated`** read-only property of the | ||
| {{domxref("NavigateEvent")}} interface returns `true` if the navigation was initiated by the user (e.g. by clicking a link, submitting a form, or pressing the browser's "Back"/"Forward" buttons), or `false` otherwise. | ||
|
|
||
| > **Note:** The table found at [Appendix: types of navigations](https://github.com/WICG/navigation-api#appendix-types-of-navigations) shows which navigation types are user-initiated. |
There was a problem hiding this comment.
Predictably :) I think it would be good to have this list on MDN.
There was a problem hiding this comment.
I've seen you leave this suggestion a few times, but I'd really suggest not duplicating the spec contents into MDN for these extreme details. It'd be good to have a single source of truth for this, so that as spec author and browser implementer, I don't have to worry about updating MDN when we change the behavior.
There was a problem hiding this comment.
While I agree that de-duplicating data is great, especially when it comes to maintenance, I think that Will's suggestion to add the data to MDN is more than reasonable. Not only will this help keep the info in one easy-to-read article, but inherently, it will also help us better track changes to the spec if/when they occur. I don't expect it to change often enough that keeping MDN and the spec repo in sync should be a significant burden (and if it is, maybe the spec is getting updated too frequently). Additionally, if the spec's described behavior changes after browsers update to match the new behavior, we need to track this in MDN (BCD specifically) so that we can relay the information to developers, otherwise developers may be surprised when their website isn't working as expected in older/newer browsers (or worse, they don't notice, assuming there's no issue at all).
There was a problem hiding this comment.
OK, well, it's up to you. I don't really understand what your criterion is for when you duplicate the spec vs. when you summarize it, but I hope you have a good system in place for monitoring spec changes.
There was a problem hiding this comment.
re monitoring spec changes (in specific lists / specific sections), this might be a useful service to suggest in reffy/webref land - I don't expect webref would extract information of that level of details, but setting up a per-section change notification system sounds like something we could probably set up if we have customers for it.
There was a problem hiding this comment.
I've raised this question with the MDN maintainers and if the consensus is not to include this I'm happy with that. But I'm not aware of any existing consensus or guideline that this level of spec detail should be off-limits to MDN.
I think @queengooborg makes a good point that if it can affect developers, and it's subject to change, isn't it a good thing for us to talk about it, so they know when it changes.
I hope you have a good system in place for monitoring spec changes
We could certainly do better here. @dontcallmedom , that sounds like a very good idea. We'd need processes on the MDN side to respond to notifications and the capacity to actually do something about it.
There was a problem hiding this comment.
for the record, I filed w3c/reffy#1114 to track that idea
There was a problem hiding this comment.
As per other comments; I'm happy to consider this addition at a later date, but I'd rather do it in a future PR, and get this one merged. I'm a bit on the fence about moving it; it is useful info, but it is complex and long-winded, and I'm not convinced that repeating it on MDN is the best use of my time, especially at this fairly nascent stage in the technology's lifespan, where it might possibly get tweaked a bit as more people start using the URL and providing more feedback.
|
|
||
| There are a few perceived limitations with the Navigation API: | ||
|
|
||
| 1. The current specification doesn't trigger {{domxref("Navigation.navigate_event", "navigate")}} on a page's first load. This might be fine for sites that use Server Side Rendering (SSR)—your server could return the correct initial state, which is the fastest way to get content to your users. But sites that leverage client-side code to create their pages may need an additional function to initialize the page. |
There was a problem hiding this comment.
| 1. The current specification doesn't trigger {{domxref("Navigation.navigate_event", "navigate")}} on a page's first load. This might be fine for sites that use Server Side Rendering (SSR)—your server could return the correct initial state, which is the fastest way to get content to your users. But sites that leverage client-side code to create their pages may need an additional function to initialize the page. | |
| 1. The current specification doesn't trigger a {{domxref("Navigation.navigate_event", "navigate")}} event on a page's first load. This might be fine for sites that use Server Side Rendering (SSR)—your server could return the correct initial state, which is the fastest way to get content to your users. But sites that leverage client-side code to create their pages may need an additional function to initialize the page. |
(because with "trigger navigate" it's not super obvious this is an event (navigate is used a lot in this API)).
There was a problem hiding this comment.
Yup, good call. Updated!
|
@chrisdavidmills , I've been through everything here at least once and commented. I've been back through things you have addressed and they look good. There are still some thing from the last few days' reviews that are outstanding - I will take another look when they're done or if you want to talk about them any more that's fine too of course. |
Thanks @wbamberg ; I really appreciate the effort you've made in giving this a thorough review. I've answered all your most recent comments, and also gone back and found a bunch of ones I missed last time round. Let me know if you feel that I've missed anything. |
|
@wbamberg woo hoo! |
* 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]>
Description
This PR adds reference documentation for the Navigation API.
Motivation
Readers will want information about this new API.
Additional details
Further details can be found in my Navigation API research document.
Related issues and pull requests
Fixes #21909