Data Management

This topic provides a detailed overview of dxDataGrid data management capabilities, including grouping, sorting, editing, etc. Most of these operations can be conducted from the user interface as well as in code. Refer to the corresponding topic to get full information about the operation of your interest.

Filtering

When a grid contains thousands of records, it may be hard to find the needed ones using scrolling or pager navigation. For those times, the dxDataGrid widget offers its filtering capabilities.

An end-user performs filtering using a filter row. To filter records by a column, the end-user must type a value or a part of it (depends on the data type) in a corresponding filter row cell. If any records are found, then the grid will contain only them. Otherwise, it displays the "No Data" message.

NOTE: Filtering is performed ignoring the letter case.

Usually, a filter row cell is a text box. But in some cases, a filter row cell is represented by a control more suitable for filtering in the particular column. For example, when the dataType option of a column is 'date', its filter row cell contains a calendar allowing a user to choose a date. Another example is a select box that appears in a filter row cell if the column's dataType is 'boolean', or if a lookup column is used.

Different filter operations may be applied to a column. To change the current filter operation, the user must choose a required item from a filtering menu. This menu is invoked when the user hovers the mouse pointer over the magnifying glass icon of a filter row cell. Operations available using this menu depend on the data type of a column and vary from type to type, as well as the default filter operation. After a filter operation is applied, the default operation can be restored by choosing the "Reset" item in the filtering menu. The following table represents filter operations by data types.

dataType Available filter operations Default filter operation
'string' 'contains' | 'notcontains' | 'startswith' | 'endswith' | '=' | '<>' 'contains'
'number' '=' | '<>' | '<' | '>' | '<=' | '>=' '='
'date' '=' | '<>' | '<' | '>' | '<=' | '>=' '='

To try filtering in action, see the demo below. To discover more about dxDataGrid filtering capabilities and how to configure them, see the following subtopics.

Show Example:
jQuery

Filtering in UI

Filtering in a UI is considered enabled when the filter row is made visible by setting the filterRow | visible option to true.

See Also

For information on how to configure the filter row, refer to the Filter Row topic.

If the filter row is visible, filtering is enabled for all grid columns. However, you can disable it for individual columns by setting their allowFiltering option to false.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    filterRow: { visible: true },
    columns: [{
        allowFiltering: false,
        // ...
    }, //...
    ]
});

The set of filter operations appearing in the filtering menu may be corrected. For this purpose, assign an array of required operations to the filterOperations option of a column. To apply one of these operations initially, specify the selectedFilterOperation option of the same column.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    columns: [{
        filterOperations: [ 'contains', 'startswith', '=' ],
        selectedFilterOperation: 'contains',
        // ...
    }, //...
    ]
});

There may be cases when a user must be able to apply a filter, but not to change the filter operation. In these cases, assign an empty array to the filterOperations option and specify the current filter operation using the selectedFilterOperation option.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    columns: [{
        filterOperations: [],
        selectedFilterOperation: 'contains',
        // ...
    }, //...
    ]
});

Filtering may operate incorrectly in a column with calculated values. To restore this functionality, implement the calculateFilterExpression callback function. This function must return an array of the following items.

  1. The data source field or a function providing actual values for a grid column. Commonly, the calculateCellValue function is passed here.
  2. The comparison operator. The following operators are available: "=", "<>", ">", ">=", "<", "<=", "startswith", "endswith", "contains", "notcontains".
  3. The value typed into a filter row cell. The actual values will be compared to this value.

The following code snippet demonstrates a common example of implementing the calculateCellValue and calculateFilterExpression functions.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    columns: [{
        calculateCellValue: function (rowData) {
            return rowData.Amount * rowData.Cost;
        },
        calculateFilterExpression: function (filterValue, selectedFilterOperation) {
            return [this.calculateCellValue, selectedFilterOperation || '=', filterValue];
        },
        // ...
    }, //...
    ]
});

Filtering in Code

To apply a filter in code, call the filter(filterExpr) method. Pass an array with the following members to this method.

  1. The data source field by which data items are filtered.
  2. The comparison operator. The following operators are available: "=", "<>", ">", ">=", "<", "<=", "startswith", "endswith", "contains", "notcontains".
  3. The value with which data source field values should be compared.

