Grid in Batch Edit Mode
- 10 minutes to read
In batch edit mode, ASPxGridView allows users to modify data in batches and send them to the server in one request.
To enable the batch edit mode, set the ASPxGridView.SettingsEditing.Mode property to Batch.
<dx:ASPxGridView ID="Grid" runat="server" ClientInstanceName="ClientGrid" ...>
<!-- ... -->
<SettingsEditing Mode="Batch" />
</dx:ASPxGridView>
Edit Data in the UI
In batch edit mode, a user focuses a cell and clicks it to start editing. To change the user action that shows an editor, specify the grid’s StartEditAction property.
<SettingsEditing Mode="Batch">
<BatchEditSettings StartEditAction="Click" />
</SettingsEditing>
The image below illustrates the grid behavior when its EditMode property is set to Cell – the Grid View shows an editor for one focused cell.
If you set the control’s EditMode property to Row, the grid shows in-place editors for all editable cells in a row.
<SettingsEditing Mode="Batch">
<BatchEditSettings EditMode="Row"/>
</SettingsEditing>
To insert and delete rows, the grid displays the New and Delete command buttons. To specify the visibility of these buttons, use the ShowNewButton, ShowNewButtonInHeader, and ShowDeleteButton properties.
<Columns>
<dx:GridViewCommandColumn ShowDeleteButton="true" ShowNewButtonInHeader="true" />
<!-- ... -->
</Columns>
The grid also allows users to use a keyboard to navigate through data cells and switch them to edit mode.
| Key | Action |
|---|---|
| Arrow Keys | Move 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 | Marks the current row as deleted. |
Disable Cell/Row Editing
To prevent a user from editing a cell or row in ASPxGridView, you can set the cancel property to true in a BatchEditStartEditing event handler.
<ClientSideEvents BatchEditStartEditing="StartEditing" />
function StartEditing(s, e) {
if (e.focusedColumn.fieldName === "Country")
e.cancel = true;
}
When the control’s EditMode property is set to Row, the grid shows in-place editors for all editable cells in the row. To delete the specified cell from the range of editable cells, use the rowValues argument property in a BatchEditStartEditing event handler.
function StartEditing(s, e) {
var columnIndex = ClientGrid.GetColumnByField('Country').index;
delete e.rowValues[columnIndex];
Disable Cell Focus
To prevent a user from focusing a cell, you can set the cancel property to true in a handler of the grid control’s FocusedCellChanging event.
function onFocusedCellChanging(s, e) {
visibleRowIndex = e.cellInfo.rowVisibleIndex;
if (e.cellInfo.column.fieldName === "Country") {
e.cancel = true;
}
}
Related Example
Edit Data in Code
Use the following ASPxClientGridViewBatchEditApi members to modify data batches in code:
The AddNewRow method inserts a new row and shows an in-place editor.
ClientGrid.batchEditApi.AddNewRow();The DeleteRow(visibleIndex) and DeleteRowByKey(key) methods mark the specified row as deleted.
ClientGrid.batchEditApi.DeleteRow(rowIndex);The RecoverRow(visibleIndex) and RecoverRowByKey(key) methods recover the row marked as deleted.
ClientGrid.batchEditApi.RecoverRow(rowIndex);The StartEdit(visibleIndex, columnIndex) and StartEditByKey(key, columnIndex) methods switch the specified cell to edit mode.
ClientGrid.batchEditApi.StartEdit(rowIndex);
Related API
| Member | Type | Description |
|---|---|---|
| BatchEditRowInserting | Event | Fires before a data row is inserted in batch edit mode. |
| BatchEditRowDeleting | Event | Fires on the client side before a data row is marked as deleted in batch edit mode. |
| BatchEditRowRecovering | Event | Fires on the client side before a data row is recovered in batch edit mode. |
| BatchEditStartEditing | Event | Fires when a cell/row switches to batch edit mode and allows you to disable cell/row editing. |
| BatchEditEndEditing | Event | Fires before a cell/row switches from edit to browse mode. |
| GetCellValue / GetCellValueByKey | Method | Gets the value of the specified cell. |
| IsDeletedRow / IsDeletedRowByKey | Method | Indicates whether the specified row is marked as deleted in batch edit mode. |
| IsNewRow | Method | Indicates whether the specified row is newly inserted. |
| SetCellValue / SetCellValueByKey | Method | Assigns a new value to the specified cell in batch edit mode. |
Related Examples
Preview Changes
In batch edit mode, ASPxGridView keeps changes on callbacks when a user interacts with unsaved modified data (for instance, when a user navigates to another page within the grid or sorts data).
If the control’s KeepChangesOnCallbacks property is enabled, the grid displays the Preview changes button in the Status Bar. When a user clicks this button, the grid shows only modified rows from all its pages.
Related API
| Member | Type | Description |
|---|---|---|
| BatchEditChangesPreviewShowing | Event | Fires before the grid switches to Preview Changes mode. |
| BatchEditChangesPreviewShown | Event | Fires after the grid switches to Preview Changes mode. |
| ShowChangesPreview | Method | Switches the grid to Preview Changes mode. |
| HideChangesPreview | Method | Switches the grid from Preview Changes to browse mode. |
Save and Discard Changes
When a user clicks the Save changes button or you call the control’s client-side UpdateEdit method, the grid raises the BatchEditChangesSaving event. Use the insertedValues, updatedValues, and deletedValues argument properties to obtain information about modified data.
<ClientSideEvents BatchEditChangesSaving="ChangesSaving" />
function ChangesSaving(s, e) {
var updatedValues = e.updatedValues;
var insertedValues = e.insertedValues;
var deletedValues = e.deletedValues;
// ...
}
Alternatively, you can call the GetUnsavedChanges method to get a hash table of inserted, updated, and deleted values.
var batchEditChanges = ClientGrid.batchEditApi.GetUnsavedChanges();
When a user clicks the Cancel changes button or you call the control’s client-side CancelEdit method, the grid raises the BatchEditChangesCanceling event.
Related API
| Member | Type | Description |
|---|---|---|
| BatchUpdate | Event | Fires on the server side before the grid saves changes and allows you to implement custom updating rules. |
| BatchEditConfirmShowing | Event | Fires before the grid shows the Confirmation dialog box. |
| BatchEditRowChangesCanceling | Event | Fires when a user clicks a row’s Cancel button in batch edit mode. |
| HasChanges | Method | Indicates whether the grid or the specified row/cell has unsaved changes in batch edit mode. |
| HasChangesByKey(key) | Method | Indicates whether the specified row or cell has unsaved changes in batch edit mode. |
| ResetChanges(visibleIndex) / ResetChangesByKey(key) | Method | Resets changes in the specified cell. |
Related Example
Validate Data
To validate data in batch edit mode, the grid raises the BatchEditRowValidating event in the following cases:
- A cell or row switches from edit to browse mode.
- A user clicks the Save changes button or you call the grid’s client-side UpdateEdit method.
- The grid switches to Preview Changes mode.
- You call the ValidateRow(visibleIndex), ValidateRowByKey(key), or ValidateRows method.
In a BatchEditRowValidating event handler, you can use the validationInfo argument property to get information about the modified row. This property also allows you to define whether the data is valid and specify an error text string for invalid data cells.
<ClientSideEvents BatchEditRowValidating="RowValidating"/>
function RowValidating(s, e) {
for (var columnIndex in e.validationInfo) {
var validationInfo = e.validationInfo[columnIndex];
if (validationInfo.value === null) {
validationInfo.isValid = false;
validationInfo.errorText = "Invalid data";
}
}
}
Related API
| Member | Description |
|---|---|
| AllowValidationOnEndEdit | Specifies whether to validate data when a cell/row/record switches from edit to browse mode. |
| AllowEndEditOnValidationError | Specifies whether an editor can lose focus when validation fails. |
| ErrorImagePosition | Gets or sets the position of the validation error image relative to the editor content. |
Related Examples
Implement a Data Item Template
In batch edit mode, ASPxGridView copies only HTML markup of the template and disables its client-side functionality. When a cell switches to edit mode, the grid shows an in-place editor to modify data. When the cell value changes and the cell switches to browse mode, the grid replaces the template content with the entered value.
You can change this behavior in the following ways:
- Allow the grid to render the template content after cell editing ends
To enable this behavior, set the control’s AllowRegularDataItemTemplate property to
true.<dx:ASPxGridView ID="Grid" runat="server" ..."> <Columns> <dx:GridViewDataTextColumn FieldName="TemplatedColumn" /> <DataItemTemplate> <!-- ... --> </DataItemTemplate> </dx:GridViewDataTextColumn> </Columns> <SettingsEditing Mode="Batch"> <BatchEditSettings AllowRegularDataItemTemplate="true" /> </SettingsEditing> </dx:ASPxGridView>- Disable cell editing
- In this mode, the templated cell is non-editable but the client-side functionality of the template’s UI elements is available. For more information, refer to the following topic: Data Item Template.
To get a container object in batch edit mode, call the GetCellTextContainer(visibleIndex, columnFieldNameOrId) or GetCellTextContainerByKey(key, columnFieldNameOrId) method.
Related Example
Multiple Cell Selection
In batch edit mode, ASPxGridView supports multiple cell selection.
To enable this functionality, set the grid’s EnableMultipleCellSelection property to true.
<SettingsEditing Mode="Batch">
<BatchEditSettings EnableMultipleCellSelection="true"/>
</SettingsEditing>
When the cell selection changes, the grid raises the CellSelectionChanging event. You can get the current selection state of the processed cell in a handler of this event and cancel the selection change.
Call the SelectCell(visibleIndex, rowIndex) or UnselectCell(visibleIndex, rowIndex) method to select or deselect a cell.
Customize the Grid Appearance and Layout
In batch edit mode, ASPxGridView highlights modified cells, as well as inserted and deleted rows.
The table below lists the properties that allow you to customize the grid appearance in batch edit mode.
| Member | Description |
|---|---|
| HighlightDeletedRows | Specifies whether the grid highlights deleted rows. |
| BatchEditModifiedCell | Specifies the appearance of modified data cells. |
| BatchEditModifiedCellStyle | Specifies the appearance of the column’s modified data cells. |
| BatchEditNewRow | Specifies the appearance of inserted rows. |
| BatchEditDeletedRow | Specifies the appearance of deleted rows. |
| BatchEditChangesPreviewGroupRow | Specifies the appearance of group rows when the grid is in Preview Changes mode. |
| FocusedCell | Specifies the appearance of the focused data cell. |
Display a Custom Toolbar
ASPxGridView allows you to control the visibility of the Status Bar where the grid displays the Preview changes, Save changes, and Cancel changes buttons. You can set the ShowStatusBar property to Hidden to hide the Status Bar and create a custom toolbar with command buttons. To display the toolbar in Preview Changes mode, enable the item’s VisibleInBatchEditPreviewChanges property.
<Toolbars>
<dx:GridViewToolbar>
<Items>
<dx:GridViewToolbarItem Text="Edit commands" Command="Custom"
VisibleInBatchEditPreviewChanges="true">
<Items>
<dx:GridViewToolbarItem Command="PreviewChanges" />
<dx:GridViewToolbarItem Command="HidePreview" />
<dx:GridViewToolbarItem Command="Update" />
<dx:GridViewToolbarItem Command="Cancel" />
</Items>
</dx:GridViewToolbarItem>
</Items>
</dx:GridViewToolbar>
</Toolbars>
<Settings ShowStatusBar="Hidden" />
Related Example
Limitations
In batch edit mode, ASPxGridView has the following limitations:
- For newly inserted rows, disables row focus and selection, and does not show the expand button until these rows are saved.
- Hides newly inserted rows if the grid sends a callback to the server (for instance, when a user sorts data or navigates to another grid page). These rows are visible in Preview Changes mode.
- When users edit a GridViewDataDropDownEditColumn cell value and focus the drop down window’s content, the grid moves focus back to the cell and prevents users from changing the window’s content.
- The GridViewCommandColumn.CustomButton.Visibility property has no effect.
- batchEditApi method calls have no effect if the column’s Visible property is set to
false. - ASPxGridLookup does not work when you place it in a grid column’s edit item or data item template.
- Navigation between cells and rows does not work for GridViewDataBinaryImageColumn.
- A GridViewDataBinaryImageColumn cell does not switch to browse mode after it loses focus.
- Does not support negative key values. Use composite values instead.
Unsupported features
- Cell merge.
- The date range functionality of embedded date editors when the grid’s EditMode property is set to
Cell. - Tabular navigation through non-editable cells (for instance, group row cells or expand buttons).
Unsupported Server-Side API
- EditingRowVisibleIndex
- IsEditing
- IsNewRowEditing
- InitNewRow
- CellEditorInitialize
- StartEdit(Int32)
- AddNewRow()
- UpdateEdit()