Skip to content

Commit b0414c1

Browse files
kdinevkdinev
authored
Merge branch 'master' into jsakamoto/fix/stories/circuit-disconnects-at-a11y-panel
2 parents a4ed85c + faf637b commit b0414c1

1 file changed

Lines changed: 322 additions & 0 deletions

File tree

‎skills/igniteui-blazor-grids/references/grid-migration.md‎

Lines changed: 322 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,322 @@
1+
# Grid Migration - Grid Lite → Premium IgbGrid
2+
3+
> **Part of the [`igniteui-blazor-grids`](../SKILL.md) skill hub.**
4+
> For `IgbGrid` setup and column configuration — see [`structure.md`](./structure.md).
5+
> For specialized grid types including `IgbGridLite` — see [`types.md`](./types.md).
6+
> For cell and row editing after migration — see [`editing.md`](./editing.md).
7+
8+
## Contents
9+
10+
- [When to Migrate from Grid Lite to IgbGrid](#when-to-migrate-from-grid-lite-to-igbgrid)
11+
- [Setup](#setup)
12+
- [Minimal Migration Example](#minimal-migration-example)
13+
- [Component and API Changes](#component-and-api-changes)
14+
- [Cell Templates](#cell-templates)
15+
- [Header Templates](#header-templates)
16+
- [Remote Data](#remote-data)
17+
- [Programmatic Sort / Filter](#programmatic-sort--filter)
18+
- [Common Enterprise Features](#common-enterprise-features)
19+
- [Cleanup After Migration](#cleanup-after-migration)
20+
- [Key Rules](#key-rules)
21+
22+
---
23+
24+
## When to Migrate from Grid Lite to IgbGrid
25+
26+
Migrate when you need any of the following features (not available in `IgbGridLite`):
27+
28+
| Feature | Grid Lite | Premium Grid (`IgbGrid`) |
29+
|---|---|---|
30+
| Cell editing | ✗ | ✓ `Editable` on column, `RowEditable` on grid |
31+
| Batch editing (with undo) | ✗ | ✗ (not supported in Blazor) |
32+
| Row adding / deleting | ✗ | ✓ `RowEditable` + `IgbActionStrip` |
33+
| Row selection | ✗ | ✓ `RowSelection="GridSelectionMode.Single|Multiple"` |
34+
| Cell selection | ✗ | ✓ `CellSelection` |
35+
| Column selection | ✗ | ✓ `ColumnSelection` |
36+
| Paging | ✗ | ✓ `IgbPaginator` child |
37+
| GroupBy | ✗ | ✓ `GroupingExpressions` (IgbGrid only) |
38+
| Column summaries | ✗ | ✓ `HasSummary` on `IgbColumn` |
39+
| Column pinning | ✗ | ✓ `Pinned` on `IgbColumn` |
40+
| Column moving | ✗ | ✓ `Moving="true"` on grid |
41+
| Master-detail rows | ✗ | ✓ `IgbGrid` row expansion |
42+
| Excel / CSV export (toolbar) | ✗ | ✓ `IgbGridToolbarExporter` |
43+
| Column hiding toolbar | ✗ | ✓ `IgbGridToolbarHiding` |
44+
| Column pinning toolbar | ✗ | ✓ `IgbGridToolbarPinning` |
45+
| Advanced filtering UI | ✗ | ✓ `IgbGridToolbarAdvancedFiltering` |
46+
| State persistence | ✗ | ✓ `IgbGridState` |
47+
| Clipboard operations | ✗ | ✓ `ClipboardOptions` |
48+
| Action strip | ✗ | ✓ `IgbActionStrip` |
49+
| Row drag and drop | ✗ | ✓ `RowDraggable="true"` |
50+
51+
---
52+
53+
## Setup
54+
55+
### 1. Replace the NuGet package registration
56+
57+
```csharp
58+
// Remove:
59+
builder.Services.AddIgniteUIBlazor(typeof(IgbGridLiteModule));
60+
61+
// Add:
62+
builder.Services.AddIgniteUIBlazor(typeof(IgbGridModule));
63+
```
64+
65+
### 2. Replace the CSS link in `index.html`
66+
67+
```html
68+
<!-- Remove: -->
69+
<link href="_content/IgniteUI.Blazor.GridLite/css/themes/light/bootstrap.css" rel="stylesheet" />
70+
71+
<!-- Add: -->
72+
<link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />
73+
<link href="_content/IgniteUI.Blazor/themes/grid/light/bootstrap.css" rel="stylesheet" />
74+
```
75+
76+
### 3. Update `_Imports.razor`
77+
78+
`IgniteUI.Blazor.Controls` covers both `IgbGridLite` and `IgbGrid` — no change needed if already present.
79+
80+
```razor
81+
@using IgniteUI.Blazor.Controls
82+
```
83+
84+
---
85+
86+
## Minimal Migration Example
87+
88+
```razor
89+
<!-- Before: -->
90+
<IgbGridLite TItem="Product" Data="@products">
91+
<IgbGridLiteColumn Field="Name" Header="Name" DataType="GridLiteColumnDataType.String" Sortable Filterable Resizable />
92+
<IgbGridLiteColumn Field="Price" Header="Price" DataType="GridLiteColumnDataType.Number" />
93+
</IgbGridLite>
94+
95+
<!-- After: -->
96+
<IgbGrid @ref="grid" Data="@products" PrimaryKey="Id" AutoGenerate="false"
97+
Width="100%" Height="600px" AllowFiltering="true">
98+
<IgbColumn Field="Name" Header="Name" DataType="GridColumnDataType.String" Sortable="true" Filterable="true" Resizable="true" />
99+
<IgbColumn Field="Price" Header="Price" DataType="GridColumnDataType.Number" Sortable="true" />
100+
</IgbGrid>
101+
102+
@code {
103+
private IgbGrid grid = default!;
104+
private List<Product> products = new();
105+
}
106+
```
107+
108+
**Key additions vs Grid Lite:**
109+
- `PrimaryKey` — required for editing, selection, and row-targeted APIs
110+
- `Height` — required for row virtualization
111+
- `AllowFiltering="true"` on the grid — enables the filter row UI; `Filterable="true"` on a column opts that column in
112+
- `@ref` — required for programmatic API access
113+
114+
---
115+
116+
## Component and API Changes
117+
118+
| Grid Lite | Premium Grid |
119+
|---|---|
120+
| `IgbGridLite` | `IgbGrid` |
121+
| `IgbGridLiteColumn` | `IgbColumn` |
122+
| `GridLiteColumnDataType` | `GridColumnDataType` |
123+
| `IgbGridLiteModule` | `IgbGridModule` |
124+
| `IgbGridLiteSortingExpression` | `IgbSortingExpression` |
125+
| `IgbGridLiteFilterExpression` | `IgbFilteringExpression` |
126+
| Column `Key` (in sort/filter objects) | Column `FieldName` (in sort/filter objects) |
127+
| `TItem` generic parameter | `TItem` (unchanged) |
128+
| No `PrimaryKey` | `PrimaryKey` required for most features |
129+
130+
---
131+
132+
## Cell Templates
133+
134+
Grid Lite has no cell templates. In `IgbGrid`, use the `BodyTemplate` render fragment on `IgbColumn`:
135+
136+
```razor
137+
<IgbColumn Field="Status" Header="Status">
138+
<BodyTemplate>
139+
@{
140+
var cell = (IgbCellTemplateContext)context;
141+
var status = cell.Cell.Value?.ToString();
142+
}
143+
<span style="color: @(status == "Active" ? "green" : "red")">@status</span>
144+
</BodyTemplate>
145+
</IgbColumn>
146+
```
147+
148+
| | Grid Lite | Premium Grid |
149+
|---|---|---|
150+
| Cell template | Not supported | `BodyTemplate` render fragment |
151+
| Cell value | — | `((IgbCellTemplateContext)context).Cell.Value` |
152+
| Row data | — | `((IgbCellTemplateContext)context).Cell.Row.Data` |
153+
| Edit template | — | `InlineEditorTemplate` render fragment |
154+
155+
---
156+
157+
## Header Templates
158+
159+
Grid Lite has no header templates. In `IgbGrid`, use the `HeaderTemplate` render fragment:
160+
161+
```razor
162+
<IgbColumn Field="Price" Header="Price">
163+
<HeaderTemplate>
164+
<strong>@((context as IgbColumnTemplateContext)?.Column.Header)</strong>
165+
</HeaderTemplate>
166+
</IgbColumn>
167+
```
168+
169+
---
170+
171+
## Remote Data
172+
173+
For server-side sort/filter, handle the `SortingDone` / `FilteringDone` events to reload data:
174+
```razor
175+
<IgbGrid @ref="grid" Data="@data" PrimaryKey="Id" Height="600px"
176+
SortingDone="OnSortingDone" FilteringDone="OnFilteringDone">
177+
</IgbGrid>
178+
179+
@code {
180+
private IgbGrid grid = default!;
181+
private List<MyItem> data = new();
182+
183+
184+
private async Task OnSortingDone(IgbSortingExpressionEventArgs args)
185+
{
186+
data = await DataService.SortAsync(args.Detail);
187+
StateHasChanged();
188+
}
189+
190+
private async Task OnFilteringDone(IgbFilteringExpressionsTreeEventArgs args)
191+
{
192+
data = await DataService.FilterAsync(args.Detail);
193+
StateHasChanged();
194+
}
195+
}
196+
```
197+
198+
---
199+
200+
## Programmatic Sort / Filter
201+
202+
```razor
203+
@code {
204+
private IgbGrid grid = default!;
205+
206+
// Sort
207+
private async Task SortByName()
208+
{
209+
await grid.SortAsync(new IgbSortingExpression[]
210+
{
211+
new IgbSortingExpression { FieldName = "Name", Dir = SortingDirection.Asc }
212+
});
213+
}
214+
215+
private async Task ClearSorting() => await grid.ClearSortAsync();
216+
217+
// Filter
218+
private void FilterActive()
219+
{
220+
var tree = new IgbFilteringExpressionsTree() { Operator = FilteringLogic.And };
221+
tree.FilteringOperands = new IgbFilteringExpression[]
222+
{
223+
new IgbFilteringExpression { FieldName = "IsActive", ConditionName = "true", SearchVal = true }
224+
};
225+
grid.FilteringExpressionsTree = tree;
226+
}
227+
228+
private async Task ClearFilters() => await grid.ClearFilterAsync();
229+
}
230+
```
231+
232+
> In Grid Lite, sort/filter expressions used a `Key` property. In `IgbGrid`, use `FieldName`.
233+
234+
---
235+
236+
## Common Enterprise Features
237+
238+
### Editing
239+
240+
```razor
241+
<IgbGrid Data="@data" PrimaryKey="Id" RowEditable="true" Height="600px">
242+
<IgbColumn Field="Name" Editable="true" />
243+
<IgbColumn Field="Price" Editable="true" DataType="GridColumnDataType.Number" />
244+
</IgbGrid>
245+
```
246+
247+
See [`editing.md`](./editing.md) for cell editing, row editing, validation, and custom editors.
248+
249+
### Row Selection
250+
251+
```razor
252+
<IgbGrid Data="@data" PrimaryKey="Id" RowSelection="GridSelectionMode.Multiple" Height="600px">
253+
<IgbColumn Field="Name" />
254+
</IgbGrid>
255+
256+
@code {
257+
// Read selected rows via grid.SelectedRows
258+
}
259+
```
260+
261+
### Paging
262+
263+
```razor
264+
<IgbGrid Data="@data" PrimaryKey="Id" Height="600px">
265+
<IgbPaginator PerPage="15" />
266+
<IgbColumn Field="Name" />
267+
</IgbGrid>
268+
```
269+
270+
See [`paging-remote.md`](./paging-remote.md) for remote paging and paginator configuration.
271+
272+
### Summaries
273+
274+
```razor
275+
<IgbColumn Field="Price" DataType="GridColumnDataType.Number" HasSummary="true" />
276+
```
277+
278+
### Toolbar + Export
279+
280+
```razor
281+
<IgbGrid Data="@data" PrimaryKey="Id" Height="600px">
282+
<IgbGridToolbar>
283+
<IgbGridToolbarTitle>Products</IgbGridToolbarTitle>
284+
<IgbGridToolbarActions>
285+
<IgbGridToolbarHiding />
286+
<IgbGridToolbarPinning />
287+
<IgbGridToolbarAdvancedFiltering />
288+
<IgbGridToolbarExporter ExportExcel="true" ExportCSV="true" />
289+
</IgbGridToolbarActions>
290+
</IgbGridToolbar>
291+
<IgbColumn Field="Name" />
292+
<IgbColumn Field="Price" />
293+
</IgbGrid>
294+
```
295+
296+
See [`features.md`](./features.md) for toolbar customization, export events, grouping, summaries, and action strip.
297+
298+
---
299+
300+
## Cleanup After Migration
301+
302+
1. Remove `IgbGridLiteModule` registration from `Program.cs`.
303+
2. Remove the `IgniteUI.Blazor.GridLite` CSS `<link>` from `index.html`.
304+
3. Rename all `IgbGridLite` → `IgbGrid`, `IgbGridLiteColumn` → `IgbColumn` in `.razor` files.
305+
4. Replace `GridLiteColumnDataType` → `GridColumnDataType` enum values.
306+
5. In sort/filter expression objects, rename the `Key` property → `FieldName`.
307+
6. Remove the `IgniteUI.Blazor.GridLite` NuGet package if no `IgbGridLite` instances remain:
308+
```bash
309+
dotnet remove package IgniteUI.Blazor.GridLite
310+
```
311+
312+
---
313+
314+
## Key Rules
315+
316+
- `PrimaryKey` is required for editing, selection, row APIs, and `IgbActionStrip` — Grid Lite had no equivalent.
317+
- `Height` (or a CSS-constrained container) is required for row virtualization in `IgbGrid`.
318+
- `AllowFiltering="true"` must be set on the grid to show the filter row; `Filterable="true"` on a column opts that column in.
319+
- Cell and header templates use Blazor render fragments (`BodyTemplate`, `HeaderTemplate`, `InlineEditorTemplate`) — not callbacks or delegates.
320+
- For remote data, handle `SortingDone` / `FilteringDone` and reload `Data` from your server.
321+
- `IgbColumn.FieldName` (in expression objects) replaces `IgbGridLiteColumn.Key` used in Grid Lite sort/filter expressions.
322+

0 commit comments

Comments
 (0)