Methods

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

addColumn(columnOptions)

Adds a new column to a grid.

Parameters:
columnOptions: Object|String
The options of the added column or the name of a data field.

To add a column to a grid, call the addColumn(columnOptions) method of the grid instance. Pass the options of the added column as the columnOptions argument. Refer to the columns option description for the full list of available options.

There may be cases, when no options, except the dataField, are required to be specified. In this instance, pass the name of the data field as the argument to the addColumn(columnOptions) method instead of the object with column options.

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.


                                    

                                    

beginCustomLoading(messageText)

Displays the load panel.

Parameters:
messageText: String
Text to be displayed in the load panel.

Normally, dxDataGrid displays a load panel automatically when it is busy rendering or loading data. Additionally, the load panel can be invoked when required by calling the beginCustomLoading(messageText) method. If you call this method without the argument, the load panel displays text specified by the loadPanel | text option. To specify the appearance of the load panel, use the properties of the loadPanel configuration object.

Once invoked from code, the load panel will not hide until the endCustomLoading() method is called.

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. Hence, be mindful when invoking the load panel with different text.

Show Example:
jQuery

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


                                    

                                    

beginUpdate()

Prevents the component from refreshing until the endUpdate method is called.

The beginUpdate and endUpdate methods allow you to apply several modifications to the component. After the beginUpdate method is called, the component does not update the UI until the endUpdate method is called. The usage of these methods prevents excessive component updating when you are changing multiple component settings at once.

byKey(key)

Allows you to obtain a data object by its key.

Parameters:
key: any
The key value of the required data object.
Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after the data object has been loaded.

The following code snippet demonstrates how to get a data object whose key equals 15.

JavaScript
dataGridInstance.byKey(15).done(function(dataObject) {
        // process 'dataObject'
    }).fail(function(error) {
        // handle error
    });

cancelEditData()

Discards changes made in a grid.

To learn how to manage the editing process from code, see the Editing in Code topic.

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.


                                    

                                    

clearFilter()

Clears the filter applied to grid records from code.

In dxDataGrid, grid records can be filtered from code using the filter(filterExpr) method or by a user using a filter row. To clear the filter applied from code, call the clearFilter() method. The user-applied filter cannot be cleared programmatically.

Show Example:
jQuery

This example shows how to apply a filter to a column and then clear it using the API of dxDataGrid. 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 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.


                                    

                                    

clearSelection()

Deselects all grid records.

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.


                                    

                                    

closeEditCell()

Draws the cell being edited from the editing state. Use this method when the edit mode is batch.

To learn how to manage the editing process from code, see the Editing in Code topic.

Show Example:
jQuery

This example shows how to use the dxDataGrid 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.


                                    

                                    

collapseAll(groupIndex)

Collapses groups in a grid.

Parameters:
groupIndex: Number| undefined
The index of the groups to collapse.

Learn more in the Expanding and Collapsing Groups topic.

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.


                                    

                                    

columnCount()

Returns the number of data columns in a grid.

Return Value: Number
The number of data columns in a grid.

The columnCount() method returns the number of columns currently presented in a grid. This number includes visible and hidden columns, but omits the selection and editing columns.

columnOption(id)

Returns the options of a column by an identifier.

Parameters:
The index or data field or caption of a column.
Return Value: Object
The options of the specified column.

Use this method to obtain an object of the options currently applied to a specific column. This method accepts one of the following.

  • Column Index
    Equals 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.

The options of the first column matching either the column index or data field or caption will be returned by this method.

For the list of options included in the object returned by the columnOption(id) method, refer to the columns option description. Additionally, you can get the value of a specific column option using the same method called with two arguments.

columnOption(id, optionName)

Returns the value of a specific column option.

Parameters:
The index or data field or caption of a column.
optionName: String
The name of the required option.
Return Value: any
The value of the specified option.

Use this method to obtain the value of a specific column option. This method accepts one of the following as the first argument.

  • Column Index
    Equals 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.

The specified option of the first column matching either the column index or data field or caption will be returned by this method.

For the list of accessible options, refer to the columns option description. Additionally, you can get all options of a specific column by calling the same method with an identifier only.

