Skip to content

Commit 9653428

Browse files
dimodidimodi
authored
Grid and TreeList Checkbox column HeaderTemplate (#996)
* docs(grid): Add documentation for GridCheckboxColumn HeaderTemplate * docs(treelist): Add TreeList checkbox column HeaderTemplate
1 parent 162f498 commit 9653428

File tree

8 files changed

+369
-52
lines changed

8 files changed

+369
-52
lines changed

‎components/grid/columns/checkbox.md

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
title: Checkbox Column
3+
page_title: Grid - Checkbox Column
4+
description: Configuration options for the Telerik Blazor Grid Checkbox Column
5+
slug: components/grid/columns/checkbox
6+
tags: telerik,blazor,grid,column,selection
7+
published: True
8+
position: 2
9+
---
10+
11+
# Grid Checkbox Column
12+
13+
This article describes the configuration parameters of the Blazor `GridCheckboxColumn`.
14+
15+
The `GridCheckboxColumn` provides an additional way for users to [select Grid rows]({%slug components/grid/selection/overview%}). By default, users can select and unselect rows by clicking anywhere on them.
16+
17+
## Parameters
18+
19+
The Grid checkbox column has the following exclusive parameters. For other available parameters, see the [appearance settings of bound columns]({%slug components/grid/columns/bound%}#appearance).
20+
21+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
22+
23+
| Parameter | Type and Default Value | Description |
24+
| --- | --- | --- |
25+
| `CheckBoxOnlySelection` | `bool` | Determines if row selection occurs only on checkbox clicks. By default, user can select rows by clicking anywhere, except on command buttons. |
26+
| `SelectAll` | `bool` <br /> (`true`) | Determines if the column header renders a checkbox to select all rows. Set this to `false` if the [Grid `SelectionMode` is `Single`]({%slug components/grid/selection/single%}). The `SelectAll` parameter has no effect when the checkbox column has a [`HeaderTemplate`](#headertemplate). |
27+
| `SelectAllMode` | `GridSelectAllMode` enum <br /> (`Current`) | Determines if the header cell checkbox selects all rows on the current page, or all rows in the Grid. `Current` selects the visible rows on the current page. `All` selects all the data items, including ones that may be currently filtered out. `All` requires the [Grid to be data-bound via its `Data` parameter, and not `OnRead`]({%slug common-features-data-binding-overview%}#how-to-provide-data). When using `OnRead`, the two `SelectAllMode`s behave identically, because the Grid controls only one page of items. |
28+
29+
>note If the Grid is bound to `IQueriable`, a header checkbox with an `All` option will execute the query over all the data. This may be a performance hit.
30+
31+
## Header Template
32+
33+
The `HeaderTemplate` of the Grid checkbox column enables developers to customize the header cell's rendering and checkbox behavior.
34+
35+
On a side note, it is possible to [center the checkboxes in the `GridCheckboxColumn`]({%slug grid-kb-center-checkbox-column%}) without using a template.
36+
37+
>caption Grid Checkbox Column Header Template
38+
39+
````CSHTML
40+
<TelerikGrid @ref="@GridRef"
41+
Data="@GridData"
42+
SelectionMode="GridSelectionMode.Multiple"
43+
@bind-SelectedItems="SelectedItems">
44+
<GridColumns>
45+
<GridCheckboxColumn Width="140px" HeaderClass="header-select-all">
46+
<HeaderTemplate>
47+
@{
48+
<TelerikCheckBox @bind-Value="@SelectAllCheckBoxValue"
49+
Enabled="@SelectAllEnabled"
50+
TabIndex="-1"
51+
Indeterminate="@(SelectAllCheckBoxValue == null)" />
52+
53+
<TelerikButton OnClick="@ToggleSelectAll">
54+
@(SelectAllCheckBoxValue.HasValue && SelectAllCheckBoxValue.Value ? "Deselect All" : "Select All")
55+
</TelerikButton>
56+
}
57+
</HeaderTemplate>
58+
</GridCheckboxColumn>
59+
<GridColumn Field="@(nameof(Product.Name))" Title="Product Name" />
60+
</GridColumns>
61+
</TelerikGrid>
62+
63+
<style>
64+
.k-grid .header-select-all .k-checkbox {
65+
vertical-align: middle;
66+
}
67+
68+
.k-grid .header-select-all,
69+
.k-grid td:first-child {
70+
text-align: center;
71+
}
72+
</style>
73+
74+
@code {
75+
List<Product> GridData { get; set; }
76+
TelerikGrid<Product> GridRef { get; set; }
77+
IEnumerable<Product> SelectedItems { get; set; } = Enumerable.Empty<Product>();
78+
bool SelectAllEnabled { get; set; }
79+
80+
void ToggleSelectAll()
81+
{
82+
if (SelectAllCheckBoxValue.HasValue && SelectAllCheckBoxValue.Value)
83+
{
84+
SelectAllCheckBoxValue = false;
85+
}
86+
else
87+
{
88+
SelectAllCheckBoxValue = true;
89+
}
90+
}
91+
92+
bool? SelectAllCheckBoxValue
93+
{
94+
get
95+
{
96+
if (IsAllDataSelected())
97+
{
98+
return true;
99+
}
100+
else if (IsAnyDataSelected())
101+
{
102+
return null;
103+
}
104+
105+
return false;
106+
}
107+
108+
set
109+
{
110+
if (value.HasValue && value.Value == true)
111+
{
112+
SelectedItems = GridRef.Data;
113+
}
114+
else
115+
{
116+
SelectedItems = new List<Product>();
117+
}
118+
}
119+
}
120+
121+
bool IsAnyDataSelected()
122+
{
123+
return GridRef.SelectedItems.Count() > 0 && GridRef.SelectedItems.Count() < GridRef.Data.Count();
124+
}
125+
126+
bool IsAllDataSelected()
127+
{
128+
return GridRef.SelectedItems.Count() == GridRef.Data.Count();
129+
}
130+
131+
bool GridHasData()
132+
{
133+
return GridRef.Data.Count() > 0;
134+
}
135+
136+
protected override void OnInitialized()
137+
{
138+
GridData = Enumerable.Range(1, 5).Select(x => new Product
139+
{
140+
Id = x,
141+
Name = "Product name " + x
142+
}).ToList();
143+
144+
// OR use an empty collection to test the behavior with no data
145+
//GridData = new List<Product>();
146+
147+
base.OnInitialized();
148+
}
149+
150+
protected override void OnAfterRender(bool firstRender)
151+
{
152+
if (firstRender)
153+
{
154+
var gridHasData = GridHasData();
155+
156+
if (SelectAllEnabled != gridHasData)
157+
{
158+
SelectAllEnabled = gridHasData;
159+
StateHasChanged();
160+
}
161+
}
162+
}
163+
164+
public class Product
165+
{
166+
public int Id { get; set; }
167+
public string Name { get; set; }
168+
public decimal Price { get; set; }
169+
public DateTime Released { get; set; }
170+
public bool Discontinued { get; set; }
171+
}
172+
}
173+
````
174+
175+
## See Also
176+
177+
* [Live Demo: Grid Selection](https://demos.telerik.com/blazor-ui/grid/selection)
178+
* [Grid Selection Overview]({%slug components/grid/selection/overview%})

‎components/grid/selection/multiple.md

Lines changed: 1 addition & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -38,23 +38,7 @@ In Multiple SelectionMode, you can select rows through the following approaches:
3838
3939
## Checkbox Selection
4040

41-
To add checkboxes in each row, add a `GridCheckboxColumn` in the `GridColumns` collection of the grid. The user can select the desired rows through the checkboxes.
42-
43-
You can force selection to happen only through the checkboxes by setting the `CheckBoxOnlySelection` parameter of the `GridCheckboxColumn` to `true`.
44-
45-
The Grid allows selection and deselection via the `SelectAll` property. Setting this property to `true` (its default value) will render a checkbox in the grid header.
46-
47-
You can add a `SelectAllMode` parameter, which supports the following options:
48-
* `Current` - selects all rows on the current page. This also applies to filtered, sorted, etc. This is the default value of the `SelectAllMode`. If the filtered/sorted rows exceed the page size, the `Current` mode will select only the filtered/sorted rows on the current page.
49-
* `All` - selects all the data in the Grid.
50-
>note If IQueriable collections are used, using the header checkbox with an `All` option will immediately execute the query over all the data. This may be a performance hit.
51-
52-
`SelectAllMode` behavior with [Virtual Scrolling]({%slug components/grid/virtual-scrolling%}):
53-
* No `OnRead` configured (the default state):
54-
* `Current` - current `PageSize` items will be selected
55-
* `All` - all items in the Data will be selected
56-
* `OnRead` configured:
57-
* `Current` and `All` will share the same behavior - the current data set (page) will be selected only, as this is the only available data.
41+
To add row selection checkboxes in each row, add a [`GridCheckboxColumn`]({%slug components/grid/columns/checkbox%}) in the `GridColumns` collection of the grid. The user can select the desired rows through the checkboxes. The column provides [additional configuration settings related to selection]({%slug components/grid/columns/checkbox%}#parameters).
5842

5943
**Usage:**
6044

‎components/grid/selection/overview.md

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,11 +37,7 @@ You can configure the selection behavior by setting `SelectionMode` to a member
3737

3838
To select a row, click on it. To select multiple rows, hold down the `Ctrl` or `Shift` key to extend the selection.
3939

40-
You can also use a checkbox column to select rows. To use it, add a `GridCheckboxColumn` 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-
By default, clicking anywhere on the row will select it, but you can require the user to activate the checkbox in the select column to select the row by setting its `CheckBoxOnlySelection` parameter to `true`.
43-
44-
It is also possible to [center the checkboxes in the `GridCheckboxColumn`]({%slug grid-kb-center-checkbox-column%}).
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).
4541

4642
You can get or set the selected items through the `SelectedItems` property. It is a collection of items from the Grid's `Data`.
4743

@@ -144,7 +140,7 @@ See how the row selection modes work
144140

145141
#### InCell Edit Mode
146142

147-
In the [Incell EditMode]({%slug components/grid/editing/incell%}) selection can be applied only via a checkbox column (`<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.
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.
148144

149145
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.
150146

‎components/grid/selection/single.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,10 @@ To un-select the item, click its checkbox again, or hold the `Ctrl` key and clic
3434
3535
## Checkbox Selection
3636

37-
In Single SelectionMode, selection is applied with a click on a row, or by clicking a checkbox if the `GridCheckboxColumn` is present in the `GridColumns` collection of the grid.
37+
In `Single` `SelectionMode`, selection is applied with a click on a row, or by clicking a checkbox in the [`GridCheckboxColumn`]({%slug components/grid/columns/checkbox%}).
3838

3939
Only one row can be selected at a time, even with checkboxes enabled, so the last one that is clicked will be selected.
4040

41-
You can force selection to happen only through the checkboxes by setting the `CheckBoxOnlySelection` parameter of the `GridCheckboxColumn` to `true`.
42-
4341
If you add a checkbox column, you should set its `SelectAll` parameter to `false` to disable the header checkbox that will select all rows.
4442

4543
## Selected Items

0 commit comments

Comments
 (0)