Visual Elements

This guide gives a detailed overview of DataGrid visual elements. Each topic in this guide contains a brief description of an element and its main features, which can be configured.

Below is a grid element map. It may be helpful as you begin learning the capabilities of the DataGrid widget. Hover over an element on the map to discover the name of this element. A click on an element navigates you to a topic devoted to this element.

DevExtreme dxDataGrid Elements

Grid Columns

There are two central elements, which the DataGrid widget is built on: grid columns and grid rows. This topic covers the main features of grid columns and the ways they can be configured.

A grid column is a visual representation of a set of data values that have a particular type. The general appearance of grid columns in the DataGrid widget is demonstrated in the image below.

DevExtreme DataGrid GridColumns

Specifying Grid Columns

By default, grid columns are generated on the base of the data source specified for DataGrid: one column for one field of a data source object. If you are not satisfied with the result, declare the columns array. The way you must declare it depends on the purposes you aim. If you want to change the set of presented columns or alter their order, fill this array with names of data source fields providing data for columns. The following code snippet illustrates this case.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    columns: ['CompanyName', 'ContactName', 'City', 'Country']
});

If you need to adjust grid column settings, declare columns as an array of objects. Each object must specify settings of one grid column. In this case, the name of a data source field should be assigned to the dataField property. For an example, see the following code snippet.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    columns: [{
            dataField: 'CompanyName',
            // Settings of the "Company Name" column are specified here
        }, {
            dataField: 'ContactName',
            // Settings of the "Contact Name" column are specified here
        }, {
            dataField: 'City',
            // Settings of the "City" column are specified here
        },
        // ...
    ]
});

These approaches can be combined. For example, you can specify some columns by objects, and other columns by the names of their data source fields.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    columns: [
        'CompanyName',
        {
            dataField: 'ContactName',
            // Settings of the "Contact Name" column are specified here
        }, {
            dataField: 'City',
            // Settings of the "City" column are specified here
        },
        // ...
    ]
});

Moreover, you can configure grid columns without declaring the columns array. Instead, change the required column settings within a callback function assigned to the grid's customizeColumns property. The array of grid columns can be accessed using the parameter of this function. Fields of each object in this array represent column properties identical to the properties described in the columns reference section. This approach is useful when you need to adjust only a few of column settings.

JavaScript
$("#gridContainer").dxDataGrid({
    customizeColumns: function (columns) {
        columns[0].width = 100;
        columns[1].width = 210;
    },
    // ...
});

Grid columns have many more features, a comprehensive list of which follows.

  • Visibility
    Each column is considered visible by default. To hide it, assign false to the visible property of a column. The headers of hidden columns appear in the column chooser.

  • Appearance
    You can completely change the appearance of a grid column. For this purpose, implement a CSS class and assign its name to the cssClass property of the column. Additionally, you can hide the lines separating one column from another by setting the showColumnLines property to false.

  • Size
    By default, all grid columns have equal width. Using the columnAutoWidth property, you can force the columns to adjust their widths to their content. If you want to specify a width for a column explicitly, use the width property of this column. In addition, you can allow a user to resize grid columns at runtime. For this purpose, assign true to the grid's allowColumnResizing property. The height of grid columns is calculated automatically depending on the height of the widget's container.

  • Text Formatting
    Values of a column can be displayed with an applied format. If required, you can also customize them by assigning a callback function to the customizeText property of the column. This function must return the text to be displayed in the column.

Setting a Data Type

A very important property of a grid column is the type of data this column contains. By default, the type of a column is determined automatically depending on the type of values that are in the data source field of this column. However, in many cases, these values must be converted into another type, e.g., when you receive numbers in a string format. If you need to convert these values, set the data type of a column explicitly using its dataType property.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    columns: [{
            dataField: 'CustomerID',
            dataType: 'number'
        }, {
            dataField: 'OrderDate',
            dataType: 'date'
        },
        // ...
    ]
});

NOTE: If your date values are of a string type, make sure they have one of the following formats in order to provide cross-browser compatibility.

  • 'yyyy/MM/dd' (i.e., '2014/08/25')
  • 'yyyy/MM/dd HH:mm:ss' (i.e., '2014/08/25 16:35:10')

Calculating the Column Index

