Methods

This section describes the methods that can be used to manipulate the DataGrid widget.

addColumn(columnOptions)

Adds a new column to the widget.

Parameters:
columnOptions:

Object

|

String

The options that configure the column or name of the data field for which a column should be created.

See Also
Show Example:
jQuery

In this example, you can add columns to a grid at runtime using the controls below the grid. Choose a data field for a new column from the select box. Then, click the 'Add Column' button to generate a column on the base of the chosen data field.


                                    

                                    

addRow()

Adds an empty data row.

See Also
Show Example:
jQuery

In this example, you can add a row to the grid using the "Add a New Row" button. This button calls the grid's addRow() method. Additionally, you can save or cancel the added row using the "Save the Row" or "Cancel" button. These buttons call the saveEditData() or cancelEditData() method respectively.


                                    

                                    

beginCustomLoading(messageText)

Displays the load panel.

Parameters:
messageText:

String

Text to be displayed in the load panel.

Normally, the load panel is invoked automatically while the widget is busy rendering or loading data. Additionally, you can invoke it by calling this method. If you call it without the argument, the load panel displays text specified by the loadPanel.text option. To specify the appearance of the load panel, use the loadPanel object. Once invoked from code, the load panel will not hide until you call the endCustomLoading() method.

NOTE
The load panel invoked from code does not replace the automatically invoked load panel. This circumstance might lead to a situation where the load panel invoked from code suddenly changes its text because it was overridden by the automatically invoked load panel. Therefore, be mindful when invoking the load panel with different text.
See Also
Show Example:
jQuery

In this example, you can invoke and hide the load panel using the buttons below the grid.


                                    

                                    

beginUpdate()

Prevents the widget from refreshing until the endUpdate() method is called.

The beginUpdate() and endUpdate() methods prevent the widget from excessive updates when you are changing multiple widget settings at once. After the beginUpdate() method is called, the widget does not update its UI until the endUpdate() method is called.

See Also

byKey(key)

Allows you to obtain a data object by its key.

Parameters:
key:

Object

|

String

|

Number

The key value of the required data object.

Return Value:

Promise<Object> (jQuery or native)

A Promise that is resolved after the data object is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

The following code shows how to get a data object whose key is 15.

JavaScript
widgetInstance.byKey(15).done(function(dataObject) {
        // process "dataObject"
    }).fail(function(error) {
        // handle error
    });
See Also

cancelEditData()

Discards changes that a user made to data.

Show Example:
jQuery

In this example, you can add a row to the grid using the "Add a New Row" button. This button calls the grid's insertRow() method. Additionally, you can save or cancel the added row using the "Save the Row" or "Cancel" button. These buttons call the saveEditData() or cancelEditData() method respectively.


                                    

                                    

cellValue(rowIndex, dataField)

Gets the value of a cell found by the row index and data field.

Parameters:
rowIndex:

Number

The index of the row to which the cell belongs.

dataField:

String

The name of the data field in the data source.

Return Value: any

The value of the cell.

See Also

cellValue(rowIndex, dataField, value)

Assigns a new value to a cell found by the row index and data field.

Parameters:
rowIndex:

Number

The index of the row to which the cell belongs.

dataField:

String

The name of the data field in the data source.

value: any

A new value for the cell.

See Also

cellValue(rowIndex, visibleColumnIndex)

Gets the value of a cell found by the row index and column index.

Parameters:
rowIndex:

Number

The index of the row to which the cell belongs.

visibleColumnIndex:

Number

The visible index of the column to which the cell belongs.

Return Value: any

The value of the cell.

See Also

cellValue(rowIndex, visibleColumnIndex, value)

Assigns a new value to a cell found by the row index and column index.

Parameters:
rowIndex:

Number

The index of the row to which the cell belongs.

visibleColumnIndex:

Number

The visible index of the column to which the cell belongs.

value: any

A new value for the cell.

NOTE
In all editing modes different from "cell", save changes by calling the saveEditData() method afterwards.
See Also

clearFilter()

Clears all filters applied to widget rows.

See Also

clearFilter(filterName)

Clears all row filters of a specific type.

Parameters:
filterName:

String

The type of the filter to be cleared.

The method's parameter specifies what type of filter should be cleared. The parameter can have one of the following values:

See Also
Show Example:
jQuery

