Configuration

This section describes the configuration options of the DataGrid widget.

accessKey

Specifies a shortcut key that sets focus on the widget element.

Type:

String

Default Value: null

The accessKey option value is passed to the accesskey attribute of the actual HTML element of the widget.

activeStateEnabled

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

Type:

Boolean

Default Value: false

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.

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.

cacheEnabled

Specifies whether or not to enable data caching.

Type:

Boolean

Default Value: true

When this option is enabled, data loaded once is saved to the cache, then the grid uses this cache when performing such operations as sorting, grouping, paging, etc. Caching is helpful when the data source is very large and takes significant time to load.

To force a cache update, use the refresh() method or reload the dataSource.

Consider disabling this feature if your grid displays current data and you need to always keep the grid up to date.

NOTE
If you fetch data from a server, some operations on the data can be executed remotely, while others - locally. If you perform basic operations (sorting, filtering and paging) remotely and advanced operations (grouping and summary calculation) locally, certain actions will force DataGrid to query the server for data repeatedly despite caching being enabled. For example, the advanced operations demand data to be reloaded in full from the server to provide correct results.

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.

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. In this scenario, consider enabling column fixing.

When this option is set to false, all grid columns have the same width, which is calculated using 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.

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 DevExtreme DataGrid ColumnChooser, 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.

columnFixing

Specifies options for column fixing.

Type:

Object

When a total column width is greater than the width of the grid's container, horizontal scrolling appears. This may happen in the following cases:

If you need specific columns to be displayed on screen regardless of the scrolling performed, set the columnFixing | enabled option to true. In this instance, the columns for which the fixed option is set to true will be anchored to the grid's edge. For instance, the command columns, the ones containing check boxes to select rows or links to save/delete rows, will be fixed since their fixed option is set to true.

You can anchor an unlimited number of columns to any grid edge. To specify a required edge, use a column's fixedPosition option.

View Demo

columnHidingEnabled

Specifies whether the widget should hide columns in order to adapt to the screen or container size.

Type:

Boolean

Default Value: false

You may want to use different layouts for different screen sizes when displaying the DataGrid in your app. While desktop monitors provide enough space to display all columns, mobile screens do not. In that case, you can enable the widget to hide certain columns automatically if they do not fit into the screen size. For this purpose, assign true to the columnHidingEnabled option. Information from hidden columns is still available in the adaptive detail row.

For hiding columns, the DataGrid uses the following principles:

  1. The lower the hidingPriority option value, the higher the probability that this column is hidden. When you do not specify hiding priorities explicitly, their values ascend from right to left beginning with 0. This means that the widget hides the rightmost columns at first.
  2. If the width of a column is specified, this column hides only if it does not fit into the width of the widget.
  3. If the width of a column is not specified, this column hides only if its content overflows.
See Also

Watch Video

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 Watch Video

customizeColumns

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

Type:

Function

Function parameters:
columns:

Array

Grid columns.

Usually, each column in DataGrid 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 parameter. Fields of each object in this array represent column options identical to the options described in the columns reference section.

customizeExportData

Customizes grid columns and data before exporting.

Type:

Function

Function parameters:
columns:

Array

rows:

Array

Grid rows. If only selected rows are to be exported, this array contains only them.

The function assigned to this option will be called between the onExporting and onExported functions. Use the arguments of this function to access and change different column and row options.

See Also

dataSource

Specifies a data source for the grid.

Default Value: null

This option accepts one of the following.

  • Array of objects
    A simple JavaScript array containing a collection of plain objects.

  • URL
    A URL to JSON data or to a service returning data in JSON format.

  • DataSource or its configuration object
    A DataSource is an object that provides a handy API for data processing. A DataSource is a stateful object, which means that it saves data processing settings and applies them each time data is loaded. All underlying data access logic of a DataSource is isolated in a Store. A Store provides an API for reading and modifying data. Unlike the DataSource, a Store is a stateless object. [note]If you use data mapping and export data to a file, the changes made to data by the map function are ommitted in the exported file. The same occurs while getting data of the selected rows. It is better to use calculated columns instead of mapping.

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