Another important property of a grid column is its index. It can be used for obtaining or changing column options by calling the columnOption, or for implementing callback functions, such as the editCellTemplate or onCellClick. Note that those indexes differ. The index passed to the columnOption method - an "initial" index - equals the index of the column in the columns array. The index used in callback functions is equal to the "visible" index of the column. It depends on the current location of a column in the grid and changes dynamically when a user reorders columns or performs grouping. The following image illustrates how the "visible" index is calculated.

DevExtreme DataGrid GridColumns

The "initial" index of a column can be obtained within a callback function also. For this purpose, use the column.index property of the object passed to this function as the argument.

Configuring Column Headers

A column header is the top cell of a column that contains a text describing the contents of the column.

DevExtreme DataGrid ColumnHeaders

A text in a column header is called "caption". Usually, a caption is generated automatically on the base of the data field assigned to this column. In this case, the caption is a more friendly name of the data field. For example, if "orderDate" is the data field, then the caption will be "Order Date". There may be cases, when specifying the caption is required, e.g., when you use a calculated column and do not assign any data field. Then, assign the required text to the caption property of the column.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    columns: [{
            dataField: 'CompanyName',
            caption: 'Company',
            // ...
        }, {
            caption: 'Contact Name',
            // ...
        },
        // ...
    ]
});

Column headers in DataGrid are also used for sorting. To apply sorting to a column, a user must click its header. An arrow indicating the applied sort order will appear in the column header. In addition, the user can use a context menu to apply sorting. It is invoked by a right-click on a column header. Various sort orders can be selected within this context menu.

DevExtreme DataGrid ColumnHeaders

In case column headers are not required, hide them by assigning false to the grid's showColumnHeaders property.

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

Fixing Grid Columns

The DataGrid widget allows you to anchor columns to the left or right grid edge. When anchored, columns are not horizontally scrolled with the grid. Use this feature if you need a column (or columns) to always be displayed, regardless of scrolling.

View Demo

To anchor columns to grid edges, set the grid's columnFixing | enabled option to true. In this instance, column fixing-related commands will be available in the column headers' context menu. Using these commands, end users can anchor any column to the left or to the right grid edge and then unfix it.

JavaScript
var dataGridOptions = {
    //...
    columnFixing: { 
        enabled: true
    }
};

DevExtreme DataGrid Column Fixing

You can prevent the fixing of a particular column by setting its allowFixing option to false. In this instance, the fixing-related commands will not be available in the column's context menu.

Columns can be fixed at runtime and at design time. If you require certain columns to appear fixed initially, set the columns' fixed option to true. In this instance, the grid's columnFixing | enabled option will automatically be set to true.

JavaScript
var dataGridOptions = {
    //...
    columns: [{
        // ...
        fixed: true
    }, {
        //...
    }]
}

DevExtreme DataGrid Column Fixing

Note that the command columns, the ones containing check boxes to select rows or links to save/delete rows, are fixed when you enable column fixing, since the fixed option is set to true for these columns internally.

Anchoring columns makes sense only when the auto width feature is disabled and the total width of columns exceeds the grid container's width. Otherwise, horizontal scrolling does not occur and fixed columns end up behaving like other columns.

Band Columns

Oftentimes, columns contain data that can be organized in logical groups. It would be smart to collect such columns under a single header. The banded layout provides you with this capability.

DevExpress DevExtreme DataGrid HTML5 BandColumns

To set up the banded layout, declare a band column using a hierarchical structure. For this purpose, assign the nested columns to the columns field of the band column. For example, the following code declares the "Address" band column and nests three columns within it.

JavaScript
var dataGridOptions = {
    // ...
    columns: [{
        caption: 'Address',
        columns: ['City', 'Street', 'Apartment']
    }, {
        // ...
    }]
};

A nested column has almost every property a regular column has. These properties are described in the columns section of the Reference.

NOTE: There is an exception though: nested columns cannot be fixed alone, therefore specifying the fixed and fixedPosition properties for them is useless. However, the whole band column can be fixed as usual.

Band columns support hierarchies of any nesting level. It means that the following structure is acceptable.

JavaScript
var dataGridOptions = {
    // ...
    columns: [{
        caption: 'A',
        columns: [ 'A1', 'A2', {
            caption: 'A3',
            columns: ['A31', 'A32', {
                caption: 'A33',
                columns: ['A331', 'A332', 'A333']
            }]
        }]
    }]
};

