Skip to content

Blazor QuickGrid article #28827

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
guardrex merged 4 commits into from
Mar 30, 2023
Merged

Blazor QuickGrid article #28827

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
076bf5e
Blazor QuickGrid article
guardrex Mar 30, 2023
371bca0
Updates
guardrex Mar 30, 2023
ec35b4a
Updates
guardrex Mar 30, 2023
b42af35
Updates
guardrex Mar 30, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions aspnetcore/blazor/components/built-in-components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: Find information on Razor components provided by the Blazor framewo
monikerRange: '>= aspnetcore-3.1'
ms.author: riande
ms.custom: mvc
ms.date: 11/08/2022
ms.date: 03/30/2023
uid: blazor/components/built-in-components
---
# ASP.NET Core built-in Razor components
Expand Down Expand Up @@ -39,7 +39,7 @@ The following built-in Razor components are provided by the Blazor framework:
* [`NavLink`](xref:blazor/fundamentals/routing#navlink-and-navmenu-components)
* [`NavMenu`](xref:blazor/fundamentals/routing#navlink-and-navmenu-components)
* [`PageTitle`](xref:blazor/components/control-head-content)
* [`QuickGrid`](xref:blazor/components/index#quickgrid-component)
* [`QuickGrid`](xref:blazor/components/quickgrid)
* [`Router`](xref:blazor/fundamentals/routing#route-templates)
* [`RouteView`](xref:blazor/fundamentals/routing#route-templates)
* [`Virtualize`](xref:blazor/components/virtualization)
Expand Down
138 changes: 0 additions & 138 deletions aspnetcore/blazor/components/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1472,144 +1472,6 @@ For more information, see the following resources:
* <xref:mvc/views/tag-helpers/builtin-th/component-tag-helper>
* <xref:blazor/components/prerendering-and-integration>

## `QuickGrid` component

:::moniker-end

:::moniker range=">= aspnetcore-8.0"

The `QuickGrid` component is a Razor component for quickly and efficiently displaying data in tabular form. `QuickGrid` provides a simple and convenient data grid component for common grid rendering scenarios and serves as a reference architecture and performance baseline for building data grid components. `QuickGrid` is highly optimized and uses advanced techniques to achieve optimal rendering performance.

To implement a `QuickGrid` component:

* Specify tags for the `QuickGrid` component in Razor markup (`<QuickGrid>...</QuickGrid>`).
* Name a queryable source of data for the grid. Use ***either*** of the following data sources:
* `Items`: A nullable `IQueryable<TGridItem>`, where `TGridItem` is the type of data represented by each row in the grid.
* `ItemsProvider`: A callback that supplies data for the grid.
* `Class`: An optional CSS class name. If provided, the class name is included in the `class` attribute of the rendered table.
* `Theme`: A theme name (default value: `default`). This affects which styling rules match the table.
* `Virtualize`: If true, the grid is rendered with virtualization. This is normally used in conjunction with scrolling and causes the grid to fetch and render only the data around the current scroll viewport. This can greatly improve the performance when scrolling through large data sets. If you use `Virtualize`, you should supply a value for `ItemSize` and must ensure that every row renders with a constant height. Generally, it's preferable not to use `Virtualize` if the amount of data rendered is small or if you're using pagination.
* `ItemSize`: Only applicable when using `Virtualize`. `ItemSize` defines an expected height in pixels for each row, allowing the virtualization mechanism to fetch the correct number of items to match the display size and to ensure accurate scrolling.
* `ItemKey`: Optionally defines a value for `@key` on each rendered row. Typically, this is used to specify a unique identifier, such as a primary key value, for each data item. This allows the grid to preserve the association between row elements and data items based on their unique identifiers, even when the `TGridItem` instances are replaced by new copies (for example, after a new query against the underlying data store). If not set, the `@key` is the `TGridItem` instance.
* `Pagination`: Optionally links this `QuickGrid{TGridItem}` instance with a `PaginationState` model, causing the grid to fetch and render only the current page of data. This is normally used in conjunction with a `Paginator` component or some other UI logic that displays and updates the supplied `PaginationState` instance.
* In the `QuickGrid` child content (<xref:Microsoft.AspNetCore.Components.RenderFragment>), specify `PropertyColumn`s, which represent `QuickGrid{TGridItem}` columns whose cells display values:
* `Property`: Defines the value to be displayed in this column's cells.
* `Format`: Optionally specifies a format string for the value. Using `Format` requires the `TProp` type to implement `IFormattable`.
* `Sortable`: Indicates whether the data should be sortable by this column. The default value may vary according to the column type. For example, a `TemplateColumn{TGridItem}` is sortable by default if any `TemplateColumn{TGridItem}.SortBy` parameter is specified.
* `InitialSortDirection`: Indicates which direction to sort in if `IsDefaultSortColumn` is `true`.
* `IsDefaultSortColumn`: Indicates whether this column should be sorted by default.
* `PlaceholderTemplate`: If specified, virtualized grids use this template to render cells whose data hasn't been loaded.

For example, add the following component to render a grid.

`Pages/QuickGridExample.razor`:

```razor
@page "/quickgrid-example"

<QuickGrid Items="@people">
<PropertyColumn Property="@(p => p.PersonId)" Sortable="true" />
<PropertyColumn Property="@(p => p.Name)" Sortable="true" />
<PropertyColumn Property="@(p => p.PromotionDate)" Format="yyyy-MM-dd" Sortable="true" />
</QuickGrid>

@code {
private record Person(int PersonId, string Name, DateOnly PromotionDate);

private IQueryable<Person> people = new[]
{
new Person(10895, "Jean Martin", new DateOnly(1985, 3, 16)),
new Person(10944, "António Langa", new DateOnly(1991, 12, 1)),
new Person(11203, "Julie Smith", new DateOnly(1958, 10, 10)),
new Person(11205, "Nur Sari", new DateOnly(1922, 4, 27)),
new Person(11898, "Jose Hernandez", new DateOnly(2011, 5, 3)),
new Person(12130, "Kenji Sato", new DateOnly(2004, 1, 9)),
}.AsQueryable();
}
```

For an example that uses an <xref:System.Linq.IQueryable> with Entity Framework Core as the queryable data source, see the [`SampleQuickGridComponent` component in the ASP.NET Core Basic Test App (`dotnet/aspnetcore` GitHub repository)](https://github.com/dotnet/aspnetcore/blob/main/src/Components/test/testassets/BasicTestApp/QuickGridTest/SampleQuickGridComponent.razor).

[!INCLUDE[](~/includes/aspnetcore-repo-ref-source-links.md)]

To use EF Core as the data source:

* Add a package reference to the app for the [`Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter) package.

[!INCLUDE[](~/includes/package-reference.md)]

* Call `AddQuickGridEntityFrameworkAdapter` on the service collection in `Startup.ConfigureServices` of `Startup.cs` (Blazor Server) or `Program.cs` (Blazor WebAssembly) to register an EF-aware implementation of `IAsyncQueryExecutor`.

* Blazor Server:

```csharp
services.AddQuickGridEntityFrameworkAdapter();
```

* Blazor WebAssembly:

```csharp
builder.Services.AddQuickGridEntityFrameworkAdapter();
```

:::moniker-end

:::moniker range=">= aspnetcore-7.0 < aspnetcore-8.0"

The `QuickGrid` component is an experimental Razor component for quickly and efficiently displaying data in tabular form. `QuickGrid` provides a simple and convenient data grid component for common grid rendering scenarios and serves as a reference architecture and performance baseline for building data grid components. `QuickGrid` is highly optimized and uses advanced techniques to achieve optimal rendering performance.

To get started with `QuickGrid`:

Add package reference for [`Microsoft.AspNetCore.Components.QuickGrid`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.QuickGrid). If using the .NET CLI to add the package reference, include the `--prerelease` option when you execute the [`dotnet add package` command](/dotnet/core/tools/dotnet-add-package).

[!INCLUDE[](~/includes/package-reference.md)]

Add the following component to render a grid.

`Pages/QuickGridExample.razor`:

```razor
@page "/quickgrid-example"
@using Microsoft.AspNetCore.Components.QuickGrid

<QuickGrid Items="@people">
<PropertyColumn Property="@(p => p.PersonId)" Sortable="true" />
<PropertyColumn Property="@(p => p.Name)" Sortable="true" />
<PropertyColumn Property="@(p => p.PromotionDate)" Format="yyyy-MM-dd" Sortable="true" />
</QuickGrid>

@code {
private record Person(int PersonId, string Name, DateOnly PromotionDate);

private IQueryable<Person> people = new[]
{
new Person(10895, "Jean Martin", new DateOnly(1985, 3, 16)),
new Person(10944, "António Langa", new DateOnly(1991, 12, 1)),
new Person(11203, "Julie Smith", new DateOnly(1958, 10, 10)),
new Person(11205, "Nur Sari", new DateOnly(1922, 4, 27)),
new Person(11898, "Jose Hernandez", new DateOnly(2011, 5, 3)),
new Person(12130, "Kenji Sato", new DateOnly(2004, 1, 9)),
}.AsQueryable();
}
```

:::moniker-end

:::moniker range=">= aspnetcore-7.0"

Access the component in a browser at the relative path `/quickgrid-example`.

For various `QuickGrid` demonstrations, see the [**QuickGrid for Blazor** app](https://aspnet.github.io/quickgridsamples/). The demo site is built using Blazor WebAssembly and is hosted on GitHub Pages. The site loads fast thanks to static prerendering using the community-maintained [`BlazorWasmPrerendering.Build` GitHub project](https://github.com/jsakamoto/BlazorWasmPreRendering.Build).

There aren't current plans to extend `QuickGrid` with features that full-blown commercial grids tend to offer, for example, hierarchical rows, drag-to-reorder columns, or Excel-like range selections. If you require advanced features that you don't wish to develop on your own, continue using third-party grids.

:::moniker-end

:::moniker range=">= aspnetcore-7.0 < aspnetcore-8.0"

> [!WARNING]
> The `QuickGrid` component is in preview for ASP.NET Core 7.x. You're welcome to use it in production if it meets your needs, but it isn't officially supported until ASP.NET Core 8.0 or later.

:::moniker-end

:::moniker range=">= aspnetcore-6.0 < aspnetcore-7.0"
Expand Down
135 changes: 135 additions & 0 deletions aspnetcore/blazor/components/quickgrid.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
---
title: ASP.NET Core Blazor QuickGrid component
author: guardrex
description: The QuickGrid component is a Razor component for quickly and efficiently displaying data in tabular form.
monikerRange: '>= aspnetcore-7.0'
ms.author: riande
ms.custom: mvc
ms.date: 03/30/2023
uid: blazor/components/quickgrid
---
# ASP.NET Core Blazor `QuickGrid` component

:::moniker range=">= aspnetcore-8.0"

The `QuickGrid` component is a Razor component for quickly and efficiently displaying data in tabular form. `QuickGrid` provides a simple and convenient data grid component for common grid rendering scenarios and serves as a reference architecture and performance baseline for building data grid components. `QuickGrid` is highly optimized and uses advanced techniques to achieve optimal rendering performance.

To implement a `QuickGrid` component:

* Specify tags for the `QuickGrid` component in Razor markup (`<QuickGrid>...</QuickGrid>`).
* Name a queryable source of data for the grid. Use ***either*** of the following data sources:
* `Items`: A nullable `IQueryable<TGridItem>`, where `TGridItem` is the type of data represented by each row in the grid.
* `ItemsProvider`: A callback that supplies data for the grid.
* `Class`: An optional CSS class name. If provided, the class name is included in the `class` attribute of the rendered table.
* `Theme`: A theme name (default value: `default`). This affects which styling rules match the table.
* `Virtualize`: If true, the grid is rendered with virtualization. This is normally used in conjunction with scrolling and causes the grid to fetch and render only the data around the current scroll viewport. This can greatly improve the performance when scrolling through large data sets. If you use `Virtualize`, you should supply a value for `ItemSize` and must ensure that every row renders with a constant height. Generally, it's preferable not to use `Virtualize` if the amount of data rendered is small or if you're using pagination.
* `ItemSize`: Only applicable when using `Virtualize`. `ItemSize` defines an expected height in pixels for each row, allowing the virtualization mechanism to fetch the correct number of items to match the display size and to ensure accurate scrolling.
* `ItemKey`: Optionally defines a value for `@key` on each rendered row. Typically, this is used to specify a unique identifier, such as a primary key value, for each data item. This allows the grid to preserve the association between row elements and data items based on their unique identifiers, even when the `TGridItem` instances are replaced by new copies (for example, after a new query against the underlying data store). If not set, the `@key` is the `TGridItem` instance.
* `Pagination`: Optionally links this `TGridItem` instance with a `PaginationState` model, causing the grid to fetch and render only the current page of data. This is normally used in conjunction with a `Paginator` component or some other UI logic that displays and updates the supplied `PaginationState` instance.
* In the `QuickGrid` child content (<xref:Microsoft.AspNetCore.Components.RenderFragment>), specify `PropertyColumn`s, which represent `TGridItem` columns whose cells display values:
* `Property`: Defines the value to be displayed in this column's cells.
* `Format`: Optionally specifies a format string for the value. Using `Format` requires the `TProp` type to implement `IFormattable`.
* `Sortable`: Indicates whether the data should be sortable by this column. The default value may vary according to the column type. For example, a `TemplateColumn<TGridItem>` is sortable by default if any `TemplateColumn<TGridItem>.SortBy` parameter is specified.
* `InitialSortDirection`: Indicates the sort direction if `IsDefaultSortColumn` is `true`.
* `IsDefaultSortColumn`: Indicates whether this column should be sorted by default.
* `PlaceholderTemplate`: If specified, virtualized grids use this template to render cells whose data hasn't been loaded.

For example, add the following component to render a grid.

`Pages/QuickGridExample.razor`:

```razor
@page "/quickgrid-example"

<QuickGrid Items="@people">
<PropertyColumn Property="@(p => p.PersonId)" Sortable="true" />
<PropertyColumn Property="@(p => p.Name)" Sortable="true" />
<PropertyColumn Property="@(p => p.PromotionDate)" Format="yyyy-MM-dd" Sortable="true" />
</QuickGrid>

@code {
private record Person(int PersonId, string Name, DateOnly PromotionDate);

private IQueryable<Person> people = new[]
{
new Person(10895, "Jean Martin", new DateOnly(1985, 3, 16)),
new Person(10944, "António Langa", new DateOnly(1991, 12, 1)),
new Person(11203, "Julie Smith", new DateOnly(1958, 10, 10)),
new Person(11205, "Nur Sari", new DateOnly(1922, 4, 27)),
new Person(11898, "Jose Hernandez", new DateOnly(2011, 5, 3)),
new Person(12130, "Kenji Sato", new DateOnly(2004, 1, 9)),
}.AsQueryable();
}
```

For an example that uses an <xref:System.Linq.IQueryable> with Entity Framework Core as the queryable data source, see the [`SampleQuickGridComponent` component in the ASP.NET Core Basic Test App (`dotnet/aspnetcore` GitHub repository)](https://github.com/dotnet/aspnetcore/blob/main/src/Components/test/testassets/BasicTestApp/QuickGridTest/SampleQuickGridComponent.razor).

[!INCLUDE[](~/includes/aspnetcore-repo-ref-source-links.md)]

To use Entity Framework (EF) Core as the data source:

* Add a package reference to the app for the [`Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter) package.

[!INCLUDE[](~/includes/package-reference.md)]

* Call `AddQuickGridEntityFrameworkAdapter` on the service collection in `Program.cs` to register an EF-aware implementation of `IAsyncQueryExecutor`:

```csharp
builder.Services.AddQuickGridEntityFrameworkAdapter();
```

:::moniker-end

:::moniker range="< aspnetcore-8.0"

The `QuickGrid` component is an experimental Razor component for quickly and efficiently displaying data in tabular form. `QuickGrid` provides a simple and convenient data grid component for common grid rendering scenarios and serves as a reference architecture and performance baseline for building data grid components. `QuickGrid` is highly optimized and uses advanced techniques to achieve optimal rendering performance.

To get started with `QuickGrid`:

Add package reference for [`Microsoft.AspNetCore.Components.QuickGrid`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.QuickGrid). If using the .NET CLI to add the package reference, include the `--prerelease` option when you execute the [`dotnet add package` command](/dotnet/core/tools/dotnet-add-package).

[!INCLUDE[](~/includes/package-reference.md)]

Add the following component to render a grid.

`Pages/QuickGridExample.razor`:

```razor
@page "/quickgrid-example"
@using Microsoft.AspNetCore.Components.QuickGrid

<QuickGrid Items="@people">
<PropertyColumn Property="@(p => p.PersonId)" Sortable="true" />
<PropertyColumn Property="@(p => p.Name)" Sortable="true" />
<PropertyColumn Property="@(p => p.PromotionDate)" Format="yyyy-MM-dd" Sortable="true" />
</QuickGrid>

@code {
private record Person(int PersonId, string Name, DateOnly PromotionDate);

private IQueryable<Person> people = new[]
{
new Person(10895, "Jean Martin", new DateOnly(1985, 3, 16)),
new Person(10944, "António Langa", new DateOnly(1991, 12, 1)),
new Person(11203, "Julie Smith", new DateOnly(1958, 10, 10)),
new Person(11205, "Nur Sari", new DateOnly(1922, 4, 27)),
new Person(11898, "Jose Hernandez", new DateOnly(2011, 5, 3)),
new Person(12130, "Kenji Sato", new DateOnly(2004, 1, 9)),
}.AsQueryable();
}
```

:::moniker-end

Access the component in a browser at the relative path `/quickgrid-example`.

There aren't current plans to extend `QuickGrid` with features that full-blown commercial grids tend to offer, for example, hierarchical rows, drag-to-reorder columns, or Excel-like range selections. If you require advanced features that you don't wish to develop on your own, continue using third-party grids.

:::moniker range="< aspnetcore-8.0"

For various `QuickGrid` demonstrations, see the [**QuickGrid for Blazor** app](https://aspnet.github.io/quickgridsamples/). The demo site is built using Blazor WebAssembly and is hosted on GitHub Pages. The site loads fast thanks to static prerendering using the community-maintained [`BlazorWasmPrerendering.Build` GitHub project](https://github.com/jsakamoto/BlazorWasmPreRendering.Build).

> [!WARNING]
> The `QuickGrid` component is in preview for ASP.NET Core 7.x. You're welcome to use it in production if it meets your needs, but it isn't officially supported until ASP.NET Core 8.0 or later.

:::moniker-end
2 changes: 1 addition & 1 deletion aspnetcore/release-notes/aspnetcore-7.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -457,7 +457,7 @@ Several additional changes were made to the Blazor project templates. It isn't f

The new `QuickGrid` component provides a convenient data grid component for most common requirements and as a reference architecture and performance baseline for anyone building Blazor data grid components.

For more information, see <xref:blazor/components/index?view=aspnetcore-7.0#quickgrid-component>.
For more information, see <xref:blazor/components/quickgrid>.

Live demo: [QuickGrid for Blazor sample app](https://aspnet.github.io/quickgridsamples/)

Expand Down
2 changes: 2 additions & 0 deletions aspnetcore/toc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -451,6 +451,8 @@ items:
uid: blazor/components/css-isolation
- name: Dynamically-rendered components
uid: blazor/components/dynamiccomponent
- name: QuickGrid component
uid: blazor/components/quickgrid
- name: Prerender and integrate components
uid: blazor/components/prerendering-and-integration
- name: Class libraries
Expand Down