From ce22e37d3e473fbef0e27535d0e3f7e88cf4216c Mon Sep 17 00:00:00 2001 From: Malcolm Smith <20709258+msmithNI@users.noreply.github.com> Date: Wed, 30 Oct 2024 13:41:00 -0500 Subject: [PATCH] Update docs --- .../blazor-workspace/NimbleBlazor/CONTRIBUTING.md | 4 +++- packages/blazor-workspace/NimbleBlazor/README.md | 14 ++++++++++---- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md b/packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md index e09a8898f3..6ef1d75144 100644 --- a/packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md +++ b/packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md @@ -16,6 +16,8 @@ For Nimble Blazor development on Windows, the suggested tools to install are: In Visual Studio, run the `Demo.Server`, `Demo.Client`, or `Demo.Hybrid` projects to see the Blazor demo apps. +Note: If you get an error stating "Failed to launch debug adapter" / "Unable to launch browser" when debugging `Demo.Client`, ensure that Microsoft Edge is the browser being used (dropdown menu from the Run button). + ### Mac / Visual Studio Code Install [Visual Studio Code](https://code.visualstudio.com/), and install the suggested extensions that appear once you open the NimbleBlazor project folders. @@ -92,7 +94,7 @@ The `NimbleBlazor.Tests.Acceptance` project starts a local Blazor Web App which To add a new acceptance test (with the Interactive Server render mode): - Add a new Razor file that uses that component in the `Pages.InteractiveServer` subfolder, with the name `[ComponentName][FunctionalityUnderTest].razor`, e.g. `DialogOpenAndClose.razor`. - Add any necessary code to initialize the component in a `@code` section in the same file. If you'll interact with the component as the test runs, you may need to add other Nimble components like buttons to trigger new actions on your component under test. - - Ensure that your Razor file has `@rendermode RenderMode.InteractiveServer` in the top section. + - Ensure that your Razor file has `@rendermode @(new InteractiveServerRenderMode(prerender: false))` in the top section. - Specify the page's URL route via a `@page` directive - for example, `@page "/InteractiveServer/DialogOpenAndClose"`. - In the `Tests.InteractiveServer` subfolder, add a new class `[ComponentName]Tests.cs` if it doesn't already exist. Add a new test method in that class. Load your Razor file with the `NewPageForRouteAsync(routeName)` method. Using the Playwright APIs, interact with the components on the page, and make assertions about the state of the component under test. diff --git a/packages/blazor-workspace/NimbleBlazor/README.md b/packages/blazor-workspace/NimbleBlazor/README.md index a631c5e663..0edfa236a5 100644 --- a/packages/blazor-workspace/NimbleBlazor/README.md +++ b/packages/blazor-workspace/NimbleBlazor/README.md @@ -101,7 +101,13 @@ Nimble supports all of the [Blazor render modes](https://learn.microsoft.com/en- - Interactive WebAssembly: Client-side rendering (CSR) using Blazor WebAssembly: `RenderMode.InteractiveWebAssembly` - Interactive Auto: Interactive SSR initially, then CSR on subsequent visits after the Blazor bundle is downloaded: `RenderMode.InteractiveAuto` - Static server-side rendering (static SSR): Default, when no render mode is specified - - ⚠️Warning: This render mode is not recommended for most use cases with Nimble. As the page is just rendered once server-side and then no state is maintained, you're unable to use event handlers or call methods on components. This also means that for components like the Nimble Table / Wafer Map, setting data can't be done easily (because the methods to do so will have no effect if called). + - ⚠️Warning: This render mode is not recommended for most use cases with Nimble. As the page is just rendered once server-side and then no state is maintained, you're unable to use event handlers or call methods on components. This also means that for components like the Nimble Table / Wafer Map, setting data can't be done vi the component methods (because they'll have no effect if called). + +#### Prerendering + +Blazor with .NET 8 uses prerendering by default for interactive render modes. With it enabled, components are initially rendered server-side without event handlers connected, which could cause unexpected behavior (no effect when users interact with controls immediately after page load). + +See the [Blazor prerendering docs](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0#prerendering) for information on how to opt out of prerendering. ### Theming and Design Tokens @@ -141,11 +147,11 @@ To provide localized strings in a localized Blazor app: ### Using Nimble Blazor in a Blazor Hybrid app -**Requirement:** Microsoft.AspNetCore.Components.WebView v8.0.4+ +**Requirement:** `Microsoft.AspNetCore.Components.WebView` v8.0.4+ This updated WebView package include a fix so that the JavaScript initialization code that Nimble/Spright Blazor uses gets loaded correctly. -Note that if using the Microsoft.AspNetCore.Components.WebView.Wpf package, it only specifies a dependency of Microsoft.AspNetCore.Components.WebView v8.0+, so you may to add need an explicit dependency on Microsoft.AspNetCore.Components.WebView to ensure a recent enough version is included. -The Demo.Hybrid project in the Blazor solution illustrates this setup. +Note that if using the `Microsoft.AspNetCore.Components.WebView.Wpf` package, it only specifies a dependency of `Microsoft.AspNetCore.Components.WebView` v8.0+, so you may to add need an explicit dependency on `Microsoft.AspNetCore.Components.WebView` to ensure a recent enough version is included. +The `Demo.Hybrid` project in the Blazor solution illustrates this setup. ## Contributing