Configuration

This section describes the configuration options of the dxDataGrid widget.

activeStateEnabled

A Boolean value specifying whether or not the widget changes its state when interacting with a user.

Type: Boolean
Default Value: true

This option is used when the widget is displayed on a platform whose guidelines include the active state change for widgets.

allowColumnReordering

Specifies whether or not grid columns can be reordered by a user.

Type: Boolean
Default Value: false

Initially, grid columns appear in the order specified by the columns array. When this array is not specified, grid columns have the same order as the fields of the first object from the data source. You can provide the capability for a user to reorder grid columns. To enable this capability, set the allowColumnReordering option to true. After that, grid columns can be reordered by dragging their headers.

Once enabled, all grid columns can be reordered by drag-and-drop. If you need to restrict a specific column from being reordered, set the allowReordering option of this column to false.

Show Example:
jQuery

Toggle the check box below to change the value of the allowColumnReordering option. Then, try to reorder grid columns by dragging a column by its header and dropping it at the required place.


                                    

                                    

allowColumnResizing

Specifies whether or not grid columns can be resized by a user.

Type: Boolean
Default Value: false

By default, the width of each grid column is calculated automatically, depending on the width of the widget's container and the total number of grid columns. To specify the width of a specific column in code, use the columns | width option. You can allow a user to resize columns at runtime. To enable this capability, set the allowColumnResizing option to true. After that, each grid column can be resized by dragging its border.

Once enabled, column resizing will be allowed for all grid columns. If you need to restrict a specific column from being resized, set the allowResizing option of this column to false.

Show Example:
jQuery

Toggle the check box below to change the value of the allowColumnResizing option. Then, try to resize a grid column by dragging its border.


                                    

                                    

cellClick

Deprecated

Use the onCellClick option instead.

cellHintEnabled

Enables a hint that appears when a user hovers the mouse pointer over a cell with truncated content.

Type: Boolean
Default Value: true

The cell's content may be truncated if the width of the cell's column becomes very small. In this case, when a user hovers the mouse pointer over such a cell, a hint containing the cell's value appears. To disable cell hints, assign false to the cellHintEnabled option.

cellHoverChanged

Deprecated

Use the onCellHoverChanged option instead.

cellPrepared

Deprecated

Use the onCellPrepared option instead.

columnAutoWidth

Specifies whether or not the width of grid columns depends on column content.

Type: Boolean
Default Value: false

When this option is set to true, each grid column has a width that is optimal for holding the content of this column. In this case, the width of the widget's container is ignored. This setting may cause the appearance of horizontal scrolling, but only if the content of a row exceeds the width of the widget's container.

When this option is set to false, all grid columns have the same width, which is calculated considering the width of the widget's container.

If grid columns contain text, then this text can be wrapped if column width is exceeded. To enable word wrapping, set true to the wordWrapEnabled option.

Show Example:
jQuery

In this example, you can change the value of the columnAutoWidth option using the check box below. Note that when this option is true, each grid column has a width that is optimal for displaying the content of this column in full. However, with this setting applied, horizontal scrolling appears as well. When the aforementioned option is false, grid columns have an even width.


                                    

                                    

columnChooser

Specifies the options of a column chooser.

Type: Object

A column chooser is a grid element that allows a user to hide specific grid columns. This element represents a panel that appears when the user clicks the ColumnChooser ChartJS icon, or when the showColumnChooser() method is called.

A grid column must have the allowHiding option set to true so that a user can drag it onto the column chooser panel.

By default, the column chooser is disabled. To enable it, set the enabled option of the columnChooser object to true. Using the width and height options of this object, you can define the size of the column chooser panel.

In addition, you can customize the text displayed by the panel when it is empty using the emptyPanelText option and the text displayed in the title of the panel using the title option.

Show Example:
jQuery

In this example, you can show/hide grid columns using the column chooser. To invoke it, click the column chooser icon. Drag a column by its header onto/from the column chooser to hide/show this column. Additionally, several options that define the column chooser appearance are changed.


                                    

                                    

columns[]

An array of grid columns.

Type: Array
Default Value: undefined

By default, a column is created for each field of a data source object, but in most cases, it is redundant. To specify a set of columns to be created in a grid, assign an array specifying these columns to the columns option. Each grid column is represented in this array by an object containing column settings or by a data source field that this column is bound to. Detailed information on specifying grid columns is given in the Specifying Grid Columns article.

Column options define the behavior and appearance of a grid column. One of the other capabilities allows you to control the sorting of column values using the allowSorting and sortOrder options, apply a filter to grid records using the allowFiltering and filterOperations options, and group grid records using the allowGrouping and groupIndex options. In addition, you can change the visibility and width of a column using corresponding options.

To get or set an option or several options for a column at runtime, use the columnOption method with the required arguments.

View Demo

Show Example:
jQuery

In this example, grid columns are configured using the columns array. Friendlier names are specified for the headers of the "Invoice Number", "City", "State" and "Employee" columns using the caption property. The "Order Date" column has an explicitly set data type, while the contents of this column are aligned to the right side using the alignment property. The "Invoice Number" and "Employee" columns have fixed widths specified by the width property. Further, the values in the "Sale Amount" column have a currency format as determined by the format property. In addition, the values of the "Employee" column are customized using a callback function assigned to the calculateCellValue property.


                                    

                                    

customizeColumns

Specifies a function that customizes grid columns after they are created.

Type: function(columns)
Function parameters:
columns: Array
Grid columns.

Usually, each column in dxDataGrid is configured individually using options within the objects of the columns array. In most cases, configuring grid columns in this fashion is sufficient to make them appear appropriately. However, there may be scenarios when columns are generated on the base of a data source and you need to adjust a few of their options. In that case, you do not need to declare the columns array. Instead, change the required options within a callback function assigned to the customizeColumns option. An array of grid columns can be accessed using the function's parameter. Fields of each object in this array represent column options identical to the options described in the columns reference section.

Show Example:
jQuery

In this example, grid columns are created automatically on the base of the data source. Further, the widths of the "Author" and "Title" columns are adjusted using a callback function assigned to the customizeColumns option.


                                    

                                    

dataErrorOccurred

Deprecated

Use the onDataErrorOccurred option instead.

dataSource

Specifies a data source for the grid.

Default Value: null

To provide data for a grid, use the dataSource option. This option takes on one of the following.

  • An Array of objects
    The fields of each object will be used to provide data for corresponding grid columns.

  • A DataSource or its Configuration Object
    The DataSource is a stateful object that includes options for data sorting, grouping and filtering; it also keeps data transformation options and applies them each time data is loaded. The DataSource also provides events intended to handle changing data and the state. The DataSource's underlying data access logic is isolated in a Store. Unlike the DataSource, a Store is a stateless object implementing a universal interface for reading and modifying data. To learn more, refer to the Data Layer topic.

