Skip to content

Commit c07744f

Browse files
xristianstefanovxristianstefanov
committed
docs(Grid): add typed tools toolbar articles
1 parent b5fa9c0 commit c07744f

File tree

2 files changed

+271
-423
lines changed

2 files changed

+271
-423
lines changed

‎components/grid/toolbar.md‎

Lines changed: 116 additions & 223 deletions
Original file line numberDiff line numberDiff line change
@@ -10,282 +10,175 @@ position: 45
1010

1111
# Grid Toolbar
1212

13-
The grid provides a toolbar where you can add a variety of actions that are not tied to a concrete row.
13+
The [Blazor Grid](https://demos.telerik.com/blazor-ui/grid/overview) toolbar can render built-in and custom tools. This article describes the built-in tools and shows how to add custom tools or customize the toolbar.
1414

15-
To use a toolbar, define the `GridToolBarTemplate` tag of the grid. In it, you can use arbitrary HTML and components to get the desired layout, and also `GridCommandButton` instances in (you can read more about the features available in those buttons in the [Command Column](slug://components/grid/columns/command) article).
15+
## Built-in Tools
1616

17-
>note The toolbar is not associated with an item from the data source. The `Item` field on the click event handler argument of a `GridCommandButton` will always be `null` and the `Edit`, `Update`, `Cancel` commands do not work with it.
17+
By default, the [Blazor Grid](https://demos.telerik.com/blazor-ui/grid/overview) displays all its built-in tools in the order below. Use the tool tag if you need to define a tool explicitly in a [custom toolbar configuration](#toolbar-configuration).
1818

19-
In this article, you will learn how to use:
19+
### Command Tools
2020

21-
* [Built-in Commands](#built-in-commands)
22-
* [Custom Commands](#custom-commands)
23-
* [Custom Layout](#custom-layout)
21+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
2422

23+
| Tool Name | Tool Tag | Description |
24+
| --- | --- | --- |
25+
| Add | `GridToolBarAddTool` | An add command that fires the [`OnAdd` event](slug://components/grid/editing/overview#events). |
26+
| CsvExport | `GridToolBarCsvExportTool` | An export command for CSV files that fires the [`OnBeforeExport` event](slug://grid-export-events#onbeforeexport). |
27+
| ExcelExport | `GridToolBarExcelExportTool` | An export command for Excel files that fires the [`OnBeforeExport` event](slug://grid-export-events#onbeforeexport). |
28+
| SearchBox | `GridToolBarSearchBoxTool` | A searchbox that filters multiple Grid columns simultaneously. |
2529

26-
## Built-in Commands
30+
### Layout Tools
2731

28-
The grid offers built-in commands that you can invoke through its toolbar. To use them, set the `Command` property of the button to the command name. The built-in command names are:
32+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
2933

30-
* `Add` - starts [inserting a new item in the grid](slug://components/grid/editing/overview).
34+
| Tool Name | Tool Tag | Description |
35+
| --- | --- | --- |
36+
| Spacer | `GridToolBarSpacerTool` | Consumes the available empty space and pushes the rest of the tools next to one another. |
3137

32-
* `ExcelExport` - starts an [Excel export of the grid data](slug://grid-export-excel).
38+
## Custom Tools
3339

34-
* `CsvExport` - starts an [CSV export of the grid data](slug://grid-export-csv).
40+
In addition to built-in tools, the Grid also supports custom tools. Use the `<GridToolBarCustomTool>` tag, which is a standard Blazor `RenderFragment`. See the example below.
3541

42+
## Toolbar Configuration
3643

37-
>caption How to insert a new item in the grid
44+
Add a `<GridToolBar>` tag inside `<TelerikGrid>` to configure a custom toolbar, for example:
3845

39-
````RAZOR
40-
@result
46+
* Arrange the Grid tools in a specific order;
47+
* Remove some of the built-in tools;
48+
* Add custom tools.
49+
50+
>caption Customize the Grid toolbar
4151
42-
<TelerikGrid Data=@MyData Pageable="true" PageSize="15" EditMode="@GridEditMode.Inline" Height="500px"
43-
OnUpdate="@UpdateHandler" OnCreate="@CreateHandler">
44-
<GridToolBarTemplate>
45-
<GridCommandButton Command="Add" Icon="@SvgIcon.Plus">Add Employee</GridCommandButton>
46-
</GridToolBarTemplate>
52+
````RAZOR
53+
<TelerikGrid Data=@GridData
54+
EditMode="@GridEditMode.Inline"
55+
Pageable="true"
56+
OnUpdate=@UpdateItem
57+
OnDelete=@DeleteItem
58+
OnCreate=@CreateItem>
59+
<GridToolBar>
60+
<GridToolBarCustomTool>
61+
<TelerikButton OnClick="@OnToolbarCustomClick">Custom Grid Tool</TelerikButton>
62+
</GridToolBarCustomTool>
63+
64+
<GridToolBarAddTool>
65+
Add a product
66+
</GridToolBarAddTool>
67+
68+
<GridToolBarCsvExportTool>
69+
Export to CSV
70+
</GridToolBarCsvExportTool>
71+
72+
<GridToolBarExcelExportTool>
73+
Export to Excel
74+
</GridToolBarExcelExportTool>
75+
76+
<GridToolBarSpacerTool />
77+
<GridToolBarSearchBoxTool />
78+
</GridToolBar>
4779
<GridColumns>
48-
<GridColumn Field=@nameof(SampleData.ID) Editable="false" Title="Employee ID" />
49-
<GridColumn Field=@nameof(SampleData.Name) Title="Employee Name" />
50-
<GridColumn Field=@nameof(SampleData.HireDate) Title="Hire Date" />
51-
<GridCommandColumn>
52-
<GridCommandButton Command="Edit" Icon="@SvgIcon.Pencil">Edit</GridCommandButton>
53-
<GridCommandButton Command="Save" Icon="@SvgIcon.Save" ShowInEdit="true">Save</GridCommandButton>
54-
<GridCommandButton Command="Cancel" Icon="@SvgIcon.Cancel" ShowInEdit="true">Cancel</GridCommandButton>
80+
<GridColumn Field=@nameof(Person.EmployeeId) Editable="false" Visible="true" Width="200px" />
81+
<GridColumn Field=@nameof(Person.Name) Width="200px" />
82+
<GridColumn Field=@nameof(Person.AgeInYears) Title="Age" Visible="false" Width="240px" />
83+
<GridColumn Field=@nameof(Person.MeetingDate) Title="Meeting Date" Width="220px" />
84+
<GridColumn Field=@nameof(Person.HireDate) Title="Hire Date" Width="230px" />
85+
<GridColumn Field=@nameof(Person.GraduateGrade) Title="Graduate Grade" Width="200px" />
86+
<GridCommandColumn Width="200px">
87+
<GridCommandButton Command="Delete" Icon="@SvgIcon.Trash"></GridCommandButton>
88+
<GridCommandButton Command="Edit" Icon="@SvgIcon.Pencil"></GridCommandButton>
89+
<GridCommandButton Command="Save" Icon="@SvgIcon.Save" ShowInEdit="true"></GridCommandButton>
5590
</GridCommandColumn>
5691
</GridColumns>
5792
</TelerikGrid>
5893
5994
@code {
60-
string result;
61-
public List<SampleData> MyData { get; set; }
95+
private List<Person> GridData { get; set; }
6296
63-
private async Task UpdateHandler(GridCommandEventArgs args)
97+
private void OnToolbarCustomClick()
6498
{
65-
SampleData item = args.Item as SampleData;
66-
67-
// perform actual data source operations here through your service
68-
SampleData updatedItem = await MyService.Update(item);
69-
70-
// update the local view-model data with the service data
71-
await GetGridData();
72-
73-
result = string.Format("Employee with ID {0} now has name {1} and hire date {2}", updatedItem.ID, updatedItem.Name, updatedItem.HireDate);
99+
Console.WriteLine("Custom Grid Toolbar tool clicked!");
74100
}
75101
76-
private async Task CreateHandler(GridCommandEventArgs args)
102+
protected override void OnInitialized()
77103
{
78-
SampleData item = args.Item as SampleData;
79-
80-
// perform actual data source operations here through your service
81-
SampleData insertedItem = await MyService.Create(item);
82-
83-
// update the local view-model data with the service data
84-
await GetGridData();
104+
var data = new List<Person>();
105+
var rand = new Random();
85106
86-
result = string.Format("On {2} you added the employee {0} who was hired on {1}.", insertedItem.Name, insertedItem.HireDate, DateTime.Now);
107+
for (int i = 0; i < 50; i++)
108+
{
109+
data.Add(new Person()
110+
{
111+
EmployeeId = i,
112+
Name = "Employee " + i.ToString(),
113+
HireDate = DateTime.Now.Date.AddDays(-(i * 2)),
114+
AgeInYears = 20,
115+
MeetingDate = DateTime.Now.Date.AddDays(i),
116+
GraduateGrade = (i % 5) + 2
117+
});
118+
}
119+
GridData = new List<Person>(data);
87120
}
88121
89-
//in a real case, keep the models in dedicated locations, this is just an easy to copy and see example
90-
public class SampleData
122+
private void CreateItem(GridCommandEventArgs args)
91123
{
92-
public int ID { get; set; }
93-
public string Name { get; set; }
94-
public DateTime HireDate { get; set; }
95-
}
124+
var argsItem = args.Item as Person;
96125
97-
async Task GetGridData()
98-
{
99-
MyData = await MyService.Read();
100-
}
126+
argsItem.EmployeeId = GridData.Count + 1;
101127
102-
protected override async Task OnInitializedAsync()
103-
{
104-
await GetGridData();
128+
GridData.Insert(0, argsItem);
105129
}
106130
107-
// the following static class mimics an actual data service that handles the actual data source
108-
// replace it with your actual service through the DI, this only mimics how the API can look like and works for this standalone page
109-
public static class MyService
131+
private void DeleteItem(GridCommandEventArgs args)
110132
{
111-
private static List<SampleData> _data { get; set; } = new List<SampleData>();
112-
113-
public static async Task<SampleData> Create(SampleData itemToInsert)
114-
{
115-
itemToInsert.ID = _data.Count + 1;
116-
_data.Insert(0, itemToInsert);
133+
var argsItem = args.Item as Person;
117134
118-
return await Task.FromResult(itemToInsert);
119-
}
135+
GridData.Remove(argsItem);
136+
}
120137
121-
public static async Task<List<SampleData>> Read()
122-
{
123-
if (_data.Count < 1)
124-
{
125-
for (int i = 1; i < 50; i++)
126-
{
127-
_data.Add(new SampleData()
128-
{
129-
ID = i,
130-
Name = "Name " + i.ToString(),
131-
HireDate = DateTime.Now.AddDays(-i)
132-
});
133-
}
134-
}
135-
136-
return await Task.FromResult(_data);
137-
}
138+
private void UpdateItem(GridCommandEventArgs args)
139+
{
140+
var argsItem = args.Item as Person;
141+
var itemForEdit = GridData.FirstOrDefault(i => i.EmployeeId == argsItem.EmployeeId);
138142
139-
public static async Task<SampleData> Update(SampleData itemToUpdate)
143+
if (itemForEdit != null)
140144
{
141-
var index = _data.FindIndex(i => i.ID == itemToUpdate.ID);
142-
if (index != -1)
143-
{
144-
_data[index] = itemToUpdate;
145-
return await Task.FromResult(_data[index]);
146-
}
147-
148-
throw new Exception("no item to update");
145+
itemForEdit.AgeInYears = argsItem.AgeInYears;
146+
itemForEdit.GraduateGrade = argsItem.GraduateGrade;
147+
itemForEdit.HireDate = argsItem.HireDate;
148+
itemForEdit.MeetingDate = argsItem.MeetingDate;
149+
itemForEdit.Name = argsItem.Name;
149150
}
150151
}
151-
}
152-
````
153152
154-
>caption The result from the code snippet above, after the built-in Create button in the toolbar was clicked
153+
public class Person
154+
{
155+
public int? EmployeeId { get; set; }
155156
156-
![Blazor Create Toolbar Button](images/create-toolbar-button.png)
157+
public string Name { get; set; }
157158
158-
## Custom Commands
159+
public int? AgeInYears { get; set; }
159160
160-
You can use the toolbar to add buttons that invoke actions specific to your application.
161+
public decimal? GraduateGrade { get; set; }
161162
162-
>caption How to define a custom command in the grid toolbar
163+
public DateTime HireDate { get; set; }
163164
164-
````RAZOR
165-
@result
166-
167-
<TelerikGrid Data=@MyData Pageable="true" PageSize="15">
168-
<GridToolBarTemplate>
169-
<GridCommandButton Command="MyToolbarCommand" OnClick="@MyCommandFromToolbar" Icon="@SvgIcon.InfoCircle">Fire My Command</GridCommandButton>
170-
</GridToolBarTemplate>
171-
<GridColumns>
172-
<GridColumn Field=@nameof(SampleData.Name) Title="Employee Name" />
173-
<GridColumn Field=@nameof(SampleData.HireDate) Title="Hire Date" />
174-
</GridColumns>
175-
</TelerikGrid>
165+
public DateTime MeetingDate { get; set; }
176166
177-
@code {
178-
string result;
179-
180-
private void MyCommandFromToolbar(GridCommandEventArgs args)
181-
{
182-
//note - the args.Item object is null because the command item is not associated with an item
183-
184-
result = "my custom toolbar command fired at " + DateTime.Now.ToString();
185-
186-
StateHasChanged();
187-
}
188-
189-
//in a real case, keep the models in dedicated locations, this is just an easy to copy and see example
190-
public class SampleData
191-
{
192-
public int ID { get; set; }
193-
public string Name { get; set; }
194-
public DateTime HireDate { get; set; }
195-
}
196-
197-
public IEnumerable<SampleData> MyData = Enumerable.Range(1, 50).Select(x => new SampleData
198-
{
199-
ID = x,
200-
Name = "name " + x,
201-
HireDate = DateTime.Now.AddDays(-x)
202-
});
167+
public Person()
168+
{
169+
GraduateGrade = 1;
170+
}
171+
}
203172
}
204173
````
205174

206-
>caption The result from the code snippet above, after the custom command button in the toolbar was clicked
207-
208-
![Blazor Custom Command Toolbar](images/custom-command-toolbar.png)
209-
210-
## Custom Layout
211-
212-
You can add your own HTML and components to create a more complex layout in the grid header to match your business needs. You can still use the grid command buttons, as well as other components and logic.
213-
214-
>caption Custom Grid Toolbar Layout
215-
216-
````RAZOR
217-
@result
218-
219-
<TelerikGrid Data=@MyData Pageable="true" PageSize="15" EditMode="@GridEditMode.Inline" Height="500px" OnCreate="@CreateHandler">
220-
221-
<GridToolBarTemplate>
222-
<div style="display: block; flex-grow: 1;">
223-
@* the first level children in the toolbar get display: inline-flex and flex-shrink: 0 inherited from the grid,
224-
we change it here to show we can, or you can work with the layout the grid defines if it suits your needs *@
225-
226-
<div style="background:yellow">
227-
<GridCommandButton Command="Add" Icon="@SvgIcon.Plus">Add Employee</GridCommandButton>
228-
</div>
229-
<div style="background: green;">
230-
<TelerikDropDownList Data="@( new List<string>() { "first", "second", "third" } )" TValue="string" TItem="string" ValueChanged="@( (string itm) => result = itm )"></TelerikDropDownList>
231-
</div>
232-
233-
<div style="border: 1px solid red;">
234-
@* one example of aligning content to the right with flex *@
235-
<button style="display: flex; margin-left: auto;"
236-
@onclick="@( () => result = $"Custom button click on {DateTime.Now}" )">
237-
Click me
238-
</button>
239-
</div>
240-
</div>
241-
</GridToolBarTemplate>
242-
243-
<GridColumns>
244-
<GridColumn Field=@nameof(SampleData.Name) Title="Employee Name" />
245-
<GridColumn Field=@nameof(SampleData.HireDate) Title="Hire Date" />
246-
<GridCommandColumn>
247-
<GridCommandButton Command="Edit" Icon="@SvgIcon.Pencil">Edit</GridCommandButton>
248-
<GridCommandButton Command="Save" Icon="@SvgIcon.Save" ShowInEdit="true">Save</GridCommandButton>
249-
<GridCommandButton Command="Cancel" Icon="@SvgIcon.Cancel" ShowInEdit="true">Cancel</GridCommandButton>
250-
</GridCommandColumn>
251-
</GridColumns>
252-
</TelerikGrid>
253-
254-
@code {
255-
string result;
256-
257-
private void CreateHandler(GridCommandEventArgs args)
258-
{
259-
SampleData newItem = args.Item as SampleData;
260-
MyData.Insert(0, newItem); // actual CRUD operations are not implemented, for brevity
261-
262-
result = string.Format("On {2} you added the employee {0} who was hired on {1}.", newItem.Name, newItem.HireDate, DateTime.Now);
263-
StateHasChanged();
264-
}
265175

266-
//in a real case, keep the models in dedicated locations, this is just an easy to copy and see example
267-
public class SampleData
268-
{
269-
public int ID { get; set; }
270-
public string Name { get; set; }
271-
public DateTime HireDate { get; set; }
272-
}
273-
274-
public List<SampleData> MyData = Enumerable.Range(1, 50).Select(
275-
x => new SampleData
276-
{
277-
ID = x,
278-
Name = "name " + x,
279-
HireDate = DateTime.Now.AddDays(-x)
280-
}).ToList();
281-
}
282-
````
176+
## Next Steps
283177

284-
>caption The result from the code snippet above, after adding a row, changing the dropdown and clicking the custom button.
178+
* [Handle Grid events](slug://grid-events)
285179

286-
![Blazor Custom Toolbar Layout](images/custom-toolbar-layout.png)
287180

288181
## See Also
289182

290-
* [Live Demo: Grid Toolbar](https://demos.telerik.com/blazor-ui/grid/editing-inline)
291-
* [Blazor Grid](slug://grid-overview)
183+
* [Grid Live Demo](https://demos.telerik.com/blazor-ui/grid/overview)
184+
* [Grid API](/blazor-ui/api/Telerik.Blazor.Components.TelerikGrid)

0 commit comments

Comments
 (0)