For example, the following call leaves only those records that have a value of more than 20 in the 'Amount' field.

JavaScript
dataGridInstance.filter(['Amount', '>', 20]);

To clear a programmatically applied filter, call the clearFilter() method.

JavaScript
dataGridInstance.clearFilter();

A user-specified filter can also be cleared from code. For this purpose, assign undefined to the filterValue option of the required column using the columnOption method.

JavaScript
dataGridInstance.columnOption('columnId', 'filterValue', undefined);

Setting Initial Filtering

If a filter must be applied to a column initially, set the filterValue option of this column. This value is applied using a filter operation specified by the selectedFilterOperation option. Note that the allowFiltering option of this column must be true. The following code leaves only those records, whose value in the "Data" column equals 10.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    columns: [{
        dataField: 'Data',
        selectedFilterOperation: '=',
        filterValue: 10
        // ...
    }, //...
    ]
});

To make initially set filtering impossible for a user to change, hide the filter row by setting the filterRow | visible option to false.

Searching

Filtering can be performed in one or several columns at a time. In addition, dxDataGrid provides you with the capability to filter records by all columns at once, i.e., to search records. In dxDataGrid, searching is performed using a search panel. To search records, a user types a text in it. Records that match this text are displayed in a grid.

See Also

To find information on configurable features of the search panel, refer to the Search Panel topic.

Searching is conducted differently in columns with different data types. To find a record by a numeric, boolean or date value, a user must enter the full value into the search panel. To find a record by a string value, entering a part of this value is sufficient.

Although by default searching is performed in all columns, you can disable it in certain columns. Since searching is filtering, both these operations are controlled by the same allowFiltering option.

Searching can also be conducted in code using the searchByText(text) method. To clear searching settings, call the same method with an empty string as the argument.

To try searching in action, open the demo below and type a text in the search panel.

Show Example:
jQuery

Grouping

dxDataGrid provides you with the capability to group grid records by values of a single or multiple columns. When grouping is applied, records with identical values in the same column or several columns are combined into one or several corresponding groups. Visually, groups are separated one from another by a group row containing a grouping value. This topic gathers information about settings that define user-specified grouping and methods that can be used to apply grouping in code.

To group records, a user must drag-and-drop a column header to the group panel. Dragging the column header back from the group panel ungroups records.

DevExtreme DataGrid Grouping

Groups in a grid are always sorted even if sorting was not applied to a column used in grouping before it was moved to the group panel. By default, groups are sorted in ascending order. To change this, a user must click the header of the grouping column.

NOTE: When moving a column back from the group panel, its resulting location depends on the allowColumnReordering option. If this option is true, the column will be placed exactly where its header is dropped. If false, the column will have a location according to the order of columns in the columns array.

Grouping in UI

To enable grouping in the UI, simply make the group panel visible using the groupPanel | visible option. If this feature is not required, hide the group panel using the same option or disallow column dragging for the group panel using the groupPanel | allowColumnDragging option.

See Also

For more information on configurable features of the group panel, refer to the Group Panel topic.

Additionally, individual columns can be prevented from being used in grouping. For these columns, the allowGrouping option must be set to false.

Grouping in Code

If required, you can apply grouping in code. For this purpose, assign an integer number to the groupIndex option of a required column using the columnOption method. To ungroup records, assign undefined to this option using the same method.

For more information on how to calculate the group index, refer to the Calculating the Group Index subtopic.

Calculating the Group Index

A group index is an integer number greater or equal to 0 that indicates the grouping order. The group index is used when specifying an initial grouping order or expanding/collapsing groups in code. Columns that are not used in grouping have the undefined group index. The following image illustrates how to calculate the group index.

DevExtreme DataGrid GroupIndexes

Expanding and Collapsing Groups

Groups can be either expanded or collapsed. When expanded, a group is represented by a group row and data rows matching the grouping value. When collapsed, a group is represented by a group row only.

DevExtreme DataGrid Groups

See Also

For more information about group rows, refer to the Group Rows topic.