By default, a column is generated for each field of data source objects, although you can specify a custom array of columns using the columns option. To get more information about specifying grid columns, see the Specifying Grid Columns topic.

When using a data source that changes dynamically, the dxDataGrid widget cannot track changes. To update the widget in this case, call its refresh() method.

For more information on how to implement a data source and bind it to your grid, refer to the Data Binding topic.

Show Example:
jQuery

In this example, the data source is declared as an array of objects that each contain the 'author', 'title', 'year', 'genre' and 'format' fields. The corresponding columns are generated automatically. Captions for column headers are generated based on the data field names.


                                    

                                    

disabled

A Boolean value specifying whether or not the widget can respond to user interaction.

Type: Boolean
Default Value: false

Create an observable variable and assign it to this option to specify the availability of the widget at runtime.

Show Example:
jQuery

In this example, you can enable/disable the dxDataGrid widget by toggling the check box below. When the widget is enabled, you can interact with it, for example, apply sorting or switch between pages. When the widget is disabled, it does not respond to your actions.


                                    

                                    

editing

Contains options that specify how grid content can be changed.

Type: Object

dxDataGrid supports editing, insertion and the removing of grid values. The availability of performing a certain operation is specified by the editEnabled, insertEnabled and removeEnabled options.

Editing in dxDataGrid can be performed in two different modes: row and batch. In the row mode, all changes made in grid rows are reflected in the data source immediately after editing completes. In the batch mode, changes are buffered before being transmitted to the data source. The user sends them manually once he or she finishes editing.

See Also
  • For more information about editing settings you can configure, including both edit modes, refer to the Editing in UI topic.
  • To discover how to manage the editing process from code, see the Editing in Code topic.

NOTE: Before allowing a user to edit, insert and remove, make sure your data source supports all these actions.

View Demo

Show Example:
jQuery

In this example, you can perform all kinds of data modifications available in the dxDataGrid widget: row editing, insertion and removal. These operations are conducted in the batch edit mode. All these settings are specified using the fields of the editing configuration object.


                                    

                                    

editingStart

Deprecated

Use the onEditingStart option instead.

editorPrepared

Deprecated

Use the onEditorPrepared option instead.

editorPreparing

Deprecated

Use the onEditorPreparing option instead.

errorRowEnabled

Indicates whether to show the error row for the grid.

Type: Boolean
Default Value: true

The error row displays the data errors that occur on the server during the grid's life cycle.

Set this option to false to avoid showing errors to end users. Instead, the error will be displayed in the browser's console. In addition, you can subscribe to the dataErrorOccured event to provide custom actions when data errors occur on the server.

filterRow

Specifies filter row options.

Type: Object

In dxDataGrid, an end-user can filter grid records at runtime using the filter row. This row is located below the grid row that contains column captions. By default, the filter row is hidden. To make it appear, set the visible option of the filterRow object to true.

To filter grid records by a value in a grid column, the user must enter the required value (or a part of it) in the filter row cell that belongs to this column. The matched records are determined according to the column's currently selected filter operation. To change this operation, the user must click the magnifying glass icon accompanying each filter row cell and choose the required filter operation from the appeared drop-down list.

See Also
  • For more information about filtering, refer to the Filtering topic.
  • To discover how to apply a filter from code, see the Filtering in Code topic.

View Demo

Show Example:
jQuery

In this example, the filter row is made visible by setting the filterRow | visible option to true. In addition, a filter operation is selected for each grid column from code using the selectedFilterOperation option. This operation can not be changed at runtime, because the filterRow | showOperationChooser option is set to false.


                                    

                                    

focusStateEnabled

Specifies whether or not the widget can be focused.

Type: Boolean
Default Value: false

grouping

Specifies the behavior of grouped grid records.

Type: Object

In dxDataGrid, records can be grouped by column values. The behavior of the grouped records is determined by the options of the grouping configuration object.

A group of records can appear in a grid either extended or collapsed. To specify that, use the autoExpandAll option. Manual group collapsing can be prohibited entirely by setting the allowCollapsing option to false. Note that specifying both of these options may result in a lack of functionality. For example, when manual collapsing of groups is prohibited, but all groups are collapsed as the autoExpandAll is set to false, there is no way of expanding any group in a grid. Hence, be mindful when using both the allowCollapsing and autoExpandAll options.

Additionally, you can collapse/expand grid groups from code. For this purpose, use the collapseAll(groupIndex) and expandAll(groupIndex) methods.

View Demo

Show Example:
jQuery

In this example, groups appear collapsed when you group grid records, because the autoExpandAll option of the grouping object is set to false.


                                    

                                    

groupPanel

Specifies options that configure the group panel.

Type: Object

Grid records in dxDataGrid can be grouped by one column or by several. Once a column is used for grouping, it is added to a group panel.

A group panel is a grid element holding the headers of columns that grid records are grouped by. To make a group panel visible, you must set its visible option to true. When the group panel is visible, a user can drag grid columns onto and from it, thus grouping grid records. If you need to prohibit the dragging of columns to the group panel, set the allowColumnDragging option to false. In this case, columns can be added to the group panel from code only. Additionally, you can change the text displayed by the group panel when it is empty using the emptyPanelText option.

View Demo

Show Example:
jQuery

In this example, grid records are initially grouped by the Format column. In addition, the group panel is made visible using the groupPanel | visible option. However, the capability to drag columns onto and from the group panel is disabled by setting the groupPanel | allowColumnDragging option to false. Thus, a user can only see how grid records are grouped, but cannot change the initial grouping.


                                    

                                    

height

Specifies the height of the widget.

Type: Number|String|function
Return Value: Number|String
The widget height.
Default Value: undefined

The option can hold a value of the following types.

  • number
    The height of the widget in pixels

  • string
    A CSS measurement of the widget height (e.g., "55px", "80%", "auto" and "inherit")

  • function
    A function returning the widget height (e.g., height:function(){ return baseHeight - 10 + "%"; })

Show Example:
jQuery

In this example, you can change the height of the dxDataGrid widget using the buttons under it. These buttons increase/decrease the widget's height by 1 pixel.


                                    

                                    

hint

Specifies the text of the hint displayed for the widget.

Type: String
Default Value: undefined

hoverStateEnabled

Specifies whether grid rows are highlighted when the mouse pointer moves over them.

Type: Boolean
Default Value: false

Show Example:
jQuery