If you use the customizeColumns option to configure columns, the hierarchical structure cannot be implemented. To band columns in this case, use the isBand and ownerBand options. Using the same options, you can distinguish band and banded columns from regular ones in code.

JavaScript
var dataGridOptions = {
    // ...
    customizeColumns: function(columns) {
        columns.push({ // Pushes the "Address" band column into the "columns" array
            caption: 'Address',
            isBand: true
        });

        var addressFields = ['City', 'Street', 'Apartment'];
        for (var i = 0; i < columns.length-1; i++) {
            if (addressFields.indexOf(columns[i].dataField) > -1) // If the column belongs to "Address",
                columns[i].ownerBand = columns.length-1; // assigns "Address" as the owner band column
        }
    }
};

Band columns support the following properties only.

NOTE: Band columns must not have the dataField option set.

View Demo

Command Columns

Command columns are columns used for interaction with an end-user. There are three types of command columns: editing column, selection column and adaptive column. The editing column appears when the editing | mode option is set to "batch" or "form". The selection column appears when the selection | mode option is set to 'multiple', provided that the showCheckBoxesMode option is not 'none'. The adaptive column appears when the columnHidingEnabled option is set to true and the total column width does not fit into the screen or container size.

You can modify the position and width of a command column using its visibleIndex and width options respectively. These options can be modified at runtime using the columnOption(id, optionName, optionValue). To modify options of the selection, editing or adaptive column, pass the "command:select", "command:edit", or "command:adaptive" string respectively to the id argument of this method.

NOTE: The default visibleIndex value of the selection column is -1. To place a column before the selection column, use indexes lower than -1.

The example below demonstrates how to swap command columns.

JavaScript
dataGrid.columnOption("command:select", "visibleIndex", 999);
dataGrid.columnOption("command:edit", "visibleIndex", -2);
dataGrid.columnOption("command:adaptive", "visibleIndex", -1)

You can also modify cells of command columns using the onCellPrepared event. If the event fires for a cell of the selection, editing, or adaptive column, the column field of the event argument object contains the command field holding the "select", "edit", or "adaptive" value respectively.

JavaScript
var dataGridOptions = {
    // ...
    onCellPrepared: function(e){
        if (e.rowType == "data")
            switch(e.column.command){
                case "select":
                    // Selection column cells
                    break;
                case "edit":
                    // Editing column cells
                    break;
                case "adaptive":
                    // Adaptive column cells
                    break;  
            }      
    }
}

View Demo

Grid Rows

Along with grid columns, grid rows are a fundamental element in the DataGrid widget. A grid row is a grid element representing a structured data item. In fact, a grid can be thought of as consisting of rows and columns.

DevExtreme DataGrid GridRows

In DataGrid, you specify data for grid columns mostly, while grid rows are formed automatically based on the contents of data source objects. Normally, a grid row is generated for each data source object.

To identify a row, a row index is used. If paging is enabled (that is, data is divided into portions), grid rows are indexed beginning with 0 on each page. Otherwise, grid rows are indexed beginning with 0 continuously. Note that group rows are counted too and thus have row indexes.

DevExtreme DataGrid GridRows

There are several features of grid rows that you can configure. They are listed below.

  • Appearance
    By default, all grid rows are displayed on a monochrome area without visual distinctions between them. If you need to distinguish one row from its neighboring rows visually, set the rowAlternationEnabled option to true. In this case, ordinary-looking rows will alternate with slightly shaded ones. Also, grid rows can be highlighted when the mouse pointer moves over them. To enable this capability, set the hoverStateEnabled property to true. Additionally, you can change the visibility of row lines using the showRowLines property.

  • Customization
    After a row has been rendered, you can apply final customizations to it. For this purpose, implement a function that handles the rowPrepared event and assign it to the onRowPrepared property. Usually, handling the rowPrepared event is sufficient for grid rows to appear according to your needs. However, some scenarios require defining grid rows in full. In such a case, implement a row template and assign it to the grid's rowTemplate property.

Grid Cells

A grid cell is formed at the intersection of a grid row and a grid column. Although a grid has many types of cells, such as filter row cells and column header cells, a "grid cell" mainly refers to a cell holding data.

DevExtreme DataGrid GridCell

