Blazor-wrapped component over ag-Grid.
:star: I appreciate your star, it helps me decide to which OSS projects I should allocate my spare time.
Blazor WASM demo can be found here.
This project implements a Blazor component that wraps the ag-Grid JavaScript data grid.
ag-Grid is a very feature-rich and capable JS control, however this Blazor-compatible, wrapped component only attempts to expose a relatively small subset of these features that were useful and needed for my own purposes.
Over time, this subset may grow as my own requirements change, and of course, from any community contributions.
Here is a list of features that are currently supported:
There are several examples that each demonstrate some typical usage under different scenarios:
Firstly, this component is still in very early stage and only being published as a nuget in the GitHub Package Repository (GPR).
Add a nuget.config file to your project (e.g. dotnet new nugetconfig
)
and edit it to include the package source for this repo:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<!--To inherit the global NuGet package sources remove the <clear/> line below -->
<clear />
<add key="nuget" value="https://api.nuget.org/v3/index.json" />
<add key="github" value="https://nuget.pkg.github.com/ebekker/index.json" />
</packageSources>
</configuration>
Note, you must also authenticate to GPR, more details can be found here.
Then add the nuget to your project:
PS> dotnet add package BlazorAgGrid
To use this component you'll need to add a few basic resource references to ag-Grid assets such as CSS and JS files as described in the docs.
Add this to the <head>
section of your index.html
file.
<script src="https://unpkg.com/ag-grid-community/dist/ag-grid-community.min.noStyle.js"></script>
<link rel="stylesheet" href="https://unpkg.com/ag-grid-community/dist/styles/ag-grid.css">
<link rel="stylesheet" href="https://unpkg.com/ag-grid-community/dist/styles/ag-theme-balham.css">
The last line assumes you're using the Balham
theme.
If you choose to use another theme,
adjust appropriately.
Next you want to add a reference to the JS interop support file
specific to this Blazor component by also adding this to your
<head>
section:
<script src="https://github.com/ebekker/blazor-ag-grid/raw/master/_content/BlazorAgGrid/blazor-ag-grid.js"></script>
Finally, in your Blazor pages, drop in the <AgGrid>
component
wherever you want to use it and configure with these properties
and child compoenents:
WidthStyle
& HeightStyle
Options
, Callbacks
and Events
(see below)<ColumnDefinition>
<RowData>
See the example projects as described above for usage examples.
In general, this Blazor component tries to follow the configuration approach of the native ag-Grid control, which is primarily to use the Grid Options interface. However, because of the need to perform JS Interop between the .NET and the JS runtimes, there are some challenges to simply using the Grid Options interface natively.
To that end, the Options interface is actually broken out into three core classes on the .NET side that are used to configure the ag-Grid and its behavior:
The GridOptions
class defines all the currently supported simple
flags and feature configurations (mostly boolean and numerical) values.
It also provides you with the ability to define Column Definitions and simple Row Data programmatically. Alternatively you can define each of these using inline child components.
Grid Options is also where you would provide a custom IDatasource implementation that would allow you to provide data from any source, such as from in-memory collection or from a back-end server.
The GridCallbacks
class defines all supported Callbacks
of ag-Grid.
This is currently limited to resolving a Row Node ID when you provide a custom Datasource.
NOTE: Grid Callbacks should NOT be used with the Blazor Server hosting model, see more details below.
The GridEvents
class defines all supported Events
of ag-Grid.
This is currently limited to being notified of a change in row selection.
This component provides an optional ConfigureScript
parameter
to allow you to specify your own native JS configuration logic.
This feature was added for scenarios where you must use a
JavaScript-local routine to perform some pre-create configuration
of the Grid Options instance. If specified, this should be the
name of a function scoped against the browser's window
object
that will be invoked with an argument of the Grid Options instance.
This function will be invoked after all the other configuration elements above have been processed and just before the ag-Grid instance is created with these options. You can use it to perform any final validation or mutation of the options instance, such as registering JS-local callbacks or event handlers.
See more details below about the Blazor Server hosting model where this comes in handy.
The Grid component exposes Api
and ColumnApi
properties that
provide access to the corresponding ag-Grid APIs.
Currently each of these interfaces only contain a very small
number of sample API methods to invoke. Right now these include
samples for column resizing and purging/refreshing the cache used
for the Infinite
row model type.
This component has been developed and tested to work with both WebAssembly and Server hosting models currently supported by Blazor.
For Blazor WASM hosting model, all features should work as expected.
However, for the Blazor Server hosting model, there are some caveats to consider. When using the Blazor Server hosting model, interop invocations across JS/.NET runtimes must be performed asynchronously in both directions. This is a necessity because in the Server hosting model, all interop is taking place over a SignalR connection and network activity inevitably incurs latency and possible disconnects that are not a consideration in the WASM hosting model.
Therefore, anywhere this component must use a synchronous invocation
should be avoided. Specifically, the GridCallbacks
interface should
not be used for the Server hosting model as this is a mechanism that
the ag-Grid instance is calling into your code to resolve some data
and ag-Grid does not support asynchronous invocations for any of the
callback functions.
There is an out for this scenario. This Blazor compenent does
support an optional ConfigureScript
parameter as described above.
As long as your logic can be specified and implementd fully in
browser-side JS code, you can use this parameter to inject your own
logic such as adding callbacks and event handlers on the Grid Options
instance just before the Grid instance is created.