New to Telerik UI for Blazor? Start a free 30-day trial

Blazor TreeList CRUD Operations

The Telerik TreeList for Blazor supports create, update, and delete operations (CRUD) with different modes and user experience. The component also supports built-in DataAnnotations or custom validation. This page describes:

How the create, update, and delete operations work in the TreeList.
What are the available edit modes and how to enable them.
The applicable TreeList commands.
The applicable TreeList events.
How to change the built-in editors for certain data types.
How to refresh the TreeList data after add, edit, and delete operations.
How the TreeList CRUD operations integrate with other component features.

Basics

The TreeList CRUD operations rely on the following algorithm:

Users execute TreeList commands (Edit, Save, Delete, and more) with the mouse or keyboard.
The TreeList fires events (OnCreate, OnDelete, OnUpdate and more), which provide information what the user did or how the component data changed.
The application applies the changes to the TreeList data source in the above event handlers.
The TreeList rebinds to display the latest data.

Model Requirements

Adding or editing rows in the TreeList sets the following requirements on the TreeList model:

The TreeList model class must have a parameterless constructor. Otherwise, use the TreeList OnModelInit event to provide a data item instance when the TreeList needs to create one. Optinally, you can also set some default values.
All editable properties must be public and have setters. These properties must not be readonly.
Self-referencing or inherited properties must not cause StackOverflowException or AmbiguousMatchException during programmatic model instance creation.

Edit Modes

The TreeList offers several ways to add and edit rows with a different user experience:

In-Cell—users modify the TreeList content cell by cell.
Inline—users modify the TreeList content row by row.
Popup—users modify the TreeList content row by row in a modal popup form.

To allow users to add or edit values in the TreeList:

Set the EditMode parameter to a member of the TreeListEditMode enum. The default EditMode parameter value is None and the built-in Add and Edit commands don't work.
Define the required command buttons and events for the selected edit mode and operations.

Set up TreeList popup edit mode

RAZOR

<TelerikTreeList EditMode="@TreeListEditMode.Popup"
                 OnUpdate="@OnTreeListUpdate">
    <TreeListColumns>
        <TreeListCommandColumn>
            <TreeListCommandButton Command="Edit">Edit</TreeListCommandButton>
        </TreeListCommandColumn>
    </TreeListColumns>
</TelerikTreeList>

See the TreeList add and edit operations in action in the complete examples for TreeList inline, in-cell, and popup editing.

Editing multiple rows at the same time is not supported. You can render editors in all TreeList data cells through column <Template>s as an alternative.

Delete Operations

Delete operations provide the same user experience in all TreeList edit modes and require the same configuration:

Delete command button.
OnDelete event.
Optional ConfirmDelete TreeList parameter. It determines if the component will show a Dialog before firing OnDelete, so that users can abort the operation.

Delete operations can work even if the TreeList EditMode parameter value is None.

See the delete operations in action in the complete examples for TreeList inline, in-cell and popup editing. Also check how to customize the Delete Confirmation Dialog.

Commands

The TreeList provides the following built-in commands, which enable users to add, delete, and edit rows:

Add—adds a new row and puts it in edit mode. Fires the OnAdd event. If the command button is in the TreeList toolbar, the new row is created at root level. If the command button is in the command column, the new row is created as a child of the current row.
Cancel—cancels the row or cell changes and exits edit mode. Fires the OnCancel event.
Delete—deletes a row. Fires the OnDelete event.
Edit—puts a TreeList row or cell in edit mode. Fires the OnEdit event.
Save—confirms the row or cell changes and exits edit mode, if the user input is valid. Fires the OnUpdate event.

Users execute commands in the following ways:

By clicking on command buttons.
By clicking on editable cells in in-cell edit mode and then anywhere else on the page.
By using the TreeList keyboard navigation.

Command buttons can only reside in a TreeList Command Column or the TreeList ToolBar. You can also trigger add and edit operations programmatically from anywhere on the web page through the TreeList State.

Events

The following table describes the TreeList events, which are related to adding, deleting, and editing items. Also check the sections about item instances and event arguments below.

