DevExtreme jQuery - DataSource API
The DataSource is an object that provides an API for processing data from an underlying store.
jQuery
var dataSource = new DevExpress.data.DataSource({
// ...
// DataSource is configured here
// ...
});Angular
import DataSource from "devextreme/data/data_source";
// ...
export class AppComponent {
dataSource: DataSource;
constructor () {
this.dataSource = new DataSource({
// ...
// DataSource is configured here
// ...
});
}
}Vue
<script>
import DataSource from 'devextreme/data/data_source';
const dataSource = new DataSource({
// ...
// DataSource is configured here
// ...
});
export default {
data() {
return {
dataSource
}
}
}
</script>React
// ...
import DataSource from 'devextreme/data/data_source';
const dataSource = new DataSource({
// ...
// DataSource is configured here
// ...
});
class App extends React.Component {
// ...
}
export default App;If you create a DataSource instance outside a UI component (as shown above), make sure to dispose of it when it is no longer required. If the instance is created inside a UI component, it is disposed of automatically.
DataSource is not designed to be used in multiple components simultaneously. If you want to share data between multiple widgets, create the store object common for all components. Each component should wrap this store in a separate DataSource.
React
use client directive to ensure the instance is created on the client only. DataSource instances do not support React serialization and therefore cannot be created on the server and sent to the client.Refer to the Data Layer and DataSource Examples articles for more information on working with data in DevExtreme.
Options
| Name | Description |
|---|---|
| customQueryParams |
Custom parameters that should be passed to an OData service with the load query. Available only for the ODataStore. |
| expand |
Specifies the navigation properties to be loaded with the OData entity. Available only for the ODataStore. |
| filter |
Specifies data filtering conditions. |
| group |
Specifies data grouping properties. |
| langParams |
Specifies parameters for language-specific sorting and filtering. |
| map |
Specifies an item mapping function. |
| onChanged |
A function that is executed after data is loaded. |
| onLoadError |
A function that is executed when data loading fails. |
| onLoadingChanged |
A function that is executed when the data loading status changes. |
| pageSize |
Specifies the maximum number of data items per page. Applies only if paginate is true. |
| paginate |
Specifies whether the DataSource loads data items by pages or all at once. Defaults to false if group is set; otherwise, true. |
| postProcess |
Specifies a post processing function. |
| pushAggregationTimeout |
Specifies the period (in milliseconds) when changes are aggregated before pushing them to the DataSource. |
| requireTotalCount |
Specifies whether the DataSource requests the total count of data items in the storage. |
| reshapeOnPush |
Specifies whether to reapply sorting, filtering, grouping, and other data processing operations after receiving a push. |
| searchExpr |
Specifies the fields to search. |
| searchOperation |
Specifies the comparison operation used in searching. |
| searchValue |
Specifies the value to which the search expression is compared. |
| select |
Specifies the fields to select from data objects. |
| sort |
Specifies data sorting properties. |
| store |
Configures the store underlying the DataSource. |
The DataSource allows you to specify CustomStore properties in its configuration object. If you define CustomStore properties as shown in the following code, they override the store.
jQuery
var infiniteList = new DevExpress.data.DataSource({
load: function (loadOptions) {
// Loading data objects
},
byKey: function (key) {
// Retrieving a data object by key
}
});Angular
import DataSource from "devextreme/data/data_source";
// ...
export class AppComponent {
infiniteList: DataSource;
constructor() {
this.infiniteList = new DataSource({
load: (loadOptions) => {
return new Promise((resolve, reject) => {
const data = // Loading data objects
resolve(data);
});
},
byKey: (key) => {
return new Promise((resolve, reject) => {
const obj = // Retrieving a data object by key
resolve(obj);
});
}
});
}
}Vue
<script>
import DataSource from 'devextreme/data/data_source';
const infiniteList = new DataSource({
load: (loadOptions) => {
// Loading data objects
},
byKey: (key) => {
// Retrieving a data object by key
}
});
export default {
// ...
data() {
return {
infiniteList
}
}
}
</script>React
// ...
import DataSource from 'devextreme/data/data_source';
const infiniteList = new DataSource({
load: (loadOptions) => {
// Loading data objects
},
byKey: (key) => {
// Retrieving a data object by key
}
});
class App extends React.Component {
// ...
}
export default App;Methods
| Name | Description |
|---|---|
| cancel(operationId) |
Cancels the load operation with a specific identifier. |
| dispose() |
Disposes of all the resources allocated to the DataSource instance. |
| filter() |
Gets the filter property's value. |
| filter(filterExpr) |
Sets the filter property's value. |
| group() |
Gets the group property's value. |
| group(groupExpr) |
Sets the group property's value. |
| isLastPage() |
Checks whether the count of items on the current page is less than the pageSize. Takes effect only with enabled paging. |
| isLoaded() |
Checks whether data is loaded in the DataSource. |
| isLoading() |
Checks whether data is being loaded in the DataSource. |
| items() |
Gets an array of data items on the current page. |
| key() |
Gets the value of the underlying store's key property. |
| load() |
Starts loading data. |
| loadOptions() |
Gets an object with current data processing settings. |
| off(eventName) |
Detaches all event handlers from a single event. |
| off(eventName, eventHandler) |
Detaches a particular event handler from a single event. |
| on(eventName, eventHandler) |
Subscribes to an event. |
| on(events) |
Subscribes to events. |
| pageIndex() |
Gets the current page index. |
| pageIndex(newIndex) |
Sets the index of the page that should be loaded on the next load() method call. |
| pageSize() |
Gets the page size. |
| pageSize(value) |
Sets the page size. |
| paginate() |
Gets the paginate property's value. |
| paginate(value) |
Sets the paginate property's value. |
| reload() |
Clears currently loaded DataSource items and calls the load() method. |
| requireTotalCount() |
Gets the requireTotalCount property's value. |
| requireTotalCount(value) |
Sets the requireTotalCount property's value. |
| searchExpr() |
Gets the searchExpr property's value. |
| searchExpr(expr) |
Sets the searchExpr property's value. |
| searchOperation() |
Gets the searchOperation property's value. |
| searchOperation(op) |
Sets the searchOperation property's value. |
| searchValue() |
Gets the searchValue property's value. |
| searchValue(value) |
Sets the searchValue property's value. |
| select() |
Gets the select property's value. |
| select(expr) |
Sets the select property's value. |
| sort() |
Gets the sort property's value. |
| sort(sortExpr) |
Sets the sort property's value. |
| store() |
Gets the instance of the store underlying the DataSource. |
| totalCount() |
Gets the number of data items in the store after the last load() operation without paging. Takes effect only if requireTotalCount is true |
Events
| Name | Description |
|---|---|
| changed |
Raised after data is loaded. |
| loadError |
Raised when data loading fails. |
| loadingChanged |
Raised when the data loading status is changed. |