This example shows how to apply a filter to a column and then clear it using the API of DataGrid. Perform the following actions using the set of controls under the grid. Select a column, to which the filter must be applied. Then, select a filter and type the text by which grid rows must be filtered. To apply the filter, click the "Apply Filter" button. To clear the applied filter, click the "Clear Filter" button.


                                    

                                    

clearGrouping()

Ungroups grid records.

For more information about grouping, see the Grouping topic.

See Also
Show Example:
jQuery

In this example, grid records are grouped by the "Format" column initially. You can also group records by the other columns. To ungroup records, click the "Clear Grouping" button located below the grid. A click on this button calls the grid's clearGrouping() method.


                                    

                                    

clearSelection()

Clears selection of all rows on all pages.

Show Example:
jQuery

In this example, you can select grid records in a multiple selection mode. To clear selection, use the "Clear Selection" button located below the grid.


                                    

                                    

clearSorting()

Clears sorting settings of all columns at once.

See Also
Show Example:
jQuery

In this example, grid records are sorted by the "Year" column initially. You can also apply sorting to the other columns. To clear sorting settings, click the "Clear Sorting" button located below the grid. A click on this button calls the grid's clearSorting() method.


                                    

                                    

closeEditCell()

Switches the cell being edited back to the normal state. Takes effect only if editing.mode is batch.

See Also
Show Example:
jQuery

This example shows how to use the DataGrid editCell(rowIndex, columnIndex) and closeEditCell() methods. Use the number boxes located under the grid to choose row and column indexes specifying the cell that must be switched into the editing state. After that, click the "Edit Cell" button, which calls the editCell(rowIndex, columnIndex) method. The specified cell will enter the editing state. To draw this cell back to the normal state, click the "Close Cell" button, which calls the closeEditCell() method.


                                    

                                    

collapseAdaptiveDetailRow()

Collapses the currently expanded adaptive detail row (if there is one).

collapseAll(groupIndex)

Collapses groups or master rows in a grid.

Parameters:
groupIndex:

Number

| undefined

The index of the groups to collapse. Pass undefined to collapse all groups. Pass -1 to collapse all master rows.

Show Example:
jQuery

In this example, grid records are grouped by the "Format" column initially. In addition, group panel is made visible enabling you to change grouping. Moreover, you can expand or collapse groups by clicking the "Expand Groups" or "Collapse Groups" button located below the grid.


                                    

                                    

collapseRow(key)

Allows you to collapse a specific group or master row by its key.

Parameters:
key: any

The key of the group or master row.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after the row is collapsed. It is a native Promise or a jQuery.Promise when you use jQuery.

To collapse a group row, call this method with an array each member of which is a grouping value. To collapse a master row, pass its key to this method.

See Also

columnCount()

Returns the number of data columns in the widget including visible and hidden columns, but without command columns.

Return Value:

Number

The number of data columns in the widget.

See Also

columnOption(id)

Gets the options of a column using its identifier.

Parameters:
id:

Number

|

String

The name, index, data field, or caption of the column.

Return Value:

Object

The options of the column.

This method gets the options of the first column found by either of the below:

  • Name
    The unique name of the column.

  • Column Index
    The index of the column in the columns array.

  • Data Field
    The name of the data source field assigned to the column.

  • Caption
    The text displayed in the column header.

  • Service String
    One of the following values:

    • "command:edit"
      Gets the editing column.

    • "command:select"
      Gets the selection column.

    • "command:adaptive"
      Gets the adaptive column.

    • Any string matching the following format: "optionName:value"
      Here, the optionName is one of the column options.

See Also

columnOption(id, optionName)

Gets the value of a specific option set for a specific column.

Parameters:
id:

Number

|

String

The name, index, data field or caption of the column.

optionName:

String

The name of the required option.

Return Value: any

The value of this option.

This method gets the value of an option of the first column found by either of the below:

  • Name
    The unique name of the column.

  • Column Index
    The index of the column in the columns array.

  • Data Field
    The name of the data source field assigned to the column.

  • Caption
    The text displayed in the column header.

  • Service String
    One of the following values:

    • "command:edit"
      Gets the editing column.

    • "command:select"
      Gets the selection column.

    • "command:adaptive"
      Gets the adaptive column.

    • Any string matching the following format: "optionName:value"
      Here, the optionName is one of the column options.

See Also

columnOption(id, optionName, optionValue)

Assigns a new value to a single option of a specific column.

Parameters:
id:

Number

|

String

