Enhanced navigation & form handling 8.0

[guardrex]

Fixes #30322
Addresses #28161

• I'm using an informal name, Normal navigation, in contrast to Enhanced navigation. Does that choice make sense?
• I'm concerned about scoping what enhanced nav applies to. We're saying "if available," but can we specify exactly when it's available?
• I'm going to add the What's New cross-link to this immediately before merging or on a separate PR. I can't hold up that article with other doc 🐈🐈🐈 also trying to get updates applied to it.

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/blazor/forms-and-input-components.md	ASP.NET Core Blazor forms and input components
aspnetcore/blazor/fundamentals/routing.md	ASP.NET Core Blazor routing and navigation
aspnetcore/blazor/fundamentals/startup.md	ASP.NET Core Blazor startup
aspnetcore/release-notes/aspnetcore-8.0.md	aspnetcore/release-notes/aspnetcore-8.0

[MackinnonBuck]

I'm using an informal name, Normal navigation, in contrast to Enhanced navigation. Does that choice make sense?

That seems reasonable. Another term explained here is "cross-document navigation" (and enhanced navigation would be an example of "same-document-navigation"). Maybe we could refer to that document to clarify that "normal" navigation means "cross-document navigation" and "enhanced" navigation is a form of "same-document navigation"?

I'm concerned about scoping what enhanced nav applies to. We're saying "if available," but can we specify exactly when it's available?

Enhanced navigation is available when:

• blazor.web.js is used (not blazor.server.js or blazor.webassembly.js)
• It's not explicitly disabled via Blazor.start({ ssr: { disableDomPreservation: true } })
• The destination URL is within the internal base URI space

But it should be noted that even if enhanced navigation is available, navigations will still go through an interactive (client-side) router if one exists.

[guardrex]

Thx @MackinnonBuck ... I'll make another pass using that information and ping u back ... probably tomorrow.

[guardrex]

• I'm drafting this now with "cross-document/cross-origin" and "same-document/same-origin" adjectives. Let's see if that works. If so, we probably don't need to cross-link.
• I'll also add the phrasing on "URI space" that we normally use (app base path) ... IF that's a valid equivalent expression. 👂
• I add to the Startup doc on disabling enhanced nav.

❓ on ...

But it should be noted that even if enhanced navigation is available, navigations will still go through an interactive (client-side) router if one exists.

I added that to the text, but why is that important to tell readers? It seems like it needs an additional remark as to why the reader would care.

[guardrex]

🛑

NOTE TO SELF: Add link to What's New (release notes) before merging!

[MackinnonBuck]

I added that to the text, but why is that important to tell readers? It seems like it needs an additional remark as to why the reader would care.

It's probably not going to be relevant to most customers. It really only applies if you were to have, for example, an interactive <Router> nested inside a server-side rendered <Router>. In such a case, the interactive router would take priority when handling navigations, so enhanced navigation wouldn't be used for navigation (since that's a server-side routing feature).

It's possible this is a detail we can leave out, since that's a very uncommon pattern - I'll leave that up to you!

[guardrex]

We can keep it ... let me try with a remark that it's an uncommon concern but for full disclosure. I'll try that now ... brb ..........

[guardrex]

Ok ...

• I updated the format of the bullet list items to ...

  * Normal navigation (cross-document navigation): a full-page ...
  * Enhanced navigation (same-document navigation)†: Blazor intercepts ...

• I tried to roll in the full disclosure remark. If we don't do something like this, it's hard to understand why the remark (first sentence now) is there.

  If enhanced navigation is available for interactive client routing, navigation always goes through the interactive client-side router. This point is only relevant in an uncommon scenario where an interactive <Router> is nested inside a server-side rendered <Router>. In that case, the interactive router takes priority when handling navigation, so enhanced navigation isn't used for navigation because it's a server-side routing feature.

  I had to play with it on a few commits, but that seems like a good draft. How does it look?

[guardrex]

@MackinnonBuck ... I'll assume this is ok now and go ahead. I'm about to wrap up for the week, and I'd like to get this in before I update DR and Artak on where everything stands. Msg me if this needs a patch.

[guardrex]

@MackinnonBuck ... One more side-question ...

WRT RC2 and forms to enable enhanced nav, the behavior will be opt-in ...

Enhanced form handling can be optionally enabled for specific forms.

I'm looking at Steve's issue ...

dotnet/aspnetcore#50551

... and will be documenting for RC2 that ...

You turn it on by adding data-enhance to the <form> element or Enhance if it's an EditForm. This is nonhierarchical since it's not desirable to enable this globally.

... so it will need to be done for every form that the dev wants enhanced nav for.

For "nonhierarchical," confirm if that it just means it must be enabled on a per-form basis. Any embedded forms in a form also needs the attribute/param.

[MackinnonBuck]

I had to play with it on a few commits, but that seems like a good draft. How does it look?

Looks great 🙂

For "nonhierarchical," confirm if that it just means it must be enabled on a per-form basis. Any embedded forms in a form also needs the attribute/param.

Yep, that's correct. You can't, for example, put data-enhance on an ancestor element to a <form> and expect enhanced navigation to be enabled for the form.