columnOption(id, optionName, optionValue)

Sets an option of a specific column.

Parameters:
The index or data field or caption of a column.
optionName: String
The name of the option to change.
optionValue: any
A new value for this option.

Using this method, you can set an option of a specific column from code. This method accepts one of the following as the first argument.

  • Column Index
    Equals 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.

The specified option of the first column matching either the column index or data field or caption will be changed by this method.

For the list of accessible options, refer to the columns option description. Also, you can set several column options at once. Use the columnOption(id, options) method to do this.

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)

Sets several options of a column at once.

Parameters:
The index or data field or caption of a column.
options: Object
The required configuration options.

Using this method, you can set several options of a specific column from code. This method accepts one of the following as the first parameter.

  • Column Index
    Equals 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.

The options of the first column matching either the column index or data field or caption will be changed by this method.

For the list of accessible options, refer to the columns option description. If you need to set only one option for a column, you can use the columnOption(id, optionName, optionValue) method instead.

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|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"
    }
});

editCell(rowIndex, columnIndex)

Sets a specific cell into the editing state.

Parameters:
rowIndex: Number
The index of a row holding the cell that should enter the editing state.
columnIndex: Number
The index of a column holding the cell that should enter the editing state.

To learn how to manage the editing process from code, see the Editing in Code topic.

Show Example:
jQuery

This example shows how to use the dxDataGrid 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.


                                    

                                    

editRow(rowIndex)

Sets a specific row into the editing state.

Parameters:
rowIndex: Number
The index of a row that should enter the editing state.

To learn how to manage the editing process from code, see the Editing in Code topic.

Show Example:
jQuery

This example illustrates the capability to direct the editing process in the dxDataGrid 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.


                                    

                                    

endCustomLoading()

Hides the load panel.

Normally, a load panel in dxDataGrid is hidden automatically when the widget 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.

Show Example:
jQuery

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


                                    

                                    

endUpdate()

Enables the component to refresh after the beginUpdate method call.

The beginUpdate and endUpdate methods allow you to apply several modifications to the component. After the beginUpdate method is called, the component does not update the UI until the endUpdate method is called. The usage of these methods prevents excessive component updating when you change multiple component setting at once.

expandAll(groupIndex)

Expands groups in a grid.

Parameters:
groupIndex: Number| undefined
The index of the groups to expand.

Learn more in the Expanding and Collapsing Groups topic.

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.


                                    

                                    

filter(filterExpr)

Applies a filter to grid records.

Parameters:
filterExpr: Array
A filter expression.

This method filters grid records from code. 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.

A user might also be able to filter records using a filter row. To enable this capability, make the filter row visible by setting the filterRow | visible option to true. Note that if the filter(filterExpr) method is called when grid records are already filtered by the user, both these filters are applied. To clear the filter applied by the filter(filterExpr) method, call the clearFilter() method. The user-specified filter can be cleared only by the user.

See Also

For more information on how to apply a filter from code, refer to the Filtering in Code topic.

Show Example:
jQuery

This example shows how to apply a filter to a column and then clear it using the API of dxDataGrid. 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.


                                    

                                    

getSelectedRowKeys()

Gets the keys of currently selected grid records.

Return Value: Array
The keys of the selected records.

If a field providing key values is not specified in a data source, the whole data object is considered the key. In this case, the getSelectedRowKeys() method returns data objects corresponding to the selected records, thus operating exactly as the getSelectedRowsData() method.

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 the data objects of currently selected grid records.

Return Value: Array
The data objects of selected records.

To get only the keys of selected grid records, call the getSelectedRowKeys() method.

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.


                                    

                                    

hideColumnChooser()

Hides the column chooser panel.

This method hides the column chooser panel. To invoke it from code, use the showColumnChooser() method.

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()

Adds a new data row to a grid.

To learn more about how to insert a new row from code, see the Insertion paragraph of the Editing in Code topic.

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.


                                    

                                    

instance()

Returns an instance of this component class.

Return Value: Object
An instance of this component class

Use this method to access other methods of the component.

Show Example:
jQuery

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


                                    

                                    

keyOf(obj)

Returns the key corresponding to the passed data object.