dateSerializationFormat

Specifies the serialization format for date-time values.

Type:

String

If you do not set the dataSource option at design time, the widget cannot detect the format of date-time values automatically. In this case, specify the dateSerializationFormat option. You can also do this to serialize date-time values to a specific format.

The following formats are supported.

  • "yyyy-MM-dd" - a local date

  • "yyyy-MM-ddTHH:mm:ss" - a local date and time

  • "yyyy-MM-ddTHH:mm:ssZ" - a UTC date and time

  • "yyyy-MM-ddTHH:mm:ssx" - a date and time with a timezone

Note that this option applies only if the forceIsoDateParsing field of the global configuration object is set to true.

JavaScript
DevExpress.config({
    forceIsoDateParsing: true
});

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.

editing

Contains options that specify how grid content can be changed.

Type:

Object

DataGrid supports editing, insertion and the removing of grid values. The availability of performing a certain operation is specified by the allowUpdating, allowAdding and allowDeleting options.

Editing in DataGrid can be performed in four different modes. For a comprehensive overview of them, see the Row Mode, Batch Mode, Cell Mode and Form Mode articles.

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

View Demo

elementAttr

Specifies the attributes to be attached to the widget's root element.

Type:

Object

Default Value: {}

When you configure this option using a server-side wrapper, pass a dictionary as shown in the following code.

Razor C#
Razor VB
@(Html.DevExtreme()
    // other widget options
    // ...
    .ElementAttr(new Dictionary<string, object>() {
        { "id", "elementId" },
        { "class", "class-name" },
        // ...
    })
)
@(Html.DevExtreme().WidgetName() _
    .ElementAttr(New Dictionary(Of String, Object) From {
        { "id", "elementId" },
        { "class", "class-name" }
    })
)

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.

export

Configures client-side export.

Type:

Object

When client-side export is enabled, the grid toolbar contains the Export button ( DevExtreme DataGrid HTML5 Toolbar Exporting ) that exports grid data to Excel. For details on exporting, refer to the Client-Side Export article.

NOTE
Client-side export requires the JSZip library. Learn where you can get it from topics in the Installation section.

View Demo Watch Video

filterRow

Specifies filter row options.

Type:

Object

In DataGrid, 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.

NOTE
This feature is not available for hidden columns.
See Also

View Demo

focusStateEnabled

Specifies whether or not the widget can be focused.

Type:

Boolean

Default Value: false

grouping

Specifies grouping settings and the behavior of grouped grid records.

Type:

Object

An end-user can group data using the group panel, the context menu appearing by a click on a column header, or both. The following list provides an overview of grouping settings that you can specify using the grouping object.

  • Enabling
    To enable grouping using the context menu, assign true to the contextMenuEnabled option. Also, you can enable grouping using the group panel. For this purpose, assign true or "auto" to the groupPanel | visible option.

    JavaScript
    var dataGridOptions = {
        // ...
        grouping: {
            // ...
            contextMenuEnabled: true // enables grouping using the context menu
        },
        groupPanel: {
            // ...
            visible: true // enables grouping using the group panel
        }
    };

    If you need to disable grouping for an individual column, assign false to the allowGrouping property of this column.

  • Behavior
    There are two modes defining how the user expands/collapses groups. The "buttonClick" mode is suitable for medium- and large-screen devices. The "rowClick" mode is designed for small-screen devices, though it performs perfectly on the others as well. For more information on these modes, see the expandMode option.

    JavaScript
    var dataGridOptions = {
        // ...
        grouping: {
            // ...
            expandMode: 'buttonClick' // 'rowClick'
        }
    };

    A group can appear either expanded or collapsed initially. To specify that, use the autoExpandAll option. Also, you can disallow the user to collapse groups. For this purpose, assign false to the allowCollapsing option.

    JavaScript
    var dataGridOptions = {
        // ...
        grouping: {
            // ...
            autoExpandAll: true, // makes the groups appear expanded
            allowCollapsing: false // disallows group collapsing
        }
    };

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

