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

Specifies a callback function that is called when a grid cell is clicked.

Type: function(clickedCell)
Function parameters:
clickedCell: Object
A grid cell that has been clicked.

If you need to perform specific actions on a cell click, assign a callback function to the cellClick option. When implementing this function, you can use data accessible through the object passed as the function's parameter. To access this data, use the following fields of this object.

  • data
    Contains the object of a data source represented by the row to which the clicked cell belongs.
  • value
    Contains the value of the clicked cell as it is specified in a data source.
  • text
    Contains the value of the clicked cell in a string format. Use this field to get the value with an applied format and precision.
  • displayValue
    Contains the value displayed by the clicked cell. Differs from the value field only when the column to which the clicked cell belongs uses lookup.
  • columnIndex
    Contains 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.
  • rowIndex
    Contains 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
    Contains the settings of the column to which the clicked cell belongs.
  • rowType
    Represents 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.
  • cellElement
    Represents the clicked cell element. Provides access to element-related jQuery operations.
  • jQueryEvent
    Provides access to the jQuery event object.

In addition, you can perform some actions on row click. For this purpose, implement the rowClick function.

NOTE: When both the cellClick and rowClick functions are specified, the former will be invoked first.

Show Example:
jQuery

In this example, a callback function is assigned to the cellClick 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.


                                    

                                    

                                    

cellHoverChanged

Specifies a callback function that is invoked when the hover state of a cell is changed.

Type: function(hoveredCellInfo)
Function parameters:
hoveredCellInfo: Object
The options of the currently hovered over or hovered out cell.

If you need to accomplish specific actions when a user moves the mouse over and away from a grid cell, assign a callback function to the cellHoverChanged option. When implementing this function, you can access cell options using the fields of the object passed to the function as a parameter. These fields are listed below.

  • eventType
    Provides information about the type of hovering. This field has either the "mouseover" or the "mouseout" value.
  • data
    Contains the object of the data source represented by the row to which the current cell belongs.
  • value
    Contains the value of the current cell as it is specified in the data source.
  • text
    Contains the value of the current cell in a string format. Use this field to get the value with a format and precision applied.
  • displayValue
    Contains the value displayed by the current cell. Differs from the value field only when the column to which the current cell belongs uses lookup.
  • columnIndex
    Contains 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.
  • rowIndex
    Contains 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 counted as rows as well, and thus have row indexes. For further information about row indexes, see the Grid Rows topic.
  • column
    Contains the settings of the column to which the current cell belongs.
  • rowType
    Represents 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.
  • cellElement
    Represents the current cell as an element. This field provides access to element-related jQuery operations.
  • jQueryEvent
    Represents the jQuery event object.
Show Example:
jQuery

In this example, a callback function is assigned to the cellHoverChanged 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.


                                    

                                    

                                    

cellPrepared

Specifies a callback function that is called after a cell has been rendered.

Type: function(cellElement, cellInfo)
Function parameters:
cellElement: Object
The cell under customization.
cellInfo: Object
The options of the current cell.

Assign a callback function to the cellPrepared option to customize a grid cell. When implementing this function, you can access the cell being customized using the function's first parameter. This parameter provides access to element-related jQuery operations. In addition, you can access the cell options using the fields of the function's second parameter. These fields are listed below.

  • data
    Contains the object of a data source represented by the row to which the current cell belongs.
  • value
    Contains the value of the current cell as it is specified in the data source.
  • text
    Contains the value of the current cell in a string format. Use this field to get the value with a format and precision applied.
  • displayValue
    Contains the value displayed by the current cell. Differs from the value field only when the column to which the current cell belongs uses lookup.
  • columnIndex
    Contains 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.
  • rowIndex
    Contains the index of a 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 counted as rows as well, and thus have row indexes. For further information about row indexes, see the Grid Rows topic.
  • column
    Contains the settings of the column to which the current cell belongs.
  • rowType
    Represents 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.
  • groupIndex
    Contains the group index of the current cell. This field is useful if the rowType field is 'group'.
  • isExpanded
    Indicates whether or not the group cell is expanded. This field is useful if the rowType field is 'group'.

