Add documentation for Blazor custom event args feature

[mkArtakMSFT]

This is a request to add documentation for Blazor Custom Event arguments feature which is (going to be) introduced as part of 6.0-preview2 release.
The feature enables the following two scenarios:

1. Capture additional event data from the DOM in .NET
2. Register custom event handlers in DOM and handle those in .NET

Draft writeup for the first scenario can be found from the 6.0-preview2 announcement blog post.
For the second scenario, please use the draft from below:

///////////////////////////////////////////////////////////////
Blazor's support for custom events is now expanded to also support custom event arguments.
This allows passing arbitrary data to .NET event handlers with custom events.

Follow the steps below to define a custom event with custom event argument(s):

** on the JavaScript side

• define a function for building the custom event argument object from the source event

function eventArgsCreator(event) { 
 return {
   customProperty1: 'any value for property 1',
   customProperty2: event.srcElement.value
 };
}

• register the custom event with the above created handler

Blazor.registerCustomEventType('customevent', {
    createEventArgs: eventArgsCreator;

Note, that the above call is done in a javascript and can be called only once (per each event).

** on the .NET side
3. define a class for the event args

public class CustomEventArgs : EventArgs{
    public string CustomProperty1 {get; set;}
    public string CustomProperty2 {get; set;}
}

4. wire up the custom event with the event args by adding an EventHandler attribute annotation for your custom event:

[EventHandler("oncustomevent", typeof(CustomEventArgs), enableStopPropagation: true, enablePreventDefault: true)]
static class EventHandlers
{
}

5. Register your event handler on the HTML element you expect to handle the event for:

<button @oncustomevent="HandleCustomEvent">Handle</button>

@code
{
    void HandleCustomEvent(CustomEventArgs eventArgs)
    {
        // here you can access the data which was passed in from the Javascript side
    }
}

Now, whenever the custom event is fired on the DOM, your event handler will be called with the data passed from the Javascript.
Note, that if you're trying to fire a custom event, you'll need to make sure that it has to have bubbles: true, as otherwise it won't get to the Blazor handler to process it.

[guardrex]

@mkArtakMSFT ...

• Coverage

  Draft writeup for the first scenario can be found from the 6.0-preview2 announcement blog post.

  The content that you provided seems to be for the same feature that DR provided in the blog post (bullet 2): https://devblogs.microsoft.com/aspnet/asp-net-core-updates-in-net-6-preview-2/#support-for-custom-event-arguments-in-blazor ... so I need info on bullet 1 ('Capture additional event data from the DOM in .NET').

  I have the UE pass for the Event Handling topic going on right now, so I'll roll this coverage in today.

• Draft with both examples: Your example covers the general setup, and DR provided a specific example in the blog post. On the draft for this, I'll use yours ☝️ for the 'how to' explanation but also add his at the end as a real world example. Let's see if it composes well on the PR. I'll ping u ✉️ on the PR.

[guardrex]

@mkArtakMSFT Update:

• The draft is on Blazor Event Handling UE Pass (dotnet/AspNetCore.Docs #21755), BUT I don't recommend looking at that today. It's rough and needs more work. I'll try to wrap up the whole PR on Saturday morning and ping u on Monday to look 👀.
• Yes! on using both your content ☝️ and DR's 'real world' custom paste event. That seems to have composed well together.

Actually, I think I misunderstood your remark on ...

Capture additional event data from the DOM in .NET

It looks like you were saying that DR's example ('real world' for a custom paste) is the 'attached to DOM-type event'.

I think we're good here. I'll ping u on Monday when that PR is ready for review.

[msbasanth]

@mkArtakMSFT @MichaelPeter

I followed the writeup for checking custom event args feature in Blazor - "Register custom event handlers in DOM and handle those in .NET".

Environment:

.NET 6.0 RC
Microsoft Visual Studio Community 2022 Preview (64-bit)
Version 17.0.0 Preview 4.1

We have few LitELement custom elements with custom events triggered. I tried to follow the documentation for as mentioned here.

What I did?

1. index.html

    <script>
        Blazor.registerCustomEventType('closed', {
            createEventArgs: { customProperty1: 'any value for property 1' }
        });
    </script>

2. define a class for the event args

@code {
    public class CustomEventArgs : EventArgs {
        public string CustomProperty1 {get; set;}
    }

3. wire up the custom event with the event args by adding an EventHandler attribute annotation for your custom event:

[EventHandler("onclosed", typeof(CustomEventArgs), enableStopPropagation: true, enablePreventDefault: true)]
static class EventHandlers
{
}

4. Register your event handler on my custom element:

<custom-control @onclosed="HandleCustomEvent">Handle</custom-control>
@code
{
    void HandleCustomEvent(CustomEventArgs eventArgs)
    {
        // here you can access the data which was passed in from the Javascript side
    }
}

Now, whenever the custom event ("closed") is fired by custom-control, my event handler is not getting called. Anything I am missing, do you have a working sample?

[guardrex]

@msbasanth ... We don't work off of closed issues/PRs, and for product unit visibility to report a potential problem with a preview feature, open an issue on their repo at ...

https://github.com/dotnet/aspnetcore/issues

If you find that the preview docs are missing something or have incorrect guidance after working with them, open a new issue from the bottom of the topic using the This page feedback button and form ...