See Also

View Demo

groupPanel

Configures the group panel.

Type:

Object

Data in DataGrid can be grouped by one column or by several. Once a column is used for grouping, it is added to the group panel.

By default, the group panel is hidden. To make it visible, set the groupPanel | visible option to true. Alternatively, the visibility of the group panel can depend on the device's screen size. To accomplish this behavior, set the visible option to "auto".

In case you need to show the group panel, but make it irresponsive, assign false to the groupPanel | allowColumnDragging option. This is useful, for instance, when grid records are grouped initially and when the user needs to know about that grouping, but must not be able to change it.

See Also
  • grouping | contextMenuEnabled - enables the user to group data using the context menu.
  • columns[] | allowGrouping - disallows grouping for an individual column.
  • grouping - defines the behavior of groups.

View Demo

headerFilter

Specifies options for filtering using a column header filter.

Type:

Object

When a column header filter is visible, each column header is accompanied by a filter icon that invokes a dropdown menu. In this menu, all unique values from the current column are listed. An end user can select one or several values for filtering the grid rows.

You can specify the column-level header filtering options using the columns | headerFilter object.

NOTE
This feature is not available for hidden columns.

For details on filtering, refer to the Filtering article.

View Demo

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

    JavaScript
    height: function () {
        return baseHeight - 10 + "%";
    }

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

loadPanel

Specifies options configuring the load panel.

Type:

Object

When DataGrid operates with a large number of records or uses a remote storage as a data source, loading data takes time. As data is being prepared, DataGrid 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.

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

masterDetail

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

Type:

Object

In DataGrid, 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 DataGrid 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'

onAdaptiveDetailRowPreparing

A handler for the adaptiveDetailRowPreparing event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

formOptions

Object

Layout options of the dxForm widget.

Default Value: null

Adaptive detail rows display information from columns that were hidden when the widget adapted to the screen or container size. The adaptiveDetailRowPreparing event fires before an adaptive detail row will be rendered. This row contains the Form widget defining the layout of row items. When implementing the event handler, you can access the Form options using the formOptions field of the handler's parameter.

NOTE
There is a number of Form options that you cannot specify using formOptions due to technical restrictions. Those are the following.
- template
- editorType
- any event handler (options whose name starts with "on...")
See Also

onCellClick

A handler for the cellClick event.

Type:

Function

|

String

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

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 key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key.

value any

The value of the clicked cell as it is specified in a data source.

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 value of the clicked cell in a string format. Use this field to get the value with applied format.

columnIndex

Number

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.

column

Object

The settings of the column to which the clicked cell belongs.

rowIndex

Number

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

rowType

String

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

jQuery

The element of the clicked cell.

row

DataGrid Row

The settings of the row to which the clicked cell belongs.

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.

onCellHoverChanged

A handler for the cellHoverChanged event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

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 key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key.

value any

The value of the current cell as it is specified in the data source.

text

String

The value of the current cell in a string format. Use this field to get the value with an applied format.

displayValue

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.

columnIndex

Number

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

Number

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

column

Object

The settings of the column to which the current cell belongs.

rowType

String

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

jQuery

The element of the hovered cell.

row

DataGrid Row

The settings of the row to which the cell belongs.

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.

onCellPrepared

A handler for the cellPrepared event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

data

Object

The object of a data source represented by the row to which the prepared cell belongs. This field is unavailable if the rowType field is set to "header", "filter" or "totalFooter".

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. This field is unavailable if the rowType field is set to "header", "filter" or "totalFooter".

value any

The value of the prepared cell as it is specified in the data source.

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 value of the current cell in a string format. Use this field to get the value with applied format.

columnIndex

Number

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.

column

Object

The settings of the column to which the prepared cell belongs.

rowIndex

Number