Groups in a grid may appear expanded or collapsed initially. To specify this for all groups, use the autoExpandAll option of the grouping object. If you need to specify this setting for an individual column, use the autoExpandGroup option of this column.

To expand or collapse a group, a user must click the arrow accompanying its group row, or press ENTER when the group row is in focus.

The same operation can be performed in code by calling the expandAll(groupIndex) and collapseAll(groupIndex) methods. To discover how to calculate the group index, which is passed to these methods, refer to the Calculating the Group Index subtopic. Calling these methods without argument expands/collapses all groups.

Setting Initial Grouping

Grouping can be applied not only at runtime, but also at design time. To do this, assign an integer value to the groupIndex option of those columns that must be used in grouping. Note that grouping order is based on those values. For information about calculating the group index, see the Calculating the Group Index subtopic.

Additionally, you can make the initially set grouping invariable. For this purpose, assign false to the allowGrouping option of the columns used in grouping. In this case, make the group panel visible, but block it by assigning false to the groupPanel | allowColumnDragging option. Thus, a user is notified about the applied grouping, but cannot change it.

Sorting

Initially, grid records appear in an order specified in the data source. At runtime, these records can be sorted. To sort records by a column, a user must click its header. First click on the header applies an ascending sort order to the column. Each subsequent click reverses the sort order. When records are sorted by a column, its header is marked with an arrow.

DevExtreme DataGrid Sorting

To clear the applied sorting settings, a user must choose "Clear Sorting" in a context menu that appears after a right-click on a column header.

DevExtreme DataGrid SortingContextMenu

Detailed information about different sorting modes, options and methods that apply and clear sorting in code is given in the following subtopics.

Sorting in UI

In dxDataGrid, records can be sorted by a single or multiple columns. To set an appropriate sorting mode, use the mode field of the sorting configuration object.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    sorting: {
        mode: 'single' // or 'multiple'
    }
});

Single Mode

By default, a single mode is set. In this mode, records can be sorted only one column at a time. Applying sorting to a column clears sorting settings of other columns. Also, a context menu, which appears when you right-click a column header, can be used to apply or clear sorting settings of a column. The following animation shows the entire process of sorting in the single mode.

DevExtreme DataGrid SortingSingleMode

Multiple Mode

In a multiple mode, when a user clicks column headers, the grid behaves like the sorting mode is single (see the previous subtopic). To sort records by multiple columns, the user must set their sort orders using the context menu mentioned earlier. Obviously, sorting settings can be cleared using this menu. Left-clicking a column header brings single-like sorting behavior back. The process of sorting in the multiple mode is illustrated by the animation below.

DevExtreme DataGrid SortingSingleMode

If sorting must not be permitted for a user, disable it by setting the sorting | mode option to 'none'. You still will be able to apply sorting in code.

The process of applying sorting can be simplified if the user has the keyboard. For more information on using the keyboard for sorting, see the Using Keyboard to Apply Sorting article.

Sorting in Code

Not only a user can sort records via the interface of dxDataGrid, but you can apply sorting from code as well. To perform this operation on a column, change its sortOrder option using the columnOption method. Note that changing this option for multiple columns in a row applies sorting for all of them sequentially.

To specify the sequence of applying sorting to columns, assign sort indexes to these columns in addition to the sort order. The sort index is specified by the sortIndex option, which can also be changed by calling the columnOption method. Since setting the sort index is useless without specifying the sort order, it is recommended to call the columnOption method in a manner shown below. Note that the calls of the columnOption method are wrapped in the beginUpdate() - endUpdate() construction in order to prevent the widget form unnecessary updating.

JavaScript
dataGridInstance.beginUpdate();
dataGridInstance.columnOption('columnId', 'sortIndex', 0);
dataGridInstance.columnOption('columnId', 'sortOrder', 'asc');
dataGridInstance.endUpdate();

To clear sorting settings of a column, assign undefined to the sortIndex option of this column using the columnOption method.

Setting Initial Sorting

To specify sorting settings for a column at design-time, use the sortOrder option of this column. If you are applying sorting to a single column, setting this option is sufficient. If you require multiple initial sorting, you may want to specify the sequence of applying it to grid columns. In that case, specify the sortIndex option in addition to sortOrder.