Parameters:
obj: Object
A data object.
Return Value: Object
The key of the passed data object.

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

option()

Returns the configuration options of this component.

Return Value: Object
An object representing the configuration options of this component.

option(optionName)

Gets the value of the specified configuration option of this component.

Parameters:
optionName: String
The name of the option to get.
Return Value: any
The value of the specified option.

If you need to get the value of a configuration option field, specify the path to the required field.

option(optionName, optionValue)

Sets a value to the specified configuration option of this component.

Parameters:
optionName: String
The name of the required option.
optionValue: any
The value you wish to assign to the required option.

To set a value to the configuration option field, specify the path to the required field.

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 of this component.

Parameters:
options: Object
An object containing the required configuration options.

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.

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.

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 dxDataGrid widget, use the paging | pageSize property.

pageSize(value)

Sets the page size.

Parameters:
value: Number
A new value of the page size.

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

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.


                                    

                                    

recoverRow(rowIndex)

Deprecated

Use the undeleteRow(rowIndex) method instead.

Recovers a row deleted in the batch edit mode.

Parameters:
rowIndex: Number
The index of the row to recover.

refresh()

Refreshes grid data.

When you use a data source that is changing dynamically, the dxDataGrid widget cannot automatically track changes that might be made in the source by a third party. In this case, to update data in the widget, call its refresh() method. Along with the main data source, a call of this method refreshes data sources of lookup columns if there are any in the grid.

NOTE: Calling the refresh() method concludes the editing process. In the row edit mode, all changes made in a row (if any) vanish. In the batch edit mode, changes are saved in a buffer waiting to be actually saved in the data source.

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.


                                    

                                    

removeRow(rowIndex)

Removes a specific row from a grid.

Parameters:
rowIndex: Number
The index of the row to be removed.

To learn more about how to remove a row from code, see the Removing paragraph of the Editing in Code topic.

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 removeRow(rowIndex) method.


                                    

                                    

repaint()

Redraws the widget.

After performing some external modifications that lead to a change of the widget container's size or visibility, the widget's state may become invalid. In this instance, use the repaint() method to redraw the widget.

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.


                                    

                                    

saveEditData()

Saves changes made in a grid.

To learn how to manage the editing process from code, see the Editing in Code topic.

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)

Searches grid records by a search string.

Parameters:
text: String
A search string.

This method searches grid records by a search string. This string is searched in those grid columns that have the allowFiltering option set to true. To clear search results, call the searchByText(text) method with an empty string as the argument.

Additionally, a user might be able to search records using a search panel. The panel is hidden by default. To make it visible, assign true to the searchPanel | visible property.

Show Example:
jQuery

This example shows how to apply a filter to a column and then clear it using the API of dxDataGrid. 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 grid records.

Use this method to select all grid records from code. To select records with specific keys, call the selectRows(keys) method. Additionally, you can specify options of user selection using properties of the selection configuration object.

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)

Selects specific grid records.

Parameters:
keys: Array
The keys of the records to be selected.

To access a grid record by a key, a field providing key values must be specified in a data source. If no key was specified, the whole data object is considered the key.

NOTE: Calling the selectRows(keys) method deselects all previously selected records.

Show Example:
jQuery

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


                                    

                                    

selectRowsByIndexes(indexes)

Selects grid rows by indexes.

Parameters:
indexes: Array
The indexes of the rows to be selected.

An array, which is passed to this method as the argument, must contain row indexes. When calculating them, data and group rows are counted, though only data rows can be selected.

Note that selection applied by the selectRowsByIndexes(indexes) method will be cleared once the current page is changed. Therefore, to preserve the selection, call this method within the contentReadyAction callback function.

NOTE: Calling the selectRowsByIndexes(indexes) method deselects all previously selected records.

Show Example:
jQuery

In this example, you can select grid records using the select 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()

Invokes the column chooser panel.

This method invokes the column chooser panel. To hide it from code, use the hideColumnChooser method.

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.


                                    

                                    

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.

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 the batch edit mode.

Parameters:
rowIndex: Number
The index of the row to recover.

To learn more about how to recover a deleted row programmatically, see the Removing paragraph of the Editing in Code topic.

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.