Skip to content

Commit 6bb0c7b

Browse files
xristianstefanovdimodi
xristianstefanov
and
dimodi
authored
docs(Grid): add typed tools toolbar articles (#2707)
* docs(Grid): add typed tools toolbar articles * chore(Grid): address comments * chore(Grid): address comments and polish samples * Update components/grid/toolbar.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/grid/toolbar.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/grid/toolbar.md Co-authored-by: Dimo Dimov <[email protected]> * chore(TreeList): apply suggestions to treelist --------- Co-authored-by: Dimo Dimov <[email protected]>
1 parent 12bce01 commit 6bb0c7b

File tree

2 files changed

+305
-298
lines changed

2 files changed

+305
-298
lines changed

‎components/grid/toolbar.md‎

Lines changed: 116 additions & 182 deletions
Original file line numberDiff line numberDiff line change
@@ -10,233 +10,167 @@ 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](#custom-tools) or create a [custom toolbar](#custom-toolbar-configuration).
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+
The [Blazor Grid](https://demos.telerik.com/blazor-ui/grid/overview) provides several built-in tools that can be added to the component toolbar. To include a specific tool in the [toolbar configuration](#toolbar-tools-configuration), use the respective tool tags below.
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+
| Tool Name | Tool Tag | Description |
33+
| --- | --- | --- |
34+
| Spacer | `GridToolBarSpacerTool` | Consumes the available empty space and pushes the rest of the tools next to one another. |
2935

30-
* `Add` - starts [inserting a new item in the grid](slug://components/grid/editing/overview).
36+
## Custom Tools
3137

32-
* `ExcelExport` - starts an [Excel export of the grid data](slug://grid-export-excel).
38+
In addition to the built-in tools, the Grid also supports custom tools. Use the `<GridToolBarCustomTool>` tag, which is a standard Blazor `RenderFragment`. See the example below.
3339

34-
* `CsvExport` - starts an [CSV export of the grid data](slug://grid-export-csv).
40+
## Toolbar Tools Configuration
3541

42+
Add a `<GridToolBar>` tag inside `<TelerikGrid>` to configure a toolbar, for example:
3643

37-
>caption How to insert a new item in the grid
44+
* Arrange the Grid tools in a specific order;
45+
* Remove some of the built-in tools;
46+
* Add custom tools.
3847

39-
````RAZOR
40-
@result
48+
>important `<GridToolBar>` and `<GridToolBarTemplate>` cannot be used together in the same Grid instance.
4149
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>
50+
>caption Grid Toolbar Tools
51+
52+
````RAZOR
53+
<TelerikGrid Data=@GridData
54+
EditMode="@GridEditMode.Inline"
55+
Pageable="true"
56+
OnUpdate=@UpdateItem
57+
OnCreate=@CreateItem>
58+
<GridToolBar>
59+
<GridToolBarCustomTool>
60+
<TelerikButton OnClick="@OnToolbarCustomClick">Custom Grid Tool</TelerikButton>
61+
</GridToolBarCustomTool>
62+
63+
<GridToolBarAddTool>
64+
Add a product
65+
</GridToolBarAddTool>
66+
67+
<GridToolBarCsvExportTool>
68+
Export to CSV
69+
</GridToolBarCsvExportTool>
70+
71+
<GridToolBarExcelExportTool>
72+
Export to Excel
73+
</GridToolBarExcelExportTool>
74+
75+
<GridToolBarSpacerTool />
76+
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.HireDate) Title="Hire Date" Width="230px" />
84+
<GridCommandColumn Width="200px">
85+
<GridCommandButton Command="Edit" Icon="@SvgIcon.Pencil"></GridCommandButton>
86+
<GridCommandButton Command="Save" Icon="@SvgIcon.Save" ShowInEdit="true"></GridCommandButton>
5587
</GridCommandColumn>
5688
</GridColumns>
5789
</TelerikGrid>
5890
5991
@code {
60-
string result;
61-
public List<SampleData> MyData { get; set; }
92+
private List<Person> GridData { get; set; }
6293
63-
private async Task UpdateHandler(GridCommandEventArgs args)
94+
private void OnToolbarCustomClick()
6495
{
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);
96+
Console.WriteLine("Custom Grid Toolbar tool clicked!");
7497
}
7598
76-
private async Task CreateHandler(GridCommandEventArgs args)
99+
protected override void OnInitialized()
77100
{
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);
101+
var data = new List<Person>();
102+
var rand = new Random();
82103
83-
// update the local view-model data with the service data
84-
await GetGridData();
85-
86-
result = string.Format("On {2} you added the employee {0} who was hired on {1}.", insertedItem.Name, insertedItem.HireDate, DateTime.Now);
104+
for (int i = 0; i < 50; i++)
105+
{
106+
data.Add(new Person()
107+
{
108+
EmployeeId = i,
109+
Name = "Employee " + i.ToString(),
110+
HireDate = DateTime.Now.Date.AddDays(-(i * 2)),
111+
AgeInYears = 20
112+
});
113+
}
114+
GridData = new List<Person>(data);
87115
}
88116
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
117+
private void CreateItem(GridCommandEventArgs args)
91118
{
92-
public int ID { get; set; }
93-
public string Name { get; set; }
94-
public DateTime HireDate { get; set; }
95-
}
119+
var argsItem = args.Item as Person;
96120
97-
async Task GetGridData()
98-
{
99-
MyData = await MyService.Read();
100-
}
121+
argsItem.EmployeeId = GridData.Count + 1;
101122
102-
protected override async Task OnInitializedAsync()
103-
{
104-
await GetGridData();
123+
GridData.Insert(0, argsItem);
105124
}
106125
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
126+
private void UpdateItem(GridCommandEventArgs args)
110127
{
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);
117-
118-
return await Task.FromResult(itemToInsert);
119-
}
120-
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-
}
128+
var argsItem = args.Item as Person;
129+
var itemForEdit = GridData.FirstOrDefault(i => i.EmployeeId == argsItem.EmployeeId);
138130
139-
public static async Task<SampleData> Update(SampleData itemToUpdate)
131+
if (itemForEdit != null)
140132
{
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");
133+
itemForEdit.AgeInYears = argsItem.AgeInYears;
134+
itemForEdit.HireDate = argsItem.HireDate;
135+
itemForEdit.Name = argsItem.Name;
149136
}
150137
}
151-
}
152-
````
153-
154-
>caption The result from the code snippet above, after the built-in Create button in the toolbar was clicked
155138
156-
![Blazor Create Toolbar Button](images/create-toolbar-button.png)
157-
158-
## Custom Commands
159-
160-
You can use the toolbar to add buttons that invoke actions specific to your application.
161-
162-
>caption How to define a custom command in the grid toolbar
139+
public class Person
140+
{
141+
public int? EmployeeId { get; set; }
163142
164-
````RAZOR
165-
@result
143+
public string Name { get; set; }
166144
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>
145+
public int? AgeInYears { get; set; }
176146
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-
});
147+
public DateTime HireDate { get; set; }
148+
}
203149
}
204150
````
205151