The visible 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 row to which the prepared cell belongs. This field can be set to one of the following values: "data", "detail", "group", "groupFooter", "header", "filter" or "totalFooter". Use this field to distinguish rows by type.

row

DataGrid Row

The settings of the row to which the cell belongs.

isSelected

Boolean

Indicates whether the prepared row is selected. This field is useful if the rowType field is set to "data"

isExpanded

Boolean

Indicates whether or not the group cell is expanded. This field is unavailable if the rowType field is set to "header", "filter" or "totalFooter".

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

onContentReady

A handler for the contentReady event. Executed when the widget's content is ready. This handler may be executed multiple times during the widget's lifetime depending on the number of times its content changes.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

Default Value: null

onContextMenuPreparing

A handler for the contextMenuPreparing event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

items

Array

An array of items to be displayed by the context menu. The item objects must have the fields that are used by the ContextMenu default item template.

target

String

The name of the grid element on which the context menu is invoked: 'headerPanel', 'header', 'content' or 'footer'.

targetElement

jQuery

The cell that has been clicked to invoke the context menu.

columnIndex

Number

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.

column

Object

The settings of the column to which the clicked cell belongs.

rowIndex

Number

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

row

DataGrid Row

The settings of the row to which the clicked cell belongs.

Default Value: null

Assign a function to perform a custom action before a context menu is displayed in the grid. For instance, you can change the set of items in the menu.

onDataErrorOccurred

A handler for the dataErrorOccured event.

Type:

Function

Function parameters:
e:

Object

Information on the occurred error.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

error JavaScript Error object

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:
Name Type Description
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. Available only in the Knockout approach.

Default Value: null

Assign a function to perform a custom action when the widget is being removed.

NOTE
The function assigned to this option is executed only if the widget is removed using the remove(), empty(), or html() jQuery methods.

onEditingStart

A handler for the editingStart event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

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

onEditorPrepared

A handler for the editorPrepared event.

Type:

Function

Function parameters:
options:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

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.

dataField

String

The name of the field providing data for the column that the editor belongs to.

row

DataGrid Row

The properties of the row that the editor belongs to.

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

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

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

editorName

String

The name of the editor widget.

editorOptions

Object

An object with configuration options for the editor widget.

dataField

String

The name of the field providing data for the column that the editor belongs to.

row

DataGrid Row

The properties of the row that the editor belongs to.

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 DataGrid 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 onEditorPreparing function will not be executed when a row or a cell switches into the editing state.

onExported

A handler for the exported event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

Default Value: null

Assign a function to perform a custom action after the exporting of the grid data is completed.

See Also
  • customizeExportData - customizes grid columns and data before exporting.
  • onExporting - allows you to request exporting details and prevent exporting.
  • onFileSaving - allows you to access exported data and/or prevent it from being saved into a file on the user's local storage.

onExporting

A handler for the exporting event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

fileName

String

The name of the file to which grid data is about to be exported.

cancel

Boolean

Indicates whether or not to cancel exporting.

Default Value: null

Assign a function to perform a custom action before exporting grid data.

See Also
  • export - configures client-side exporting.
  • customizeExportData - customizes grid columns and data before exporting.
  • onExported - allows you to notify an end user when exporting is completed.
  • onFileSaving - allows you to access exported data and/or prevent it from being saved into a file on the user's local storage.

onFileSaving

A handler for the fileSaving event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

fileName

String

The name of the file to be saved.

format

String

The format of the file to be saved. Equals 'EXCEL' for an Excel file.

data

BLOB

Exported data as a BLOB.

cancel

Boolean

To cancel file saving, assign true to this parameter.

Default Value: null

Assign a function to perform a custom action before an Excel file with exported data will be saved on the user's local storage.

See Also
  • onExporting - allows you to request exporting details and prevent exporting.
  • onExported - allows you to notify an end user when exporting is completed.

onInitialized

A handler for the initialized event. Executed only once, after the widget is initialized.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

Default Value: null

You cannot access elements in the widget because this handler is executed before they are ready. Use the onContentReady handler instead.

