Batch Edit Mode

• Aug 01, 2019
• 8 minutes to read

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

Batch Edit Mode Settings

Customize the ASPxGridView‘s functionality in batch edit mode using the following features:

Edit mode

End-users can use in-line editors to edit data in a grid. The GridViewBatchEditSettings.EditMode property allows you to specify which control element (data cell or data row) end-users can use to edit data.

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:

• GridViewBatchStartEditAction.FocusedCellClick - Specifies a click on the focused cell (default value).
• GridViewBatchStartEditAction.Click - Specifies a click on the cell.
• GridViewBatchStartEditAction.DblClick - Specifies a double click on the cell.

Preventing end-user editing

Set the column’s GridColumnEditFormSettings.Visible property to false to prevent an end-user from switching to the edit mode. These column cells are skipped when end-users navigate through cells using the TAB key.

Confirmation on losing changes

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

Validation

The ASPxGridView allows you to validate grid data client side in batch edit mode. Use the ASPxClientGridView.BatchEditRowValidating 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 ASPxClientGridView.BatchEditRowValidating event.

• true - In this default settings, the control checks edited data cell/row 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 th editor until an end-user inputs the correct value.

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

To validate grid data programmatically, use the ASPxClientGridViewBatchEditApi.ValidateRow method for the specified data row/cell and the ASPxClientGridViewBatchEditApi.ValidateRows method for all displayed data.

See the T171182: ASPxGridView - How to implement custom date validation in Batch Edit mode code example to learn more information about grid validation in batch edit mode.

Data Item Template

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

Use the ASPxClientGridViewBatchEditApi.GetCellTextContainer method to get a column’s container object when the grid 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.

The following code example demonstrates how to use the described API resources: T506160: How to use and modify a control placed in the DataItemTemplate.

In Batch Edit mode, use the DataItemTemplate only to customize the appearance as the grid copies only a row’s HTML markup when creating a new row.

Appearance Customization

The ASPxGridView highlights all modified values in batch edit mode.

You can customize the visual presentation of modified data cells/rows using the following properties:

• GridViewStyles.BatchEditModifiedCell - Contains style settings for modified data cells.
• GridViewDataColumn.BatchEditModifiedCellStyle - Contains style settings for modified data cells in a certain data column only.
• GridViewStyles.BatchEditNewRow - Contains style settings for newly added data rows.
• GridViewStyles.BatchEditDeletedRow - Contains style settings for deleted data rows.

You also can remove deleted data rows from the grid instead of highlighting them. To do this, switch the GridViewBatchEditSettings.HighlightDeletedRows property to false.

The grid stores the Update and Cancel buttons within its status bar. You can use the status bar‘s style settings to adjust these buttons’ appearance.

The following code snippets illustrate how to hide the Update and Cancel buttons:

• Using the ASPxGridSettings.ShowStatusBar property.

  ASPX

  
  ...
  <Settings ShowStatusBar="Hidden"/>
  ...
  

• Modifying the grid’s dxgvStatusBar CSS class.

  CSS

  
  .dxgvStatusBar {
      display: none;
  }
  

Client-side Functionality

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

Start editing

Member	Description
ASPxClientGridView.StartEditRow	Invokes in-line editors in a specified row.
ASPxClientGridViewBatchEditApi.StartEdit	Invokes the in-line editor in a specified cell.

Add/Delete row

Member	Description
ASPxClientGridView.AddNewRow	Adds a new row. Does not perform a callback in batch edit mode.
ASPxClientGridView.DeleteRow	Deletes the specified row.
ASPxClientGridViewBatchEditApi.IsNewRow	Indicates if the row with a specified visible index is newly created.
ASPxClientGridViewBatchEditApi.IsDeletedRow	Indicates if the row with a specified visible index is deleted.

Finish editing

Member	Description
ASPxClientGridViewBatchEditApi.EndEdit	Ends cell or row editing.
ASPxClientGridView.UpdateEdit	Ends cell or row editing and send all changes to the server.
ASPxClientGridViewBatchEditApi.ResetChanges	Resets all unsaved changes in a specified row/cell.
ASPxClientGridView.CancelEdit	Cancels all changes, and switches the grid 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 ASPxGridView provides a set of events that allow you to perform custom actions when end-users interact with the grid in batch edit mode.

Server-side events

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

ASPX