The name, index, data field, or caption of the column.

optionName:

String

The name of the option to change.

optionValue: any

A new value for this option.

This method sets an option of the first column found by either of the below:

  • Name
    The unique name of the column.

  • Column Index
    The index of the column in the columns array.

  • Data Field
    The name of the data source field assigned to the column.

  • Caption
    The text displayed in the column header.

  • Service String
    One of the following values:

    • "command:edit"
      Gets the editing column.

    • "command:select"
      Gets the selection column.

    • "command:adaptive"
      Gets the adaptive column.

    • Any string matching the following format: "optionName:value"
      Here, optionName is one of the column options.

    NOTE
    In command columns, you can change only the width and the visibleIndex.
See Also
Show Example:
jQuery

In this example, a click on a column applies the "clicked" style to this column. This operation is performed in code by changing the cssClass option of the clicked column using the columnOption(id, optionName, optionValue) method.


                                    

                                    

                                    

columnOption(id, options)

Assigns new values to several options of a specific column at once.

Parameters:
id:

Number

|

String

The name, index, data field, or caption of the column.

options:

Object

The options with their new values.

This method changes options of the first column found by either of the below:

  • Name
    The unique name of the column.

  • Column Index
    The index of the column in the columns array.

  • Data Field
    The name of the data source field assigned to the column.

  • Caption
    The text displayed in the column header.

  • Service String
    One of the following values:

    • "command:edit"
      Gets the editing column.

    • "command:select"
      Gets the selection column.

    • "command:adaptive"
      Gets the adaptive column.

    • Any string matching the following format: "optionName:value"
      Here, optionName is one of the column options.

    NOTE
    In command columns, you can change only the width and the visibleIndex.
See Also

defaultOptions(rule)

Specifies the device-dependent default configuration options for this component.

Parameters:
rule:

Object

An object specifying default options for the component and the device for which the options must be applied.

Object structure:
device:

Object

|

Array<Object>

|

function

An object representing device parameters, or an array of objects representing device parameters, or a function that provides information on the current device as an input parameter and returning a Boolean value.

options:

Object

A configuration object with specified options.

The defaultOptions method is a static method supported by the widget class. The following code demonstrates how to specify default options for all buttons in the application executed on the iOS platform.

JavaScript
DevExpress.ui.dxButton.defaultOptions({ 
    device: { platform: "ios" },
    options: {
        text: "Click me"
    }
});

deleteColumn(id)

Removes a specific column from the widget.

Parameters:
id:

Number

|

String

The name, index, data field, or caption of the column.

This method removes the first column found by either of the below:

  • Name
    The unique name of the column.

  • Column Index
    The index of the column in the columns array.

  • Data Field
    The name of the data source field assigned to the column.

  • Caption
    The text displayed in the column header.

See Also

deleteRow(rowIndex)

Removes a specific row from the widget.

Parameters:
rowIndex:

Number

The index of the row to be removed.

Show Example:
jQuery

In this example, grid rows can be deleted using the set of controls below the grid. To delete a row, select its index in the number box and then click the "Delete Row" button. This button calls the deleteRow(rowIndex) method.


                                    

                                    

deselectAll()

Clears the selection of all rows on all pages or the currently rendered page only.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after the selection is cleared. It is a native Promise or a jQuery.Promise when you use jQuery.

Depending on the value of the selectAllMode option, this method clears selection of all rows on all pages or on the currently rendered pages only. The selection is cleared of only those rows that meet filtering conditions if a filter is applied. To clear selection regardless of the selectAllMode option's value or applied filters, call the clearSelection() method.

See Also

deselectRows(keys)

Clears selection of specific rows.

Parameters:
keys:

Array<any>

The keys of rows whose selection should be cleared.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after selection is cleared. It is a native Promise or a jQuery.Promise when you use jQuery.

To access a row by its key, you should specify the field that provides keys in the data source. If no key was specified, the whole data object is considered the key.

See Also

dispose()

Removes the widget from the DOM.

editCell(rowIndex, dataField)

Switches a specific cell into the editing state. The cell is found by the row index and data field. Takes effect only if the editing mode is 'batch' or 'cell'.

Parameters:
rowIndex:

Number

The index of the row that owns the cell.

dataField:

String

The name of the data field in the data source.

See Also

editCell(rowIndex, visibleColumnIndex)

