Batch Edit Mode
- 11 minutes to read
Note
Starting from v18.2, the ASPxGridView supports callbacks in batch edit mode.
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.
Online Demo
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.
Cell Focus and Keyboard Navigation
You can use keyboard to navigate through cells when the grid’s GridBatchEditSettings.StartEditAction property is set to “FocusedCellClick”. In this mode, click a grid data cell to focus the cell, and click it again to start cell editing.
Key | Action |
---|---|
Arrow Keys | Moves focus between cells. |
Tab | Moves focus to the next cell. |
Shift+Tab | Moves focus to the previous cell. |
Enter | Starts and ends editing. |
F2 | Starts editing. |
Delete | Deletes a row that contains the focused cell. |
The ASPxGridView provides client-side APIs that allow you to manage the focused data cell.
- ASPxClientGridView.GetFocusedCell - Returns information about the focused cell.
- ASPxClientGridView.SetFocusedCell - Focuses the specified cell.
- ASPxClientGridViewBatchEditApi.MoveFocusBackward - Moves focus to the previous cell in the row.
- ASPxClientGridViewBatchEditApi.MoveFocusForward - Moves focus to the next cell in the row.
Refer to the “Client-Side Functionality” and “Batch Edit Mode” sections in this topic for more information about events related to cell focusing and navigation in batch edit mode.
Prevent End-user Editing
Set the column’s GridColumnEditFormSettings.Visible property to false to prevent an end user from editing cells. These column cells are skipped when end users use TAB to navigate through cells. You can also use the ASPxClientGridView.BatchEditStartEditing event’s ASPxClientCancelEventArgs.cancel argument to cancel editing. Refer to the ASPxGridView - Batch Editing - How to cancel editing or disable the editor conditionally online example for more information.
Confirmation on Losing Changes
A grid displays a “confirm” message before a grid callback or postback is performed if it contains modified data. You can use the ASPxGridTextSettings.ConfirmOnLosingBatchChanges property to customize this message’s text, or set the GridBatchEditSettings.ShowConfirmOnLosingChanges property to false to disable it.
Validation
The ASPxGridView allows you to validate grid data on the client side in batch edit mode. Use the ASPxClientGridView.BatchEditRowValidating event to specify whether an end user’s 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 the editor until an end user enters 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 that illustrates how to validate grid data in batch edit mode.
Data Item Template
ASPxGridView supports templates in batch edit mode. The ASPxGridView provides a set of API members to help process data cells’ content specified in data item templates.
- ASPxClientGridViewBatchEditApi.GetCellTextContainer - Gets a column’s container object when the grid is in batch edit mode.
- GridBatchEditSettings.AllowRegularDataItemTemplate - Specifies whether to overwrite a data item’s template in a data cell when its editing is complete.
The following code example demonstrates how to use the described API resources: T506160: How to use and modify a control placed in the DataItemTemplate.
Preview Changes Before Saving
You can preview and modify inserted, deleted and edited rows before you click the “Update” button and the control sends these changes to the server.
Set the GridViewBatchEditSettings.KeepChangesOnCallbacks property to true to show the “Show changes” button. This button allows you to display modified rows grouped by user operation type (delete, add, edit) and modify them. The “Save changes” or “Cancel changes” buttons allow you to end batch editing and save/cancel changes. To close the Changes Preview mode and display all grid rows (including modified ones), click “Hide changes”.
By default, the grid displays only command items that allow you to edit data when the grid is in Changes Preview mode:
To display other command items (including custom and templated items) in Changes Preview mode, set a command item’s VisibleInBatchEditPreviewChanges property to true.
<dx:ASPxGridView runat="server" ID="Grid" ...>
<Toolbars>
<dx:GridViewToolbar ItemAlign="Right">
<Items>
...
<dx:GridViewToolbarItem Text="Export to PDF" Name="CustomExportToPDF" VisibleInBatchEditPreviewChanges="True" >
</dx:GridViewToolbarItem>
...
</Items>
</dx:GridViewToolbar>
</Toolbars>
...
<ClientSideEvents ToolbarItemClick="OnToolbarItemClick" />
</dx:ASPxGridView>
To customize the grid in Changes Preview mode, you can override the .dxgvBECP CSS class.
Note
The ASPxGridView supports adaptivity in Preview Changes mode.
Appearance Customization
The ASPxGridView highlights all modified values in batch edit mode.
You can use the following properties to customize data cells’/rows’ appearance:
- 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.
- GridViewStyles.FocusedCell - Contains style settings for a focused data cell.
- GridViewStyles.BatchEditChangesPreviewGroupRow - Contains style settings for a row in Changes Preview mode.
You also can remove deleted data rows from the grid instead of highlighting them. To do this, set the GridViewBatchEditSettings.HighlightDeletedRows property to false.
The grid displays the Update and Cancel buttons in the status bar. You can use the status bar‘s style settings to change these buttons’ appearance.
The following code snippets illustrate how to hide the Update and Cancel buttons:
Using the ASPxGridSettings.ShowStatusBar property.
... <Settings ShowStatusBar="Hidden"/> ...
Modifying the grid’s dxgvStatusBar CSS class.
.dxgvStatusBar { display: none; }
Client-Side API
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 edit
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 the specified visible index was created. |
ASPxClientGridViewBatchEditApi.IsDeletedRow | Indicates if the row with the specified visible index was deleted. |
Finish edit
Member | Description |
---|---|
ASPxClientGridViewBatchEditApi.EndEdit | Ends cell or row editing. |
ASPxClientGridView.UpdateEdit | Ends cell or row editing and sends 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. |
Cell Focus and Navigation
Member | Description |
---|---|
ASPxClientGridView.GetFocusedCell | Returns information about the focused cell. |
ASPxClientGridView.SetFocusedCell | Focuses the specified cell. |
ASPxClientGridViewBatchEditApi.MoveFocusBackward | Moves focus to the previous cell in the row. |
ASPxClientGridViewBatchEditApi.MoveFocusForward | Moves focus to the next cell in the row. |
Preview Changes
Member | Descriuption |
---|---|
ASPxClientGridViewBatchEditApi.ShowChangesPreview | Swithches the grid to Changes Preview mode. |
ASPxClientGridViewBatchEditApi.HideChangesPreview | Closes the Changes Preview mode and displays all grid rows (including modified rows). |
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 information.
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 a 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 the changed values.
<dx:ASPxGridView ID="Grid" runat="server" KeyFieldName="ID" OnBatchUpdate="Grid_BatchUpdate" >
<ClientSideEvents .../>
<Columns>
...
</Columns>
<SettingsEditing Mode="Batch" />
</dx:ASPxGridView>
The ASPxGridView raises the ASPxGridView.FocusedRowChanged event when an end user moves focus from one row to another or after the ASPxGridView.FocusedRowIndex property’s value was changed in code.
Client-side events
The ASPxClientGridView provides a set of the client-side events listed in the following tables:
Add/Delete 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. Save/Cancel changes
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/disables displaying a batch edit confirmation message. Start/End edit
Member Description ASPxClientGridView.BatchEditStartEditing Occurs when the grid is switched to batch edit mode. ASPxClientGridView.BatchEditEndEditing Occurs when the grid leaves batch edit mode. Validation
Member Description ASPxClientGridView.BatchEditRowValidating Enables you to specify whether row data is valid and provide error text.
Batch Edit Mode Limitations
There are ASPxGridView control features and API members that are not in effect in batch edit mode. All user changes are stored on the client-side.
Unsupported features
The features below are not supported when the grid is in batch edit mode:
- 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 does not 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 allows you to determine if the editor is focused (the ASPxClientEdit.GotFocus and ASPxClientEdit.LostFocus client events do not work). This imposes the the ASPxBinaryImage limitations 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.
- Negative key values are not supported. Instead, use a composite value.
- 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.
- Focus and selection of newly created rows are not supported.
- Newly created rows disappear after a callback in batch edit mode. They are visible only in Preview Changes mode.
- The ASPxGridLookup does not work in the ASPxGridView’s EditItemTemplate or DataItemTemplate in batch edit mode.
Unsupported server-side API
The following ASPxGridView members are not in effect when the grid is in batch edit mode:
Properties
Events
Methods
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:
The ASPxClientGridView.GetTopVisibleIndex property does not return the correct values if rows were deleted/inserted. Use the ASPxClientGridViewBatchEditApi.GetRowVisibleIndices instead.
The ASPxClientGridView.batchEditApi object is not in effect if the column’s Visible property is set to false.
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 the copy 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 combo boxes
How to update a master grid and its detail grids simultaneously