Data Editing

If your data source supports modification, you can utilize the dxDataGrid 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 dxDataGrid editing capabilities.

Editing in UI

Editing in a UI is specified by the fields of the editing configuration object. Among them, you can find fields that enable/disable insertion and removing, as well as editing itself. By default, all these features are disabled. In order 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
    }
});

Additionally, you can specify whether a user can edit values in a specific column. For this purpose, use the allowUpdating option of this column.

Editing in the dxDataGrid widget can be carried out in a row or batch mode. To specify the mode, set the editing | mode option to the 'row', 'batch', 'cell' or 'form' as shown in the code snippet below.

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

Each edit mode has its own set of controls appearing in a grid. Refer to the Data Modification Controls topic for more information.

Row Mode

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

  • Editing
    Each row in the row mode is supplied with the "Edit" button. When a user clicks this button, the respective row enters the editing state. At the same time, the "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 a grid row is in the editing state, 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
    To insert a new row, a user must click the "Add" button indicated by a cross glyph on a grid.

    DevExtreme DataGrid InsertionRowMode

  • Removing
    To remove a row, a user must click the "Delete" button accompanying this row. This will cause dxDataGrid 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. Using this mode prevents the data source from excessive updates when editing is performed frequently.

  • Editing
    In the batch mode, rows are edited by cells. When the user clicks a cell, it 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 saved in a buffer and the cell is marked as edited.

    DevExtreme DataGrid EditingBatchMode

  • Insertion
    To insert a new row, a user must click the "Add" button indicated on a grid by a cross glyph. The inserted row appears empty requiring the user to fill it with data. The following actions, in fact, edit this row: clicking a cell, entering a value, saving the value by clicking another cell.

    DevExtreme DataGrid InsertionBatchMode

  • Removing
    To remove a row, a user must click the "Delete" button accompanying this row. The row will be marked as removed, while the "Delete" button will be replaced by the "Undelete" button recovering the row.

    DevExtreme DataGrid RemovingBatchMode

All changes made in a grid will not be transmitted to the data source until the user clicks the "Save" button represented on a grid by a floppy disk glyph. Next to this button, the "Revert" button locates, which discards all changes. Both these buttons are inactive until a change is made. While neither saved nor discarded, edited cells, added and deleted rows are highlighted.

NOTE
If the user closes the browser before saving changes in the data source, they will be 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

    DevExtreme DataGrid InsertionRowMode

  • Removing
    To remove a row, a user must click the "Delete" button accompanying this row. This will cause dxDataGrid 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

Editing in Code

dxDataGrid 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
        }
    });