Switches a specific cell into the editing state. The cell is found by the row index and column index. Takes effect only if the editing mode is 'batch' or 'cell'.

Parameters:
rowIndex:

Number

The index of the row that owns the cell.

visibleColumnIndex:

Number

The visible index of the column that owns the cell.

See Also
Show Example:
jQuery

This example shows how to use the DataGrid editCell(rowIndex, visibleColumnIndex) and closeEditCell() methods. Use the number boxes located under the grid to choose row and column indexes specifying the cell that must be switched into the editing state. After that, click the "Edit Cell" button, which calls the editCell(rowIndex, visibleColumnIndex) method. The specified cell will enter the editing state. To draw this cell back to the normal state, click the "Close Cell" button, which calls the closeEditCell() method.


                                    

                                    

editRow(rowIndex)

Switches a specific row into the editing state. Takes effect only if the editing mode is 'row', 'popup' or 'form'.

Parameters:
rowIndex:

Number

The index of the row.

See Also
Show Example:
jQuery

This example illustrates the capability to direct the editing process in the DataGrid widget from code. First, select the index of the row that must be switched into the editing state. Then, click the "Edit the Row" button located under the grid. A click on this button calls the editRow(rowIndex) method with the selected index passed as the argument. After the record is edited, save or discard changes by clicking the "Save the Row" or "Cancel" button.


                                    

                                    

element()

Gets the root element of the widget.

Return Value:

Element (jQuery or HTML)

The widget's root element. An HTML element or a jQuery element when you use jQuery.

See Also

endCustomLoading()

Hides the load panel.

Normally, the widget hides the load panel automatically once data is ready. But if you have invoked the load panel from code using the beginCustomLoading(messageText) method, you must call the endCustomLoading() method to hide it.

See Also
Show Example:
jQuery

In this example, you can invoke and hide the load panel using the buttons below the grid.


                                    

                                    

endUpdate()

Refreshes the widget after a call of the beginUpdate() method.

Main article: beginUpdate()

See Also

expandAdaptiveDetailRow(key)

Expands an adaptive detail row found by the key of its parent data row.

Parameters:
key: any

The key of the data row.

To access a data row by its key, you should specify the field that provides keys in the data source. If no key was specified, the whole data object is considered the key.

See Also

expandAll(groupIndex)

Expands groups or master rows in a grid.

Parameters:
groupIndex:

Number

| undefined

The index of the groups to expand. Pass undefined to expand all groups. Pass -1 to expand all master rows.

NOTE
This method cannot be called when using a remote data source.
See Also
Show Example:
jQuery

In this example, grid records are grouped by the "Format" column initially. In addition, the group panel is made visible enabling you to change grouping. Moreover, you can expand or collapse groups by clicking the "Expand Groups" or "Collapse Groups" button located below the grid.


                                    

                                    

expandRow(key)

Allows you to expand a specific group or master row by its key.

Parameters:
key: any

The key of the group or master row.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after the row is expanded. It is a native Promise or a jQuery.Promise when you use jQuery.

To expand a group row, call this method with an array (each member of which is a grouping value). To expand a master row, pass its key to this method.

See Also

exportToExcel(selectionOnly)

Exports grid data to Excel.

Parameters:
selectionOnly:

Boolean

Specifies whether to export all the data presented in the grid or the selected rows only.

For details on exporting, refer to the Client-Side Exporting article.

See Also

filter()

Returns a filter expression applied to the widget's data source using the filter(filterExpr) method.

Return Value: any

filter(filterExpr)

Applies a filter to the widget's data source.

Parameters:
filterExpr: any

Pass an array with the following members to this method.

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

This method applies a filter before the filter row, search panel, or header filter does. To clear all filters applied both from code and the UI, call the clearFilter() method.

See Also
Show Example:
jQuery

This example shows how to apply a filter to a column and then clear it using the API of DataGrid. Perform the following actions using the set of controls under the grid. Select a column, to which a filter must be applied. Then, select a filter to apply to that column. After that, type the text by which grid records must be filtered. To apply the specified filter, click the "Apply Filter" button. To clear the applied filter, click the "Clear Filter" button.


                                    

                                    

focus()

Sets focus on the widget.

See Also

focus(element)

Sets focus on a specific cell.

Parameters:
element:

DOM Node

|

jQuery

The element of the cell.

getCellElement(rowIndex, dataField)

Gets a cell by the row index and data field.

Parameters:
rowIndex:

Number