A grid cell can be in a normal or editing state. The appearance of a grid cell depends on the type of data that its column contains. The following image shows how cells that belong to columns of different types look like in the normal and editing states.

DevExtreme DataGrid GridCell

Although the appearance of a grid cell is determined by its column settings, there are several grid properties that allow you to perform cell-level customizations. After a cell has been rendered, you can apply final customizations to it. For this purpose, assign a function to the onCellPrepared property. This function will be executed when the cellPrepared event fires.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    onCellPrepared: function (eventInfo) {
        // ...
    }
});

Usually, implementing the onCellPrepared function is sufficient for grid cells to appear according to your specifications. However, some scenarios require you to define grid cells in full. In that case, implement a cell template and assign it to the cellTemplate property of the column, which the cell belong to. Similarly, you can specify a template for a cell in the editing state using the editCellTemplate property. Different grid columns can have different templates specified.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    columns: [{
            dataField: 'CompanyName',
            cellTemplate: function(cellElement, cellInfo) {
                // ... 
            },
            editCellTemplate: function(cellElement, cellInfo) {
                // ...
            }
        }, {
            dataField: 'ContactName',
            cellTemplate: function(cellElement, cellInfo) {
                // ... 
            },
            editCellTemplate: function(cellElement, cellInfo) {
                // ...
            }
        }
        // ...
    ]
});

Pager

A pager is a grid element that allows a user to navigate through grid pages and change their size at runtime.

DevExtreme DataGrid Pager

As illustrated in the image above, the pager consists of a page navigator and a page size selector, both configured by the pager object.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    pager: {
        // Pager is configured here
    }
});

By default, the page navigator contains page numbers only. Clicking a page number navigates the user to that page. Additionally, the page navigator can contain buttons that navigate the user to the previous or next page. To make them visible, assign true to the showNavigationButtons property.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    pager: {
        showNavigationButtons: true
        // ...
    }
});

Moreover, you can accompany the page navigator with a text displaying information on the current page number and the total page count. To make this text visible, assign true to the showInfo property. To change this text, use the infoText property.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    pager: {
        showInfo: true,
        infoText: 'Your text goes here'
        // ...
    }
});

The page size selector contains page sizes that can be selected. They are specified by the allowedPageSizes option of the pager configuration object. Note that the page size selector is hidden by default. To make it visible, assign true to the showPageSizeSelector option of the same object.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    pager: {
        allowedPageSizes: [3, 5, 8],
        showPageSizeSelector: true,
        // ...
    }
});

Whether the pager is visible depends on whether paging is enabled. If required, you can change the visibility of the whole pager (page navigator and page size selector) explicitly using its visible property.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    pager: {
        visible: true,
        // ...
    }
});

Filter Row

A filter row is a grid element that enables users to filter grid records. The filter row consists of cells that correspond to a grid column. A filter row cell contains a filter operation chooser represented by a magnifying glass icon. Hovering over this element opens a list that permits users to change the filter applied to a column. Operations available in this list are specified by the filterOperations property of a particular column.

DevExtreme DataGrid FilterRow

To configure the filter row, use filterRow object fields.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    filterRow: {
        // Filter row is configured here
    }
});

By default, the filter row is hidden. To make it visible, set the visible property of the filterRow object to true.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    filterRow: {
        visible: true
    }
});

A filter row can have additional elements, e.g., when a column has a 'date' or 'boolean' dataType, or a column is declared as a lookup column. The image below illustrates a filter row with a date and a boolean cell. The date cell contains a calendar that helps choose a date value, while the boolean cell is a select box containing two items: true and false.

DevExtreme DataGrid FilterRow

Configurable features of the filter row, which can be specified within the filterRow object, are listed below.

  • Visibility
    In addition to the visibility of the whole filter row, which is mentioned earlier, you can individually specify the visibility of operation choosers using the showOperationChooser property.

  • Behavior
    By default, a filter applies automatically when a user finishes typing a string in a filter row cell. Alternatively, you can give a user the opportunity to apply a filter at the required time. To do this, assign 'onClick' to the applyFilter option. In this case, a filter will be applied by a click on the "Apply Filter" button.

  • Texts
    You can specify required descriptions for the items appearing in the filter list using the operationDescriptions property. A description for the reset operation should be specified separately using the resetOperationText property.

Search Panel

