Skip to content

Commit d225226

Browse files
marin-bratanovmarin-bratanov
authored
Grid treelist searchbox (#128)
* docs(grid): search box * docs(treelist): search box * docs(grid,treelist): update searchbox behavior with filtering
1 parent 363e183 commit d225226

File tree

4 files changed

+328
-0
lines changed

4 files changed

+328
-0
lines changed

‎components/grid/filtering.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ In this article:
1717
* [Basics](#basics)
1818
* [Filter Row](#filter-row)
1919
* [Filter Menu](#filter-menu)
20+
* [Toolbar Search Box](#toolbar-search-box)
2021
* [Filter From Code](#filter-from-code)
2122
* [More Examples](#more-examples)
2223

@@ -152,6 +153,124 @@ A key difference in the behavior from the [filter row](#filter-row) is that the
152153
![](images/filter-menu-1.png)
153154

154155

156+
157+
## Toolbar Search Box
158+
159+
You can add a search box in the grid toolbar that lets the user type their query and the grid will look up all visible string columns with a case-insensitive `Contains` operator, and filter them accordingly. You can change the filter delay, and the fields the grid will use - see the [Customize the SearchBox](#customize-the-searchbox) section below.
160+
161+
The search box is independent from the standard filters. If you have filters applied, the searchbox will amend and respect them. Thus, you can also apply filtering to results returned from the search box.
162+
163+
To enable the search box, add the `<GridSearchBox>` tag in the `<GridToolBar>`.
164+
165+
>caption Search box in the Telerik grid
166+
167+
````CSHTML
168+
@* A search panel in the grid toolbar *@
169+
170+
<TelerikGrid Data=@GridData Pageable="true" Height="400px">
171+
<GridToolBar>
172+
<GridSearchBox />
173+
</GridToolBar>
174+
<GridColumns>
175+
<GridColumn Field="@(nameof(Employee.EmployeeId))" />
176+
<GridColumn Field=@nameof(Employee.Name) />
177+
<GridColumn Field=@nameof(Employee.Team) Title="Team" />
178+
<GridColumn Field=@nameof(Employee.IsOnLeave) Title="On Vacation" />
179+
</GridColumns>
180+
</TelerikGrid>
181+
182+
@code {
183+
public List<Employee> GridData { get; set; }
184+
185+
protected override void OnInitialized()
186+
{
187+
GridData = new List<Employee>();
188+
var rand = new Random();
189+
for (int i = 0; i < 15; i++)
190+
{
191+
GridData.Add(new Employee()
192+
{
193+
EmployeeId = i,
194+
Name = "Employee " + i.ToString(),
195+
Team = "Team " + i % 3,
196+
IsOnLeave = i % 2 == 0
197+
});
198+
}
199+
}
200+
201+
public class Employee
202+
{
203+
public int EmployeeId { get; set; }
204+
public string Name { get; set; }
205+
public string Team { get; set; }
206+
public bool IsOnLeave { get; set; }
207+
}
208+
}
209+
````
210+
211+
>caption The result from the code snippet above
212+
213+
![grid search box](images/search-box-overview.gif)
214+
215+
### Customize the SearchBox
216+
217+
The `GridSearchBox` component offers the following settings to customize its behavior:
218+
219+
* `DebounceDelay` - the time in `ms` with which the typing is debounced. This provides a performance optimization when using the `OnRead` event - filtering does not happen on every keystroke anymore. The default value is `300`.
220+
221+
* `Fields` - a list of `string` that denotes the fields names that the gris should search in. By default, the grid looks in all string fields in its currently visible columns, and you can define a subset of that.
222+
223+
* `Class` - a CSS class rendered on the wrapper of the searchbox so you can customize its appearance.
224+
225+
>caption Customize the search box to have a long filter delay and to only use certain fields
226+
227+
````CSHTML
228+
@* Increased delay and a subset of the columns are allowed for filtering *@
229+
230+
<TelerikGrid Data=@GridData Pageable="true" Height="400px">
231+
<GridToolBar>
232+
<GridSearchBox DebounceDelay="1000" Fields="@SearchableFields" />
233+
</GridToolBar>
234+
<GridColumns>
235+
<GridColumn Field="@(nameof(Employee.EmployeeId))" />
236+
<GridColumn Field=@nameof(Employee.Name) />
237+
<GridColumn Field=@nameof(Employee.Team) Title="Team" />
238+
<GridColumn Field=@nameof(Employee.IsOnLeave) Title="On Vacation" />
239+
</GridColumns>
240+
</TelerikGrid>
241+
242+
@code {
243+
List<string> SearchableFields = new List<string> { "Team" };
244+
245+
List<Employee> GridData { get; set; }
246+
247+
protected override void OnInitialized()
248+
{
249+
GridData = new List<Employee>();
250+
var rand = new Random();
251+
for (int i = 0; i < 15; i++)
252+
{
253+
GridData.Add(new Employee()
254+
{
255+
EmployeeId = i,
256+
Name = "Employee " + i.ToString(),
257+
Team = "Team " + i % 3,
258+
IsOnLeave = i % 2 == 0
259+
});
260+
}
261+
}
262+
263+
public class Employee
264+
{
265+
public int EmployeeId { get; set; }
266+
public string Name { get; set; }
267+
public string Team { get; set; }
268+
public bool IsOnLeave { get; set; }
269+
}
270+
}
271+
````
272+
273+
155274
## Filter From Code
156275

157276
You can set the grid filters from your code through the grid [state]({%slug grid-state%}).

‎components/grid/images/search-box-overview.gif

84.8 KB
Loading

‎components/treelist/filtering.md

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ In this article:
1717
* [Basics](#basics)
1818
* [Filter Row](#filter-row)
1919
* [Filter Menu](#filter-menu)
20+
* [Toolbar Search Box](#toolbar-search-box)
2021

2122

2223
## Basics
@@ -202,6 +203,214 @@ A key difference in the behavior from the [filter row](#filter-row) is that the
202203
203204
![](images/filter-menu.png)
204205

206+
207+
## Toolbar Search Box
208+
209+
You can add a search box in the treelist toolbar that lets the user type their query and the treelist will look up all visible string columns with a case-insensitive `Contains` operator, and filter them accordingly. You can change the filter delay, and the fields the treelist will use - see the [Customize the SearchBox](#customize-the-searchbox) section below.
210+
211+
The search box is independent from the standard filters. If you have filters applied, the searchbox will amend and respect them. Thus, you can also apply filtering to results returned from the search box.
212+
213+
To enable the search box, add the `<TreeListSearchBox>` tag in the `<TreeListToolBar>`.
214+
215+
>caption Search box in the Telerik treelist
216+
217+
````CSHTML
218+
@* A search panel in the treelist toolbar *@
219+
220+
<TelerikTreeList Data="@Data"
221+
ItemsField="@(nameof(Employee.DirectReports))"
222+
Pageable="true">
223+
<TreeListToolBar>
224+
<TreeListSearchBox />
225+
</TreeListToolBar>
226+
<TreeListColumns>
227+
<TreeListColumn Field="Name" Expandable="true" Width="320px" />
228+
<TreeListColumn Field="Id" Editable="false" Width="120px" />
229+
<TreeListColumn Field="EmailAddress" Width="220px" />
230+
</TreeListColumns>
231+
</TelerikTreeList>
232+
233+
@code {
234+
public List<Employee> Data { get; set; }
235+
236+
// sample model
237+
238+
public class Employee
239+
{
240+
// hierarchical data collections
241+
public List<Employee> DirectReports { get; set; }
242+
243+
// data fields for display
244+
public int Id { get; set; }
245+
public string Name { get; set; }
246+
public string EmailAddress { get; set; }
247+
}
248+
249+
// data generation
250+
251+
// used in this example for data generation and retrieval for CUD operations on the current view-model data
252+
public int LastId { get; set; } = 1;
253+
254+
protected override async Task OnInitializedAsync()
255+
{
256+
Data = await GetTreeListData();
257+
}
258+
259+
async Task<List<Employee>> GetTreeListData()
260+
{
261+
List<Employee> data = new List<Employee>();
262+
263+
for (int i = 1; i < 15; i++)
264+
{
265+
Employee root = new Employee
266+
{
267+
Id = LastId,
268+
Name = $"root: {i}",
269+
EmailAddress = $"{i}@example.com",
270+
DirectReports = new List<Employee>(),
271+
};
272+
data.Add(root);
273+
LastId++;
274+
275+
for (int j = 1; j < 4; j++)
276+
{
277+
int currId = LastId;
278+
Employee firstLevelChild = new Employee
279+
{
280+
Id = currId,
281+
Name = $"first level child {j} of {i}",
282+
EmailAddress = $"{currId}@example.com",
283+
DirectReports = new List<Employee>(),
284+
};
285+
root.DirectReports.Add(firstLevelChild);
286+
LastId++;
287+
288+
for (int k = 1; k < 3; k++)
289+
{
290+
int nestedId = LastId;
291+
firstLevelChild.DirectReports.Add(new Employee
292+
{
293+
Id = LastId,
294+
Name = $"second level child {k} of {j} and {i}",
295+
EmailAddress = $"{nestedId}@example.com",
296+
}); ;
297+
LastId++;
298+
}
299+
}
300+
}
301+
302+
return await Task.FromResult(data);
303+
}
304+
}
305+
````
306+
307+
>caption The result from the code snippet above
308+
309+
![treelist search box](images/search-box-overview.gif)
310+
311+
### Customize the SearchBox
312+
313+
The `TreeListSearchBox` component offers the following settings to customize its behavior:
314+
315+
* `DebounceDelay` - the time in `ms` with which the typing is debounced. Filtering does not happen on every keystroke and that can reduce the flicker for the end user. The default value is `300`.
316+
317+
* `Fields` - a list of `string` that denotes the fields names that the gris should search in. By default, the treelist looks in all string fields in its currently visible columns, and you can define a subset of that.
318+
319+
* `Class` - a CSS class rendered on the wrapper of the searchbox so you can customize its appearance.
320+
321+
>caption Customize the search box to have a long filter delay and to only use certain fields
322+
323+
````CSHTML
324+
<TelerikTreeList Data="@Data"
325+
ItemsField="@(nameof(Employee.DirectReports))"
326+
Pageable="true">
327+
<TreeListToolBar>
328+
<TreeListSearchBox DebounceDelay="1000" Fields="@SearchableFields"/>
329+
</TreeListToolBar>
330+
<TreeListColumns>
331+
<TreeListColumn Field="Name" Expandable="true" Width="320px" />
332+
<TreeListColumn Field="Id" Editable="false" Width="120px" />
333+
<TreeListColumn Field="EmailAddress" />
334+
</TreeListColumns>
335+
</TelerikTreeList>
336+
337+
@code {
338+
List<string> SearchableFields = new List<string> { "Name" };
339+
340+
List<Employee> Data { get; set; }
341+
342+
// sample model
343+
344+
public class Employee
345+
{
346+
// hierarchical data collections
347+
public List<Employee> DirectReports { get; set; }
348+
349+
// data fields for display
350+
public int Id { get; set; }
351+
public string Name { get; set; }
352+
public string EmailAddress { get; set; }
353+
}
354+
355+
// data generation
356+
357+
// used in this example for data generation and retrieval for CUD operations on the current view-model data
358+
public int LastId { get; set; } = 1;
359+
360+
protected override async Task OnInitializedAsync()
361+
{
362+
Data = await GetTreeListData();
363+
}
364+
365+
async Task<List<Employee>> GetTreeListData()
366+
{
367+
List<Employee> data = new List<Employee>();
368+
369+
for (int i = 1; i < 15; i++)
370+
{
371+
Employee root = new Employee
372+
{
373+
Id = LastId,
374+
Name = $"root: {i}",
375+
EmailAddress = $"{i}@example.com",
376+
DirectReports = new List<Employee>(),
377+
};
378+
data.Add(root);
379+
LastId++;
380+
381+
for (int j = 1; j < 4; j++)
382+
{
383+
int currId = LastId;
384+
Employee firstLevelChild = new Employee
385+
{
386+
Id = currId,
387+
Name = $"first level child {j} of {i}",
388+
EmailAddress = $"{currId}@example.com",
389+
DirectReports = new List<Employee>(),
390+
};
391+
root.DirectReports.Add(firstLevelChild);
392+
LastId++;
393+
394+
for (int k = 1; k < 3; k++)
395+
{
396+
int nestedId = LastId;
397+
firstLevelChild.DirectReports.Add(new Employee
398+
{
399+
Id = LastId,
400+
Name = $"second level child {k} of {j} and {i}",
401+
EmailAddress = $"{nestedId}@example.com",
402+
}); ;
403+
LastId++;
404+
}
405+
}
406+
}
407+
408+
return await Task.FromResult(data);
409+
}
410+
}
411+
````
412+
413+
205414
## See Also
206415

207416
* [Live Demo: TreeList Filter Row](https://demos.telerik.com/blazor-ui/treelist/filter-row)

‎components/treelist/images/search-box-overview.gif

78.4 KB
Loading

0 commit comments

Comments
 (0)