|
| 1 | +--- |
| 2 | +title: CheckBoxList |
| 3 | +page_title: Grid - Filtering CheckBoxList |
| 4 | +description: Enable and configure filtering CheckBoxList in Grid for Blazor. |
| 5 | +slug: grid-checklist-filter |
| 6 | +tags: telerik,blazor,grid,filtering,filter,CheckBoxList |
| 7 | +published: True |
| 8 | +position: 15 |
| 9 | +--- |
| 10 | + |
| 11 | +# Grid CheckBoxList Filtering |
| 12 | + |
| 13 | +You can change the [filter menu]({%slug grid-filter-menu%}) to show a list of checkboxes with the distinct values from the data source. This lets your users filter records by a commonly found value quickly, and select multiple values with ease. The behavior is similar to Excel filtering. |
| 14 | + |
| 15 | +To enable the checkbox list filtering in the grid: |
| 16 | + |
| 17 | +1. Set the `FilterMode` parameter of the grid to `Telerik.Blazor.GridFilterMode.FilterMenu` |
| 18 | +1. Set the `FilterMenuType` parameter of the grid to `Telerik.Blazor.FilterMenuType.CheckBoxList`. It defaults to `Menu` for the default behavior. |
| 19 | + |
| 20 | +You can also change the filter menu behavior for a particular column - its own `FilterMenuType` parameter can be either `Menu` or `CheckBoxList` regardless of the main grid parameter. This lets you mix both modes as necessary for your application - you can either have all grid columns use the same mode with a single setting, or override it for a few columns that need the less common mode. |
| 21 | + |
| 22 | +>caption CheckList filter in the grid |
| 23 | +
|
| 24 | +````CSHTML |
| 25 | +@* Checkbox List Filter for the Name, Team and Vacation columns, the ID column overrides it to Menu *@ |
| 26 | +
|
| 27 | +<TelerikGrid Data=@GridData Pageable="true" Height="400px" |
| 28 | + FilterMode="@GridFilterMode.FilterMenu" FilterMenuType="@FilterMenuType.CheckBoxList"> |
| 29 | + <GridColumns> |
| 30 | + <GridColumn Field="@(nameof(Employee.EmployeeId))" FilterMenuType="@FilterMenuType.Menu" /> |
| 31 | + <GridColumn Field=@nameof(Employee.Name) /> |
| 32 | + <GridColumn Field=@nameof(Employee.Team) Title="Team" /> |
| 33 | + <GridColumn Field=@nameof(Employee.IsOnLeave) Title="On Vacation" /> |
| 34 | + </GridColumns> |
| 35 | +</TelerikGrid> |
| 36 | +
|
| 37 | +@code { |
| 38 | + public List<Employee> GridData { get; set; } |
| 39 | +
|
| 40 | + protected override void OnInitialized() |
| 41 | + { |
| 42 | + GridData = new List<Employee>(); |
| 43 | + var rand = new Random(); |
| 44 | + for (int i = 0; i < 15; i++) |
| 45 | + { |
| 46 | + GridData.Add(new Employee() |
| 47 | + { |
| 48 | + EmployeeId = i, |
| 49 | + Name = "Employee " + i.ToString(), |
| 50 | + Team = "Team " + i % 3, |
| 51 | + IsOnLeave = i % 2 == 0 |
| 52 | + }); |
| 53 | + } |
| 54 | + } |
| 55 | +
|
| 56 | + public class Employee |
| 57 | + { |
| 58 | + public int EmployeeId { get; set; } |
| 59 | + public string Name { get; set; } |
| 60 | + public string Team { get; set; } |
| 61 | + public bool IsOnLeave { get; set; } |
| 62 | + } |
| 63 | +} |
| 64 | +```` |
| 65 | + |
| 66 | +>caption The result from the snippet above |
| 67 | +
|
| 68 | + |
| 69 | + |
| 70 | + |
| 71 | +## Custom Data |
| 72 | + |
| 73 | +By default, the grid takes the `Distinct` values from its `Data` to populate the chekcbox list filter for each field. |
| 74 | + |
| 75 | +When using the [`OnRead` event]({%slug components/grid/manual-operations%}) to customize the data operations and/or perform them on the server/service, the grid will only have the current page of data. This will limit the options the user will see so you may want to provide the full list. |
| 76 | + |
| 77 | +To customize the checkbox list behavior, you should use the [filter menu template]({%slug grid-templates-filter%}#filter-menu-template). To help you with that, we have exposed the `TelerikCheckBoxListFilter` component that you can place inside the `FilterMenuTemplate` to get the default grid UI. It provides the following settings: |
| 78 | + |
| 79 | +* `FilterDescriptor` - the filter descriptor where filters will be populated when checkboxes are selected. The component creates the necessary descriptors for you and reads existing ones. This makes it easy to plug into the grid without any additional code through two-way binding (`@bind-FilterDescriptor="@context.FilterDescriptor"`).. |
| 80 | + |
| 81 | +* `Data` - the data that will be rendered in the checkbox list. This is where you can supply the desired options to change what the grid displays. |
| 82 | + |
| 83 | +* `Field` - the field from the data that will be used to take the `Distinct` options. It must match the name and type of the column field for which this filter is defined. This lets you use the same models that the grid uses, or to define smaller models to reduce the data you fetch for the filter lists. |
| 84 | + |
| 85 | +>caption Provide all filtering options when using OnRead |
| 86 | +
|
| 87 | +````CSHTML |
| 88 | +@using Telerik.DataSource |
| 89 | +@using Telerik.DataSource.Extensions |
| 90 | +
|
| 91 | +Filter by selecting a few names. Then filter by the Teams field (the fields that use application-provided data).<br /> |
| 92 | +You will see you have all the options for the teams and all the options for the names.<br /> |
| 93 | +Now try to filter by the On Vacation column - it will use only the current grid data and you may have only a single option, |
| 94 | +depending on how you filter the data so you may never be able to get back all values. |
| 95 | +
|
| 96 | +
|
| 97 | +<TelerikGrid Data=@CurrentGridData Pageable="true" Height="400px" |
| 98 | + TotalCount="Total" OnRead="@OnReadHandler" |
| 99 | + FilterMode="@GridFilterMode.FilterMenu" FilterMenuType="@FilterMenuType.CheckBoxList"> |
| 100 | + <GridColumns> |
| 101 | + <GridColumn Field="@(nameof(Employee.EmployeeId))" Filterable="false" /> |
| 102 | + <GridColumn Field="@nameof(Employee.Name)"> |
| 103 | + <FilterMenuTemplate Context="context"> |
| 104 | + <TelerikCheckBoxListFilter Data="@NameOptions" |
| 105 | + Field="@(nameof(NameFilterOption.Name))" |
| 106 | + @bind-FilterDescriptor="@context.FilterDescriptor"> |
| 107 | + </TelerikCheckBoxListFilter> |
| 108 | + </FilterMenuTemplate> |
| 109 | + </GridColumn> |
| 110 | + <GridColumn Field="@nameof(Employee.Team)" Title="Team"> |
| 111 | + <FilterMenuTemplate Context="context"> |
| 112 | + <TelerikCheckBoxListFilter Data="@TeamsList" |
| 113 | + Field="@(nameof(TeamNameFilterOption.Team))" |
| 114 | + @bind-FilterDescriptor="@context.FilterDescriptor"> |
| 115 | + </TelerikCheckBoxListFilter> |
| 116 | + </FilterMenuTemplate> |
| 117 | + </GridColumn> |
| 118 | + <GridColumn Field="@nameof(Employee.IsOnLeave)" Title="On Vacation" /> |
| 119 | + </GridColumns> |
| 120 | +</TelerikGrid> |
| 121 | +
|
| 122 | +@code { |
| 123 | + List<Employee> AllGridData { get; set; } |
| 124 | +
|
| 125 | + IEnumerable<Employee> CurrentGridData { get; set; } |
| 126 | + int Total { get; set; } |
| 127 | +
|
| 128 | + #region custom-filter-data |
| 129 | + List<TeamNameFilterOption> TeamsList { get; set; } |
| 130 | + List<NameFilterOption> NameOptions { get; set; } |
| 131 | +
|
| 132 | + //obtain filter lists data from the data source to show all options |
| 133 | + async Task GetTeamOptions() |
| 134 | + { |
| 135 | + if (TeamsList == null) // sample of caching since we always want all distinct options, |
| 136 | + //but we don't want to make unnecessary requests |
| 137 | + { |
| 138 | + TeamsList = await GetNamesFromService(); |
| 139 | + } |
| 140 | + } |
| 141 | +
|
| 142 | + async Task<List<TeamNameFilterOption>> GetNamesFromService() |
| 143 | + { |
| 144 | + await Task.Delay(500);// simulate a real service delay |
| 145 | +
|
| 146 | + // this is just one example of getting distinct values from the full data source |
| 147 | + // in a real case you'd probably call your data service here instead |
| 148 | + // or apply further logic (such as tie the returned data to the data the grid will have according to your business logic) |
| 149 | + List<TeamNameFilterOption> data = AllGridData.OrderBy(z => z.Team).Select(z => z.Team). |
| 150 | + Distinct().Select(t => new TeamNameFilterOption { Team = t }).ToList(); |
| 151 | +
|
| 152 | + return await Task.FromResult(data); |
| 153 | + } |
| 154 | +
|
| 155 | + async Task GetNameOptions() |
| 156 | + { |
| 157 | + if (NameOptions == null) |
| 158 | + { |
| 159 | + NameOptions = await GetNameOptionsFromService(); |
| 160 | + } |
| 161 | + } |
| 162 | +
|
| 163 | + async Task<List<NameFilterOption>> GetNameOptionsFromService() |
| 164 | + { |
| 165 | + await Task.Delay(500);// simulate a real service delay |
| 166 | +
|
| 167 | + List<NameFilterOption> data = AllGridData.OrderBy(z => z.Name).Select(z => z.Name). |
| 168 | + Distinct().Select(n => new NameFilterOption { Name = n }).ToList(); |
| 169 | +
|
| 170 | + return await Task.FromResult(data); |
| 171 | + } |
| 172 | + #endregion custom-filter-data |
| 173 | +
|
| 174 | + async Task OnReadHandler(GridReadEventArgs e) |
| 175 | + { |
| 176 | + //typical data retrieval for the grid |
| 177 | + var filteredData = await AllGridData.ToDataSourceResultAsync(e.Request); |
| 178 | + CurrentGridData = filteredData.Data as IEnumerable<Employee>; |
| 179 | + Total = filteredData.Total; |
| 180 | + } |
| 181 | +
|
| 182 | + protected override async Task OnInitializedAsync() |
| 183 | + { |
| 184 | + // generate data that simulates the database for this example |
| 185 | + // the actual grid data is retrieve in its OnRead handler |
| 186 | + AllGridData = new List<Employee>(); |
| 187 | + var rand = new Random(); |
| 188 | + for (int i = 0; i < 15; i++) |
| 189 | + { |
| 190 | + AllGridData.Add(new Employee() |
| 191 | + { |
| 192 | + EmployeeId = i, |
| 193 | + Name = "Employee " + i.ToString(), |
| 194 | + Team = "Team " + i % 3, |
| 195 | + IsOnLeave = i % 2 == 0 |
| 196 | + }); |
| 197 | + } |
| 198 | +
|
| 199 | + // get custom filters data. In a future version you will be able to call these methods |
| 200 | + // from the template initialization instead of here (or in OnRead) so that they fetch data |
| 201 | + // only when the user actually needs filter values, instead of always - that could improve server performance |
| 202 | + await GetTeamOptions(); |
| 203 | + await GetNameOptions(); |
| 204 | + } |
| 205 | +
|
| 206 | + public class Employee |
| 207 | + { |
| 208 | + public int EmployeeId { get; set; } |
| 209 | + public string Name { get; set; } |
| 210 | + public string Team { get; set; } |
| 211 | + public bool IsOnLeave { get; set; } |
| 212 | + } |
| 213 | +
|
| 214 | + // in this sample we use simplified models to fetch less data from the service |
| 215 | + // instead of using the full Employee model that has many fields we do not need for the filters |
| 216 | +
|
| 217 | + public class TeamNameFilterOption |
| 218 | + { |
| 219 | + public string Team { get; set; } |
| 220 | + } |
| 221 | +
|
| 222 | + public class NameFilterOption |
| 223 | + { |
| 224 | + public string Name { get; set; } |
| 225 | + } |
| 226 | +} |
| 227 | +```` |
| 228 | + |
| 229 | + |
| 230 | + |
| 231 | +## See Also |
| 232 | + |
| 233 | + * [Grid Filtering Overview]({%slug components/grid/filtering%}) |
| 234 | + * [Live Demo: Grid CheckBox List Filter](https://demos.telerik.com/blazor-ui/grid/filter-checkboxlist) |
| 235 | + |
0 commit comments