In this example, you can change the value of the hoverStateEnabled option by toggling the check box below. To see the changes, hover over a row in the grid.


                                    

                                    

initNewRow

Deprecated

Use the onInitNewRow option instead.

loadPanel

Specifies options configuring the load panel.

Type: Object

When dxDataGrid operates with a large number of records or uses a remote storage as a data source, loading data takes time. While data is not yet ready, dxDataGrid displays a load panel.

The load panel consists of a pane, a loading indicator and a text. You can specify whether the pane or loading indicator must be displayed using the showPane or showIndicator options respectively. The text displayed by the load panel can be specified using the text option. Also, you can change the height or width of the load panel using the corresponding options of the loadPanel configuration object.

Additionally, you can show/hide the load panel from code when using the beginCustomLoading(messageText) and endCustomLoading() methods.

Show Example:
jQuery

In this example, several settings of the load panel are changed using the fields of the loadPanel object. To see the changes, refresh the grid's data source by clicking the "Refresh" button. Data for this example is obtained from www.odata.org.


                                    

                                    

masterDetail

Allows you to build a master-detail interface in the grid.

Type: Object

In dxDataGrid, a master-detail interface supplies a usual data row with an expandable section that contains the details on this data row. In that case, the data row is called "master row", while the section is called "detail section".

To enable the master-detail interface, assign true to the masterDetail | enabled option. After that, specify the template for detail sections using the masterDetail | template option. Templates allow you to place virtually anything into the detail sections. For example, you can display another dxDataGrid or any other UI widget there. For more information on specifying the template for the detail sections, see the template option description.

View Demo

Watch Video

noDataText

Specifies text displayed when a grid does not contain any records.

Type: String
Default Value: "No data"

Show Example:
jQuery

In this example, the grid is empty because no data source is assigned to it. You can specify the text to be displayed in the empty grid. Type your text in the text box under the grid. After that, make the text box lose focus by clicking the surrounding area. The typed text will be assigned to the noDataText option and will appear in the grid.


                                    

                                    

onCellClick

A handler for the cellClick event.

Type: function(e)|String
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
jQueryEvent: jQuery.Event
The jQuery event.
data: Object
The object of the data source represented by the row to which the clicked cell belongs.
key: any
The value of the clicked cell as it is specified in a data source.
value: any
The value of the clicked cell in a string format. Use this field to get the value with applied format and precision.
displayValue: String
The value displayed by the clicked cell. Differs from the value field only when the column to which the clicked cell belongs uses lookup.
text: String
The current index of the column to which the clicked cell belongs. For more information on how this index is calculated, refer to the Calculating the Column Index topic.
columnIndex: Number
The index of the row to which the clicked cell belongs. When you have several pages in a grid, grid rows are indexed beginning with 0 on each page. Note that group cells are also counted as rows and, thus, have row indexes. For further information about row indexes, see the Grid Rows topic.
column: Object
The settings of the column to which the clicked cell belongs.
rowIndex: Number
The type of the row to which the clicked cell belongs. This field equals 'data' for ordinary rows or 'group' for group rows. Use this field to distinguish rows by type.
rowType: String
Provides access to element-related jQuery operations.
cellElement: jQuery
The element of the clicked cell.
Default Value: null

The cellClick event fires when a user clicks a grid cell. When implementing a handling function for this event, use the object passed to this function as its parameter. Among the fields of this object, you can find data relating to the clicked cell.

Alternatively, you can navigate to a specific URL when the cellClick event fires. For this purpose, assign this URL to the onCellClick option.

In addition, you can perform some actions when a user clicks a row. For this purpose, handle the rowClick event.

NOTE: cellClick fires before rowClick.

Show Example:
jQuery

In this example, a callback function is assigned to the onCellClick property. This function applies a CSS style to a clicked cell. To see the function in action, click a cell in the grid. You will see the text in this cell become orange.


                                    

                                    

                                    

onCellHoverChanged

A handler for the cellHoverChanged event.

Type: function(e)
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
eventType: String
Identifies whether the cell has been hovered over or hovered out. This field equals either "mouseover" or "mouseout".
data: Object
The object of the data source presented by the row to which the current cell belongs.
key: any
The value of the current cell as it is specified in the data source.
value: any
The value of the current cell in a string format. Use this field to get the value with an applied format and precision.
text: String
The value displayed by the current cell. Differs from the value field only when the column to which the current cell belongs uses lookup.
displayValue: String
The index of the column to which the current cell belongs. For more information on how this index is calculated, refer to the Calculating the Column Index topic.
columnIndex: Number
The index of the row to which the current cell belongs. When you have several pages in a grid, grid rows are indexed beginning with 0 on each page. Note that group cells are also counted as rows and, thus, have row indexes. For further information about row indexes, see the Grid Rows topic.
rowIndex: Number
The settings of the column to which the current cell belongs.
column: Object
The type of the row to which the current cell belongs. This field equals 'data' for ordinary rows or 'group' for group rows. Use this field to distinguish rows by type.
rowType: String
Provides access to element-related jQuery operations.
cellElement: jQuery
The element of the hovered cell.
Default Value: null

The cellHoverChanged event fires when the hover state of a grid cell is changed. When implementing a handling function for this event, use the object passed to this function as its parameter. Among the fields of this object, you can find data relating to the cell whose hover state has been changed. For example, to identify whether a cell has been hovered over or hovered out, check the value of the eventType field.

Show Example:
jQuery

In this example, a callback function is assigned to the onCellHoverChanged property. Within this function a CSS style is applied to a cell when it is hovered over. Once the cell is hovered out, the style is removed. Thus, this callback function implements a custom hot-track feature for grid cells.


                                    

                                    

                                    

onCellPrepared

A handler for the cellPrepared event.

Type: function(e)
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
data: Object
The object of a data source represented by the row to which the prepared cell belongs.
key: any
The value of the prepared cell as it is specified in the data source.
value: any
The value of the prepared cell in a string format. Use this field to get the value with applied format and precision.
displayValue: String
The value displayed by the prepared cell. Differs from the value field only when the column to which the prepared cell belongs uses lookup.
text: String
The index of the column to which the prepared cell belongs. For more information on how this index is calculated, refer to the Calculating the Column Index topic.
columnIndex: Number
The index of the row to which the prepared cell belongs. When you have several pages in a grid, grid rows are indexed beginning with 0 on each page. Note that group cells are also counted as rows and, thus, have row indexes. For further information about row indexes, see the Grid Rows topic.
column: Object
The settings of the column to which the prepared cell belongs.
rowIndex: Number
The type of the row to which the prepared cell belongs. This field equals 'data' for ordinary rows or 'group' for group rows. Use this field to distinguish rows by type.
rowType: String
The group index of the prepared cell. This field is useful if the rowType field is 'group'.
groupIndex: Number
Indicates whether or not the group cell is expanded. This field is useful if the rowType field is 'group'.
isSelected: Boolean
The prepared cell; provides access to element-related jQuery operations.
isExpanded: Boolean
Indicates whether or not the current row is expanded.
cellElement: jQuery
The element of the prepared cell.
Default Value: null