The index of the row that owns the cell.

dataField:

String

The name of the data field in the data source.

Return Value:

Element (jQuery or HTML)

| undefined

The cell's container. An HTML element or a jQuery element when you use jQuery. If the specified row or data field does not exist, the method returns undefined.

See Also

getCellElement(rowIndex, visibleColumnIndex)

Gets a cell by the row index and column index.

Parameters:
rowIndex:

Number

The index of the row that owns the cell.

visibleColumnIndex:

Number

The visible index of the column that owns the cell.

Return Value:

Element (jQuery or HTML)

| undefined

The cell's container. An HTML element or a jQuery element when you use jQuery. If the specified row or column does not exist, the method returns undefined.

See Also

getCombinedFilter()

Returns the total filter that combines all the filters applied.

Return Value: any

Use this method to get the total filter, which combines filters applied using the filter(filterExpr) method, filter row, header filter and the search panel. Note that the total filter contains getters. To get the total filter with data fields, call the getCombinedFilter(returnDataField) method.

See Also

getCombinedFilter(returnDataField)

Returns the total filter that combines all the filters applied.

Parameters:
returnDataField:

Boolean

Specifies whether the total filter should contain data fields instead of getters.

Return Value: any

Use this method to get the total filter, which combines filters applied using the filter(filterExpr) method, filter row, header filter and the search panel.

See Also

getDataSource()

Gets the DataSource instance.

Return Value:

DataSource

See Also

getInstance(element)

Gets the widget's instance using a DOM element.

Parameters:
element:

DOM Node

|

jQuery

An element containing the widget.

Return Value:

Object

The widget's instance.

getKeyByRowIndex(rowIndex)

Gets the key of a row by its index.

Parameters:
rowIndex:

Number

The visible index of the row.

Return Value: any

The key of the row. If nothing is found, returns undefined.

getRowElement(rowIndex)

Gets the element of a row by its index.

Parameters:
rowIndex:

Number

The visible index of the row.

Return Value:

Array<DOM Node>

|

jQuery

| undefined

The element of the row; provides access to element-related jQuery operations.

Note that if the widget has fixed columns, the method returns an array of two separate elements: with unfixed and with fixed columns.

See Also

getRowIndexByKey(key)

Gets the index of a row by its key.

Parameters:
key:

Object

|

String

|

Number

The key of the row.

Return Value:

Number

The visible index of the row. If nothing is found, returns -1.

getScrollable()

Gets the instance of the scrollable part of the widget.

Return Value:

Scrollable

The instance of the scrollable part of the widget.

For information on API members of the scrollable part, refer to the ScrollView section, but bear in mind that several members described there are unavailable. Those are the following.

Options:

  • pullingDownText
  • pulledDownText
  • refreshingText
  • reachBottomText
  • onPullDown
  • onReachBottom

Methods:

  • release(preventScrollBottom)
  • refresh()
See Also

getSelectedRowKeys()

Gets the currently selected rows' keys.

Return Value:

Array<any>

|

Promise<any> (jQuery or native)

The currently selected rows' keys or a Promise that is resolved with an array of keys.

The whole data object is considered a key if the field providing keys is not specified in the data source. In this case, this method returns data objects, that is, operates like the getSelectedRowsData() method.

Note that when selection is deferred, the method returns a Promise (a native Promise or a jQuery.Promise when you use jQuery) that should be resolved with an array of keys.

See Also
Show Example:
jQuery

In this example, the button located under the grid calls the getSelectedRowKeys() method of the grid. In the area between the grid and the button, you can see the contents of the array returned by this method.


                                    

                                    

getSelectedRowsData()

Gets data objects of currently selected rows.

Return Value:

Array<any>

|

Promise<any> (jQuery or native)

Data objects of currently selected rows or a Promise that is resolved with an array of these objects.

When selection is deferred, the method returns a Promise (a native Promise or a jQuery.Promise when you use jQuery) that should be resolved with an array of objects.

NOTE
Calculated values cannot be obtained because this method gets data objects directly from the data source.
See Also
Show Example:
jQuery

This example shows the use of the grid's getSelectedRowsData() method. Select several records in the grid and then click the "Update List" button located below the grid. This button calls the aforementioned method and updates the dxList widget located on the right. As a result, the selected records appear in this widget.


                                    

                                    

getTotalSummaryValue(summaryItemName)

Gets the value of a total summary item.

