Batch Edit Mode

  • 7 min to read

The ASPxTreeList control allows you to modify tree list data client-side and then send it to the server in a single request. All user changes are maintained client-side until a user clicks the Update or Cancel button. Set the ASPxGridViewEditingSettings.Mode property to Batch to enable the batch edit functionality.

ASPxTreeList-BatchEditing

Online Demo

ASPxTreeList - Batch Editing and Updating

Batch Edit Mode Settings

Customize the ASPxTreeList's functionality in batch edit mode using the following features.

Edit mode

End-users can use in-line editors to edit data in a tree list. The TreeListBatchEditSettings.EditMode property allows you to specify which control element (data cell or data node) end-users can use to edit data.

ASPxTreeList-Batch-Cell

Start edit action

Set the GridBatchEditSettings.StartEditAction property to one of the following values to specify which user action invokes a data cell's in-line editor:

New Node Insertion

When inserting a new child node, the control gets a parent node's key field name. A newly inserted parent node does not have a key field until it is saved to the server by clicking the Update button. Use the ASPxTreeList.SetBatchEditInsertedNodeKeyValue method to specify the newly inserted node key. This allows you to create the control’s tree-like data structure in batch edit mode.

Preventing end-user edits

Set the column's TreeListColumnEditFormSettings.Visible property to false to prevent end users from switching to edit mode. These column cells are skipped when end users navigate through cells using the TAB key.

Confirmation on losing changes

A tree list displays a "confirm" message before a grid callback or postback is performed if it contains modified data. Customize the message text using the TreeListSettingsText.ConfirmOnLosingBatchChanges property, or disable it by setting the GridBatchEditSettings.ShowConfirmOnLosingChanges property to false.

Validation

The ASPxTreeList allows you to validate tree list data client side in batch edit mode. Use the ASPxClientTreeList.BatchEditNodeValidating event to specify whether end user changes are valid.

Set the GridBatchEditSettings.AllowValidationOnEndEdit property to one of the following values to specify when to fire the ASPxClientTreeList.BatchEditNodeValidating event.

  • true - In this default setting, the control checks edited data cells/nodes when an in-line editor loses focus.

    The ValidationSettings.SetFocusOnError property is not in effect in batch edit mode if the input value fails validation and needs to re-focus an editor. Instead, set the GridBatchEditSettings.AllowEndEditOnValidationError property to false to focus the editor until an end user inputs the correct value.

  • false - In this case, the control checks all edited data cells/nodes when an end-user clicks the Update button.

To validate tree list data programmatically, use the ASPxClientTreeListBatchEditApi.ValidateNode method for the specified data node/cell, and the ASPxClientTreeListBatchEditApi.ValidateNodes method for all displayed data.

Set the ValidationSettings.Display property to Dynamic to prevent the render of the empty space (the validation error element) near the edit cell.


settings.CellEditorInitialize = (s, e) => {
    ASPxEdit editor = (ASPxEdit)e.Editor;
    editor.ValidationSettings.Display = Display.Dynamic;
};

Data Item Template

The ASPxTreeList provides a set of API members to help process the content of data cells specified in data item templates.

Use the ASPxClientTreeListBatchEditApi.GetCellTextContainer method to get a column's container object when the tree list is in batch edit mode. Use the GridBatchEditSettings.AllowRegularDataItemTemplate property to specify whether to overwrite a data item template in a data cell when its editing is completed.

Appearance Customization

The ASPxTreeList highlights all modified values in batch edit mode.

ASPxTreeList-Batch-VisualElements

You can customize the visual presentation of modified data cells/nodes using the following properties.

Client-side Functionality

The ASPxClientTreeList.batchEditApi property provides access to the batch edit client API. The tables below list the API resources that you can use to invoke tree list commands client-side.

Start editing

Member Description
ASPxClientTreeList.StartEditNewNode Invokes in-line editors in a specified node.
ASPxClientTreeListBatchEditApi.StartEdit Invokes the in-line editor in a specified cell.

Add/Delete node

Member Description
ASPxClientTreeListBatchEditApi.AddNewNode Adds a new node. Does not perform a callback in batch edit mode.
ASPxClientTreeList.DeleteNode Deletes the specified node.
ASPxClientTreeListBatchEditApi.IsNewNode Indicates if the node with a specified visible index is newly created.
ASPxClientTreeListBatchEditApi.IsDeletedNode Indicates if the node with a specified visible index is deleted.

Finish editing

Member Description
ASPxClientTreeListBatchEditApi.EndEdit Ends cell or node editing.
ASPxClientTreeList.UpdateEdit Ends cell or node editing, and sends all changes to the server.
ASPxClientTreeListBatchEditApi.ResetChanges Resets all unsaved changes in a specified node/cell.
ASPxClientTreeList.CancelEdit Cancels all changes, and switches the Tree List to browse mode.

Note that there are client-side methods that are not in effect in batch edit mode. See the Batch Edit Mode Limitations - Unsupported client-side API topic for more details.

Batch Edit Mode Events

The ASPxTreeList provides a set of events that allow you to perform custom actions when end-users interact with the tree list in batch edit mode.

Server-side events

The ASPxTreeList.BatchUpdate event allows you to implement a custom data updating mechanism. The event fires when an end-user clicks the Update button or calls the ASPxTreeList.UpdateEdit method; the ASPxTreeList.BatchUpdate event handler receives an argument containing information about all changed values.

Client-side events

The ASPxClientTreeList provides a set of client-side methods that occur only when the tree list is in batch edit mode. These methods are listed in the following tables.

Batch Edit Mode Limitations

There are ASPxTreeList control features and API members that are not in effect in batch edit mode, since all user changes are maintained client-side.

Unsupported features

The features below are not supported when the tree list is in batch edit mode.

Unsupported server-side API

The following ASPxTreeList members are not in effect when the tree list is in batch edit mode.

You can use the client-side API instead of the unsupported server-side API to implement the tasks listed above.