The cellPrepared event fires after a cell has been rendered. When implementing a handling function for this event, use the object passed to this function as its parameter. Among the fields of this object, you can find data relating to the prepared cell.

View Demo

Show Example:
jQuery

In this example, cells that have empty values are colored in cornsilk using a handler assigned to the onCellPrepared property.


                                    

                                    

                                    

onContentReady

A handler for the contentReady event.

Type: function
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
Default Value: null

Assign a function to perform a custom action when widget content is ready.

Show Example:
jQuery

In this example, you can perform various operations in a grid, including sorting, grouping and filtering. Doing this, you may notice when the function assigned to the onContentReady option is called. This function counts its own invocations and displays this number.


                                    

                                    

onDataErrorOccurred

A handler for the dataErrorOccured event.

Type: function
Function parameters:
e: Object
Information on the occurred error.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
The standard Error object that defines the occurred error.
Default Value: null

To handle errors that might occur in the data source, implement a handling function and assign it to the onDataErrorOccurred option. To obtain a human-readable representation of the occurred error, use the message field of the error object passed to the handling function as the parameter's field.

onDisposing

A handler for the disposing event.

Type: function
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the data that is available for binding against the element.
Default Value: null

Assign a function to perform a custom action when you dispose of this component.

onEditingStart

A handler for the editingStart event.

Type: function(e)
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
data: Object
The data object of the row.
key: any
The key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key. If a row has not been transmitted to the data source yet, its key is undefined.
cancel: Boolean
A flag allowing you to prevent the row from switching into the editing state.
column: Object
The options of the column whose cell is switching into the editing state; useful in batch edit mode.
Default Value: null

The editingStart event fires before a row (in row edit mode) or a cell (in batch edit mode) switches into the editing state. When implementing a handler for this event, use the object passed to it as its argument. Among the fields of this object, you can find parameters of the about-to-be-edited row.

If you need to prevent a specific row or cell from switching into the editing state, assign true to the cancel field of the object passed to the handler as the argument.

You can also distinguish rows that exist in the data source from rows that have not yet been transmitted to the data source. For this purpose, use the key field of the object with the row parameters. Not-yet-transmitted rows have this field undefined.

View Demo

Show Example:
jQuery

In this example, only buffered rows can be edited. If you try to edit a row that is already in the data source, your attempt will be ignored. This behavior is accomplished by setting the cancel flag depending on the value of the key field inside the onEditingStart function.


                                    

                                    

onEditorPrepared

A handler for the editorPrepared event.

Type: function(options)
Function parameters:
options: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
parentType: String
Identifies the type of the editor's parent element. Equals 'dataRow', 'filterRow', 'headerRow' or 'searchPanel'. Depending on the value of this field, different options are passed to the onEditorPrepared handling function.
value: any
The current value of the editor.
setValue(newValue): any
A method that should be called to change the cell value when the editor value is changed.
updateValueTimeout: Number
Specifies the delay between the moment a user stops entering a filter value in the filter row or search panel and the moment this value is applied.
width: Number
The width of the editor; equals null for editors of all parent types except for the 'searchPanel'.
disabled: Boolean
Identifies whether or not the editor is disabled.
rtlEnabled: Boolean
Identifies whether or not the editor uses a right-to-left representation.
editorElement: jQuery
Provides access to element-related jQuery operations.
readOnly: Boolean
Identifies whether or not the editor responds to user actions.
Default Value: null

Many grid elements are constructed on editors. For example, the search panel is constructed on a text box, the selection column is built on check boxes in full, etc. Obviously, editors are also used to edit a cell or a row in a grid. When default editors provided by dxDataGrid do not meet your requirements, you can customize them by changing their settings within the onEditorPrepared function. This function will be called after an editor is created.

When implementing this function, use the object passed to it as its argument. Among the fields of this object, you can find the options of the created editor. These options differ depending on the parent element of the editor. To identify the parent element, check the parentType field of the function's argument.

When the parentType is 'dataRow' or 'headerRow', you can use the options described in the columns reference section.

NOTE: If you have specified the editCellTemplate option, the onEditorPrepared function will not be executed when a row or a cell switches into the editing state.

onEditorPreparing

A handler for the editorPreparing event.

Type: function(e)
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
parentType: String
Identifies the type of the editor's parent element. Equals 'dataRow', 'filterRow', 'headerRow' or 'searchPanel'. Depending on the value of this field, different options are passed to the editorPreparing handler.
value: any
The current value of the editor.
setValue(newValue): any
A method that should be called to change a cell value when the editor value is changed.
updateValueTimeout: Number
Specifies the delay between the moment a user stops entering a filter value in the filter row or search panel and the moment this value is applied.
width: Number
The width of the editor; equals null for editors of all parent types except for the 'searchPanel'.
disabled: Boolean
Identifies whether or not the editor is disabled.
rtlEnabled: Boolean
Identifies whether or not the editor uses a right-to-left representation.
cancel: Boolean
A flag allowing you to cancel the creation of the editor. Set it to true and implement a custom editor if your scenario requires it.
editorElement: jQuery
Provides access to element-related jQuery operations.
readOnly: Boolean
Identifies whether or not the editor responds to user actions.
Default Value: null

Many grid elements are constructed on editors. For example, the search panel is constructed on a text box, the selection column is built on check boxes in full, etc. Obviously, editors are also used to edit a cell or a row in a grid. When default editors provided by dxDataGrid do not meet your requirements, implement a custom editor. For this purpose, assign a function to the onEditorPreparing option. This function accepts an object as the parameter. Assign true to the cancel field of this object. After that, implement your editor using the other fields of this object.

You can distinguish editors by their parent element. Also, the parent element defines data passed to the onEditorPreparing function. To identify the parent element, check the parentType field of the function's argument.

When the parentType is 'dataRow' or 'headerRow', you can use the options described in the columns reference section.

NOTE: If you have specified the editCellTemplate option, the onEditorPrepared function will not be executed when a row or a cell switches into the editing state.

onInitNewRow

A handler for the initNewRow event.

Type: function(e)
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
data: Object
Data of the inserted row; initially empty.
Default Value: null