Parameters:
summaryItemName:

String

The name of the total summary item.

Return Value: any

The automatically calculated value of the total summary item.

See Also

getVisibleColumns()

Gets all visible columns.

Return Value:

Array<DataGrid column>

Visible columns; may include command columns.

getVisibleColumns(headerLevel)

Gets all visible columns at a specific hierarchical level of column headers. Use it to access banded columns.

Parameters:
headerLevel:

Number

The level of column headers.

Return Value:

Array<DataGrid column>

Visible columns; may include command columns.

getVisibleRows()

Gets currently rendered rows.

Return Value:

Array<DataGrid Row>

Currently rendered rows.

See Also

hasEditData()

Checks whether the widget has unsaved changes.

Return Value:

Boolean

true if the widget has unsaved changes; otherwise - false.

hideColumnChooser()

Hides the column chooser.

Show Example:
jQuery

In this example, you can show/hide the column chooser using the buttons under the grid. These buttons call the showColumnChooser() and hideColumnChooser() methods.


                                    

                                    

insertRow()

Deprecated

Use the addRow() method instead.

Adds a new data row to a grid.

See Also

instance()

Returns this widget's instance. Use it to access other methods of the widget.

Return Value:

Object

This widget's instance.

See Also
Show Example:
jQuery

In this example, the instance method is used to obtain the instance of the DataGrid widget. Next, the clearSelection() method is called of this instance.


                                    

                                    

isAdaptiveDetailRowExpanded(key)

Checks whether a specific adaptive detail row is expanded or collapsed.

Parameters:
key: any

The key of a data row.

To access a data row by its key, specify the field that provides keys in the data source. If no key was specified, the whole data object is considered the key.

See Also

isRowExpanded(key)

Checks whether a specific group or master row is expanded or collapsed.

Parameters:
key: any

The key of the group or master row.

Return Value:

Boolean

true if the row is expanded; false if collapsed.

To check whether a group row is expanded, call this method with an array, in which each member is a grouping value. To check if a master row is expanded, pass its key to this method.

See Also

isRowSelected(data)

Checks whether the row that represents a specific data object is selected. Takes effect only if selection.deferred is true.

Parameters:
data: any

The row's data object.

Return Value:

Boolean

true if the row is selected; false otherwise.

See Also

isRowSelected(key)

Checks whether the row with a specific key is selected. Takes effect only if selection.deferred is false.

Parameters:
key: any

The key of the row.

Return Value:

Boolean

true if the row is selected; false otherwise.

See Also

keyOf(obj)

Gets a data object's key.

Parameters:
obj:

Object

A data object.

Return Value: any

The data object's key.

If a field providing key values is not specified in the data source, the whole data object is considered the key. In this case, this method returns its argument.

See Also

off(eventName)

Detaches all event handlers from the specified event.

Parameters:
eventName:

String

The name of the event to unsubscribe from.

Return Value:

Object

The object for which this method is called.

See Also

off(eventName, eventHandler)

Detaches a particular event handler from the specified event.

Parameters:
eventName:

String

The name of the event to unsubscribe from.

eventHandler:

function

The handler to be detached from the specified event.

Return Value:

Object

The object for which this method is called.

See Also

on(eventName, eventHandler)

Subscribes to a specified event.

Parameters:
eventName:

String

The name of the event to be subscribed.

eventHandler:

function

An event handler for the specified event.

Return Value:

Object

The object for which this method is called.

Use this method to subscribe to one of the events listed in the Events section.

See Also

on(events)

Subscribes to the specified events.

Parameters:
events:

Object

An object of the following structure: { "eventName1": handler1, "eventName2": handler2, ...}

Return Value:

Object

The object for which this method is called.

Use this method to subscribe to several events with one method call. Available events are listed in the Events section.

See Also

option()

Gets the widget's options.

Return Value:

Object

The widget's options.

See Also

option(optionName)

Gets a specific option value.

Parameters:
optionName:

String

The option name or the full path to the option.

Return Value: any

This option value.

See Also

option(optionName, optionValue)

Assigns a new value to a specific option.

Parameters:
optionName:

String

The option name or the full path to the option.

optionValue: any

A new value for this option.

See Also
Show Example:
jQuery

In this example, you can change the value of the pager.visible option at runtime using the check box under the grid. In code, this value is changed by calling the grid's option(optionName, optionValue) method.


                                    

                                    

