From feb78debd5cd6dd85d8a909af952a3a0e6b89939 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Wed, 22 Nov 2023 14:44:34 -0500 Subject: [PATCH] Update additional Blazor start examples (#31109) --- .../blazor/components/event-handling.md | 168 +++++++++++------- .../blazor/components/js-spa-frameworks.md | 21 ++- 2 files changed, 127 insertions(+), 62 deletions(-) diff --git a/aspnetcore/blazor/components/event-handling.md b/aspnetcore/blazor/components/event-handling.md index 4d84e513ad23..736d01fa5f0b 100644 --- a/aspnetcore/blazor/components/event-handling.md +++ b/aspnetcore/blazor/components/event-handling.md @@ -152,84 +152,104 @@ Blazor supports custom event arguments, which enable you to pass arbitrary data Custom events with custom event arguments are generally enabled with the following steps. -1. In JavaScript, define a function for building the custom event argument object from the source event: +In JavaScript, define a function for building the custom event argument object from the source event: - ```javascript - function eventArgsCreator(event) { - return { - customProperty1: 'any value for property 1', - customProperty2: event.srcElement.value - }; - } - ``` +```javascript +function eventArgsCreator(event) { + return { + customProperty1: 'any value for property 1', + customProperty2: event.srcElement.value + }; +} +``` -1. Register the custom event with the preceding handler in a [JavaScript initializer](xref:blazor/fundamentals/startup#javascript-initializers). +Register the custom event with the preceding handler in a [JavaScript initializer](xref:blazor/fundamentals/startup#javascript-initializers). - `wwwroot/{PACKAGE ID/ASSEMBLY NAME}.lib.module.js`: +`wwwroot/{PACKAGE ID/ASSEMBLY NAME}.lib.module.js`: - ```javascript - export function afterStarted(blazor) { - blazor.registerCustomEventType('customevent', { - createEventArgs: eventArgsCreator - }); - } - ``` +:::moniker-end - In the preceding example, the `{PACKAGE ID/ASSEMBLY NAME}` placeholder of the file name represents the package ID or assembly name of the app. +:::moniker range=">= aspnetcore-8.0" - > [!NOTE] - > The call to `registerCustomEventType` is performed in a script only once per event. - > - > For the call to `registerCustomEventType`, use the `blazor` parameter (lowercase `b`) provided by `afterStarted`. Although the registration is valid when using the `Blazor` object (uppercase `B`), the preferred approach is to use the parameter. +For a Blazor Web App: -1. Define a class for the event arguments: +```javascript +export function afterWebStarted(blazor) { + blazor.registerCustomEventType('customevent', { + createEventArgs: eventArgsCreator + }); +} +``` - ```csharp - namespace BlazorSample.CustomEvents; +For a Blazor Server or Blazor WebAssembly app: - public class CustomEventArgs : EventArgs - { - public string? CustomProperty1 {get; set;} - public string? CustomProperty2 {get; set;} - } - ``` +:::moniker-end -1. Wire up the custom event with the event arguments by adding an attribute annotation for the custom event: +:::moniker range=">= aspnetcore-6.0" - * In order for the compiler to find the `[EventHandler]` class, it must be placed into a C# class file (`.cs`), making it a normal top-level class. - * Mark the class `public`. - * The class doesn't require members. - * The class *must* be called "`EventHandlers`" in order to be found by the Razor compiler. - * Place the class under a namespace specific to your app. - * Import the namespace into the Razor component (`.razor`) where the event is used. +```javascript +export function afterStarted(blazor) { + blazor.registerCustomEventType('customevent', { + createEventArgs: eventArgsCreator + }); +} +``` - ```csharp - using Microsoft.AspNetCore.Components; +In the preceding example, the `{PACKAGE ID/ASSEMBLY NAME}` placeholder of the file name represents the package ID or assembly name of the app. - namespace BlazorSample.CustomEvents; +> [!NOTE] +> The call to `registerCustomEventType` is performed in a script only once per event. +> +> For the call to `registerCustomEventType`, use the `blazor` parameter (lowercase `b`) provided by the Blazor start event. Although the registration is valid when using the `Blazor` object (uppercase `B`), the preferred approach is to use the parameter. + +Define a class for the event arguments: + +```csharp +namespace BlazorSample.CustomEvents; + +public class CustomEventArgs : EventArgs +{ + public string? CustomProperty1 {get; set;} + public string? CustomProperty2 {get; set;} +} +``` - [EventHandler("oncustomevent", typeof(CustomEventArgs), enableStopPropagation: true, enablePreventDefault: true)] - public static class EventHandlers - { - } - ``` +Wire up the custom event with the event arguments by adding an attribute annotation for the custom event: -1. Register the event handler on one or more HTML elements. Access the data that was passed in from JavaScript in the delegate handler method: +* In order for the compiler to find the `[EventHandler]` class, it must be placed into a C# class file (`.cs`), making it a normal top-level class. +* Mark the class `public`. +* The class doesn't require members. +* The class *must* be called "`EventHandlers`" in order to be found by the Razor compiler. +* Place the class under a namespace specific to your app. +* Import the namespace into the Razor component (`.razor`) where the event is used. - ```razor - @using namespace BlazorSample.CustomEvents +```csharp +using Microsoft.AspNetCore.Components; - +namespace BlazorSample.CustomEvents; - @code - { - private void HandleCustomEvent(CustomEventArgs eventArgs) - { - // eventArgs.CustomProperty1 - // eventArgs.CustomProperty2 - } - } - ``` +[EventHandler("oncustomevent", typeof(CustomEventArgs), enableStopPropagation: true, enablePreventDefault: true)] +public static class EventHandlers +{ +} +``` + +Register the event handler on one or more HTML elements. Access the data that was passed in from JavaScript in the delegate handler method: + +```razor +@using namespace BlazorSample.CustomEvents + + + +@code +{ + private void HandleCustomEvent(CustomEventArgs eventArgs) + { + // eventArgs.CustomProperty1 + // eventArgs.CustomProperty2 + } +} +``` If the `@oncustomevent` attribute isn't recognized by [IntelliSense](/visualstudio/ide/using-intellisense), make sure that the component or the `_Imports.razor` file contains an `@using` statement for the namespace containing the `EventHandler` class. @@ -267,6 +287,32 @@ Add JavaScript code to supply data for the subclass with `wwwroot/{PACKAGE ID/ASSEMBLY NAME}.lib.module.js`: +:::moniker-end + +:::moniker range=">= aspnetcore-8.0" + +For a Blazor Web App: + +```javascript +export function afterWebStarted(blazor) { + blazor.registerCustomEventType('custompaste', { + browserEventName: 'paste', + createEventArgs: event => { + return { + eventTimestamp: new Date(), + pastedData: event.clipboardData.getData('text') + }; + } + }); +} +``` + +For a Blazor Server or Blazor WebAssembly app: + +:::moniker-end + +:::moniker range=">= aspnetcore-6.0" + ```javascript export function afterStarted(blazor) { blazor.registerCustomEventType('custompaste', { @@ -284,7 +330,7 @@ export function afterStarted(blazor) { In the preceding example, the `{PACKAGE ID/ASSEMBLY NAME}` placeholder of the file name represents the package ID or assembly name of the app. > [!NOTE] -> For the call to `registerCustomEventType`, use the `blazor` parameter (lowercase `b`) provided by `afterStarted`. Although the registration is valid when using the `Blazor` object (uppercase `B`), the preferred approach is to use the parameter. +> For the call to `registerCustomEventType`, use the `blazor` parameter (lowercase `b`) provided by the Blazor start event. Although the registration is valid when using the `Blazor` object (uppercase `B`), the preferred approach is to use the parameter. The preceding code tells the browser that when a native [`paste`](https://developer.mozilla.org/docs/Web/API/Element/paste_event) event occurs: diff --git a/aspnetcore/blazor/components/js-spa-frameworks.md b/aspnetcore/blazor/components/js-spa-frameworks.md index 8e6e8623367f..27b5550a0232 100644 --- a/aspnetcore/blazor/components/js-spa-frameworks.md +++ b/aspnetcore/blazor/components/js-spa-frameworks.md @@ -170,6 +170,25 @@ Using a [JavaScript initializer](xref:blazor/fundamentals/startup#javascript-ini `wwwroot/{PACKAGE ID/ASSEMBLY NAME}.lib.module.js`: +:::moniker range=">= aspnetcore-8.0" + +For a Blazor Web App: + +```javascript +export function afterWebStarted(blazor) { + let targetElement = document.getElementById('quoteContainer2'); + blazor.rootComponents.add(targetElement, 'quote', + { + text: "Crow: I have my doubts that this movie is actually 'starring' " + + "anybody. More like, 'camera is generally pointed at.'" + }); +} +``` + +For a Blazor Server or Blazor WebAssembly app: + +:::moniker-end + ```javascript export function afterStarted(blazor) { let targetElement = document.getElementById('quoteContainer2'); @@ -182,7 +201,7 @@ export function afterStarted(blazor) { ``` > [!NOTE] -> For the call to `rootComponents.add`, use the `blazor` parameter (lowercase `b`) provided by `afterStarted`. Although the registration is valid when using the `Blazor` object (uppercase `B`), the preferred approach is to use the parameter. +> For the call to `rootComponents.add`, use the `blazor` parameter (lowercase `b`) provided by the Blazor start event. Although the registration is valid when using the `Blazor` object (uppercase `B`), the preferred approach is to use the parameter. For an advanced example with additional features, see the example in the `BasicTestApp` of the ASP.NET Core reference source (`dotnet/aspnetcore` GitHub repository):