Blazor-wrapped component over ag-Grid.
⭐ 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:
- Inline static & programmatic column definitions
- Inline static and inline dynamic & programatic row data
- Client-side and Infinite row model types
- Custom Datasource
- Custom Row ID resolution
- Custom Datasource
- Single- and Multi-row selection
- Selection notification
- Paging
- Sorting
- Various tweaks and customizations to the features above such as:
- page size
- cell-selection suppression
- datasource page caching
- row deselection
- Grid and Column APIs
- local JS script configuration
- Works with both Blazor WASM and Blazor Server hosting models (with some caveats)
There are several examples that each demonstrate some typical usage under different scenarios:
- Example1 - demonstrates Blazor WASM + ASP.NET Core hosted example
- Example2 - similar to Example1 but this is purely WASM client with no back-end. This Example is the one that is used for the public demo.
- Example3 - demonstrates Blazor Server hosting model. This is an adaptation of Example1 and demonstrates some of the caveats that need to be considered and addressed with the Server hosting model (more details below).
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 BlazorAgGridTo 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="_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:
- Properties:
WidthStyle&HeightStyleOptions,CallbacksandEvents(see below)
- Child Components:
<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:
- GridOptions
- GridCallbacks
- GridEvents
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.