content icon indicating copy to clipboard operation
content copied to clipboard
Published 3 weeks ago • verified publisher icon mdn

add docs for the Navigation API

Open chrisdavidmills opened this issue 3 years ago • 7 comments

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

chrisdavidmills avatar Oct 31 '22 11:10 chrisdavidmills

Preview URLs (55 pages)
Flaws (29)

Note! 54 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/Window Title: Window Flaw count: 29

  • macros:
    • /en-US/docs/Web/API/Window/messageManager does not exist
    • /en-US/docs/Web/API/Window/performance redirects to /en-US/docs/Web/API/performance_property
    • /en-US/docs/Web/API/Window/returnValue does not exist
    • /en-US/docs/Web/API/Window/setResizable does not exist
    • /en-US/docs/Web/API/Window/home does not exist
    • and 20 more flaws omitted
  • broken_links:
    • Can't resolve /en-US/docs/The_message_manager
  • bad_bcd_links:
    • no explanation!
    • no explanation!
    • no explanation!
External URLs (170)

URL: /en-US/docs/Web/API/NavigationDestination Title: NavigationDestination

URL: /en-US/docs/Web/API/NavigationDestination/getState Title: NavigationDestination.getState()

URL: /en-US/docs/Web/API/NavigationDestination/index Title: NavigationDestination.index

URL: /en-US/docs/Web/API/NavigationDestination/key Title: NavigationDestination.key

URL: /en-US/docs/Web/API/NavigationDestination/sameDocument Title: NavigationDestination.sameDocument

URL: /en-US/docs/Web/API/NavigationDestination/url Title: NavigationDestination.url

URL: /en-US/docs/Web/API/NavigationDestination/id Title: NavigationDestination.id

URL: /en-US/docs/Web/API/NavigationTransition Title: NavigationTransition

URL: /en-US/docs/Web/API/NavigationTransition/finished Title: NavigationTransition.finished

URL: /en-US/docs/Web/API/NavigationTransition/navigationType Title: NavigationTransition.navigationType

URL: /en-US/docs/Web/API/NavigationTransition/from Title: NavigationTransition.from

URL: /en-US/docs/Web/API/NavigateEvent Title: NavigateEvent

URL: /en-US/docs/Web/API/NavigateEvent/hashChange Title: NavigateEvent.hashChange

URL: /en-US/docs/Web/API/NavigateEvent/canIntercept Title: NavigateEvent.canIntercept

URL: /en-US/docs/Web/API/NavigateEvent/downloadRequest Title: NavigateEvent.downloadRequest

URL: /en-US/docs/Web/API/NavigateEvent/NavigateEvent Title: NavigateEvent()

URL: /en-US/docs/Web/API/NavigateEvent/navigationType Title: NavigateEvent.navigationType

URL: /en-US/docs/Web/API/NavigateEvent/intercept Title: NavigateEvent.intercept()

URL: /en-US/docs/Web/API/NavigateEvent/destination Title: NavigateEvent.destination

URL: /en-US/docs/Web/API/NavigateEvent/info Title: NavigateEvent.info

URL: /en-US/docs/Web/API/NavigateEvent/scroll Title: NavigateEvent.scroll()

URL: /en-US/docs/Web/API/NavigateEvent/userInitiated Title: NavigateEvent.userInitiated

URL: /en-US/docs/Web/API/NavigateEvent/signal Title: NavigateEvent.signal

URL: /en-US/docs/Web/API/NavigateEvent/formData Title: NavigateEvent.formData

URL: /en-US/docs/Web/API/Window/navigation Title: Window.navigation

URL: /en-US/docs/Web/API/NavigationCurrentEntryChangeEvent Title: NavigationCurrentEntryChangeEvent

URL: /en-US/docs/Web/API/NavigationCurrentEntryChangeEvent/navigationType Title: NavigationCurrentEntryChangeEvent.navigationType

URL: /en-US/docs/Web/API/NavigationCurrentEntryChangeEvent/NavigationCurrentEntryChangeEvent Title: NavigationCurrentEntryChangeEvent()

URL: /en-US/docs/Web/API/NavigationCurrentEntryChangeEvent/from Title: NavigationCurrentEntryChangeEvent.from

URL: /en-US/docs/Web/API/NavigationHistoryEntry Title: NavigationHistoryEntry

URL: /en-US/docs/Web/API/NavigationHistoryEntry/getState Title: NavigationHistoryEntry.getState()

URL: /en-US/docs/Web/API/NavigationHistoryEntry/index Title: NavigationHistoryEntry.index

URL: /en-US/docs/Web/API/NavigationHistoryEntry/key Title: NavigationHistoryEntry.key

URL: /en-US/docs/Web/API/NavigationHistoryEntry/sameDocument Title: NavigationHistoryEntry.sameDocument

URL: /en-US/docs/Web/API/NavigationHistoryEntry/url Title: NavigationHistoryEntry.url

URL: /en-US/docs/Web/API/NavigationHistoryEntry/id Title: NavigationHistoryEntry.id

URL: /en-US/docs/Web/API/NavigationHistoryEntry/dispose_event Title: NavigationHistoryEntry: dispose event

URL: /en-US/docs/Web/API/Navigation Title: Navigation

