Data Editing

If your data source supports modification, you can utilize the DataGrid widget not only for displaying data, but for editing it as well. Data can be edited in code as well as in UI. Topics in the "Editing" section provide a detailed overview of DataGrid editing capabilities.

Editing in UI

The fields of the editing configuration object specify editing in a UI. Among them, you can find fields that enable/disable insertion and removing, as well as editing itself. By default, all these features are disabled. To enable them, add the following code to the grid's configuration object:

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    editing: {
        allowUpdating: true, // Enables editing
        allowAdding: true, // Enables insertion
        allowDeleting: true // Enables removing
    }
});

You can also specify whether a user can edit values in a specific column by using the allowUpdating option of this column.

Editing in the DataGrid widget can be carried out in several modes. To specify the mode, set the editing | mode option as shown in the code below.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    editing: {
        mode: 'row', // 'batch' | 'cell' | 'form' | 'popup'
        // ...
    }
});
See Also

Row Mode

In the row mode, the data source immediately reflects all changes made in grid rows after the row switches from the editing state back to the normal state.

  • Editing
    Each row in the row mode is supplied with an "Edit" button. When a user clicks this button, the respective row enters the editing state, and "Save" and "Cancel" buttons appear in place of the "Edit" button. A user must click the "Save" button to save changes or the "Cancel" button to discard them.

    DevExtreme DataGrid EditingRowMode

    NOTE
    When editing a grid row and a user clicks the "Edit" button of another row, the former one switches its state to normal. All changes made in this row (if any) vanish.
  • Insertion
    A user must click the "Add" button indicated by a cross glyph on a grid to insert a new row.

    DevExtreme DataGrid InsertionRowMode

  • Removing
    To remove a row, a user must click the "Delete" button accompanying this row which causes the DataGrid to display a pop-up window requesting the user to confirm the deletion of the row.

    DevExtreme DataGrid RemovingRowMode

View Demo

Batch Mode

In the batch mode, changes are buffered before being transmitted to the data source to prevent the data source from excessive updates when it is frequently edited.

  • Editing
    Cells edit rows in the batch mode. When a user clicks a cell, it enters the editing state, and the user can change its value. To return the cell to its normal state, the user clicks another cell or any other area in the grid. This saves the changes made to the cell in a buffer and marks the cell as edited.

    DevExtreme DataGrid EditingBatchMode

  • Insertion
    A user must click the "Add" button indicated on a grid by a cross glyph to insert a new row. The new row is empty, and the user can fill it with data. The same editing rules as described above apply to this new row.

    DevExtreme DataGrid InsertionBatchMode

  • Removing
    A user must click the "Delete" button accompanying this row to remove a row. This marks it as removed, and the "Undelete" button for recovering the row replaces "Delete" button.

    DevExtreme DataGrid RemovingBatchMode

All changes made in a grid do not transmit to the data source until the user clicks a floppy disk glyph that represents the "Save" button on a grid. The "Revert" button which discards all changes is next to this button, and they are both inactive until a change is made. New and edited cells and deleted rows are highlighted while changes are not saved or discarded.

NOTE
If the user closes the browser without saving changes, they are lost.

View Demo

Cell Mode

In cell mode, all changes made in grid cells are reflected in the data source immediately after the cell switches from the editing state back to the normal state.

  • Editing
    When a user clicks a cell, the latter enters the editing state where the user changes its value. To switch the cell back to the normal state, the user clicks another cell or any other area of the grid. After that, changes made in the cell are instantly reflected in the data source. To switch the cell back to the normal state without saving changes, use the Esc key.

    NOTE
    If validation is configured for the data grid, an end-user will be locked in the cell's editing state until he/she enters a valid value or clicks the "Cancel Changes" button.
    See Also

    DevExtreme DataGrid EditingRowMode

  • Insertion
    To insert a new row, a user must click the "Add" button indicated by a cross glyph on a grid. The new row will be added to the data source after losing focus.

    NOTE
    If validation is configured for the data grid, an end-user will be locked in the row's editing state until he/she enters valid values or cancels the row insertion using the "Cancel Changes" button of any invalid cell.
    See Also
    • [Data Validation](/Documentation/Guide/Widgets/Common/UI_Widgets/Data Validation/)

    DevExtreme DataGrid InsertionRowMode

  • Removing
    To remove a row, a user must click the "Delete" button accompanying this row. This will cause DataGrid to display a pop-up window requesting that the user confirms the deletion of the row.

    DevExtreme DataGrid RemovingRowMode

View Demo

Form Mode

The form editing mode is technically equivalent to the row mode. The only difference is a visual presentation of a row in the editing state.

When a row is being edited in the form mode, it transforms into a form as shown at the screenshot below.

View Demo

Popup Mode