By default, a row inserted into a grid contains no data. If you need this row to contain some data, e.g., default values of row cells, implement a function handling the initNewRow event. Use the data field of the object passed to this function as the argument to access the data object of the new row. Initially, this data object is empty. Populate this object with data in such a manner that its fields correspond to the fields of a data source object.

NOTE: Populating all fields of the data object is not necessary. Populate only those of them that must initialize the specific cells of a new row.

View Demo

Show Example:
jQuery

In this example, you can insert rows into a grid. Before a new row appears, the onInitNewRow function initializes its format data field with a "paperback" value.


                                    

                                    

onOptionChanged

A handler for the optionChanged event.

Type: function
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the data that is available for binding against the element.
value: any
Specifies a new value for the option.
Default Value: null

Assign a function to perform a custom action after an option of the component is changed.

onRowClick

A handler for the rowClick event.

Type: function(e)|String
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
jQueryEvent: jQuery.Event
The jQuery event.
data: Object
The object of the data source represented by the clicked row.
key: any
The key value of the clicked row.
values: Array
Values of the clicked row as they exist in the data source.
columns: Array
Grid columns. Each column in this array is represented by an object with column settings. The order of columns in this array and columns in the columns array coincides.
rowIndex: Number
The index of the clicked row. When you have several pages in a grid, grid rows are indexed beginning with 0 on each page. Note that group rows are also counted and, thus, have row indexes. For further information about row indexes, see the Grid Rows topic.
rowType: String
The type of the clicked row. This field equals 'data' for ordinary rows, 'group' for group rows or 'detail' for detail sections. Use this field to distinguish rows by type.
isSelected: Boolean
Indicates whether the clicked row is selected.
isExpanded: Boolean
Indicates whether or not the group row is expanded. This field is useful if the rowType field is 'group'.
groupIndex: Number
The group index of the clicked row. This field is useful if the rowType field is 'group'.
rowElement: jQuery
The clicked row; provides access to element-related jQuery operations.
handled: Boolean
Indicates if the grid has already handled the row click event.
Default Value: null

The rowClick event fires when a user clicks a grid row. When implementing a handling function for this event, use the object passed to this function as its parameter. Among the fields of this object, you can find data relating to the clicked row.

Alternatively, you can navigate to a specific URL when the rowClick event fires. For this purpose, assign this URL to the onRowClick option.

NOTE: When the clicked row is in the editing state, or switches to the editing state, the rowClick event will not fire.

In addition, you can perform some actions when a user clicks a cell. For this purpose, handle the cellClick event. Note that the cellClick fires before the rowClick.

Show Example:
jQuery

In this example, a callback function is assigned to the onRowClick property. This function applies a CSS style to a clicked row. To see the function in action, click a row in the grid. You will see this row painted gray.


                                    

                                    

                                    

onRowInserted

A handler for the rowInserted event.

Type: function(e)
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
data: Object
Data of the row.
key: any
The key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key.
The standard Error object that defines the occurred error.
Default Value: null

The rowInserted event fires after a row has been inserted into the data source. When implementing a handling function for this event, use the object passed to this function as its argument. Among the fields of this object, you can find the key and data of the inserted row.

NOTE: In batch edit mode, when several rows have been inserted, the onRowInserted function will be executed for each row individually.

View Demo

onRowInserting

A handler for the rowInserting event.

Type: function(e)
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
data: Object
Data of the row.
cancel: Boolean
A flag allowing you to prevent the row from being inserted into the data source.
Default Value: null

The rowInserting event fires before a new grid row is transmitted to the data source. To handle this event, implement a function and assign it to the onRowInserting option. Using the function's argument, you can access the object with information about the event.

Among the fields of this object, you can find the cancel flag that allows you to prevent the row from being transmitted to the data source. In order to accomplish that, set this flag to true. The behavior of rejected rows depends on the edit mode. In row mode, a rejected row does not switch back to the normal state. In batch mode, rejected rows stay buffered.

NOTE: In batch edit mode, when several rows are to be inserted, the onRowInserting function will be executed for each row individually.

View Demo

Show Example:
jQuery

In this example, if you try to save a new row without the "Author" or "Title" field specified, this row will be rejected and the alert dialog box will appear.


                                    

                                    

onRowPrepared

A handler for the rowPrepared event.

Type: function(e)
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
data: Object
The object of a data source represented by the prepared row.
key: any
Values of the current row as they exist in the data source.
values: any
The index of the prepared row. When you have several pages in a grid, grid rows are indexed beginning with 0 on each page. Note that group cells are also counted as rows and, thus, have row indexes. For further information about row indexes, see the Grid Rows topic.
columns: Array
Grid columns. Each column in this array is represented by an object with column settings. The order of columns in this array and columns in the columns array coincides.
rowIndex: Number
Indicates whether the prepared row is selected.
rowType: String
The type of the prepared row. This field equals 'data' for ordinary rows, 'group' for group rows or 'detail' for detail sections. Use this field to distinguish rows by type.
groupIndex: Number
The prepared row; provides access to element-related jQuery operations.
isSelected: Boolean
Indicates whether the prepared row is selected.
isExpanded: Boolean
Indicates whether the prepared row is expanded.
rowElement: jQuery
The element of the hovered row.
Default Value: null

The rowPrepared event fires after a row has been rendered. When implementing a handling function for this event, use the object passed to this function as its parameter. Among the fields of this object, you can find data relating to the prepared row.

Show Example:
jQuery

In this example, all grid records that represent books written in the 19th century are colored in silver using the handler assigned to the onRowPrepared property.


                                    

                                    

                                    

onRowRemoved

A handler for the rowRemoved event.

Type: function(e)
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
data: Object
Data of the row.
key: any
The key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key.
The standard Error object that defines the occurred error.
Default Value: null

The rowRemoved event fires after a row has been removed from the data source. When implementing a handling function for this event, use the object passed to this function as its argument. Among the fields of this object, you can find the data and key of the removed row.

NOTE: In batch edit mode, when several rows have been removed, the onRowRemoved function will be executed for each row individually.

View Demo

onRowRemoving

A handler for the rowRemoving event.

Type: function(e)
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
data: Object
Data of the row.
key: any
The key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key.
cancel: Boolean
A flag allowing you to prevent the row from being removed from the data source.
Default Value: null

The rowRemoving event fires before a row is removed from a data source. To handle this event, implement a function and assign it to the onRowRemoving option. Using the function's argument, you can access the object with information about the event.