URL: /en-US/docs/Web/API/Navigation/back Title: Navigation.back()

URL: /en-US/docs/Web/API/Navigation/updateCurrentEntry Title: Navigation.updateCurrentEntry()

URL: /en-US/docs/Web/API/Navigation/currententrychange_event Title: Navigation: currententrychange event

URL: /en-US/docs/Web/API/Navigation/canGoForward Title: Navigation.canGoForward

URL: /en-US/docs/Web/API/Navigation/transition Title: Navigation.transition

URL: /en-US/docs/Web/API/Navigation/entries Title: Navigation.entries()

URL: /en-US/docs/Web/API/Navigation/reload Title: Navigation.reload()

URL: /en-US/docs/Web/API/Navigation/currentEntry Title: Navigation.currentEntry

URL: /en-US/docs/Web/API/Navigation/traverseTo Title: Navigation.traverseTo()

URL: /en-US/docs/Web/API/Navigation/canGoBack Title: Navigation.canGoBack

URL: /en-US/docs/Web/API/Navigation/navigatesuccess_event Title: Navigation: navigatesuccess event

URL: /en-US/docs/Web/API/Navigation/navigate_event Title: Navigation: navigate event

URL: /en-US/docs/Web/API/Navigation/navigateerror_event Title: Navigation: navigateerror event

URL: /en-US/docs/Web/API/Navigation/forward Title: Navigation.forward()

URL: /en-US/docs/Web/API/Navigation/navigate Title: Navigation.navigate()

URL: /en-US/docs/Web/API/Navigation_API Title: Navigation API

(this comment was updated 2022-11-20 09:26:40.197769)

github-actions[bot] avatar Oct 31 '22 11:10 github-actions[bot]

@domenic all interface landing pages now created; see preview URLs in https://github.com/mdn/content/pull/21960#issuecomment-1296964628.

chrisdavidmills avatar Nov 02 '22 11:11 chrisdavidmills

@domenic thanks for all the great review comments. I've answered them all, and added all the member pages for the Navigation interface.

chrisdavidmills avatar Nov 04 '22 08:11 chrisdavidmills

This pull request has merge conflicts that must be resolved before it can be merged.

github-actions[bot] avatar Nov 07 '22 10:11 github-actions[bot]

Hi @domenic ! I've now created all of the pages for the Navigation API. The preview URLs are her: https://github.com/mdn/content/pull/21960/#issuecomment-1296964628

There are a lot of pages here; I don't think you need to go through everything with a fine toothcomb. I've used the same narrative and examples as I have on pages you've already seen. And If something is wrong in one place, it'll be the same in other places.

I think my main concerns are:

  • I wonder if some of the examples are a bit weak, but then again it'll be nice to get this published, and we can improve examples over time.
  • I wanted to include a solid definition of the different navigation types, e.g. see https://pr21960.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/NavigateEvent/navigationType#value. Does my description sound OK?

chrisdavidmills avatar Nov 07 '22 11:11 chrisdavidmills

This generally looks great! Your description of navigation types sounds perfect.

Only a couple minor things I noticed clicking around:

  • https://pr21960.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/NavigateEvent/canIntercept says "missing spec data"

  • https://pr21960.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Navigation/forward and pages like it (e.g. https://pr21960.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Navigation/navigatesuccess_event) have very confusing "Syntax" sections, because they are missing navigation.. I.e. I would expect navigation.forward(options), not forward(options).

  • https://pr21960.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/NavigationHistoryEntry/dispose_event would benefit from describing the scenarios where disposal happens in more detail. They are:

    • Forward history entries are cleared, e.g. as in the example at https://github.com/wicg/navigation-api#notifications-on-entry-disposal
    • The user clears their history using browser settings or UI
    • You go over the 50-page history limit (not specified anywhere, but widely implemented; see e.g. https://www.google.com/search?q=history+length+limit+50)

domenic avatar Nov 08 '22 06:11 domenic

Thanks @domenic! Some answers to your points:

https://pr21960.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/NavigateEvent/canIntercept says "missing spec data"

Ah yeah, this is because the BCD additions I made for the Navigation API haven't been merged yet. The data was mostly there already, but I needed to added this one.

https://pr21960.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Navigation/forward and pages like it (e.g. https://pr21960.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Navigation/navigatesuccess_event) have very confusing "Syntax" sections, because they are missing navigation.. I.e. I would expect navigation.forward(options), not forward(options).

This is an interesting point. I've done it just like Syntax is shown in all the other MDN pages. I can see why you'd say this, but I guess the trouble is that we are just talking about the syntax of the particular method, and not its parent object...if you did this you'd be getting into the realm of a code example rather than pure syntax. And the code example, later on, shows the actual usage. I have passed this feedback on to see what the MDN powers that be think.

https://pr21960.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/NavigationHistoryEntry/dispose_event would benefit from describing the scenarios where disposal happens in more detail.

Good call; adding this in the next commit.

chrisdavidmills avatar Nov 08 '22 07:11 chrisdavidmills

@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.

wbamberg avatar Nov 17 '22 19:11 wbamberg

@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.

chrisdavidmills avatar Nov 20 '22 09:11 chrisdavidmills

@wbamberg woo hoo!

chrisdavidmills avatar Nov 20 '22 18:11 chrisdavidmills