|
2 | 2 | title: Overview |
3 | 3 | page_title: Grid - Selection Overview |
4 | 4 | description: Selection basics in the Grid for Blazor. |
5 | | -slug: components/grid/selection/overview |
| 5 | +slug: grid-selection-overview |
6 | 6 | tags: telerik,blazor,grid,selection,overview |
7 | 7 | published: True |
8 | 8 | position: 0 |
9 | 9 | --- |
10 | 10 |
|
11 | 11 | # Grid Selection |
12 | 12 |
|
13 | | -The Grid component offers support for row selection. |
14 | | - |
15 | | -In this article: |
16 | | - |
17 | | -* [Selection Basics](#selection-basics) |
18 | | - * [Example - Enable Row Selection](#example---enable-row-selection) |
19 | | - * [Example - Select rows with checkboxes only](#example---select-rows-with-checkboxes-only) |
20 | | -* [Notes](#notes) |
21 | | - * [Editing Modes](#editing-modes) |
22 | | - * [Selection in Template](#selection-in-template) |
23 | | - * [Asynchronous Operations](#asynchronous-operations) |
24 | | - * [SelectedItems Equals Comparison](#selecteditems-equals-comparison) |
25 | | - * [Handle Data Changes](#handle-data-changes) |
26 | | - * [Selection in Grid with virtualized rows](#selection-in-grid-with-virtualized-rows) |
27 | | - * [Row Drag and Drop](#row-drag-and-drop) |
28 | | - |
29 | | - |
30 | | -## Selection Basics |
31 | | - |
32 | | -You can configure the selection behavior by setting `SelectionMode` to a member of the `Telerik.Blazor.GridSelectionMode` enum. The row selection can be: |
33 | | - |
34 | | -* `None` - (the default value) to disable row selection |
35 | | -* [Single]({%slug components/grid/selection/single%}) |
36 | | -* [Multiple]({%slug components/grid/selection/multiple%}) |
37 | | - |
38 | | -To select a row, click on it. To select multiple rows, hold down the `Ctrl` or `Shift` key to extend the selection. |
39 | | - |
40 | | -You can also use a checkbox column to select rows. To use it, add a [`GridCheckboxColumn`]({%slug components/grid/columns/checkbox%}) in the `GridColumns` collection of the grid. It works with both selection modes. With multiple selection mode, the checkbox column offers [additional functionality]({%slug components/grid/selection/multiple%}#checkbox-selection). |
41 | | - |
42 | | -You can get or set the selected items through the `SelectedItems` property. It is a collection of items from the Grid's `Data`. |
43 | | - |
44 | | -The [single selection]({%slug components/grid/selection/single%}) and [multiple selection]({%slug components/grid/selection/multiple%}) articles provide more examples and details on using the grid features. |
45 | | - |
46 | | -### Example - Enable Row Selection |
47 | | - |
48 | | -````CSHTML |
49 | | -See how the row selection modes work |
| 13 | +The Grid component supports row and cell selection. When you select a row or a cell, they will be highlighted in the Grid. This article provides an overview of the Grid selection behavior and configuration: |
50 | 14 |
|
51 | | -<select @bind=@selectionMode> |
52 | | - <option value=@GridSelectionMode.Single>Single</option> |
53 | | - <option value=@GridSelectionMode.Multiple>Multiple</option> |
54 | | -</select> |
| 15 | +* [Enable row or cell selection](#enable-row-or-cell-selection) |
| 16 | +* [Use single or multiple selection](#use-single-or-multiple-selection) |
| 17 | +* [Access selected rows or cells](#access-selected-rows-or-cells) |
| 18 | +* [Handle selection events](#events) |
| 19 | +* [Combine selection with other Grid features](#integration-with-other-grid-features) |
55 | 20 |
|
56 | | -<TelerikGrid Data=@GridData |
57 | | - SelectionMode="@selectionMode" |
58 | | - Pageable="true"> |
59 | | - <GridColumns> |
60 | | - <GridCheckboxColumn SelectAll="@( selectionMode == GridSelectionMode.Single ? false : true )" Title="Select" Width="70px" /> |
61 | | - <GridColumn Field=@nameof(Employee.Name) /> |
62 | | - <GridColumn Field=@nameof(Employee.Team) Title="Team" /> |
63 | | - </GridColumns> |
64 | | -</TelerikGrid> |
65 | | -
|
66 | | -@code { |
67 | | - public List<Employee> GridData { get; set; } |
| 21 | +## Enable Row or Cell Selection |
68 | 22 |
|
69 | | - GridSelectionMode selectionMode = GridSelectionMode.Single; |
| 23 | +You can configure the Grid either for row or cell selection: |
70 | 24 |
|
71 | | - protected override void OnInitialized() |
72 | | - { |
73 | | - GridData = new List<Employee>(); |
74 | | - for (int i = 0; i < 15; i++) |
75 | | - { |
76 | | - GridData.Add(new Employee() |
77 | | - { |
78 | | - EmployeeId = i, |
79 | | - Name = "Employee " + i.ToString(), |
80 | | - Team = "Team " + i % 3 |
81 | | - }); |
82 | | - } |
83 | | - } |
| 25 | +* To enable row selection: |
| 26 | + * Set the [Grid `SelectionMode` parameter](#use-single-or-multiple-selection) or |
| 27 | + * Add a `<GridSelectionSettings>` tag to the `<GridSettings>` tag, and set the `SelectionType` parameter to `GridSelectionType.Row`. |
| 28 | + * Optionally, you can also select rows through the [checkbox column]({%slug components/grid/columns/checkbox%}). |
| 29 | +* To enable cell selection: |
| 30 | + * Add a `<GridSelectionSettings>` tag to the `<GridSettings>` tag, and set the `SelectionType` parameter to the `Cell` member of the `Telerik.Blazor.GridSelectionType` enum. |
84 | 31 |
|
85 | | - public class Employee |
86 | | - { |
87 | | - public int EmployeeId { get; set; } |
88 | | - public string Name { get; set; } |
89 | | - public string Team { get; set; } |
90 | | - } |
91 | | -} |
92 | | -```` |
| 32 | +See [Rows Selection Options]({%slug grid-selection-row%}#basics) and [Cells Selection Options]({%slug grid-selection-cell%}#basics) for more details. |
93 | 33 |
|
94 | | -### Example - Select rows with checkboxes only |
| 34 | +## Use Single or Multiple Selection |
95 | 35 |
|
96 | | -````CSHTML |
97 | | -@* Require clicks on the checkboxes for row selection*@ |
| 36 | +You can configure the selection behavior by setting the Grid `SelectionMode` parameter to a member of the `Telerik.Blazor.GridSelectionMode` enum. The Grid supports the following selection modes: |
98 | 37 |
|
99 | | -<TelerikGrid Data=@GridData Navigable="true" |
100 | | - SelectionMode="GridSelectionMode.Multiple" |
101 | | - Pageable="true" |
102 | | - Height="400px"> |
103 | | - <GridColumns> |
104 | | - <GridCheckboxColumn CheckBoxOnlySelection="true" /> |
105 | | - <GridColumn Field=@nameof(Employee.Name) /> |
106 | | - <GridColumn Field=@nameof(Employee.Team) Title="Team" /> |
107 | | - </GridColumns> |
108 | | -</TelerikGrid> |
| 38 | +* `None` (default)—Disables row and cell selection. |
| 39 | +* `Single`—Allows the user to select only one cell or row at a time. If the user attempts to select multiple cells or rows sequentially, only the most recent selection will take effect. |
| 40 | +* `Multiple`—Allows the user to select multiple rows or cells at a time. |
109 | 41 |
|
110 | | -@code { |
111 | | - public List<Employee> GridData { get; set; } |
| 42 | +## Access Selected Rows or Cells |
112 | 43 |
|
113 | | - protected override void OnInitialized() |
114 | | - { |
115 | | - GridData = new List<Employee>(); |
116 | | - for (int i = 0; i < 15; i++) |
117 | | - { |
118 | | - GridData.Add(new Employee() |
119 | | - { |
120 | | - EmployeeId = i, |
121 | | - Name = "Employee " + i.ToString(), |
122 | | - Team = "Team " + i % 3 |
123 | | - }); |
124 | | - } |
125 | | - } |
| 44 | +The Grid exposes two parameters to get or set its selected rows and cells. |
126 | 45 |
|
127 | | - public class Employee |
128 | | - { |
129 | | - public int EmployeeId { get; set; } |
130 | | - public string Name { get; set; } |
131 | | - public string Team { get; set; } |
132 | | - } |
133 | | -} |
134 | | -```` |
| 46 | +* Use the `SelectedItems` parameter (`IEnumerable<T>`) to access the selected rows. |
| 47 | +* Use the `SelectedCells` parameter (`IEnumerable<GridSelectedCellDescriptor>`) to access the selected cells. |
135 | 48 |
|
| 49 | +Both parameters support two-way binding. You can also use the parameters to pre-select rows or cells for your users. |
136 | 50 |
|
137 | | -## Notes |
| 51 | +See [Selected Rows]({%slug grid-selection-row%}#selected-rows) and [Selected Cells]({%slug grid-selection-cell%}#selected-cells) for more details. |
138 | 52 |
|
139 | | -### Editing Modes |
| 53 | +## Events |
140 | 54 |
|
141 | | -#### InCell Edit Mode |
| 55 | +You can respond to the user action of selecting a new item through the Grid events: |
142 | 56 |
|
143 | | -In the [Incell EditMode]({%slug components/grid/editing/incell%}) selection can be applied only via a [checkbox column]({%slug components/grid/columns/checkbox%}) (`<GridCheckboxColumn />`). This is required due to the overlapping action that triggers selection and InCell editing (clicking in the row) - if row click selection was enabled with InCell editing, each attempt to select a row would put a cell in edit mode; and each attempt to edit a cell would select a new row. Such user experience is confusing, and so selection will only work through the row selection checkbox. |
| 57 | +* Use the [`SelectedItemsChanged` event]({%slug grid-selection-row%}#selecteditemschanged) to respond to row selection. |
| 58 | +* Use the [`SelectedCellsChanged` event]({%slug grid-selection-cell%}#selectedcellschanged) to respond to cell selection. |
144 | 59 |
|
145 | | -To see how to select the row that is being edited in InCell edit mode without using a `<GridCheckboxColumn />` check out the [Row Selection in Edit with InCell EditMode]({%slug grid-kb-row-select-incell-edit%}) Knowledge Base article. |
| 60 | +## Integration with Other Grid Features |
146 | 61 |
|
147 | | -#### Inline and Popup Edit Modes |
148 | | - |
149 | | -In [Inline EditMode]({%slug components/grid/editing/inline%}) and [Popup EditMode]({%slug components/grid/editing/popup%}) selection can be done by clicking on the desired row or by using a `<GridCheckboxColumn />`. |
150 | | - |
151 | | -### Selection in Template |
152 | | - |
153 | | -When using the [Grid column Template]({%slug grid-templates-column%}) and you want to stop the Selection from being triggered when the user clicks in it, you should add the `@onclick:stopPropagation` directive to the element. |
154 | | - |
155 | | ->caption Prevent row selection from happening when the user clicks inside a template |
156 | | -
|
157 | | -````CSHTML |
158 | | -<GridColumn Field=@nameof(Product.ProductId) Title="Id"> |
159 | | - <Template> |
160 | | - <span @onclick:stopPropagation> |
161 | | - <TelerikNumericTextBox Value="@((context as Product).ProductId)"></TelerikNumericTextBox> |
162 | | - </span> |
163 | | - </Template> |
164 | | -</GridColumn> |
165 | | -```` |
166 | | - |
167 | | -If you are using the [Row Template]({%slug components/grid/features/templates%}#row-template), the grid cannot render selection checkboxes for you, so you have to bind them yourself to a field in the model, and handle their selection changed event to populate the `SelectedItems` collection of the grid. You can find an example to get started in the following thread: [Grid Row Template with Selection - Unsure how to Bind to Selected Item](https://feedback.telerik.com/blazor/1463819-grid-row-template-with-selection-unsure-how-to-bind-to-selected-item) |
168 | | - |
169 | | -### Asynchronous Operations |
170 | | - |
171 | | -Asynchronous operations such as loading data on demand should be handled in the [`OnRowClick`]({%slug grid-events%}#onrowclick) or [`OnRowDoubleClick`]({%slug grid-events%}#onrowdoubleclick) events rather than in the [`SelectedItemsChanged`]({%slug grid-events%}#selecteditemschanged). |
172 | | - |
173 | | -### SelectedItems Equals Comparison |
174 | | - |
175 | | -The `SelectedItems` collection is compared against the Grid `Data` collection in order to determine which rows will be highlighted. The default behavior of the framework is to compare objects by their reference. |
176 | | - |
177 | | -When the `SelectedItems` are obtained from a different data source to the Grid (e.g., from a separate service method and not from the view-model), the references may not match and so there will be no highlighted items. In such cases, you have to [override the `Equals` method of the underlying model class]({%slug grid-state%}#equals-comparison) so that it matches them, for example, by a unique identifier rather than by reference so that two objects can be equal regardless of their origin, but according to their contents. When you are overriding the `Equals` method, it is also recommended to override the [`GetHashCode`](https://docs.microsoft.com/en-us/dotnet/api/system.object.gethashcode) method as well. |
178 | | - |
179 | | -### Handle Data Changes |
180 | | - |
181 | | -When the grid `Data` collection changes, the `SelectedItems` collection has the following behavior: |
182 | | - |
183 | | -* If the Grid does *not* use an `ObservableCollection` for its `Data` - The `SelectedItems` collection will be preserved. You need to clear or manipulate it when the data is changed according to your needs and business logic. |
184 | | - |
185 | | - * If you update or delete an item, you must make the same update in the selected items through the grid [editing events]({%slug components/grid/editing/overview%}). |
186 | | - |
187 | | -* When using an `ObservableCollection` for the grid `Data`- If an item is removed or the entire data is cleared using the collection's `.Clear()` method, it will automatically update the `SelectedItems` collection too (the removed Data items will be removed from the Selected Items collection). |
188 | | - |
189 | | - * The other CRUD operations (Create and Update), you should use the grid [editing events]({%slug components/grid/editing/overview%}) to handle the situation according to your business logic and preferred behavior. |
190 | | - * When the data changes and the selected items are cleared, the `SelectedItemsChanged` event will fire with the empty collection. If you are using two-way binding, the collection will be cleared. |
191 | | - |
192 | | -### Selection in Grid with virtualized rows |
193 | | - |
194 | | -When the Grid has [virtualized rows]({%slug components/grid/virtual-scrolling%}) and the `SelectionMode` is set to [`Multiple`]({%slug components/grid/selection/multiple%}) the selectable items will be the one in the current set of items (page). If you select an item and scroll down to some of the ones that are not rendered yet (virtualization kicks in) and you want to select that range with the `Shift` button, the selection will start from the position of the first item of the current set (page) to the last selected item. |
195 | | - |
196 | | -### Row Drag and Drop |
197 | | - |
198 | | -If the user drags selected rows, the current row selection will be cleared on row drop. |
| 62 | +The selection feature behavior may differ when the Grid configuration includes row or cell selection and other Grid features. In these situations, certain limitations might arise, or additional adjustments may be required. |
199 | 63 |
|
| 64 | +See [Rows Selection and Other Grid Features]({%slug grid-selection-row%}#row-selection-and-other-grid-features) and [Cells Selection and Other Grid Features]({%slug grid-selection-cell%}#cell-selection-and-other-grid-features) for more details. |
200 | 65 |
|
201 | 66 | ## See Also |
202 | 67 |
|
203 | | - * [Live Demo: Grid Selection](https://demos.telerik.com/blazor-ui/grid/selection) |
204 | | - * [Single Selection]({%slug components/grid/selection/single%}) |
205 | | - * [Multiple Selection]({%slug components/grid/selection/multiple%}) |
| 68 | +* [Live Demo: Grid Row Selection](https://demos.telerik.com/blazor-ui/grid/row-selection) |
| 69 | +* [Live Demo: Grid Cell Selection](https://demos.telerik.com/blazor-ui/grid/cell-selection) |
0 commit comments