DataProvider
See the Server-side data guide for examples and configuration details.
Members
DEFAULT_SETTINGS
DataProvider.DEFAULT_SETTINGS
Returns the default settings applied when the plugin is enabled without explicit configuration.
LICENSE
DataProvider.LICENSE
Returns the license token of the plugin, its display name, where it is checked, and the tokens it requires.
PLUGIN_KEY
DataProvider.PLUGIN_KEY
Returns the plugin key used to identify this plugin in Handsontable settings.
PLUGIN_PRIORITY
DataProvider.PLUGIN_PRIORITY
Returns the priority order used to determine the order in which plugins are initialized.
SETTING_KEYS
DataProvider.SETTING_KEYS
Returns the setting keys that trigger a plugin update when changed via updateSettings. Besides its own key,
the settings of the plugins the query reads: re-applying one of them resets the page, sort, or filters, so the
query has to be read again and the rows fetched for it. The framework wrappers pass only the settings that
changed, so such a setting usually arrives without dataProvider.
SETTINGS_VALIDATORS
DataProvider.SETTINGS_VALIDATORS
Returns validator functions for each plugin setting to verify their values are valid before applying them.
Methods
createRows
dataProvider.createRows([options]) ⇒ Promise<void>
Server create via onRowsCreate. Use rowsAmount to insert more than one row in one call.
After a successful onRowsCreate, refetches the current query unless refetchAfterCreate is false;
Hooks#afterRowsMutation fires in both cases. With the refetch off, a fetchRows request that is
still in flight when the create finishes (a sort or filter change made just before) would otherwise resolve
later and loadData() the rows onRowsCreate applied out of the grid, so that one case refetches anyway
(superseding the pending request, which fires Hooks#afterDataProviderFetchAbort). With the
SheetsBar plugin, a create that finishes while its sheet is not shown refetches that sheet anyway too:
the grid shows another sheet then, so onRowsCreate has no grid to apply the rows to.
| Param | Type | Description |
|---|---|---|
| [options] | object | optional position, referenceRowId, rowsAmount. |
destroy
dataProvider.destroy()
Destroys the plugin.
disablePlugin
dataProvider.disablePlugin()
Disables the plugin, aborts the fetch the grid is waiting for, and resets query state. With the
SheetsBar plugin, fetches of the sheets you do not see keep running.
Hook listeners registered with addHook are removed by super.disablePlugin() via clearHooks().
The constructor registers Hooks#hasExternalDataSource for the period before the first enablePlugin();
enablePlugin() registers it again so it survives each updatePlugin() cycle.
enablePlugin
dataProvider.enablePlugin()
Enables the plugin, syncs query parameters from Pagination, ColumnSorting, and Filters, and registers hooks.
fetchData
dataProvider.fetchData([overrides]) ⇒ Promise<({rows: Array<*>, totalRows: number}|null)>
Fetches rows from fetchRows with current or overridden query parameters. With the SheetsBar plugin, it
fetches the sheet you see.
Emits: [Hooks#event:afterDataProviderFetch](/docs/react-data-grid/api/hooks/#afterdataproviderfetch) when data loads., [Hooks#event:afterDataProviderFetchError](/docs/react-data-grid/api/hooks/#afterdataproviderfetcherror) when `fetchRows` throws a non-abort error., Hooks#afterDataProviderFetchAbort when the request is superseded, aborted,event: or ends with `AbortError`.
| Param | Type | Description |
|---|---|---|
| [overrides] | object | optional Partial query overrides (e.g. { page: 2 }, { pageSize: 20, page: 1 }, { sort }, { filters }). Pass { skipLoading: true } to mark internal refetches (for example sort or CRUD); Hooks#beforeDataProviderFetch receives it, and it is not passed to fetchRows. Numeric page is clamped to at least 1. When the response totalRows implies fewer pages than the requested page, fetches again at the last valid page without applying the out-of-range result (avoids redundant afterPageChange loads and aborted duplicate requests after row removal on the last page). |
getQueryParameters
dataProvider.getQueryParameters() ⇒ DataProviderQueryParameters
Returns: DataProviderQueryParameters - Copy of current query parameters (sort and filters are cloned when non-null).
getRowId
dataProvider.getRowId(visualRow) ⇒ *
| Param | Type | Description |
|---|---|---|
| visualRow | number | Visual row index. |
Returns: * - Row id from rowId option, or undefined.
isEnabled
dataProvider.isEnabled() ⇒ boolean
Check if the plugin is enabled in the handsontable settings.
isFetching
dataProvider.isFetching() ⇒ boolean
Tells whether the grid is waiting for a fetchRows response that shows the loading overlay. A fetch that passes
skipLoading: true does not count. The answer is already false inside the Hooks#afterDataProviderFetch,
Hooks#afterDataProviderFetchError, and Hooks#afterDataProviderFetchAbort listeners of the fetch
that settled, unless another fetch has started in the meantime. With the sheets bar, it answers for the sheet
you see.
removeRows
dataProvider.removeRows(rowIds) ⇒ Promise<void>
Server remove via onRowsRemove. Pass one row id or an array of ids.
After a successful onRowsRemove, refetches from the server. When the remove clears every row currently
loaded (typical when emptying the last page) and the current page is greater than 1, loads the previous page
in one request. Otherwise refetches the current page, then loads the previous page when that response is empty
and the current page is still greater than 1.
Throws:
ErrorWhen any id isnullorundefined.
| Param | Type | Description |
|---|---|---|
| rowIds | Array<*> * | Row id or ids. |
updatePlugin
dataProvider.updatePlugin([newSettings])
Re-applies settings and refetches when the instance is already initialized. Two payloads leave the
configuration in place: one whose dataProvider is no longer the grid’s (an earlier afterUpdateSettings
listener replaced it with a nested updateSettings() call, which already re-applied the plugin), and one that
sends the dataProvider object whose rows the plugin already fetched, which would otherwise abort the running
fetch and refetch the same rows. A payload that also re-applies a plugin the query reads (Pagination,
ColumnSorting, Filters, or columns, which clears the sort) runs the full cycle, because that plugin’s state
was reset and the query has to be read from it again.
| Param | Type | Description |
|---|---|---|
| [newSettings] | object | optional The settings passed to updateSettings(). |
updateRows
dataProvider.updateRows(rows) ⇒ Promise<void>
Server update via onRowsUpdate. Pass an array of { id, changes, rowData? } (same shape as onRowsUpdate).
Throws:
ErrorWhen any payload omitsidoridisnull.
| Param | Type | Description |
|---|---|---|
| rows | Array<object> | Row update payloads (one or more). |