A search panel is a grid element that allows a user to search records by a search string. The search string is highlighted in the found records. The search panel can be thought of as a filter row cell that applies a filter to all grid columns at once.

DevExtreme DataGrid SearchPanel

Searching is performed 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.

To configure the search panel, use searchPanel object fields.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    searchPanel: {
        // Search panel is configured here
    }
});

By default, the search panel is hidden. To make it visible, set the visible property of the searchPanel object to true.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    searchPanel: {
        visible: true
    }
});

Configurable features of the search panel are listed below. Options that control them must be specified within the searchPanel object.

  • Text Highlighting
    By default, the search string is highlighted in matched records. To disable this feature, assign false to the highlightSearchText property.

  • Appearance
    The width of the search panel can be adjusted using the width property. Additionally, you can change the text displayed by an empty search panel. For this purpose, use the placeholder property.

Group Panel

To group grid records, use a group panel. A user can drag-and-drop columns onto and from it, thus grouping grid records by these columns.

DevExtreme DataGrid GroupPanel

To configure the group panel, use the fields of the groupPanel object.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    groupPanel: {
        // Group panel is configured here
    }
});

By default, the group panel is hidden. To make it visible, set the visible property of the groupPanel object to true.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    groupPanel: {
        visible: true
    }
});

Building a multi-platform application, you may want to show/hide the group panel depending on the device's screen size. For this purpose, assign "auto" to the groupPanel | visible option. In this case, the group panel will be hidden on small-screen devices, and shown on the others.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    groupPanel: {
        visible: "auto"
    }
});

There are several additional features of the group panel that may be configured. They are listed below.

  • Blocking the Group Panel
    If required, you can prohibit drag-and-drop but leave the group panel visible. In that case, assign false to the allowColumnDragging field of the groupPanel object. This is useful, for instance, when grid records are grouped initially and when a user needs to know about that grouping, but must not be able to change it.

  • Specifying a Placeholder
    You can change the text displayed by an empty group panel. Use the groupPanel | emptyPanelText property for this purpose.

See Also

Group Rows

Grouped records in a grid are headed by a group row, which contains the name of that group and helps users identify it.

DevExtreme DataGrid GroupRows

NOTE: Although group rows look like rows, internally they are treated like cells. Therefore, in DataGrid documentation, you are just as likely to encounter "group row" as "group cell".

A grid group can be in an expanded or collapsed state. When a group is expanded, it appears as a set of data rows headed with a group row. This state is illustrated by the image above. In the collapsed state, a group is represented by a group row only. By default, group rows appear expanded, but you may force them to appear collapsed by setting the grouping | autoExpandAll property to false.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    grouping: {
        autoExpandAll: false // groups appear collapsed
    }
});

In some cases, a grid group may be too large to fit into a grid page. If so, the group is parted, and a message notifying a user about that fact is added to the text of the group row. If you are not satisfied with that message, change it using the groupContinuedMessage and groupContinuesMessage properties of the grouping | texts object.

See Also

Group Summary

A group summary item is a grid element that aggregates a column of data in a group. It can display the result of different calculations within the group, for example, the number of rows, sum of the column's numeric values, the minimum or maximum value, etc.

DevExtreme DataGrid GroupPanel

To define a group summary item, use the summary | groupItems array.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    summary: {
        groupItems: [{
            // Group summary item configuration
        }
        // ...
        ]
    }
});

The following features of the group summary item can be changed.

  • Location
    By default, group summary items are displayed in the header of a group row. You can also align the items by columns within the group row by setting the alignByColumn option to true. In addition, you can place items to the group footer by setting the showInGroupFooter option to true. In both these scenarios, you can place items to alternative columns by using the showInColumn option.

  • Value Format
    Use the valueFormat option to specify the kind of data that is represented by the group summary item.

  • Text Format
    To accompany the summary value with a text, use the displayFormat option. The additional calculations on the value can be performed in the customizeText function.

NOTE: To learn how to implement a group summary, refer to the Summaries | Group Summary topic.

Selection Column

When a user is allowed to select records in the multiple mode, a grid is supplemented with a selection column. This column contains a set of check boxes, each of which corresponds to a data row. Toggling a check box selects or deselects the row.

DevExtreme DataGrid SelectionColumn

The selection column appears when the selection | mode property is set to 'multiple'.

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

