KristofferStrube.Blazor.DOM 0.2.2

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
dotnet add package KristofferStrube.Blazor.DOM --version 0.2.2
NuGet\Install-Package KristofferStrube.Blazor.DOM -Version 0.2.2
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="KristofferStrube.Blazor.DOM" Version="0.2.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add KristofferStrube.Blazor.DOM --version 0.2.2
#r "nuget: KristofferStrube.Blazor.DOM, 0.2.2"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install KristofferStrube.Blazor.DOM as a Cake Addin
#addin nuget:?package=KristofferStrube.Blazor.DOM&version=0.2.2

// Install KristofferStrube.Blazor.DOM as a Cake Tool
#tool nuget:?package=KristofferStrube.Blazor.DOM&version=0.2.2

License: MIT GitHub issues GitHub forks GitHub stars NuGet Downloads (official NuGet)

Introduction

A Blazor wrapper for the DOM browser API.

The API standardizes a lot of the most basic structures for working within the browser. This includes models for Events, Aborting mechanisms, and Nodes in the DOM. This project implements a wrapper around the API for Blazor so that we can easily and safely interact with it from Blazor.

The project will not focus on the part of the API related to Nodes as this often leads to misuse of Blazor by circumventing the Blazor rendering engine.

Demo

The sample project can be demoed at https://kristofferstrube.github.io/Blazor.DOM/

On each page, you can find the corresponding code for the example in the top right corner.

On the Status page you can see how much of the WebIDL specs this wrapper has covered.

Events

The package brings a wrapper for EventTargets. This enables us to listen for specific Events happening on objects and to dispatch these events ourselves.

ElementReference element; // Some element that we have a reference to.

EventTarget eventTarget = await EventTarget.CreateAsync(JSRuntime, element);

EventListener<Event> callback = await EventListener<Event>.CreateAsync(JSRuntime, async (e) =>
{
    if (await e.GetTypeAsync() is "pointerdown")
    {
        await e.PreventDefaultAsync();
        Console.WriteLine("A pointer was pressed down and we prevented the default behaviour.");
    }
    else
    {
        Console.WriteLine("Some other pointer event happened.");
    }
});

await eventTarget.AddEventListenerAsync("pointerdown", callback);
await eventTarget.AddEventListenerAsync("pointermove", callback);
await eventTarget.AddEventListenerAsync("pointerup", callback);
await eventTarget.AddEventListenerAsync("pointerleave", callback);

The above example serves as an imperative alternative to the the native way to listen to events. But it also opens up for controlling some of the options available on events like preventing the default behavior programmatically. In the above example we use this on a ElementReference, but we can also create an EventTarget from an IJSObjectReference instead which means we can listen for events happening on any JS object that emits events.

Aborting

In JS the counterpart to a CancellationTokenSource is called an AbortController. Like we can get a CancellationToken from an CancellationTokenSource in .NET we can get an AbortSignal from an AbortController in JS. Multiple standard APIs and libraries allow us to parse an AbortSignal to functions to be able to stop some long-running action.

Let's imagine that there is some JS function which is cancellable called myLongRunningFunction(signal) which accepts an AbortSignal. Then we can cancel it if we need to like this.

AbortController abortController = await AbortController.CreateAsync(JSRuntime);
AbortSignal abortSignal = await abortController.GetSignalAsync();

await JSRuntime.InvokeVoidAsync("myLongRunningFunction", abortSignal);

// At a later point we can cancel this long running function from another method.
await abortController.AbortAsync();

Issues

Feel free to open issues on the repository if you find any errors with the package or have wishes for features.

This project uses the IJSCreatable interface from the Blazor.WebIDL package to define that Events should be able to construct themselves given a JS reference.

Many classes from the Blazor.CSSFontLoading, Blazor.MediaCaptureStreams, and Blazor.WebAudio projects extend the EventTarget class from this library to be able to dispatch and listen to events.

These repositories are going to use the library in the future to support a variety of features.

This project is going to be used in the Blazor.UIEvent project but we have not started progress on wrapping the UI Event API yet.

This repository was built with inspiration and help from the following series of articles:

Product Compatible and additional computed target framework versions.
.NET net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (5)

Showing the top 5 NuGet packages that depend on KristofferStrube.Blazor.DOM:

Package Downloads
KristofferStrube.Blazor.Streams The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Streams wrapper implementation for Blazor.

KristofferStrube.Blazor.MediaCaptureStreams The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Media Capture and Streams API wrapper implementation for Blazor.

KristofferStrube.Blazor.SVGAnimation The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

SVG Animation API wrapper implementation for Blazor.

KristofferStrube.Blazor.WebAudio The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Web Audio API wrapper implementation for Blazor.

KristofferStrube.Blazor.Window The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Window wrapper implementation for Blazor.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.2.2 114 4/28/2024
0.2.1 211 4/9/2024
0.2.0 232 3/10/2024
0.1.1 2,296 6/21/2023
0.1.0 72 6/21/2023
0.1.0-alpha.8 73 6/20/2023
0.1.0-alpha.7 74 6/20/2023
0.1.0-alpha.6 64 6/20/2023
0.1.0-alpha.5 152 4/10/2023
0.1.0-alpha.4 93 4/10/2023
0.1.0-alpha.3 76 4/10/2023
0.1.0-alpha.2 132 3/1/2023
0.1.0-alpha.1 97 1/18/2023
0.1.0-alpha.0 91 1/16/2023