The popup mode is the form mode with the form placed in a popup window.

Form - Popup Editing Mode

View Demo

Editing in Code

DataGrid provides API methods for editing, inserting and removing data from code.

  • Editing
    In the row edit mode, to switch a row into the editing state, call the editRow(rowIndex) method. To switch it back to the normal state, call either the saveEditData() or cancelEditData() methods depending on whether changes must be saved or discarded.

    In the batch edit mode, to switch a cell into the editing state, call the editCell(rowIndex, columnIndex) method. To switch it back to the normal state, call the closeEditCell() method. After editing is completed, call either saveEditData() or cancelEditData() to save or cancel all changes in the data source.

  • Insertion
    To insert a new empty row into a grid, call the addRow() method.

  • Removing
    To remove a row, call the deleteRow(rowIndex) method with the index of the row to be removed passed as the parameter. If you have set the batch edit mode, you can recover a removed row. For this purpose, call the undeleteRow(rowIndex) method.

The aforesaid methods accept a row index or a column index as their parameters. When calculating the row index, note that if you have several pages in a grid, grid rows are indexed beginning with 0 on each page. If you use grouping in your grid, group rows are counted too and thus have row indexes, although they cannot be edited. As calculating the column index tends to be slightly more complicated, see the Calculating the Column Index topic to learn how to do it.

Handling Editing Events

While modifying data (either through editing, insertion or deletion) a number of events are raised that you can handle. The options that allow you to handle these events are listed below. Each option accepts a callback function that performs actions required by you.

  • Editing Events
    When editing has been initiated by a user or in code, the editingStart event fires. Within the function handling this event, you can manipulate the row (in row edit mode and form edit mode) or its cell (in batch edit mode) that is about to enter the editing state. You can also prevent the row or cell from entering the editing state using the cancel field of the object passed to the editingStart handler as the argument.

    JavaScript
    $("#gridContainer").dxDataGrid({
        // ...
        onEditingStart: function (info) {
            info.cancel = true
        }
    });

    When editing is complete, changes must be transmitted to the data source. But first, a function handling the rowUpdating event is executed. Within this function, you can also cancel the updating of the data source or change the data that must be transmitted to it using the fields of the object passed to this function as the argument.

    JavaScript
    $("#gridContainer").dxDataGrid({
        // ...
        onRowUpdating: function (info) {
            // specify required actions here
        }
    });

    After the data source has been updated, the rowUpdated event fires. To handle this event, assign a function to the onRowUpdated option. When implementing this function, you can use the updated data and the key of the row whose data has been updated. To access them, use the fields of the function's argument as you would other event-handling functions.

    JavaScript
    $("#gridContainer").dxDataGrid({
        // ...
        onRowUpdated: function (info) {
            // specify required actions here
        }
    });
  • Insertion Events
    When inserted, a new row appears empty in a grid. If you need to initialize it, implement a function handling the initNewRow event and assign it to the onInitNewRow option. Populate the data field of the object, which is passed to this function as the argument, with data in such a manner that its fields correspond to the fields of a data source object.

    JavaScript
    $("#gridContainer").dxDataGrid({
        // ...
        onInitNewRow: function (info) {
            info.data = {
                field1: 'data1',
                field2: 'data2',
                // ...
            }
        }
    });

    Before an inserted row is transmitted to the data source, the rowInserting event will fire. To handle it, implement a function and assign it to the onRowInserting option. Within this function, you can cancel the insertion of the new row or change its data using the fields of the object passed to this function as the argument.

    JavaScript
    $("#gridContainer").dxDataGrid({
        // ...
        onRowInserting: function (info) {
            // specify required actions here
        }
    });

    After a row has been inserted into the data source, the rowInserted event fires. When implementing a handling function for this event, you can use the data and the key of this row. To access them, use the fields of the function's argument similarly to other event-handling functions.

    JavaScript
    $("#gridContainer").dxDataGrid({
        // ...
        onRowInserted: function (info) {
            // specify required actions here
        }
    });
  • Removing Events
    Before a row is removed from a data source, the rowRemoving event fires. To handle this event, implement a function and assign it to the onRowRemoving option. Within this function, you can cancel the removing of the row or manipulate it with data using the fields of the object passed to this function as the argument.

    JavaScript
    $("#gridContainer").dxDataGrid({
        // ...
        onRowRemoving: function (info) {
            // specify required actions here
        }
    });

    After a row has been removed from the data source, the rowRemoved event fires. To handle this event, implement a function and assign it to the onRowRemoved option. When implementing this function, you can use the data and the key of the removed row. To access them, use the fields of the function's argument similarly to other event-handling functions.

    JavaScript
    $("#gridContainer").dxDataGrid({
        // ...
        onRowRemoved: function (info) {
            // specify required actions here
        }
    });