If cell customization does not meet your needs, define a custom cell markup for each grid column using the cellTemplate callback function.

Show Example:
jQuery

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


                                    

                                    

                                    

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.

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.


                                    

                                    

contentReadyAction

An action performed when the grid content is ready.

Type: String|function(e)
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Returns the grid 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 the grid content is ready.

Alternatively, you can assign a URL to which the browser will navigate when the grid 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 contentReadyAction option is called. This function counts its own invocations and displays this number.


                                    

                                    

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

Specifies a callback function that is called when an error occurs in the data source.

Type: function(errorObject)
Function parameters:
Information on the occurred error.
Default Value: null

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

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 Configuration Object
    The dxDataGrid widget creates a DataSource object internally to retrieve data from a storage. 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.

    NOTE: It is important that dxDataGrid accepts not a DataSource instance, but a DataSource configuration object.

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.

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

Enables you to manipulate a row or a cell before it switches into the editing state.

Type: function(rowInfo)
Function parameters:
rowInfo: Object
Parameters of the row that is switching into the editing state.
Object structure:
data: Object
The data object of the row.
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 the batch edit mode.

When editing has been initiated by a user or in code, certain actions can be performed. To specify them, implement a callback function and assign it to the editingStart option. This function will be called before a row or a cell switches into the editing state. Using the function's argument, you can access the object with the parameters of the row.

NOTE: In batch edit mode, the editingStart function is called before a cell (not a row) switches into the editing state. However, this function still accepts the parameters of the row, which this cell belongs to.

Among the row parameters passed to the callback function, you can find the cancel flag allowing you to prevent the row or its cell from switching into the editing state. In order to accomplish that, set this flag to true. In this case, the row or its cell will refuse any attempts to switch into the editing state.

You can also distinguish rows existing in the data source from buffered rows, which have not been transmitted to the data source yet. For this purpose, use the key field of the object with the row parameters. Buffered rows have this field undefined.

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 editingStart function.


                                    

                                    

editorPrepared

Allows you to customize editors contained in a grid after they were created.

Type: function(editorContainer, options)
Function parameters:
editorContainer: Object
The container of the editor being customized.
options: Object
The options of the editor being customized.

Many grid elements are constructed on the base of editors. For example, the search panel is constructed upon 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 editorPrepared function. This function will be called after an editor is created.

When implementing this function, use the objects passed to it as the arguments. The first object represents the container of the editor being customized. This object provides access to element-related jQuery operations. To access the options of the editor, use the fields of the function's second argument. These options differ depending on the parent element of the editor. However, there is a set of options that is always passed to the editorPrepared function.

  • parentType 'dataRow' | 'filterRow' | 'headerRow' | 'searchPanel'
    Identifies the type of the editor's parent element. Depending on the value of this field, different options are passed to the editorPrepared function.
  • value
    Contains the current value of the editor.
  • setValue(newValue)
    A method that should be called to change the cell value when the editor value is changed.
  • width
    Contains the width of the editor; equals null for editors of all parent types except for the 'searchPanel'.
  • disabled
    A flag identifying whether or not the editor responds to user actions.
  • rtlEnabled
    A flag identifying whether or not the editor uses a right-to-left representation.

In addition to these options, 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 editorPrepared function will not be called when a row or a cell switches into the editing state.

editorPreparing

Allows you to customize editors contained in a grid before they are created.

Type: function(editorContainer, options)
Function parameters:
editorContainer: Object
The container of the editor being customized.
options: Object
The options of the editor being customized.

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 the dxDataGrid do not meet your requirements, you can customize them by changing their settings within the editorPreparing function. This function will be called before an editor is created.