onInitNewRow

A handler for the initNewRow event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

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

onKeyDown

A handler for the keyDown event.

Type:

Function

Function parameters:
e:

Object

Provides function parameters.

Object structure:
Name Type Description
component

Object

Provides access to the widget instance.

element

jQuery

An HTML element of the widget.

jQueryEvent

jQuery.Event

Specifies the jQuery event that caused the action execution.

handled

Boolean

Indicates if the grid has already handled the key down event.

Default Value: null

Assign a function to perform a custom action when a key is pressed down when the widget is focused.

onOptionChanged

A handler for the optionChanged event.

Type:

Function

Function parameters:
e:

Object

Provides function parameters.

Object structure:
Name Type Description
component

Object

Provides access to the widget instance.

name

String

Specifies the name of the option whose value is changed.

fullName

String

Specifies a full name of the option whose value is changed. The full name is formed by concatenating the names of the options that are presented in the hierarchy of the given option. The names are delimited by commas.

value any

Specifies a new value for the option.

element

jQuery

An HTML element of the widget.

model

Object

Provides access to the data that is available for binding against the element. Available only in the Knockout approach.

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

|

String

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

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 visible 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
If there are any internal grid handlers for the row click, the rowClick event fires only after these handlers are executed. In this case, the handled field of the handler function parameter is set to true.

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

NOTE
When the clicked row is in the editing state, or switches to the editing state, the rowClick event will not fire. Instead, you can use the cellClick.

onRowCollapsed

A handler for the rowCollapsed event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

key any

The key of the group or master row.

Default Value: null

Assign a function to perform a custom action after a master or group row is collapsed in the grid.

onRowCollapsing

A handler for the rowCollapsing event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

key any

The key of the group or master row.

cancel

Boolean

Indicates whether to cancel collapsing the row.

Default Value: null

Assign a function to perform a custom action before a master or group row is collapsed in the grid. For instance, you can prevent collapsing by setting the cancel field of the object passed as the handler's parameter to true.

onRowExpanded

A handler for the rowExpanded event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

key any

The key of the group or master row.

Default Value: null

Assign a function to perform a custom action after a master or group row is expanded in the grid.

onRowExpanding

A handler for the rowExpanding event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

key any

The key of the group or master row.

cancel

Boolean

Indicates whether to cancel expanding the row.

Default Value: null

Assign a function to perform a custom action before a master or group row is expanded in the grid. For instance, you can prevent expanding by setting the cancel field of the object passed as the handler's parameter to true.

onRowInserted

A handler for the rowInserted event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

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.

error JavaScript Error object

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

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

data

Object

The object of the data source represented by the inserted row.

cancel

Boolean

|

jQuery.Promise

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. If you need to perform an asynchronous action before saving the newly added row, assign a jQuery.Promise object to the cancel field. The row will be inserted when the jQuery.Promise object is resolved.

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

View Demo

onRowPrepared

A handler for the rowPrepared event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

data

Object

The object of a data source represented by the prepared row. This field is unavailable if the rowType field is set to "header", "filter" or "totalFooter".

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. This field is unavailable if the rowType field is set to "header", "filter" or "totalFooter".

values any

Values of the current 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 visible 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.

rowType

String

The type of the prepared row. This field can be set to one of the following values: "data", "detail", "group", "groupFooter", "header", "filter" or "totalFooter". Use this field to distinguish rows by type.

groupIndex

Number

The group index of the current row. This field is useful if the rowType field is 'group'.

isSelected

Boolean

Indicates whether the prepared row is selected. This field is useful if the rowType field is set to "data"

isExpanded

Boolean

Indicates whether the prepared row is expanded. This field is unavailable if the rowType field is set to "header", "filter" or "totalFooter".

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.

onRowRemoved

A handler for the rowRemoved event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

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.

error JavaScript Error object

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

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

data

Object

Row's data.

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

|