Event	Required	Description	Item Instance	If Cancelled
`OnAdd`	No	Fires on `Add` command button click, before the TreeList enters add mode. This event preceeds `OnCreate` or `OnCancel`.	New	TreeList remains in read mode.
`OnCancel`	No	Fires on `Cancel` command invocation.	New or cloned	TreeList remains in add or edit mode.
`OnCreate`	To add new items.	Fires on `Save` command invocation for new items. This event succeeds `OnAdd`.	New	TreeList remains in add mode.
`OnDelete`	To delete items.	Fires on `Delete` command button click.	Original	TreeList won't rebind. Deletion depends on the app itself.
`OnEdit`	No	Fires on `Edit` command invocation, before the TreeList actually enters edit mode. This event preceeds `OnCreate` or `OnCancel`.	Original	TreeList remains in read mode.
`OnModelInit`	Depends on the TreeList model type	Fires when the TreeList requires a new model instance, which is immediately before `OnAdd` or immediately after `OnEdit`. Use this event when the TreeList model type is an interface, abstract class, or has no parameterless constructor.	No event arguments	Not cancellable
`OnUpdate`	To edit existing items.	Fires on `Save` command invocation for existing items. This event succeeds `OnEdit`.	Cloned	TreeList remains in edit mode.

The following considerations apply for the TreeList CRUD events:

Most events provide a TreeListCommandEventArgs argument in the handler. OnModelInit has no event argument.
All events, except OnModelInit, are cancellable and the user action can be prevented. Cancelling OnDelete does not automatically prevent item deletion from the TreeList data source. This depends entirely on the executed application code.
The OnCreate, OnDelete, and OnUpdate events are required when using add, delete, and edit operations, respectively. The app must use these events to modify the TreeList data source. The TreeList does not modify its data directly.

Some events always fire in the same sequence, based on the user actions. In the list below, the value input and validation occur between the second and third event:

OnModelInit, OnAdd, and OnCreate for add operations
OnEdit, OnModelInit, and OnUpdate for edit operations

Both user workflows can end with the OnCancel event instead of OnCreate or OnUpdate.

Use async Task instead of async void for event handlers that execute awaitable operations. Otherwise the TreeList may show incorrect data, or the app may throw exceptions related to disposed objects or concurrency.

Item Instances

The TreeList does not expose or modify its data items directly in add or edit mode. Instead, the component creates a new item instance or clones an existing one. The user is always changing the values of the separate item instance. The TreeList uses Activator.CreateInstance<TItem>() and PropertyInfo.SetValue() to create and populate items for add and edit mode. This approach:

Allows users to cancel their changes and revert to the original data item values.
Provides the app with full control over the data source.
Sets some requirements for the TreeList model class and for updating Entity Framework models.

TreeListCommandEventArgs

All events in the Events table, except OnModelInit, provide a TreeListCommandEventArgs event argument. It exposes the following properties:

Property Name	Type	Description
`Field`	`string`	The column `Field` name. Applicable only for in-cell edit mode.
`IsCancelled`	`bool`	Defines if the user action should be prevented. See the Comparison table below for details.
`IsNew`	`bool`	Defines if `Item` is a newly added row or an existing row.
`Item`	`object`	The data item, which the user is adding, deleting, or editing. Cast it to the TreeList model type.
`ParentItem`	`object?`	The parent of the data item, which the user is adding. Available only in the `OnCreate` event. Cast the object to the TreeList model type.
`Value`	`object`	The data item value, which the user is editing. You can cast it to the correct type, based on the `Field`. Applicable only for in-cell edit mode.

Column Editors

You can customize the column editors through the column EditorType parameter, or by using an editor template. The EditorType parameter accepts a member of the TreeListEditorType enum:

Column Field Type	Valid `TreeListEditorType` Enum Members
`bool`	`CheckBox` (default) `Switch`
`DateTime`	`DatePicker` (default) `DateTimePicker` `TimePicker`
`string`	`TextArea` `TextBox` (default)

Setting column editor type

RAZOR

<TreeListColumn Field="@nameof(Race.StartDateTime)"
                EditorType="@TreeListEditorType.DateTimePicker" />

Rebinding After Data Changes

During add, edit, and delete operations, the TreeList expects the application to make changes to the data source (database) and then provide the latest data to the component.

In the OnCreate, OnDelete, and OnUpdate event handler, the application must do one of the following:

Make a read request to the database. Retrieve the latest data and set it as the new value of the TreeList Data parameter. The TreeList will rebind automatically. The following examples demonstrate this approach:
Use the event arguments to update the local item collection in the Data parameter manually.

Integration with Other Features

Updated rows comply with the current filter, search, and sort settings, just like all other rows. As a result, an updated row may render at a different place or disappear.

When editing a row with child items, it will collapse unless you override the Equals() method of the TreeList model class.

Learn more integration details for the inline and in-cell edit modes.

Examples

See TreeList CRUD operations in action at: