Skip to content

docs(Grid): add typed tools toolbar articles #2707

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jan 20, 2025
Merged

docs(Grid): add typed tools toolbar articles #2707

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
c07744f
docs(Grid): add typed tools toolbar articles
xristianstefanov Jan 15, 2025
8a967a8
chore(Grid): address comments
xristianstefanov Jan 16, 2025
b3050f2
chore(Grid): address comments and polish samples
xristianstefanov Jan 20, 2025
7011a0e
Update components/grid/toolbar.md
xristianstefanov Jan 20, 2025
8c89367
Update components/grid/toolbar.md
xristianstefanov Jan 20, 2025
7da2789
Update components/grid/toolbar.md
xristianstefanov Jan 20, 2025
1fa3f87
chore(TreeList): apply suggestions to treelist
xristianstefanov Jan 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
339 changes: 116 additions & 223 deletions components/grid/toolbar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,282 +10,175 @@ position: 45

# Grid Toolbar

The grid provides a toolbar where you can add a variety of actions that are not tied to a concrete row.
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.

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).
## Built-in Tools

>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.
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).

In this article, you will learn how to use:
### Command Tools

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

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

## Built-in Commands
### Layout Tools

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:
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)

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

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

* `CsvExport` - starts an [CSV export of the grid data](slug://grid-export-csv).
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.

## Toolbar Configuration

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

````RAZOR
@result
* Arrange the Grid tools in a specific order;
* Remove some of the built-in tools;
* Add custom tools.

>caption Customize the Grid toolbar

<TelerikGrid Data=@MyData Pageable="true" PageSize="15" EditMode="@GridEditMode.Inline" Height="500px"
OnUpdate="@UpdateHandler" OnCreate="@CreateHandler">
<GridToolBarTemplate>
<GridCommandButton Command="Add" Icon="@SvgIcon.Plus">Add Employee</GridCommandButton>
</GridToolBarTemplate>
````RAZOR
<TelerikGrid Data=@GridData
EditMode="@GridEditMode.Inline"
Pageable="true"
OnUpdate=@UpdateItem
OnDelete=@DeleteItem
OnCreate=@CreateItem>
<GridToolBar>
<GridToolBarCustomTool>
<TelerikButton OnClick="@OnToolbarCustomClick">Custom Grid Tool</TelerikButton>
</GridToolBarCustomTool>

<GridToolBarAddTool>
Add a product
</GridToolBarAddTool>

<GridToolBarCsvExportTool>
Export to CSV
</GridToolBarCsvExportTool>

<GridToolBarExcelExportTool>
Export to Excel
</GridToolBarExcelExportTool>

<GridToolBarSpacerTool />
<GridToolBarSearchBoxTool />
</GridToolBar>
<GridColumns>
<GridColumn Field=@nameof(SampleData.ID) Editable="false" Title="Employee ID" />
<GridColumn Field=@nameof(SampleData.Name) Title="Employee Name" />
<GridColumn Field=@nameof(SampleData.HireDate) Title="Hire Date" />
<GridCommandColumn>
<GridCommandButton Command="Edit" Icon="@SvgIcon.Pencil">Edit</GridCommandButton>
<GridCommandButton Command="Save" Icon="@SvgIcon.Save" ShowInEdit="true">Save</GridCommandButton>
<GridCommandButton Command="Cancel" Icon="@SvgIcon.Cancel" ShowInEdit="true">Cancel</GridCommandButton>
<GridColumn Field=@nameof(Person.EmployeeId) Editable="false" Visible="true" Width="200px" />
<GridColumn Field=@nameof(Person.Name) Width="200px" />
<GridColumn Field=@nameof(Person.AgeInYears) Title="Age" Visible="false" Width="240px" />
<GridColumn Field=@nameof(Person.MeetingDate) Title="Meeting Date" Width="220px" />
<GridColumn Field=@nameof(Person.HireDate) Title="Hire Date" Width="230px" />
<GridColumn Field=@nameof(Person.GraduateGrade) Title="Graduate Grade" Width="200px" />
<GridCommandColumn Width="200px">
<GridCommandButton Command="Delete" Icon="@SvgIcon.Trash"></GridCommandButton>
<GridCommandButton Command="Edit" Icon="@SvgIcon.Pencil"></GridCommandButton>
<GridCommandButton Command="Save" Icon="@SvgIcon.Save" ShowInEdit="true"></GridCommandButton>
</GridCommandColumn>
</GridColumns>
</TelerikGrid>

@code {
string result;
public List<SampleData> MyData { get; set; }
private List<Person> GridData { get; set; }

private async Task UpdateHandler(GridCommandEventArgs args)
private void OnToolbarCustomClick()
{
SampleData item = args.Item as SampleData;

// perform actual data source operations here through your service
SampleData updatedItem = await MyService.Update(item);

// update the local view-model data with the service data
await GetGridData();

result = string.Format("Employee with ID {0} now has name {1} and hire date {2}", updatedItem.ID, updatedItem.Name, updatedItem.HireDate);
Console.WriteLine("Custom Grid Toolbar tool clicked!");
}

private async Task CreateHandler(GridCommandEventArgs args)
protected override void OnInitialized()
{
SampleData item = args.Item as SampleData;

// perform actual data source operations here through your service
SampleData insertedItem = await MyService.Create(item);

// update the local view-model data with the service data
await GetGridData();
var data = new List<Person>();
var rand = new Random();

result = string.Format("On {2} you added the employee {0} who was hired on {1}.", insertedItem.Name, insertedItem.HireDate, DateTime.Now);
for (int i = 0; i < 50; i++)
{
data.Add(new Person()
{
EmployeeId = i,
Name = "Employee " + i.ToString(),
HireDate = DateTime.Now.Date.AddDays(-(i * 2)),
AgeInYears = 20,
MeetingDate = DateTime.Now.Date.AddDays(i),
GraduateGrade = (i % 5) + 2
});
}
GridData = new List<Person>(data);
}

//in a real case, keep the models in dedicated locations, this is just an easy to copy and see example
public class SampleData
private void CreateItem(GridCommandEventArgs args)
{
public int ID { get; set; }
public string Name { get; set; }
public DateTime HireDate { get; set; }
}
var argsItem = args.Item as Person;

async Task GetGridData()
{
MyData = await MyService.Read();
}
argsItem.EmployeeId = GridData.Count + 1;

protected override async Task OnInitializedAsync()
{
await GetGridData();
GridData.Insert(0, argsItem);
}

// the following static class mimics an actual data service that handles the actual data source
// replace it with your actual service through the DI, this only mimics how the API can look like and works for this standalone page
public static class MyService
private void DeleteItem(GridCommandEventArgs args)
{
private static List<SampleData> _data { get; set; } = new List<SampleData>();

public static async Task<SampleData> Create(SampleData itemToInsert)
{
itemToInsert.ID = _data.Count + 1;
_data.Insert(0, itemToInsert);
var argsItem = args.Item as Person;

return await Task.FromResult(itemToInsert);
}
GridData.Remove(argsItem);
}

public static async Task<List<SampleData>> Read()
{
if (_data.Count < 1)
{
for (int i = 1; i < 50; i++)
{
_data.Add(new SampleData()
{
ID = i,
Name = "Name " + i.ToString(),
HireDate = DateTime.Now.AddDays(-i)
});
}
}

return await Task.FromResult(_data);
}
private void UpdateItem(GridCommandEventArgs args)
{
var argsItem = args.Item as Person;
var itemForEdit = GridData.FirstOrDefault(i => i.EmployeeId == argsItem.EmployeeId);

public static async Task<SampleData> Update(SampleData itemToUpdate)
if (itemForEdit != null)
{
var index = _data.FindIndex(i => i.ID == itemToUpdate.ID);
if (index != -1)
{
_data[index] = itemToUpdate;
return await Task.FromResult(_data[index]);
}

throw new Exception("no item to update");
itemForEdit.AgeInYears = argsItem.AgeInYears;
itemForEdit.GraduateGrade = argsItem.GraduateGrade;
itemForEdit.HireDate = argsItem.HireDate;
itemForEdit.MeetingDate = argsItem.MeetingDate;
itemForEdit.Name = argsItem.Name;
}
}
}
````

>caption The result from the code snippet above, after the built-in Create button in the toolbar was clicked
public class Person
{
public int? EmployeeId { get; set; }

![Blazor Create Toolbar Button](images/create-toolbar-button.png)
public string Name { get; set; }

## Custom Commands
public int? AgeInYears { get; set; }

You can use the toolbar to add buttons that invoke actions specific to your application.
public decimal? GraduateGrade { get; set; }

>caption How to define a custom command in the grid toolbar
public DateTime HireDate { get; set; }

````RAZOR
@result

<TelerikGrid Data=@MyData Pageable="true" PageSize="15">
<GridToolBarTemplate>
<GridCommandButton Command="MyToolbarCommand" OnClick="@MyCommandFromToolbar" Icon="@SvgIcon.InfoCircle">Fire My Command</GridCommandButton>
</GridToolBarTemplate>
<GridColumns>
<GridColumn Field=@nameof(SampleData.Name) Title="Employee Name" />
<GridColumn Field=@nameof(SampleData.HireDate) Title="Hire Date" />
</GridColumns>
</TelerikGrid>
public DateTime MeetingDate { get; set; }

@code {
string result;

private void MyCommandFromToolbar(GridCommandEventArgs args)
{
//note - the args.Item object is null because the command item is not associated with an item

result = "my custom toolbar command fired at " + DateTime.Now.ToString();

StateHasChanged();
}

//in a real case, keep the models in dedicated locations, this is just an easy to copy and see example
public class SampleData
{
public int ID { get; set; }
public string Name { get; set; }
public DateTime HireDate { get; set; }
}

public IEnumerable<SampleData> MyData = Enumerable.Range(1, 50).Select(x => new SampleData
{
ID = x,
Name = "name " + x,
HireDate = DateTime.Now.AddDays(-x)
});
public Person()
{
GraduateGrade = 1;
}
}
}
````

>caption The result from the code snippet above, after the custom command button in the toolbar was clicked

![Blazor Custom Command Toolbar](images/custom-command-toolbar.png)

## Custom Layout

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.

>caption Custom Grid Toolbar Layout

````RAZOR
@result

<TelerikGrid Data=@MyData Pageable="true" PageSize="15" EditMode="@GridEditMode.Inline" Height="500px" OnCreate="@CreateHandler">

<GridToolBarTemplate>
<div style="display: block; flex-grow: 1;">
@* the first level children in the toolbar get display: inline-flex and flex-shrink: 0 inherited from the grid,
we change it here to show we can, or you can work with the layout the grid defines if it suits your needs *@

<div style="background:yellow">
<GridCommandButton Command="Add" Icon="@SvgIcon.Plus">Add Employee</GridCommandButton>
</div>
<div style="background: green;">
<TelerikDropDownList Data="@( new List<string>() { "first", "second", "third" } )" TValue="string" TItem="string" ValueChanged="@( (string itm) => result = itm )"></TelerikDropDownList>
</div>

<div style="border: 1px solid red;">
@* one example of aligning content to the right with flex *@
<button style="display: flex; margin-left: auto;"
@onclick="@( () => result = $"Custom button click on {DateTime.Now}" )">
Click me
</button>
</div>
</div>
</GridToolBarTemplate>

<GridColumns>
<GridColumn Field=@nameof(SampleData.Name) Title="Employee Name" />
<GridColumn Field=@nameof(SampleData.HireDate) Title="Hire Date" />
<GridCommandColumn>
<GridCommandButton Command="Edit" Icon="@SvgIcon.Pencil">Edit</GridCommandButton>
<GridCommandButton Command="Save" Icon="@SvgIcon.Save" ShowInEdit="true">Save</GridCommandButton>
<GridCommandButton Command="Cancel" Icon="@SvgIcon.Cancel" ShowInEdit="true">Cancel</GridCommandButton>
</GridCommandColumn>
</GridColumns>
</TelerikGrid>

@code {
string result;

private void CreateHandler(GridCommandEventArgs args)
{
SampleData newItem = args.Item as SampleData;
MyData.Insert(0, newItem); // actual CRUD operations are not implemented, for brevity

result = string.Format("On {2} you added the employee {0} who was hired on {1}.", newItem.Name, newItem.HireDate, DateTime.Now);
StateHasChanged();
}

//in a real case, keep the models in dedicated locations, this is just an easy to copy and see example
public class SampleData
{
public int ID { get; set; }
public string Name { get; set; }
public DateTime HireDate { get; set; }
}

public List<SampleData> MyData = Enumerable.Range(1, 50).Select(
x => new SampleData
{
ID = x,
Name = "name " + x,
HireDate = DateTime.Now.AddDays(-x)
}).ToList();
}
````
## Next Steps

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

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

## See Also

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