jQuery.Promise

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. If you need to perform an asynchronous action before deleting the row, assign a jQuery.Promise object to the cancel field. The row will be actually deleted when the jQuery.Promise object is resolved.

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

onRowUpdated

A handler for the rowUpdated event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

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.

error JavaScript Error object

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

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

oldData

Object

Row's old data.

newData

Object

Row's updated data.

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

|

jQuery.Promise

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. If you need to perform an asynchronous action before saving the updated row, assign a jQuery.Promise object to the cancel field. The row will be actually updated when the jQuery.Promise object is resolved.

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

View Demo

onRowValidating

A handler for the rowValidating event.

Type:

Function

Function parameters:
e:

Object

Provides function parameters.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

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

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

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.
Does not include calculated values.

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 to the function as the argument. Arrays of all selected records and their data are also accessible through the same object.

NOTE
The following fields of the object passed to the function are available only if the selection is instant: currentSelectedRowKeys, currentDeselectedRowKeys, selectedRowKeys, selectedRowsData.

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

onToolbarPreparing

A handler for the toolbarPreparing event.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

Object

The widget instance.

element

jQuery

The widget's container.

model

Object

Data that is available for binding against the element. Available only in the Knockout approach.

toolbarOptions

Object

An object containing options of the toolbar.

Default Value: null

The toolbarPreparing event fires before the toolbar is created. This allows you to customize its options. For this purpose, use the object passed to the handling function as a parameter. Among the fields of this object, you can find data related to the toolbar options.

By default, the widget has the following toolbar items.

  • DataGrid Toolbar Column Chooser Button - columnChooserButton
  • DataGrid Toolbar Add Button - addRowButton
  • DataGrid Toolbar Save Button - saveButton
  • DataGrid Toolbar Revert Button - revertButton
  • DevExtreme DataGrid HTML5 Toolbar Exporting - exportButton
  • DataGrid Toolbar Apply Filter Button - applyFilterButton
  • groupPanel
  • searchPanel

Items availability depends on the DataGrid configuration.

JavaScript
$(function() {
    $("#gridContainer").dxDataGrid({
        // . . .
        onToolbarPreparing: function (e) {
            var toolbarItems = e.toolbarOptions.items;
            // Modifies an existing item
            $.each(toolbarItems, function(_, item) {
                if(item.name === "saveButton") {
                    // Change the item options here
                }
            }); 

            // Adds a new item
            toolbarItems.push({
                widget: 'dxButton', 
                options: { icon: 'user', onClick: function(){ ... } },
                location: 'after' });
        }
    });
});

View Demo Watch Video

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 Watch Video

paging

Specifies paging options.

Type:

Object

In DataGrid, 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

remoteOperations

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

Type:

String

|

Boolean

|

Object

Default Value: 'auto'

Data for the DataGrid can be stored on the client or come from the server. As a rule, manipulating data on the server enhances DataGrid performance. However, the server might be falling short of implementing certain operations, in which case, they can be performed on the client.

Data operations can be categorized into basic operations (filtering, sorting, paging) and advanced operations (grouping, group paging, summary calculation). The following table shows where data operations are performed by default.

Basic operations Advanced operations
CustomStore client client
ODataStore server client (always)
NOTE
You cannot perform data operations on the server with an ArrayStore, a LocalStore or an array of objects.

To control individual operations, assign a Boolean value to a corresponding field of the remoteOperations object. To control all operations simultaneously, assign a Boolean value directly to the remoteOperations option.

NOTE
If you assign true to remoteOperations, the group paging feature is still performed on the client. To delegate it to the server, assign true to the remoteOperations | groupPaging, but note that with this setting, all other operations are delegated to the server also.
NOTE
If actual data is stored on the server, making data operations local does not guarantee that there won't be any queries for data to the server while these operations are being performed. It only guarantees that calculations will be performed on the client.

Note that when operations are performed remotely, the DataGrid does not support:

View Demo

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

rowTemplate

Specifies a custom template for grid rows.

Type:

template

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 is invoked every time DataGrid 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, and you can access row options using the fields of the function's second parameter that are listed below.

  • data
    Contains the object of the data source represented by the current row.
  • component
    Contains the DataGrid instance.
  • values
    Contains an array of values of the current row in the order 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 count as rows and have row indexes. For further information about row indexes, see the Grid Rows topic.
  • columns
    Contains an array of grid columns. An object with column settings represents each column in this array. The order of columns in this array coincides with the columns array.
  • isSelected
    Indicates whether or not the current row is selected.
  • rowType
    Defines 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'.

When utilizing the Knockout or AngularJS library in your application, you can specify the row template using the dxTemplate markup component. Note that dxTemplate should be bound to a <table> HTML element.

  • Knockout

    HTML
    <div data-bind="dxDataGrid: {
        <!-- other grid settings go here -->
        rowTemplate: 'rowTemplateName'
    }">
        <table data-options="dxTemplate: { name: 'rowTemplateName' }" >
            <tr>
                <td data-bind="text: data.id"></td>
                <td data-bind="text: data.name"></td>
            </tr>
        </table>
    </div>
  • AngularJS

    HTML
    <div dx-data-grid="{
        <!-- other grid settings go here -->
        rowTemplate: 'rowTemplateName'
    }" dx-item-alias="item">
        <table data-options="dxTemplate: { name: 'rowTemplateName' }" >
            <tr>
                <td>{{ item.data.id }}</td>
                <td>{{ item.data.name }}</td>
            </tr>
        </table>
    </div>

It is also possible to define a row template in markup. For this purpose, use one of the following template engines. The cell settings mentioned above 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.

When you implement a row template with a template engine, take into account certain specifics. Particularly, the <tr> element that represents a row should have the dx-row class for correct operation of all widget features.

View Demo

NOTE
When you use a row template, we recommend you disable the column reordering, grouping, and column fixing features. The template's content cannot automatically synchronize with the column layout, which makes these features inoperative.

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

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.

scrolling

A configuration object specifying scrolling options.

Type:

Object

The DataGrid 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

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 DataGrid widget. To make it visible, set the visible property of the searchPanel configuration object to true.

See Also

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

View Demo

selectedRowKeys

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

Type:

Array

NOTE
This option applies only if selection is instant.

Apart from runtime selection, the DataGrid 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 key option of the underlying Store of the dataSource. If no key was specified, the whole data object is considered the key, however, we recommend specifying the key to prevent selection from being duplicated.

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

selection

Specifies options of runtime selection.

Type:

Object

DataGrid 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

View Demo

selectionFilter

Specifies filters for the records that must appear initially selected.

Default Value: []
NOTE
This option applies only if selection is deferred.

This option also allows you to obtain filter expressions for the currently selected rows. Note that if all records are selected, the selectionFilter value is null. If there are no selected records, the value contains an empty array.

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

showBorders

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

Type:

Boolean

Default Value: false

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.

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 a native look for the widget. In case you still require the column lines to be displayed, choose another theme.

View Demo

showRowLines

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

Type:

Boolean

Default Value: false
Default for ios: true

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 DataGrid, 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

View Demo

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.

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

DataGrid 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 DataGrid: 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

twoWayBindingEnabled

Specifies whether to enable two-way data binding.

Type:

Boolean

Default Value: true

Two-way data binding ensures that the UI tracks changes made in the data source by a 3rd-party instrument, and vice versa, the data source gets updated according to changes in the UI. Thus, the widget and its data source can continue to correspond to each other.

NOTE
DataGrid provides this feature through Knockout and AngularJS resources, so make sure that you have added these libraries to your app.

In certain scenarios, you may want to implement two-way data binding in DataGrid on your own. For this purpose, you can specify cellTemplate and/or editCellTemplate options. If so, make sure that you have the twoWayBindingEnabled option set to false.

visible

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

Type:

Boolean

Default Value: true

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 + "%";
    }

wordWrapEnabled

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

Type:

Boolean

Default Value: false