Additionally, you can make the initially set sorting impossible for an end-user to change. For this purpose, assign false to the allowSorting option of the columns with sorting applied, or turn the sorting off completely by setting the sorting | mode option to 'none'.

Using Keyboard to Apply Sorting

If an end-user is equipped with a keyboard, he or she can clear and apply sorting to multiple columns without using the context menu. In this instance, the user must click a column header with the CTRL key pressed to clear sorting settings of the column.

When multiple sorting is allowed, the first click on a column header with the SHIFT key pressed applies sorting in the ascending order to this column. Subsequent clicks with SHIFT pressed reverses the sort order. In that case, the existing sorting settings of other columns are preserved.

Data Navigation

In order to provide the best usability, data in a grid is divided into pages containing a reasonable number of records. This feature noticeably improves the performance of the dxDataGrid widget. Paging settings are specified by the fields of the paging configuration object.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    paging: {
        // Paging settings are specified here
    }
});

To specify the number of records one page contains, assign an integer number to the pageSize field of this object.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    paging: {
        pageSize: 10
    }
});

A grid can start displaying data from a particular page. To specify the page, use the pageIndex field of the paging object. Note that the page index is zero-based. Thus, page 1 has index 0, page 2 - index 1, etc. For example, the following code specifies the page 10 to be displayed initially.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    paging: {
        pageIndex: 9
    }
});

When you do not need paging, disable it by setting the paging | enabled field to false. Note that in this case, all data will be loaded at once, which may affect grid performance.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    paging: {
        enabled: false
    }
});

In the following subtopics, you will learn to configure and use scrolling and pager navigation.

Pager Navigation

A user can navigate through data using a pager consisting of a page navigator and a page selector. To switch between pages, the user must choose a required page number from the page navigator. To change the page size at runtime, the user can choose one of predefined page sizes from the page size selector.

See Also

Refer to the Pager topic for a detailed description of the pager and its configurable features.

NOTE: In order to use the pager, data paging must be enabled.

Show Example:
jQuery

Scrolling

Scrolling allows an end-user to browse through grid records without being distracted by the necessity of switching pages. Vertical and horizontal scrolling may be present in a grid. Moreover, vertical scrolling can function in several modes. Scrolling cannot be performed in code.

NOTE: In dxDataGrid documentation, the word "scrolling" without specification refers to vertical scrolling. When horizontal scrolling is in question, this fact is stressed.

See the following subtopics to learn how to specify the required mode of vertical scrolling and discover settings that may lead to the appearance of horizontal scrolling.

Vertical Scrolling

Vertical scrolling is the main type of scrolling that enables a user to navigate through grid records. To scroll, the user can drag a scroll bar, which is located on the right side of a grid, or use the mouse wheel.

dxDataGrid supports three modes of vertical scrolling: standard, virtual and infinite. To specify the scrolling mode, set the mode option of the scrolling object.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    scrolling: {
        mode: 'standard' // 'virtual' || 'infinite'
    }
});
  • Standard Mode
    In a standard scrolling mode, the grid loads one page at a time. This operation may affect grid performance as the loaded page may contain many grid records. Moreover, if the pager is disabled, a user can only see the first page. Thus, using this mode is recommended only when you have a small data source or display a large data source using the pager for navigation purposes.

  • Virtual Mode
    In a virtual scrolling mode, the grid loads pages at runtime when they get into its field of vision. Once a page is out of the field of vision, it is removed from the grid. This behavior allows an end-user to scroll through large amounts of grid records without notable lags. To specify the size of the loaded pages, use the paging | pageSize option. Note that in this scrolling mode, the scroll bar is positioned considering the total number of grid records. This feature allows the user to move from the first to the last grid record promptly even when there are thousands of records between them.

  • Infinite Mode
    If it is necessary to move gradually from the beginning to the end of the grid, use scrolling in the infinite mode. Grid pages in this mode are loaded when the scroll bar reaches the end of its scale. This scrolling mode requires paging to be enabled. The size of a page is specified by the pageSize option as well.

    NOTE: Avoid using infinite scrolling in conjunction with pager navigation or grouping.