To change the selection column display policy, use the showCheckBoxesMode option. For example, you can hide it and the multiple selection well be possible only using the Ctrl/Cmd or Shift key.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    selection: {
        showCheckBoxesMode: 'none'
    }
});

Additionally, a user can select/deselect all rows at once using the check box located in the header of the selection column. Rows can be selected/deselected on the currently rendered pages or on all pages. To define this, specify the selectAllMode option. If the capability of all rows selection is not required, assign false to the selection | allowSelectAll property.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    selection: {
        // ...
        allowSelectAll: true,
        selectAllMode: 'page' // or 'allPages'
    }
});

Column Chooser

In DataGrid, a user may be capable of altering the set of presented columns at runtime. This capability is provided by a grid element called "column chooser". A column chooser is a panel that contains column headers. It can be invoked by a click on DevExtreme DataGrid ColumnChooser.

The column chooser has two modes defining how the user chooses columns. In the "dragAndDrop" mode, the user moves column headers to/from the column chooser by drag-and-drop. When in this mode, the column chooser contains the headers of hidden columns only.

In the "select" mode, the user selects check boxes in the column chooser to show specific columns. This mode is preferable if you display DataGrid on a touch-enabled device.

By default, the column chooser is in the "dragAndDrop" mode. To change this, use the mode option of the columnChooser object.

JavaScript
$("#gridContainer").dxDataGrid({
    columnChooser: {
        mode: 'select' // 'dragAndDrop'
    }
});

To note the difference between these modes in action, see the example at the end of this subtopic.

The columnChooser object also configures the appearance of the column chooser. The following features can be changed using the properties of this object.

  • Availability
    By default, a user cannot invoke the column chooser, because its enabled property is set to false. To enable it, set this property to true.

  • Size
    You can change the size of the column chooser panel using the height and width properties.

  • Texts
    If you are not satisfied with the text displayed in the title of the column chooser, change it using the title property. In addition, you can change the text displayed by the column chooser panel when it's empty. For this purpose, use the emptyPanelText property.

Show Example:
AngularJS
Knockout
jQuery

This example illustrates differences between the modes of the column chooser. Choose a mode from the select box below the grid. Then, click the icon in the upper-right corner of the grid to invoke the column chooser. Depending on the chosen mode, you will be able either to select column headers or move them to/from the column chooser by drag-and-drop.


                                    

                                    

This example illustrates differences between the modes of the column chooser. Choose a mode from the select box below the grid. Then, click the icon in the upper-right corner of the grid to invoke the column chooser. Depending on the chosen mode, you will be able either to select column headers or move them to/from the column chooser by drag-and-drop.


                                    

                                    

This example illustrates differences between the modes of the column chooser. Choose a mode from the select box below the grid. Then, click the icon in the upper-right corner of the grid to invoke the column chooser. Depending on the chosen mode, you will be able either to select column headers or move them to/from the column chooser by drag-and-drop.


                                    

                                    

Load Panel

When data is taking noticeable time to be loaded, which may occur if you use a remote data source, DataGrid displays a load panel that notifies the user of the data loading process.

DevExtreme DataGrid LoadPanel

As you can see in the image above, the load panel consists of a loading indicator, a pane and a text. You can configure the load panel using loadPanel object properties.

JavaScript
$("#gridContainer").dxDataGrid({
    loadPanel: {
        // Load panel is configured here
    }
});

The following load panel features can be changed using the properties of the loadPanel object.

  • Availability
    By default, the load panel is enabled for remote data sources only. To enable it for any data source, regardless whether it is local or remote, assign true to the enabled property. To disable the load panel completely, assign false to the same property.

  • Pane Visibility
    The load panel pane is visible by default. If it is not required, hide it by assigning false to the showPane property.

  • Loading Indicator Options
    By default, the loading indicator is visible. If you require hiding it, assign false to the showIndicator property. Additionally, you can specify the image to be displayed as a loading indicator. For this purpose, assign the URL of this image to the indicatorSrc property.

  • Text
    To change the text displayed by the load panel, use its text property.

  • Size
    The size of the load panel can be changed using its width and height properties.

Since the grid load panel is practically the DevExtreme LoadPanel widget, you can specify any option belonging to this widget in the loadPanel object.

Data Modification Controls