When implementing this function, use the objects passed to it as the arguments. The first object represents the container of the editor being customized. This object provides access to element-related jQuery operations. To access the options of the editor, use the fields of the function's second argument. These options differ depending on the parent element of the editor. However, there is a set of options that is always passed to the editorPreparing function.

  • parentType 'dataRow' | 'filterRow' | 'headerRow' | 'searchPanel'
    Identifies the type of the editor's parent element. Depending on the value of this field, different options are passed to the editorPreparing function.
  • value
    Contains the current value of the editor.
  • setValue(newValue)
    A method that should be called to change a cell value when the editor value is changed.
  • width
    Contains the width of the editor; equals null for editors of all parent types except for 'searchPanel'.
  • disabled
    A flag identifying whether the editor responds to user actions.
  • rtlEnabled
    A flag identifying whether the editor uses a right-to-left representation.
  • cancel
    A flag allowing you to cancel the creation of the editor. Set it to true and implement a custom editor if it is required by your scenario.

In addition to these options, 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 editorPreparing function will not be called when a row or a cell switches into the editing state.

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.
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.


                                    

                                    

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.

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.

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.

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

    JavaScript
    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.


                                    

                                    

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

Enables you to initialize a row on insertion.

Type: function(rowInfo)
Function parameters:
rowInfo: Object
Parameters of the inserted row.
Object structure:
data: Object
Data of the inserted row; initially empty.

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 callback function and assign it to the initNewRow option. 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 specific cells of a new row.

Show Example:
jQuery

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


                                    

                                    

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.


                                    

                                    

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.


                                    

                                    

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.

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.

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.


                                    

                                    

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.

Show Example:
jQuery

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


                                    

                                    

rowClick

Specifies a callback function that is called when a grid row is clicked.

Type: function(clickedRow)
Function parameters:
clickedRow: Object
A grid row that has been clicked.

If you must perform specific actions on a row click, assign a callback function to the rowClick option. When implementing this function, you can use data accessible through the object passed as the function's first parameter. To access this data, use the following fields of this object.

  • data
    Contains the object of a data source represented by the clicked row.
  • values
    Contains an array of values of the clicked row as they exist in the data source.
  • rowIndex
    Contains 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 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 the clicked row is selected.
  • rowType
    Represents the type of the clicked 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 clicked row. This field is useful if the rowType field is 'group'.
  • isExpanded
    Indicates whether the clicked row is expanded. This field is useful if the rowType field is 'group'.
  • rowElement
    Represents the clicked row of an element. Provides access to element-related jQuery operations.
  • jQueryEvent
    Provides access to the jQuery-event object.

NOTE: When the clicked row is in an editing state, or switches to an editing state, the rowClick function will not be invoked.

In addition, you can perform actions on a cell click. To do so, implement the cellClick function.

NOTE: When both the cellClick and rowClick functions are specified, the former will be invoked first.

Show Example:
jQuery

In this example, a callback function is assigned to the rowClick 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.


                                    

                                    

                                    

rowInserted

Enables you to perform certain actions after a row has been inserted into the data source.

Type: function(rowInfo)
Function parameters:
rowInfo: Object
Parameters of the inserted row.
Object structure:
data: Object
Data of the row.
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.

After a row has been inserted into the data source, actions specified by the rowInserted callback function are performed. When implementing this function, you can access the object with the parameters of the row, which include data and key value, using the function's argument.

NOTE: In batch edit mode, when several rows have been inserted, the rowInserted function is invoked for each row individually.

rowInserting

Enables you to perform certain actions before a row is transmitted to the data source.

Type: function(rowInfo)
Function parameters:
rowInfo: Object
Parameters of the row that is about to be inserted.
Object structure:
data: Object
Data of the row.
cancel: Boolean
A flag allowing you to prevent the row from being inserted into the data source.

When an inserted grid row is about to be transmitted to a data source, you may need to perform certain actions. To specify them, implement a callback function and assign it to the rowInserting option. This function will be called before a row is added to the data source. Using the function's argument, you can access the object with the parameters of the row.