option(options)

Sets one or more options.

Parameters:
options:

Object

The options along with their new values.

See Also

pageCount()

Returns how many pages the grid contains.

Return Value:

Number

The number of pages in the grid.

NOTE
If you use infinite scrolling, this method returns how many pages the grid has loaded up until now.
See Also

pageIndex()

Gets the index of the current page.

Return Value:

Number

The index of the current page.

When using the pager, this method returns a value that is one less than the number of the current page.

When using scrolling in a virtual or infinite mode, this method return the index of the page whose record is displayed first in the grid.

See Also
Show Example:
jQuery

This example illustrates how to obtain the current page index using the grid's pageIndex() method. You can call this method by clicking the "Get the Current Page Index" button located under the grid.


                                    

                                    

pageIndex(newIndex)

Switches a grid to a specified page.

Parameters:
newIndex:

Number

The index of the page to switch to.

This method allows you to switch between pages without using the pager or scrolling. Note that the page index, which is passed as the argument to the pageIndex(newIndex) method, is one number less than the page number.

See Also
Show Example:
jQuery

In this example, you can switch between pages at runtime using the number box below instead of a usual pager. Data for this example is obtained from www.odata.org.


                                    

                                    

pageSize()

Gets the current page size.

Return Value:

Number

The current page size.

To specify the page size when configuring the DataGrid widget, use the paging.pageSize property.

See Also

pageSize(value)

Sets the page size.

Parameters:
value:

Number

A new value of the page size.

To specify the page size when configuring the DataGrid widget, use the paging.pageSize property.

See Also
Show Example:
jQuery

In this example, you can change the size of a grid page at runtime using the number box below instead of a usual page size selector. Data for this example is obtained from www.odata.org.


                                    

                                    

refresh()

Reloads data in the widget.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after data is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

The widget cannot track changes made in the data source by a third party. To bring data in the widget up to date in this case, call this method. Data sources of lookup columns will be updated along with the main data source.

NOTE
Calling the refresh() method ends the editing process. In batch editing mode, changes are saved in a buffer waiting to be saved in the data source. In other modes, all unsaved changes vanish.
See Also
Show Example:
jQuery

This example illustrates the use of the grid's refresh() method. Here, you can change the array specified as a data source to the grid without using the grid's API. A click on the "Delete a Random Record" button deletes a record straight from this array. The grid, however, does not mirror these changes yet. To force it, click the "Refresh" button, which calls the grid's refresh() method.


                                    

                                    

registerKeyHandler(key, handler)

Registers a handler to be executed when a user presses a specific key.

Parameters:
key:

String

The key for which the handler should be registered.

handler:

function

A handler.

The key argument accepts one of the following values:

  • "backspace"
  • "tab"
  • "enter"
  • "escape"
  • "pageUp"
  • "pageDown"
  • "end"
  • "home"
  • "leftArrow"
  • "upArrow"
  • "rightArrow"
  • "downArrow"
  • "del"
  • "space"
  • "F"
  • "A"
  • "asterisk"
  • "minus"

A custom handler for a key cancels the default handler for this key.

See Also

removeRow(rowIndex)

Deprecated

Use the deleteRow(rowIndex) method instead.

Removes a specific row from a grid.

Parameters:
rowIndex:

Number

The index of the row to be removed.

See Also

repaint()

Repaints the widget. Call it if you made modifications that changed the widget's state to invalid.

See Also
Show Example:
jQuery

In this example, you can change the visibility of the column chooser using the check box below the grid. After the column chooser has been hidden, the area occupied by it becomes free. In order to adapt the layout of the grid to the container, the grid's repaint() method is called. The same operation is required after the column chooser has been made visible.


                                    

                                    

repaintRows(rowIndexes)

Repaints specific rows.

Parameters:
rowIndexes:

Array<Number>

Row indexes.

This method updates the row objects and their visual representation.

See Also

saveEditData()

Saves changes that a user made to data.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after changes are saved in the data source. It is a native Promise or a jQuery.Promise when you use jQuery.

Show Example:
jQuery

In this example, you can add a row to the grid using the "Add a New Row" button. This button calls the grid's insertRow() method. Additionally, you can save or cancel the added row using the "Save the Row" or "Cancel" button. These buttons call the saveEditData() or cancelEditData() method respectively.


                                    

                                    

searchByText(text)

Seeks a search string in the columns whose allowSearch option is true.

Parameters:
text:

String

A search string. Pass an empty string to clear search results.

Show Example:
jQuery

This example shows how to apply a filter to a column and then clear it using the API of DataGrid. Perform the following actions using the set of controls under the grid. Select a column, to which the filter must be applied. Then, select a filter to apply to that column. After that, type a text by which grid records must be filtered. To apply the specified filter, click the "Apply Filter" button. To clear the applied filter, click the "Clear Filter" button.


                                    

                                    

selectAll()

Selects all rows.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after all rows are selected. It is a native Promise or a jQuery.Promise when you use jQuery.

Depending on the value of the selectAllMode option, this method selects all rows on all pages or on the currently rendered pages only. If a filter is applied, this method selects only those rows that meet the filtering conditions.

See Also
Show Example:
jQuery

In this example, you can select grid records in a multiple selection mode. However, you cannot select all records at once using the check box in the header of the selection column, since the selection.allowSelectAll option is set to false. Instead, use the "Select All Records" button for the same purpose.


                                    

                                    

selectRows(keys, preserve)

Selects rows by keys.

Parameters:
keys:

Array<any>

The keys of the rows to be selected.

preserve:

Boolean

Specifies whether previously selected rows should stay selected.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after the rows are selected. It is a native Promise or a jQuery.Promise when you use jQuery.

By default, this method call clears selection of previously selected rows. To keep these rows selected, call this method with true as the second argument.

JavaScript
widgetInstance.selectRows([5, 10, 12], true);

To access a row by its key, specify the field that provides keys. For this, use the key option of the Store that underlies the dataSource. If no key was specified, the whole data object is considered the key. However, we recommend specifying the key option to prevent selection from being duplicated.

See Also
Show Example:
jQuery

In this example, you can select grid records using the tag box located under the grid. The selection is performed by calling the selectRows(keys, preserve) method.


                                    

                                    

selectRowsByIndexes(indexes)

Selects rows by indexes.

Parameters:
indexes:

Array<Number>

The indexes of the rows to be selected.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after the rows are selected. It is a native Promise or a jQuery.Promise when you use jQuery.

This method has the following specifics:

  • This method call clears selection of all previously selected rows.
  • When calculating row indexes, the widget counts data and group rows. Nevertheless, only data rows can be selected.
  • If the pager is used, selection is cleared once a user moves to a different page. To preserve it, call this method within the onContentReady handler.
See Also
Show Example:
jQuery

In this example, you can select grid records using the tag box located under the grid. The selection is performed by calling the selectRowsByIndexes(indexes) method. Note that group rows cannot be selected even though their indexes can be passed to this method.


                                    

                                    

showColumnChooser()

Shows the column chooser.

Show Example:
jQuery

In this example, you can show/hide the column chooser using the buttons under the grid. These buttons call the showColumnChooser() and hideColumnChooser() methods.


                                    

                                    

state()

Returns the current state of the grid.

Return Value:

Object

An opaque data object presenting the grid state.

See Also

state(state)

Sets the grid state.

Parameters:
state:

Object

An opaque data object presenting the grid state.

See Also

totalCount()

Returns the number of records currently held by a grid.

Return Value:

Number

The number of records currently held by a grid.

Use this method to get the number of records currently held by a grid. Note that if records are filtered by a user using the filter row and search panel or from code using the filter(filterExpr) and searchByText(text) methods, the totalCount() method returns the number of records left after filtering.

See Also
Show Example:
jQuery

In this example, you can call the totalCount() method by clicking the "Get Total Count" button located under the grid. Note that if grid records are filtered, this method returns a different value.


                                    

                                    

undeleteRow(rowIndex)

Recovers a row deleted in batch editing mode.

Parameters:
rowIndex:

Number

The index of the row to recover.

Show Example:
jQuery

In this example, grid rows can be deleted in the batch edit mode. To delete a row, select its index in the number box and then click the "Delete Row" button located under the grid. This button calls the removeRow(rowIndex) method. Deleted rows can be restored. For this purpose, select the index of the row, which must be restored, in the number box and click the "Undelete Row" button located under the grid. This button calls the undeleteRow(rowIndex) method. Additionally, you can save or discard the executed changes using the "Save Changes" or "Cancel Changes" button. These buttons call the saveEditData() or cancelEditData() method respectively.


                                    

                                    

updateDimensions()

Updates the widget's content after resizing.

See Also