<dx:ASPxGridView ID="Grid" runat="server" KeyFieldName="ID" OnBatchUpdate="Grid_BatchUpdate" >
    <ClientSideEvents .../>
    <Columns>
        ...
    </Columns>
    <SettingsEditing Mode="Batch" />
</dx:ASPxGridView>

C#

protected void Grid_BatchUpdate(object sender, ASPxDataBatchUpdateEventArgs e) {
    foreach(var args in e.InsertValues)
        InsertNewItem(args.NewValues);
    foreach(var args in e.UpdateValues)
        UpdateItem(args.Keys, args.NewValues);
    foreach(var args in e.DeleteValues)
        DeleteItem(args.Keys, args.Values);

    e.Handled = true;
}

Client-side events

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

• Batch adding/deleting rows

  Member	Description
  ASPxClientGridView.BatchEditRowInserting	Occurs on the client side before the grid inserts a row in batch edit mode.
  ASPxClientGridView.BatchEditRowDeleting	Occurs on the client side before the grid deletes a row in batch edit mode.

• Batch saving/canceling

  Member	Description
  ASPxClientGridView.BatchEditChangesSaving	Occurs on the client side before data changes are saved in batch edit mode.
  ASPxClientGridView.BatchEditChangesCanceling	Occurs on the client side before data changes are canceled in batch edit mode.
  ASPxClientGridView.BatchEditConfirmShowing	Enables you to prevent the display of a batch edit confirmation message.

• Batch editing

  Member	Description
  ASPxClientGridView.BatchEditStartEditing	Occurs when a grid switches to batch edit mode.
  ASPxClientGridView.BatchEditEndEditing	Occurs when a grid leaves batch edit mode.

• Batch validation

  Member	Description
  ASPxClientGridView.BatchEditRowValidating	Enables you to specify whether row data is valid and then provide error text.

• Batch template cell focus

  Member	Description
  ASPxClientGridView.BatchEditTemplateCellFocused	Enables you to provide navigation in batch edit mode for editors in a templated cell.

Batch Edit Mode Limitations

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

Unsupported features

The features below are not supported when the grid is in batch edit mode:

• Endless Paging mode is not supported.
• The JavaScript code contained within the href link attribute is not executed in Internet Explorer. See the Links / “A” tags do not work in IE together with GridView in Batch Edit Mode Knowledge Base article for more information.
• The date range functionality of embedded date editors does not function in Cell batch edit mode.
• Cell merging functionality doesn’t work in batch edit mode.
• The select check boxes of newly created rows are disabled until the rows are saved.

• The ASPxBinaryImage control does not have any built-in functionality that would allow you to determine if the editor is focused (the ASPxClientEdit.GotFocus and ASPxClientEdit.LostFocus client events do not work). This imposes the following limitations on using ASPxBinaryImage in batch edit mode:

  • Cell/row navigation does not work for GridViewDataBinaryImageColumn.
  • ASPxGridView cannot be switched to browse mode when a user clicks outside the grid while editing the GridViewDataBinaryImageColumn.
• The focus shifts from the grid to a drop-down editor (in the DropDownWindowTemplate object) when you edit the GridViewDataDropDownEditColumn column and finishes the batch editing.

Unsupported server-side API

The following ASPxGridView members are not in effect when the grid is in batch edit mode:

• Properties

  • ASPxGridView.EditingRowVisibleIndex
  • ASPxGridView.IsEditing
  • ASPxGridView.IsNewRowEditing

• Events

  • ASPxGridView.InitNewRow
  • ASPxGridView.CellEditorInitialize

• Methods

  • ASPxGridView.StartEdit
  • ASPxGridView.AddNewRow

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

• Unsupported client-side API

  The following members of the ASPxClientGridView are not in effect when the grid is in batch edit mode:

  • ASPxClientGridView.IsEditing
  • ASPxClientGridView.IsNewRowEditing

  The ASPxClientGridView.GetTopVisibleIndex property does not return the correct values if rows were deleted/inserted. Use the ASPxClientGridViewBatchEditApi.GetRowVisibleIndices instead.

Code Examples

A simple Batch Editing implementation

How to cancel editing or disable the editor conditionally

How to conditionally enable and disable the editing on the client side

How to implement copy and clone functionality

How to calculate values on the fly

How to implement custom date validation

How to update total summaries on the client side

How to implement cascading comboboxes

How to update a master grid and all its detail grids simultaneously