To spot the difference between those scrolling modes, see the demo below.

Show Example:
jQuery

Horizontal Scrolling

In addition to the vertical scrolling, an end-user may encounter horizontal scrolling, which allows users to browse columns that are concealed because they extend beyond the borders of the widget container. This type of scrolling is rather rare and cannot be configured by any options. It appears when the total width of grid columns exceeds the width of the widget container, which might occur in two cases:

  • when you have specified constant widths for all grid columns;
  • when the width of columns is calculated on the base of their content. It is the result of setting the columnAutoWidth option to true.

Switching Pages in Code

Regardless of the way you choose to browse data in your grid, switching between pages is available in code. dxDataGrid provides the pageIndex method for this purpose. Being called without arguments, this method returns the index of the current page. To switch the grid to a required page, pass the index of this page to this method. Note that the page index is zero-based. Thus, page 1 has index 0, page 2 - index 1, etc. For example, the following code switches the grid to page 10.

JavaScript
dataGridInstance.pageIndex(9);

Selection

Selection is a dxDataGrid feature that allows an end-user to mark certain rows in a grid as selected. Selected rows have a differing appearance from regular rows. After a row is selected, its data may be processed the way you require.

NOTE: Only data rows can be selected.

In the following subtopics, you will learn how to configure selection in a UI and in code, select rows initially and use the keyboard to perform selection.

Selecting in UI

Selection in the dxDataGrid widget can be carried out in a single or multiple mode. To specify the mode, set the selection | mode option to either 'single' or 'multiple' as shown in the code snippet below. Setting this option is obligatory, because selection is disabled by default.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    selection: {
        mode: 'single' // 'multiple'
    }
});

Single Mode

A single mode is preferable when you only need one grid row to be selected at a time. To select a row in this mode, an end-user must click this row. When a user clicks another row, the formerly selected one becomes unselected.

Additionally, a selected row can be deselected by a mouse click as you press the CTRL key. For information on keyboard shortcuts in dxDataGrid, see the Keyboard Navigation and Selecting Using Keyboard Shortcuts topics.

The animation below demonstrates how to perform selection in a single mode.

DevExtreme DataGrid Selection

Multiple Mode

When you need to select several rows at once, set the multiple selection mode. This mode supplements a grid with a selection column that contains check boxes accompanying each grid row. A user can select rows using these check boxes. In a multiple mode, when a user clicks different rows, the grid behaves like the selection mode is single (see the previous subtopic), but once the user clicks a checkbox, grid behavior changes. From this point forward, clicking a row selects it. Grid behavior reverts to single-like when the user decides to deselect all grid rows by unchecking all check boxes.

DevExtreme DataGrid Selection

The selection column enables a user to select all rows at once. This feature is controlled by the allowSelectAll option of the selection object, which is true by default. To disable the feature, set this option to false. Note that the user will still be able to deselect all rows at once.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    selection: {
        mode: 'multiple',
        allowSelectAll: false
    }
});

When a row is being selected, specific actions can be performed if required. To learn how to specify them, refer to the Handling the Selection Event topic.

Selecting in Code

dxDataGrid provides several methods with which to perform selection in code. If you have row keys, call the selectRows(keys) method passing them as the argument. If you only have data objects, obtain the keys using the keyOf(obj) method and then call the selectRows(keys) method.

JavaScript
var key = dataGridInstance.keyOf(dataObject);
dataGridInstance.selectRows(key);

Additionally, you can select rows by their indexes using the selectRowsByIndexes(indexes) method.

JavaScript
dataGridInstance.selectRowsByIndexes([1, 8, 6]);

When row indexes are being calculated, data and group rows are counted, though only data rows can be selected. Refer to the Grid Rows article to get more information on how to calculate row indexes.

NOTE: Unlike selectRows(keys), the selectRowsByIndexes(indexes) method applies selection that will be cleared automatically once the current page is changed. Therefore, to preserve the selection, call this method within the contentReadyAction callback function.

If you need to select all rows in a grid, call the selectAll() method.

JavaScript
dataGridInstance.selectAll();