Among the fields of this object, you can find the cancel flag that allows you to prevent the row from being removed from the data source. In order to accomplish that, set this flag to true. The behavior of the rows, whose removal was canceled, depends on the edit mode. In row mode, such a row is preserved. In batch mode, such rows are displayed as recoverable.

NOTE: In a batch edit mode, when several rows are to be removed, the onRowRemoving function will be executed for each row individually.

View Demo

Show Example:
jQuery

In this example, grid settings allow you to delete rows. Since batch edit mode is set, you can also recover deleted rows. Note that when you save changes, rows that have the format field equaling "hardcover" will not be deleted from the data source and will stay recoverable. It is the result of implementing the onRowRemoving function that prohibits these rows from being deleted.


                                    

                                    

onRowUpdated

A handler for the rowUpdated event.

Type: function(e)
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
data: Object
Updated data of the row; contains only those fields that have been updated.
key: any
The key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key.
The standard Error object that defines the occurred error.
Default Value: null

The rowUpdated event fires after a row has been updated in the data source. When implementing a handling function for this event, use the object passed to this function as its parameter. Among the fields of this object, you can find the data object and the key value of the updated row. Note that the data object contains only those fields of a row that have been updated.

NOTE: In batch edit mode, when several rows have been updated, the onRowUpdated function will be executed for each row individually.

View Demo

onRowUpdating

A handler for the rowUpdating event.

Type: function(e)
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
oldData: Object
Old data of the row.
newData: Object
Updated data of the row.
key: any
The key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key.
cancel: Boolean
A flag allowing you to prevent the row from being updated.
Default Value: null

The rowUpdating event fires before a row is updated in a data source. To handle this event, implement a function and assign it to the onRowUpdating option. Using the function's argument, you can access the object with information about the event.

Among the fields of this object, you can find the cancel flag that allows you to prevent the row from being updated. In order to accomplish this, set this flag to true. The behavior of the rows, whose updating was canceled, depends on the edit mode. In row mode, such a row does not switch back to the normal state. In batch mode, changes in such rows stay buffered.

NOTE: In batch edit mode, when several rows are to be updated, the onRowUpdating function will be executed for each row individually.

View Demo

Show Example:
jQuery

In this example, grid settings allow you to edit rows in batch mode. Note that when you save changes, rows that have the format field equaling "hardcover" will not be updated in the data source. It is the result of implementing the onRowUpdating function that prohibits these rows from being updated.


                                    

                                    

onRowValidating

A handler for the rowValidating event.

Type: function(e)
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
brokenRules: Array
An array of broken rules. The structure of rule objects is described in the Validation Rules section.
isValid: Boolean
Indicates whether all the rules checked for the cells in the current row are satisfied.
key: any
The key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key.
newData: Object
Data of the validated row after user changes.
oldData: Object
Data of the validated row as it was before user changes.
errorText: String
The error message to be displayed in the grid's error row.
Default Value: null

When data in a cell or in several cells is changed, the validation rules specified for these cells are checked. Before the validation result (messages on the broken rules) is displayed in the grid, you can interfere by handling the rowValidating event. For instance, you can provide a common text for all the cells where validation rules are not satisfied. This text will be displayed under the validated row in a specially added error row. To provide a common text for a row, specify the errorText field of the event handling function's parameter. In addition, you can change the validation result before it is displayed, by performing an additional check and setting the result to the isValid field of the event handling function's parameter.

In batch mode, when several row updates are committed simultaneously, the rowValidating error fires for each row that has changes.

onSelectionChanged

A handler for the selectionChanged event.

Type: function(e)
Function parameters:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element.
currentSelectedRowKeys: Array
The keys of the rows that have been selected currently.
currentDeselectedRowKeys: Array
The keys of the rows that have been deselected currently.
selectedRowKeys: Array
The keys of all selected rows.
selectedRowsData: Array
The data of all selected rows.
Default Value: null

The selectionChanged event fires when a grid record has been selected/deselected. When implementing a function that handles this event, you can use arrays of keys of those grid records that have been currently selected or deselected. These arrays can be accessed through the fields of the object passed as the function's parameter. Arrays of all selected records and their data are also accessible through the same object.

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

To retrieve data by using a key, use the byKey(key) method.

View Demo

pager

Specifies the options of a grid pager.

Type: Object

A pager is a grid element that allows the user to navigate through grid pages and change their size at runtime. By default, the pager is visible if paging is enabled and you do not use virtual or infinite scrolling. To change the pager's visibility explicitly, use its visible option.

The pager consists of a page navigator and a page size selector. The page navigator contains the numbers of pages. Clicking a page number navigates the user to the page. The page size selector contains the page sizes that can be selected. They are specified by the allowedPageSizes option of the pager configuration object. The page size selector is hidden by default. To make it visible, assign true to the pager's showPageSizeSelector option.

View Demo

Show Example:
jQuery

In this example, the page size selector is made visible using the pager | showPageSizeSelector option. In addition, the set of allowed page sizes is altered by setting the pager | allowedPageSizes option.


                                    

                                    

paging

Specifies paging options.

Type: Object

In dxDataGrid, records can be loaded either page by page or all at once. Needless to say that the latter approach affects grid performance, especially when the number of loading records is very large. If you, however, want to use it, disable paging by setting the paging | enabled option to false.

When paging is on, you can specify the size of grid pages using the pageSize option. Additionally, if you require displaying grid records starting with a certain page, assign its index to the pageIndex option.

A paginated grid can be navigated by a user at runtime. For this purpose, he or she can use a pager or scrolling.

View Demo

Show Example:
jQuery

In this example, fields of the paging object are used to specify paging settings. The size of a grid page is set to 8 records using the paging | pageSize option. In addition, the index of a start page is specified using the paging | pageIndex option. Data for this example is obtained from www.odata.org.


                                    

                                    

remoteOperations

Specifies the operations that must be performed on the server side.

Default Value: "auto"

Data that you use in your grid can be stored on the client side or come from a remote server. In many cases, manipulating data on a server enhances grid performance. However, your server might be falling short in performing certain operations. In that case, specify to perform them on the client-side using the remoteOperations option.

By default, this option is set to 'auto'. It means that whether operations are performed on the client or on the server side depends on the type of the data source. The use of an array of objects, an ArrayStore or a LocalStore forces dxDataGrid to perform filtering, sorting and paging locally. If you use an ODataStore or a CustomStore, these operations are performed remotely.

To control individual operations, set the filtering, paging and sorting fields of the remoteOperations object. To control all operations together, assign a boolean value directly to the remoteOperations option.

NOTE
Certain grid features, such as summary or expanding/collapsing all groups at once, are available only if the grid operates with local data.
NOTE
When setting this option to false or assigning an object with field(s) set to false, corresponding operations are performed locally, but they are accompanied by loading data from the remote server. This is required to use actual data when performing these operations locally.