DataGrid provides the capability to modify data it contains. Data modification can be conducted in three edit modes: row, batch and cell. In addition, data modification can be restricted to only one or several operations, e.g., editing only, or removing and insertion. These parameters are specified by properties of the editing object.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    editing: {
        mode: 'batch', // Specifying the edit mode
        allowUpdating: true, // Enable editing
        allowAdding: true, // Enable insertion
        allowDeleting: true // Enable removing
    }
});

Depending on the specified properties of the editing object, a certain set of controls is presented in a grid. For more information on these controls, see the following subtopics.

Editing in the Row Mode

This subtopic describes controls that appear in the DataGrid widget when the mode property is set to "row". These controls are illustrated by the image below.

DevExtreme DataGrid Editing

Depending on the specified properties of the editing object, different controls are presented in a grid. These controls and the options that enable them are listed below.

  • allowUpdating is true
    This setting supplements each grid row with the "Edit" button. Clicking this button switches the corresponding row into the editing state. At the same time, the "Save" and "Cancel" buttons appear.

  • allowAdding is true
    This setting adds the "Add" button to the upper-right corner of the DataGrid widget.

  • allowDeleting is true
    This setting adds the "Delete" button to each grid row.

In addition, the text of a certain button can be changed using the fields of the editing | texts object.

Button Field
Edit editRow
Delete deleteRow
Save saveRowChanges
Cancel cancelRowChanges
Add addRow h

NOTE: The h mark directs the property to specify text for the hint appearing when a user hovers the mouse pointer over a button, but not for that button.

Editing in the Batch Mode

This subtopic describes controls that appear in the DataGrid widget when the edit mode property is set to "batch". These controls are illustrated by the image below.

DevExtreme DataGrid Editing

Depending on the specified properties of the editing object, different controls are presented in a grid. These controls and the options that enable them are listed below. Note that the "Save" and "Revert" buttons appear in a grid even if only one of the allowUpdating, allowAdding or allowDeleting properties is true.

  • allowUpdating is true
    No extra buttons are added.

  • allowAdding is true
    This setting adds the "Add" button to the upper-right corner of the DataGrid widget.

  • allowDeleting is true
    This setting adds the "Delete" button to each grid row. When a user clicks one of these buttons, it is substituted by the "Undelete" button.

In addition, the text of a certain button can be changed using the fields of the editing | texts object (if this button is not represented by an icon).

Button Field
Delete deleteRow
Undelete saveRowChanges
Add addRow h
Save saveAllChanges h
Revert cancelAllChanges h

NOTE: The h mark directs the property to specify text for the hint that appears when a user hovers the mouse pointer over a button, but not for that button.

Editing in the Cell Mode

This subtopic describes controls that appear in the DataGrid widget when the mode property is set to "cell". These controls are illustrated by the image below.

DevExtreme DataGrid Editing

Depending on the specified properties of the editing object, different controls are presented in a grid. These controls and the options that enable them are listed below.

  • allowUpdating is true
    No extra buttons are added.

  • allowAdding is true
    This setting adds the "Add" button to the upper-right corner of the DataGrid widget.

  • allowDeleting is true
    This setting adds the "Delete" button to each grid row.

In addition, the text of a certain button can be changed using the fields of the editing | texts object.

Button Field
Delete deleteRow
Add addRow h

NOTE: The h mark directs the property to specify text for the hint that appears when a user hovers the mouse pointer over a button, but not for that button.

Total Summary

A total summary item is a grid element that aggregates the entire column of data. It can display the result of different calculations, for example, the number of rows, sum of the column's numeric values, the minimum or maximum value, etc.

Total Summary

To define a total summary item, use the summary | totalItems array.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    summary: {
        totalItems: [{
            // Total summary item configuration
        }
        // ...
        ]
    }
});

The following features of a total summary item can be changed.

  • Location
    The total summary item can be placed to another column using the showInColumn option. You can also change the text alignment.

  • Value Format
    Use the valueFormat option to specify what kind of data is represented by the total summary item.

  • Text Format
    To accompany the summary value with a text, use the displayFormat option. Additional calculations on the value can be performed in the customizeText function.

NOTE: To learn how to implement a total summary, refer to the Summaries | Total Summary topic.

Master-Detail Interface

The master-detail interface enables you to display additional information in the expandable section of a data row. The data row is called "master row", while the section is called "detail section".

Total Summary

To learn how to use this feature, refer to the Master-Detail Interface topic.