Selection can also be cleared in code by calling the clearSelection() method.

JavaScript
dataGridInstance.clearSelection();

Setting Initial Selection

Rows can be selected not only at runtime, but also at design time. If you require certain rows to appear selected, declare an array of their keys and assign it to the selectedRowKeys option.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    selectedRowKeys: [1, 5, 8]
});

Note that the specified selection mode does not affect the initial selection. Thus, you can specify multiple rows to be selected initially even if the selection mode is single.

Selecting Using Keyboard Shortcuts

In a multiple selection mode, the keyboard and keyboard shortcuts can be used to perform selection. To select any several rows, a user must click them while pressing the CTRL key. To select a range from one row to another, a user must press the SHIFT key, click the first row and then the second one keeping SHIFT pressed. To select all grid rows at once, the CTRL + A shortcut can be used. The allowSelectAll option must be true in that case.

For an overview of all key combinations presented in dxDataGrid, refer to the Keyboard Navigation article.

Handling the Selection Event

When one or several rows are being selected, a callback function assigned to the selectionChanged option is called. Within this function, you can specify performing actions if it is required by your scenario. When implementing the selectionChanged function, use information about selected and deselected rows. This information is accessible via the fields of the object passed to the selectionChanged function. The following fields are available.

  • currentSelectedRowKeys
    Contains the keys of freshly selected rows.

  • currentDeselectedRowKeys
    Contains the keys of freshly deselected rows.

  • selectedRowKeys
    Contains the keys of all selected rows.

  • selectedRowsData
    Contains the data of all selected rows.

NOTE: If a field providing key values is not specified in a data source, the whole data object is considered key for a grid record. In this case, all arrays passed to the selectionChanged function contain data objects instead of keys.

Additionally, you can obtain the keys or data objects of selected rows outside the selectionChanged function at any point of the lifetime of your application. For this purpose, use the getSelectedRowKeys() and getSelectedRowsData() methods.

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 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: {
        editEnabled: true, // Allowing editing
        insertEnabled: true, // Allowing insertion
        removeEnabled: true // Allowing removing
    }
});

Additionally, you can specify whether a user can edit values in a specific column. For this purpose, use the allowEditing 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 | editMode option to either 'row' or 'batch' as shown in the code snippet below.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    editing: {
        editMode: 'row', // 'batch'
        // ...
    }
});
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

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.

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 insertRow() method.

  • Removing
    To remove a row, call the removeRow(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

In the process of editing, insertion and removing data, a number of events are raised that can be handled. 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 function is called. Within this function, you can manipulate the row (in row 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 function as the argument.

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

    When editing is complete, changes must be transmitted to the data source. But first, a callback function assigned to the rowUpdating option is called. 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({
        // ...
        rowUpdating: function (rowInfo) {
            // specify required actions here
        }
    });

    After the data source has been updated, the rowUpdated function is called. 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 similarly to other event-handling functions.

    JavaScript
    $("#gridContainer").dxDataGrid({
        // ...
        rowUpdated: function (rowInfo) {
            // specify required actions here
        }
    });
  • Insertion Events
    When inserted, a new row appears empty in a grid. If you need to initialize it, implement the initNewRow function. 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({
        // ...
        initNewRow: function (rowInfo) {
            rowInfo.data = {
                field1: 'data1',
                field2: 'data2',
                // ...
            }
        }
    });

    Before an inserted row will be transmitted to the data source, a callback function assigned to the rowInserting option is called. 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({
        // ...
        rowInserting: function (rowInfo) {
            // specify required actions here
        }
    });

    After a row has been inserted into the data source, the rowInserted function is called. When implementing this function, 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({
        // ...
        rowInserted: function (rowInfo) {
            // specify required actions here
        }
    });
  • Removing Events
    Before a row is removed from a data source, actions specified by the rowRemoving callback function are performed. Within this function, you can cancel the removing of the row or manipulate with data using the fields of the object passed to this function as the argument.

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

    After a row has been removed from the data source, the rowRemoved function is called. 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({
        // ...
        rowRemoved: function (rowInfo) {
            // specify required actions here
        }
    });