rowAlternationEnabled

Specifies whether or not grid rows must be shaded in a different way.

Type: Boolean
Default Value: false

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.

View Demo

Show Example:
jQuery

In this example, you can change the value of the rowAlternationEnabled option using the check box below.


                                    

                                    

rowClick

Deprecated

Use the onRowClick option instead.

rowInserted

Deprecated

Use the onRowInserted option instead.

rowInserting

Deprecated

Use the onRowInserting option instead.

rowPrepared

Deprecated

Use the onRowPrepared option instead.

rowRemoved

Deprecated

Use the onRowRemoved option instead.

rowRemoving

Deprecated

Use the onRowRemoving option instead.

rowTemplate

Specifies a custom template for grid rows.

Type: String|function(rowElement, rowInfo)|DOM Node|jQuery
Function parameters:
rowElement: jQuery
The row under customization.
rowInfo: Object
The options of the current row.

Use the rowTemplate option to define the markup of all rows in a grid. Implement a callback function defining the content of a grid row and assign it to this option. This function will be invoked every time dxDataGrid rerenders itself.

When implementing the rowTemplate function, you can access the row under customization using the function's first parameter. This parameter provides access to element-related jQuery operations. In addition, you can access row options using the fields of the function's second parameter. These fields are listed below.

  • data
    Contains the object of the data source represented by the current row.
  • values
    Contains an array of values of the current row as they exist in the data source.
  • rowIndex
    Contains the index of the current row. When you have several pages in the grid, grid rows are indexed beginning with 0 on each page. Note that group cells are also counted as rows, and thus have row indexes. For further information about row indexes, see the Grid Rows topic.
  • columns
    Contains an array of grid columns. Each column in this array is represented by an object with column settings. The order of columns in this array and columns in the columns array coincides.
  • isSelected
    Indicates whether or not the current row is selected.
  • rowType
    Represents the type of the current row. This field equals 'data' for ordinary rows or 'group' for group rows. Use this field to distinguish rows by type.
  • groupIndex
    Contains the group index of the current row. This field is useful if the rowType field is 'group'.
  • isExpanded
    Indicates whether or not the current row is expanded. This field is useful if the rowType field is 'group'.

It is also possible to define a row template in markup. For this purpose, use one of the following template engines. The above mentioned cell settings can be accessed in a similar manner inside the template.

Using a template engine, pass one of the following values to the rowTemplate option.

  • A jQuery object representing the template's container.
  • A DOM Node representing the template's container.
  • A function that returns a jQuery object or a DOM Node representing the template's container.

NOTE: When you use a row template, we recommend you to disable the column reordering and grouping features. It is desirable because the template content can not be automatically synchronized with the column layout what makes these features inoperative.

To customize a row without defining the entire template, handle the rowPrepared event.

See Also

View Demo

rowUpdated

Deprecated

Use the onRowUpdated option instead.

rowUpdating

Deprecated

Use the onRowUpdating option instead.

rtlEnabled

Specifies whether or not the current component supports a right-to-left representation.

Type: Boolean
Default Value: false

If you need to switch the display of this DevExtreme component to right-to-left, enable a specifically designed configuration option - rtlEnabled. When this option is set to true, the text flows from right to left, and the layout the component's elements is reversed. To switch the entire application/site to a right-to-left representation, use the static DevExpress.rtlEnabled field.

Show Example:
jQuery

In this example, you can change the value of the rtlEnabled option at runtime using the check box under the grid.


                                    

                                    

scrolling

A configuration object specifying scrolling options.

Type: Object

The dxDataGrid widget supplies a user with an opportunity to scroll grid records. Scrolling can be performed within one page when used in conjunction with the pager or throughout the whole data source. In the latter case, data is still loaded by pages but a user moves through them continuously without noticing it. To specify required scrolling behavior, use the mode property of the scrolling configuration object.

View Demo

Show Example:
jQuery

In this example, the infinite scrolling mode is specified for a grid using the scrolling | mode option. Data for this example is obtained from www.odata.org.


                                    

                                    

searchPanel

Specifies options of the search panel.

Type: Object

A search panel is a grid element that allows the user to search grid records by a search string. Searching performs in those grid columns that have the allowFiltering option set to true.

The search panel is located in the upper-right corner of the dxDataGrid widget. To make it visible, set the visible property of the searchPanel configuration object to true.

See Also
  • To discover how to configure the search panel, see the Search Panel topic.
  • For more information about searching, refer to the Searching topic.

Also, you can search grid records by a search string from code. Call the searchByText(text) method to do this.

View Demo

Show Example:
jQuery

In this example, the search panel is made visible using the visible option of the searchPanel object. Additionally, its width is changed using the width option of the same object.


                                    

                                    

selectedRowKeys

Specifies the keys of the records that must appear selected initially.

Type: Array

Apart from runtime selection, the dxDataGrid provides the capability to display specific grid records selected initially. For this purpose, specify an array containing the keys of grid records that must appear selected and assign it to the selectedRowKeys field.

NOTE: To access a grid record by a key, a field providing key values must be specified in a data source (see the example below). If no key was specified, the whole data object is considered the key.

You can obtain the selected row keys or data objects. For further information, see the getSelectedRowKeys() and getSelectedRowsData() method descriptions.

Show Example:
jQuery

In this example, several grid records appear selected initially. It is accomplished by assigning their keys in the form of an array to the selectedRowKeys option.


                                    

                                    

selection

Specifies options of runtime selection.

Type: Object

dxDataGrid provides users with the capability of selecting grid records at runtime. End-users can perform selection in a single or multiple mode. To specify the required mode, use the mode property of the selection configuration object. You can disable selection completely using the same property.

When the multiple selection mode is specified, a user is capable of selecting all grid records at once using the main check box or the CTRL + A shortcut. To disable this feature, set the allowSelectAll option to false.

Furthermore, you can perform specific actions when a grid record has been selected/deselected. For additional information, refer to the onSelectionChanged option description.

See Also

For a structured overview of dxDataGrid selection capabilities, see the Selection article.

View Demo

Show Example:
jQuery

In this example, you can select multiple records in a grid. This feature is enabled by setting the selection | mode option to "multiple". However, you cannot select all records at once as the allowSelectAll option is set to false.


                                    

                                    

selectionChanged

Deprecated

Use the onSelectionChanged option instead.

showBorders

Specifies whether the outer borders of the grid are visible or not.

Type: Boolean
Default Value: false

Show Example:
jQuery

