Grid in Batch Edit Mode

• Feb 02, 2024
• 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.

• ASPX

<dx:ASPxGridView ID="Grid" runat="server" ClientInstanceName="ClientGrid" ...>
    <!-- ... -->
    <SettingsEditing Mode="Batch" />
</dx:ASPxGridView>

Run Demo: ASPxGridView - Batch Edit Mode

Watch Video: Batch Editing in 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.

• ASPX

<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.

• ASPX

<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.

• ASPX

<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.

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.

• ASPX

<ClientSideEvents BatchEditStartEditing="StartEditing" />

• JS

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.

• JS

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.

• JS

function onFocusedCellChanging(s, e) {
    visibleRowIndex = e.cellInfo.rowVisibleIndex;
    if (e.cellInfo.column.fieldName === "Country") {
        e.cancel = true;
    }
}

Related Example

View Example: How to enable or disable the cell edit functionality in batch mode based on a condition

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.

• The DeleteRow(visibleIndex) and DeleteRowByKey(key) methods mark the specified row as deleted.

• The RecoverRow(visibleIndex) and RecoverRowByKey(key) methods recover the row marked as deleted.

• The StartEdit(visibleIndex, columnIndex) and StartEditByKey(key, columnIndex) methods switch the specified cell to edit mode.

Related API

Related Examples

View Example: How to implement clone functionality in batch edit mode

View Example: How to calculate values dynamically in batch edit mode

View Example: Cascading combo boxes in batch edit mode

View Example: How to use WebMethods to implement cascading combo boxes in batch edit mode

View Example: How to implement an edit item template in batch mode

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

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.

• ASPX

<ClientSideEvents BatchEditChangesSaving="ChangesSaving" />

• JS

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.

• JS

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

Related Example

View Example: A simple batch editing implementation

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.

• ASPX

<ClientSideEvents BatchEditRowValidating="RowValidating"/>

• JS

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

Related Examples

View Example: How to implement custom date validation in batch edit mode

View Example: How to validate entered cell values on the server in batch edit mode

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.

• ASPX

<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 editingIn 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

View Example: How to use and modify a control placed in DataItemTemplate

Multiple Cell Selection

In batch edit mode, ASPxGridView supports multiple cell selection.

Run Demo: ASPxGridView - Multiple Cell Selection

To enable this functionality, set the grid’s EnableMultipleCellSelection property to true.

• ASPX

<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.

View Example: How to modify cell styles dynamically in Batch Edit mode

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.

• ASPX

<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

View Example: How to implement custom buttons in the status bar in batch edit mode

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()

Unsupported Client-Side API

• IsEditing
• IsNewRowEditing
• RowDblClick