From a5dc2db11c5e3a8c2a12582d681f073161c0a525 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Wed, 13 Sep 2023 10:55:00 -0400 Subject: [PATCH 1/8] Enhanced navigation & form handling 8.0 --- .../blazor/forms-and-input-components.md | 2 +- aspnetcore/blazor/fundamentals/routing.md | 49 ++++++++++++++++++- 2 files changed, 49 insertions(+), 2 deletions(-) diff --git a/aspnetcore/blazor/forms-and-input-components.md b/aspnetcore/blazor/forms-and-input-components.md index 5988da909481..4124f8cde26c 100644 --- a/aspnetcore/blazor/forms-and-input-components.md +++ b/aspnetcore/blazor/forms-and-input-components.md @@ -175,7 +175,7 @@ In the preceding `Starship1` component: * The component is an input component for editing string values. The `@bind-Value` directive attribute binds the `Model.Id` model property to the component's property. * The `Submit` method is registered as a handler for the callback. The handler is called when the form is submitted by the user. -Blazor enhances page navigation and form handling by intercepting the request in order to apply the response to the existing DOM, preserving as much of the rendered form as possible. The enhancement avoids the need to fully load the page and provides a much smoother user experience, similar to a single-page app (SPA), although the component is rendered on the server. +Blazor enhances page navigation and form handling by intercepting the request in order to apply the response to the existing DOM, preserving as much of the rendered form as possible. The enhancement avoids the need to fully load the page and provides a much smoother user experience, similar to a single-page app (SPA), although the component is rendered on the server. For more information, see . [Streaming rendering](xref:blazor/components/rendering#streaming-rendering) is supported with forms. For an example, see the [`StreamingRenderingForm` test asset (`dotnet/aspnetcore` GitHub repository)](https://github.com/dotnet/aspnetcore/blob/main/src/Components/test/testassets/Components.TestServer/RazorComponents/Pages/Forms/StreamingRenderingForm.razor). diff --git a/aspnetcore/blazor/fundamentals/routing.md b/aspnetcore/blazor/fundamentals/routing.md index 51caaee4cc99..290773273d8b 100644 --- a/aspnetcore/blazor/fundamentals/routing.md +++ b/aspnetcore/blazor/fundamentals/routing.md @@ -458,7 +458,22 @@ Slashes and segments of the captured path are decoded. For a route template of ` Use to manage URIs and navigation in C# code. provides the event and methods shown in the following table. -:::moniker range=">= aspnetcore-7.0" +:::moniker range=">= aspnetcore-8.0" + +| Member | Description | +| ------ | ----------- | +| | Gets the current absolute URI. | +| | Gets the base URI (with a trailing slash) that can be prepended to relative URI paths to produce an absolute URI. Typically, corresponds to the `href` attribute on the document's `` element ([location of `` content](xref:blazor/project-structure#location-of-head-and-body-content)). | +| | Navigates to the specified URI. If `forceLoad` is `false`:
  • And enhanced navigation is available at the current URL, Blazor's enhanced navigation is activated.
  • Otherwise, Blazor performs a full-page reload for the requested URL.
If `forceLoad` is `true`:
  • Client-side routing is bypassed.
  • The browser is forced to load the new page from the server, whether or not the URI is normally handled by the client-side router.
If `replace` is `true`, the current URI in the browser history is replaced instead of pushing a new URI onto the history stack. | +| | An event that fires when the navigation location has changed. For more information, see the [Location changes](#location-changes) section. | +| | Converts a relative URI into an absolute URI. | +| | Based on the app's base URI, converts an absolute URI into a URI relative to the base URI prefix. For an example, see the [Produce a URI relative to the base URI prefix](#produce-a-uri-relative-to-the-base-uri-prefix) section. | +| [`RegisterLocationChangingHandler`](#handleprevent-location-changes) | Registers a handler to process incoming navigation events. Calling always invokes the handler. | +| | Returns a URI constructed by updating with a single parameter added, updated, or removed. For more information, see the [Query strings](#query-strings) section. | + +:::moniker-end + +:::moniker range=">= aspnetcore-7.0 < aspnetcore-8.0" | Member | Description | | ------ | ----------- | @@ -500,6 +515,38 @@ Use to manage URIs and :::moniker-end +:::moniker range=">= aspnetcore-8.0" + +## Enhanced navigation and form handling + +*This section applies to static and interactive server rendering in Blazor Web Apps.* + +Blazor Web Apps are capable of two types of routing for page navigation and form handling requests: + +* Normal navigation: A full-page reload is triggered for the request URL. +* Enhanced navigation: Blazor intercepts the request and performs a `fetch` request instead. Blazor then patches the response content into the page's DOM. Blazor's enhanced navigation and form handling avoid the need for a full-page reload and preserves more of the page state, so pages load faster and more smoothly. + +When calling : + +* If `forceLoad` is `false`: + * And enhanced navigation is available at the current URL, Blazor's enhanced navigation is activated. + * Otherwise, Blazor performs a full-page reload for the requested URL. +* If `forceLoad` is `true`: Blazor performs a full-page reload for the requested URL, whether enhanced navigation is available or not. + +You can refresh the current page by calling `NavigationManager.Refresh(bool forceLoad = false)`, which always performs an enhanced navigation, if available. If enhanced navigation isn't available, Blazor performs a full-page reload. + +```csharp +Navigation.Refresh(); +``` + +Pass `true` to the `forceLoad` parameter to ensure a full-page reload is always performed, even when enhanced navigation is available: + +```csharp +Navigation.Refresh(true); +``` + +:::moniker-end + ## Produce a URI relative to the base URI prefix Based on the app's base URI, converts an absolute URI into a URI relative to the base URI prefix. From 5c0dd0ceac05d52fe7c04784c24d499114026e15 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Thu, 14 Sep 2023 06:25:41 -0400 Subject: [PATCH 2/8] Updates --- aspnetcore/blazor/fundamentals/routing.md | 22 ++++++++++++++++------ aspnetcore/blazor/fundamentals/startup.md | 23 ++++++++++++++++++++++- 2 files changed, 38 insertions(+), 7 deletions(-) diff --git a/aspnetcore/blazor/fundamentals/routing.md b/aspnetcore/blazor/fundamentals/routing.md index 290773273d8b..492e1d2fd95e 100644 --- a/aspnetcore/blazor/fundamentals/routing.md +++ b/aspnetcore/blazor/fundamentals/routing.md @@ -464,7 +464,7 @@ Use to manage URIs and | ------ | ----------- | | | Gets the current absolute URI. | | | Gets the base URI (with a trailing slash) that can be prepended to relative URI paths to produce an absolute URI. Typically, corresponds to the `href` attribute on the document's `` element ([location of `` content](xref:blazor/project-structure#location-of-head-and-body-content)). | -| | Navigates to the specified URI. If `forceLoad` is `false`:
  • And enhanced navigation is available at the current URL, Blazor's enhanced navigation is activated.
  • Otherwise, Blazor performs a full-page reload for the requested URL.
If `forceLoad` is `true`:
  • Client-side routing is bypassed.
  • The browser is forced to load the new page from the server, whether or not the URI is normally handled by the client-side router.
If `replace` is `true`, the current URI in the browser history is replaced instead of pushing a new URI onto the history stack. | +| | Navigates to the specified URI. If `forceLoad` is `false`:
  • And enhanced navigation is available at the current URL, Blazor's enhanced navigation is activated.
  • Otherwise, Blazor performs a full-page reload for the requested URL.
If `forceLoad` is `true`:
  • Client-side routing is bypassed.
  • The browser is forced to load the new page from the server, whether or not the URI is normally handled by the client-side interactive router.

For more information, see the [Enhanced navigation and form handling](#enhanced-navigation-and-form-handling) section.

If `replace` is `true`, the current URI in the browser history is replaced instead of pushing a new URI onto the history stack.

| | | An event that fires when the navigation location has changed. For more information, see the [Location changes](#location-changes) section. | | | Converts a relative URI into an absolute URI. | | | Based on the app's base URI, converts an absolute URI into a URI relative to the base URI prefix. For an example, see the [Produce a URI relative to the base URI prefix](#produce-a-uri-relative-to-the-base-uri-prefix) section. | @@ -519,16 +519,24 @@ Use to manage URIs and ## Enhanced navigation and form handling -*This section applies to static and interactive server rendering in Blazor Web Apps.* +*This section applies to Blazor Web Apps.* Blazor Web Apps are capable of two types of routing for page navigation and form handling requests: -* Normal navigation: A full-page reload is triggered for the request URL. -* Enhanced navigation: Blazor intercepts the request and performs a `fetch` request instead. Blazor then patches the response content into the page's DOM. Blazor's enhanced navigation and form handling avoid the need for a full-page reload and preserves more of the page state, so pages load faster and more smoothly. +* Normal navigation: For all cross-document/cross-origin navigation, a full-page reload is triggered for the request URL. +* Enhanced navigation: For some same-document/same-origin navigation†, Blazor intercepts the request and performs a `fetch` request instead. Blazor then patches the response content into the page's DOM. Blazor's enhanced navigation and form handling avoid the need for a full-page reload and preserves more of the page state, so pages load faster, usually without losing the user's scroll position on the page. + +†Enhanced navigation is available when: + +* The Blazor Web App script (`blazor.web.js`) is used, not the Blazor Server script (`blazor.server.js`) or Blazor WebAssembly script (`blazor.webassembly.js`). +* The feature isn't [explicitly disabled](xref:blazor/fundamentals/startup#enhanced-navigation-and-form-handling). +* The destination URL is within the internal base URI space (the app's base path). + +If enhanced navigation is available for interactive client routing, navigation always goes through the interactive client-side router. When calling : -* If `forceLoad` is `false`: +* If `forceLoad` is `false`, which is the default: * And enhanced navigation is available at the current URL, Blazor's enhanced navigation is activated. * Otherwise, Blazor performs a full-page reload for the requested URL. * If `forceLoad` is `true`: Blazor performs a full-page reload for the requested URL, whether enhanced navigation is available or not. @@ -539,12 +547,14 @@ You can refresh the current page by calling `NavigationManager.Refresh(bool forc Navigation.Refresh(); ``` -Pass `true` to the `forceLoad` parameter to ensure a full-page reload is always performed, even when enhanced navigation is available: +Pass `true` to the `forceLoad` parameter to ensure a full-page reload is always performed, even if enhanced navigation is available: ```csharp Navigation.Refresh(true); ``` +To disable enhanced navigation and form handling, see . + :::moniker-end ## Produce a URI relative to the base URI prefix diff --git a/aspnetcore/blazor/fundamentals/startup.md b/aspnetcore/blazor/fundamentals/startup.md index fac7e0859e7e..d5a6c0ef62ab 100644 --- a/aspnetcore/blazor/fundamentals/startup.md +++ b/aspnetcore/blazor/fundamentals/startup.md @@ -462,7 +462,7 @@ In `wwwroot/index.html`, remove the default SVG round indicator in `
= aspnetcore-8.0" + +## Disable enhanced navigation and form handling + +*This section applies to Blazor Web Apps.* + +To disable enhanced navigation and form handling, set `disableDomPreservation` to `true` for `Blazor.start`: + +```html + + +``` + +In the preceding example, the `{BLAZOR SCRIPT}` placeholder is the Blazor script path and file name. + +:::moniker-end + ## Additional resources * [Environments: Set the app's environment](xref:blazor/fundamentals/environments) From d0a5b4a9ea6420ceb1e45c8c8fe18221f465ceed Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Thu, 14 Sep 2023 12:26:55 -0400 Subject: [PATCH 3/8] Update aspnetcore/blazor/fundamentals/routing.md Co-authored-by: Mackinnon Buck --- aspnetcore/blazor/fundamentals/routing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/blazor/fundamentals/routing.md b/aspnetcore/blazor/fundamentals/routing.md index 492e1d2fd95e..f42fa67ed203 100644 --- a/aspnetcore/blazor/fundamentals/routing.md +++ b/aspnetcore/blazor/fundamentals/routing.md @@ -523,8 +523,8 @@ Use to manage URIs and Blazor Web Apps are capable of two types of routing for page navigation and form handling requests: -* Normal navigation: For all cross-document/cross-origin navigation, a full-page reload is triggered for the request URL. -* Enhanced navigation: For some same-document/same-origin navigation†, Blazor intercepts the request and performs a `fetch` request instead. Blazor then patches the response content into the page's DOM. Blazor's enhanced navigation and form handling avoid the need for a full-page reload and preserves more of the page state, so pages load faster, usually without losing the user's scroll position on the page. +* Normal navigation: Cross-document navigation; a full-page reload is triggered for the request URL. +* Enhanced navigation: Same-document navigation;†, Blazor intercepts the request and performs a `fetch` request instead. Blazor then patches the response content into the page's DOM. Blazor's enhanced navigation and form handling avoid the need for a full-page reload and preserves more of the page state, so pages load faster, usually without losing the user's scroll position on the page. †Enhanced navigation is available when: From 1155759df4649facf6e40a113c2a589b4a69c57a Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Thu, 14 Sep 2023 12:34:50 -0400 Subject: [PATCH 4/8] Updates --- aspnetcore/blazor/fundamentals/routing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/aspnetcore/blazor/fundamentals/routing.md b/aspnetcore/blazor/fundamentals/routing.md index f42fa67ed203..033839d2bbd6 100644 --- a/aspnetcore/blazor/fundamentals/routing.md +++ b/aspnetcore/blazor/fundamentals/routing.md @@ -523,8 +523,8 @@ Use to manage URIs and Blazor Web Apps are capable of two types of routing for page navigation and form handling requests: -* Normal navigation: Cross-document navigation; a full-page reload is triggered for the request URL. -* Enhanced navigation: Same-document navigation;†, Blazor intercepts the request and performs a `fetch` request instead. Blazor then patches the response content into the page's DOM. Blazor's enhanced navigation and form handling avoid the need for a full-page reload and preserves more of the page state, so pages load faster, usually without losing the user's scroll position on the page. +* Normal navigation (cross-document navigation): a full-page reload is triggered for the request URL. +* Enhanced navigation (ame-document navigation)†: Blazor intercepts the request and performs a `fetch` request instead. Blazor then patches the response content into the page's DOM. Blazor's enhanced navigation and form handling avoid the need for a full-page reload and preserves more of the page state, so pages load faster, usually without losing the user's scroll position on the page. †Enhanced navigation is available when: @@ -532,7 +532,7 @@ Blazor Web Apps are capable of two types of routing for page navigation and form * The feature isn't [explicitly disabled](xref:blazor/fundamentals/startup#enhanced-navigation-and-form-handling). * The destination URL is within the internal base URI space (the app's base path). -If enhanced navigation is available for interactive client routing, navigation always goes through the interactive client-side router. +If enhanced navigation is available for interactive client routing, navigation always goes through the interactive client-side router. This logic is only relevant in an uncommon scearnio where an interactive `` is nested inside a server-side rendered ``. In such a case, the interactive router takes priority when handling navigations, so enhanced navigation isn't used for navigation, since that's a server-side routing feature. When calling : From 9ed78a8aafe355eb60f272b52e771b3dae24a45d Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Thu, 14 Sep 2023 12:35:24 -0400 Subject: [PATCH 5/8] Updates --- aspnetcore/blazor/fundamentals/routing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/blazor/fundamentals/routing.md b/aspnetcore/blazor/fundamentals/routing.md index 033839d2bbd6..60a66923f284 100644 --- a/aspnetcore/blazor/fundamentals/routing.md +++ b/aspnetcore/blazor/fundamentals/routing.md @@ -524,7 +524,7 @@ Use to manage URIs and Blazor Web Apps are capable of two types of routing for page navigation and form handling requests: * Normal navigation (cross-document navigation): a full-page reload is triggered for the request URL. -* Enhanced navigation (ame-document navigation)†: Blazor intercepts the request and performs a `fetch` request instead. Blazor then patches the response content into the page's DOM. Blazor's enhanced navigation and form handling avoid the need for a full-page reload and preserves more of the page state, so pages load faster, usually without losing the user's scroll position on the page. +* Enhanced navigation (same-document navigation)†: Blazor intercepts the request and performs a `fetch` request instead. Blazor then patches the response content into the page's DOM. Blazor's enhanced navigation and form handling avoid the need for a full-page reload and preserves more of the page state, so pages load faster, usually without losing the user's scroll position on the page. †Enhanced navigation is available when: From b828fdada8c18e5a5a505de24114ad26a8a34c83 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Thu, 14 Sep 2023 12:38:30 -0400 Subject: [PATCH 6/8] Updates --- aspnetcore/blazor/fundamentals/routing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/blazor/fundamentals/routing.md b/aspnetcore/blazor/fundamentals/routing.md index 60a66923f284..351e36bd62cb 100644 --- a/aspnetcore/blazor/fundamentals/routing.md +++ b/aspnetcore/blazor/fundamentals/routing.md @@ -532,7 +532,7 @@ Blazor Web Apps are capable of two types of routing for page navigation and form * The feature isn't [explicitly disabled](xref:blazor/fundamentals/startup#enhanced-navigation-and-form-handling). * The destination URL is within the internal base URI space (the app's base path). -If enhanced navigation is available for interactive client routing, navigation always goes through the interactive client-side router. This logic is only relevant in an uncommon scearnio where an interactive `` is nested inside a server-side rendered ``. In such a case, the interactive router takes priority when handling navigations, so enhanced navigation isn't used for navigation, since that's a server-side routing feature. +If enhanced navigation is available for interactive client routing, navigation always goes through the interactive client-side router. This logic is only relevant in an uncommon scenario where an interactive `` is nested inside a server-side rendered ``. In such a case, the interactive router takes priority when handling navigation, so enhanced navigation isn't used for navigation, since that's a server-side routing feature. When calling : From 82a902b852de0cd91d5cfc6821f69bc52b7b9ab3 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Thu, 14 Sep 2023 12:40:03 -0400 Subject: [PATCH 7/8] Updates --- aspnetcore/blazor/fundamentals/routing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/blazor/fundamentals/routing.md b/aspnetcore/blazor/fundamentals/routing.md index 351e36bd62cb..15968b72f79d 100644 --- a/aspnetcore/blazor/fundamentals/routing.md +++ b/aspnetcore/blazor/fundamentals/routing.md @@ -532,7 +532,7 @@ Blazor Web Apps are capable of two types of routing for page navigation and form * The feature isn't [explicitly disabled](xref:blazor/fundamentals/startup#enhanced-navigation-and-form-handling). * The destination URL is within the internal base URI space (the app's base path). -If enhanced navigation is available for interactive client routing, navigation always goes through the interactive client-side router. This logic is only relevant in an uncommon scenario where an interactive `` is nested inside a server-side rendered ``. In such a case, the interactive router takes priority when handling navigation, so enhanced navigation isn't used for navigation, since that's a server-side routing feature. +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 `` is nested inside a server-side rendered ``. 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. When calling : From 54f1a957e20b8ef019aaaef93f1cd674c2324722 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Fri, 15 Sep 2023 10:00:03 -0400 Subject: [PATCH 8/8] Updates --- aspnetcore/release-notes/aspnetcore-8.0.md | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-8.0.md b/aspnetcore/release-notes/aspnetcore-8.0.md index 1cf1c23d218d..32385eb520a1 100644 --- a/aspnetcore/release-notes/aspnetcore-8.0.md +++ b/aspnetcore/release-notes/aspnetcore-8.0.md @@ -70,20 +70,9 @@ For more information, see . - ---> +For more information, see . ### Streaming rendering