In this example, you can change the visibility of grid borders by toggling the check box below.


                                    

                                    

showColumnHeaders

Specifies whether column headers are visible or not.

Type: Boolean
Default Value: true

A column header contains a column caption. For more information about captions, see the columns | caption option description.

Show Example:
jQuery

In this example, you can change the visibility of column headers by toggling the check box below.


                                    

                                    

showColumnLines

Specifies whether or not vertical lines separating one grid column from another are visible.

Type: Boolean
Default Value: true
NOTE
If you use the Android or iOS theme, specifying this option doesn't affect anything. These themes avoid displaying column lines in order to provide native look for the widget. In case you still require the column lines to be displayed, choose another theme.

View Demo

Show Example:
jQuery

In this example, you can change the visibility of the lines that separate grid columns by toggling the check box below.


                                    

                                    

showRowLines

Specifies whether or not horizontal lines separating one grid row from another are visible.

Type: Boolean
Default Value: false
Show Example:
jQuery

In this example, you can change the visibility of the lines that separate grid rows by toggling the check box below.


                                    

                                    

sortByGroupSummaryInfo[]

Allows you to sort groups according to the values of group summary items.

Type: Array
Default Value: undefined

Normally, when records are grouped by a column, the groups are sorted according to the values of this column. In a number of cases, such approaches cannot address your needs, e.g., when you require to sort groups by the number of records in each. For these cases, you can implement sorting according to the values of group summary items. These items are specified in the groupItems array. Assume that you have the following code that specifies three group summary items.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    summary: {
        groupItems: [{
            column: 'Age',
            summaryType: 'avg',
            name: 'Average Age Group Summary'
        }, {
            column: 'Income',
            summaryType: 'max'
        }, {
            column: 'Tasks',
            summaryType: 'min'
        }]
    }
});

To use these summary items for sorting groups, assign an array of objects to the sortByGroupSummaryInfo option. In each object of this array, specify the summaryItem field. This field determines the summary item to be used for summary-based sorting. In the following code, three objects form the sortByGroupSummaryInfo array. In each object, the summaryItem option determines different summary items using different values.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    summary: {
        groupItems: [ ... ]
    },
    sortByGroupSummaryInfo: [
        { summaryItem: 1 }, // determines the maximum income item using its index in the "groupItems" array
        { summaryItem: 'min' }, // determines the minimum tasks item using its aggregate function
        { summaryItem: 'Average Age Group Summary' } // determines the average age item using its name
    ]
});

After that, set the groupColumn option for objects in the sortByGroupSummaryInfo array. This option identifies the column that must be used in grouping in order that a particular summary-based sorting setting be applied. If you have omitted this option from an object, the sorting setting specified by this object will be applied regardless of the column used in grouping.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    summary: {
        groupItems: [ ... ]
    },
    sortByGroupSummaryInfo: [
        { summaryItem: 1, groupColumn: 'Tasks' }, // applies sorting only when records are grouped by the "Tasks" column
        { summaryItem: 'min', groupColumn: 'Last Name' }, // applies sorting only when records are grouped by a "Last Name" column
        { summaryItem: 'Average Age Group Summary' } // applies sorting regardless the grouping column
    ]
});
NOTE
If several summary-based sorting settings match the current grouping, their indexes in the sortByGroupSummaryInfo array will dictate the order of their application.

In addition, you can set an ascending or descending sort order for each summary-based sorting object using its sortOrder option.

sorting

Specifies options of runtime sorting.

Type: Object

In dxDataGrid, a user can sort records by columns at runtime. To make a column available for sorting, set its allowSorting option to true. Sorting can be executed in various modes. To specify the required mode, use the mode property of the sorting configuration object.

See Also

For a structured overview of dxDataGrid sorting capabilities, see the Sorting article.

View Demo

Show Example:
jQuery

In this example, you can sort grid records by multiple columns as the sorting | mode option is set to 'multiple'. To sort records by only one column, click a column header. To sort records by multiple columns, right-click a column header and choose a sort order for the column.


                                    

                                    

stateStoring

Specifies options of state storing.

Type: Object

At runtime, end-users may adjust user interface settings to their needs. By default, these settings disappear when you dispose of the grid; on next loading, the grid appears in its original configuration. If user settings need to be saved and then restored, enable client-side state storing for the grid by setting the stateStoring | enabled option to true. The grid state will be saved under a specified storage key. The saving operation is conducted after a certain amount of time has passed since the last change of the state. To specify the amount of time in milliseconds, use the savingTimeout option.

dxDataGrid supports various types of state storing. The type of storage that will suit your needs best depends on the supposed lifetime of user-specified grid settings. For more information about state storing types, refer to the type option description.

dxDataGrid provides the state method to operate the grid state in code. Call this method without arguments to obtain the grid state. When you need to set the grid state, call this method with the state object as its argument. You can also return the widget to its default state by calling the state method with the empty array or null argument.

View Demo

summary

Specifies the options of the grid summary.

Type: Object

A summary is a grid feature that provides a synopsis of data contained in the grid. A summary consists of several items. A summary item displays a value that is a product of applying an aggregate function to the data of a specific column.

There are two types of summary in dxDataGrid: group and total. The group summary is calculated on a group of data, which is segregated during grouping. To specify the items of the group summary, declare an array of objects and assign it to the summary | groupItems field.

The total summary is calculated on all data contained in the grid. To specify the items of the total summary, declare an array of objects and assign it to the summary | totalItems field.

Watch Video

tabIndex

Specifies the widget tab index.

Type: Number
Default Value: 0

visible

A Boolean value specifying whether or not the widget is visible.

Type: Boolean
Default Value: true

Show Example:
jQuery

In this example, you can change the visibility of the dxDataGrid widget at runtime by toggling the check box below.


                                    

                                    

width

Specifies the width of the widget.

Type: Number|String|function
Return Value: Number|String
The widget width.
Default Value: undefined

The option can hold a value of the following types.

  • numeric
    The widget width in pixels.
  • string
    A CSS measurement of the widget width (e.g., "55px", "80%", "auto" and "inherit").
  • function
    The function returning the widget width. For example, see the following code.

    JavaScript
    width: function () { 
        return baseWidth - 10 + "%";
    }
Show Example:
jQuery

In this example, you can change the width of the dxDataGrid widget using the buttons under it. These buttons increase/decrease the widget's width by 1 pixel.


                                    

                                    

wordWrapEnabled

Specifies whether text that does not fit into a column should be wrapped.

Type: Boolean
Default Value: false

Show Example:
jQuery

In this example, you can change the value of the wordWrapEnabled option at runtime by toggling the check box below.