Among the row parameters passed to the callback function, 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 the row mode, a rejected row does not switch back to the normal state. In the batch mode, rejected rows stay buffered.

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

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.


                                    

                                    

rowPrepared

Specifies a callback function that is called after a row has been rendered.

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

Assign a callback function to the rowPrepared option to customize a grid row. When implementing this 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 the options of the row 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 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
    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 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.

If row customization does not meet your needs, define a custom row markup using the rowTemplate callback function.

Show Example:
jQuery

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


                                    

                                    

                                    

rowRemoved

Enables you to perform certain actions after a row has been removed from the data source.

Type: function(rowInfo)
Function parameters:
rowInfo: Object
Parameters of the row that has been removed.
Object structure:
data: Object
Data of the row.
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.

After a row has been removed from the data source, actions specified by the rowRemoved callback function are performed. When implementing this function, you can access the object with the parameters of the row, which include data and key value, using the function's argument.

NOTE: In batch edit mode, when several rows have been removed, the rowRemoved function is invoked for each row individually.

rowRemoving

Enables you to perform certain actions before a row is removed from the data source.

Type: function(rowInfo)
Function parameters:
rowInfo: Object
Parameters of the row that is about to be removed.
Object structure:
data: Object
Data of the row.
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.

Before a row is removed from a data source, actions specified by the rowRemoving callback function are performed. When implementing this function, you can access the object with the parameters of the row using the function's argument.

Among the row parameters passed to the callback function, 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 removing 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 batch edit mode, when several rows are to be removed, the rowRemoving function will be invoked for each row individually.

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 rowRemoving function that prohibits these rows from being deleted.


                                    

                                    

rowTemplate

Specifies a custom template for grid rows.

Type: String|function(rowElement, rowInfo)
Function parameters:
rowElement: Object
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.

If you use a template engine, assign the rowTemplate option - the name of the template preceded by the '#' symbol. The above mentioned cell settings can be accessed in a similar manner inside the template.

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, use the rowPrepared callback function.

View Demo

rowUpdated

Enables you to perform certain actions after a row has been updated in the data source.

Type: function(rowInfo)
Function parameters:
rowInfo: Object
Parameters of the row that has been updated.
Object structure:
data: Object
Updated data of the row; contains only those fields that has been updated.
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.

After a row has been updated in the data source, actions specified by the rowUpdated callback function are performed. When implementing this function, you can access the object with the parameters of the row, which include a data object and key value, using the function's argument. 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 rowUpdated function is invoked for each row individually.

rowUpdating

Enables you to perform certain actions before a row is updated in the data source.

Type: function(rowInfo)
Function parameters:
rowInfo: Object
Parameters of the row that is about to be updated.
Object structure:
oldData: Object
Old data of the row.
newData: Object
Updated data of the row.
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.

Before a row is updated in a data source, actions specified by the rowUpdating callback function are performed. When implementing this function, you can access the object with the parameters of the row using the function's argument.

Among the row parameters passed to the callback function, you can find the cancel flag that allows you to prevent the row from being updated. In order to accomplish that, 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 rowUpdating function will be invoked for each row individually.

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 rowUpdating function that prohibits this rows from being updated.


                                    

                                    

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.

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.

Note that 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.

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.

If at least one grid record matches a search string, this string is highlighted in the located record. To disable this feature, assign false to the highlightSearchText property. Additionally, you can specify the width of the search panel and the text displayed in it when it is empty using the width and placeholder options respectively.

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

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 the data source (see the demo 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 selectionChanged option description.

See Also

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

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

Specifies a callback function that is called when a grid record has been selected/deselected.

Type: function(selectedRowsInfo)
Function parameters:
selectedRowsInfo: Object
Information on selected rows.
Object structure:
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.

When implementing a function for this option, 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 key for a grid record. In this case, all arrays passed to the selectionChanged function contain data objects instead of keys.

View Demo

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

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.


                                    

                                    

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.

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.

View Demo

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.