206-
>caption The result from the code snippet above, after the custom command button in the toolbar was clicked
152+
## Custom Toolbar Configuration
207153

208-
![Blazor Custom Command Toolbar](images/custom-command-toolbar.png)
154+
Add a `<GridToolBarTemplate>` tag inside `<TelerikGrid>` to configure a custom toolbar. You can add your own HTML and components to create a more complex layout in the Grid header to match your business needs and also `GridCommandButton` instances (read more about the features available in those buttons in the [Command Column](slug://components/grid/columns/command) article).
209155

210-
## Custom Layout
156+
When using a `<GridToolBarTemplate>`, you need to use the `Tab` key to navigate between the focusable items. This is because the `<GridToolBarTemplate>` allows rendering of custom elements. On the other hand, the `<GridToolBar>` uses the [built-in keyboard navigation](slug://accessibility-overview#keyboard-navigation) through arrow keys.
211157

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
158+
>caption Custom Grid Toolbar
215159
216160
````RAZOR
217161
@result
218162
219163
<TelerikGrid Data=@MyData Pageable="true" PageSize="15" EditMode="@GridEditMode.Inline" Height="500px" OnCreate="@CreateHandler">
220164
221165
<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>
166+
<div style="display: flex; width: 100%; justify-content: space-between;">
167+
<GridCommandButton Command="Add" Icon="@SvgIcon.Plus">
168+
Add Employee
169+
</GridCommandButton>
170+
171+
<button @onclick="@( () => result = $"Custom button click on {DateTime.Now}" )">
172+
Click Me
173+
</button>
240174
</div>
241175
</GridToolBarTemplate>
242176
@@ -252,7 +186,7 @@ You can add your own HTML and components to create a more complex layout in the
252186
</TelerikGrid>
253187
254188
@code {
255-
string result;
189+
private string result;
256190
257191
private void CreateHandler(GridCommandEventArgs args)
258192
{
@@ -273,19 +207,19 @@ You can add your own HTML and components to create a more complex layout in the
273207
274208
public List<SampleData> MyData = Enumerable.Range(1, 50).Select(
275209
x => new SampleData
276-
{
277-
ID = x,
278-
Name = "name " + x,
279-
HireDate = DateTime.Now.AddDays(-x)
280-
}).ToList();
210+
{
211+
ID = x,
212+
Name = "name " + x,
213+
HireDate = DateTime.Now.AddDays(-x)
214+
}).ToList();
281215
}
282216
````
283217

284-
>caption The result from the code snippet above, after adding a row, changing the dropdown and clicking the custom button.
218+
## Next Steps
285219

286-
![Blazor Custom Toolbar Layout](images/custom-toolbar-layout.png)
220+
* [Handle Grid events](slug://grid-events)
287221

288222
## See Also
289223

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

0 commit comments

Comments
 (0)