Data Binding

dxDataGrid can represent data obtained from different sources. You can declare an array of plain objects or implement a custom store encapsulating some sophisticated logic - dxDataGrid will operate with any source fast and seamless. In this guide, you will learn the ways of providing and binding data to the dxDataGrid widget.

Before you begin, please make sure you have successfully linked the necessary libraries and added the dxDataGrid widget to your page. If not, start by learning how to do this using the Installation topic.

NOTE: You can configure the dxDataGrid widget using the jQuery, Knockout or AngularJS approach. Code snippets in this guide use the jQuery approach.

See Also

Provide Data

You can use one of the two approaches to provide data for dxDataGrid. The first is declaring an array of plain objects and using it as a data source. For more information on this approach, see the Using an Array of Objects topic. The second is implementing a data source using the data library. With its new level of sophistication, this approach brings you the privileges and flexibility not before seen in primitive arrays. This approach is discussed in greater detail in the Using the Data Library topic.

Using an Array of Objects

The simplest way of providing data for dxDataGrid is using an array of plain objects. Each object in this array represents a grid row, while the fields of this object provide information for grid columns. For an example, consider the following code snippet.

JavaScript
var gridDataSource = [
    { author: 'D. Adams', title: "The Hitchhiker's Guide to the Galaxy", year: 1979, genre: 'Comedy, sci-fi' },
    { author: 'K. Vonnegut', title: "Cat's Cradle", year: 1963, genre: 'Satire, sci-fi' },
    { author: 'M. Mitchell', title: "Gone with the Wind", year: 1936, genre: 'Historical fiction' }
];

This array contains three objects that will be represented in a grid by three rows. Each object holds four fields providing data for four grid columns. Next, you need to bind this array to your grid. To learn how to do it, refer to the Bind Data topic.

Using the Data Library

DevExtreme is supplied with a set of components called "data library" that helps you read and write data. A comprehensive overview of data library features is provided in the Data Layer topic. There are two main concepts, which the data library is built on: DataSource and Store.

DataSource is a stateful object that keeps sorting, grouping, filtering and data transformation options and applies them each time data is loaded. It also provides events intended to handle data and state changes. More information on the DataSource object can be found in the Reference section.

Store is a universal data access interface supporting a number of methods for reading and editing data. You can find the list of these methods in the What Are Stores topic. There are four types of stores.

  • ArrayStore - provides access to an in-memory array
  • LocalStore - provides access to the HTML5 web storage
  • ODataStore - provides access to a remote OData service
  • CustomStore - allows you to implement your own data access logic

dxDataGrid accepts a DataSource instance or a DataSource configuration object. The instance or the object must have the store field specified (except for a CustomStore, where all store settings are specified directly in the object). This field can be set to an object configuring a store of any type listed above. In the further subtopics, you will see examples of configuration sufficient for using a store of each type.

Using an ArrayStore

This type of store is great when you need a simple data source with the data lifetime equaling the lifetime of your application. An ArrayStore is created from an array of plain objects. dxDataGrid creates it automatically when such an array is specified for it (see Using an Array of Objects). However, you may need to create an ArrayStore explicitly if you require handling the events of data loading, updating, etc., in a special way on the store level. The code snippet below illustrates the minimal configuration of an ArrayStore that can be used to provide data for the dxDataGrid widget.

JavaScript
var gridDataSource = {
    store: {
        type: 'array',
        data: [
            { author: 'D. Adams', title: "The Hitchhiker's Guide to the Galaxy", year: 1979, genre: 'Comedy, sci-fi' },
            { author: 'K. Vonnegut', title: "Cat's Cradle", year: 1963, genre: 'Satire, sci-fi' },
            { author: 'M. Mitchell', title: "Gone with the Wind", year: 1936, genre: 'Historical fiction' }
        ]
    }
};

In addition, you can specify the store's key option to have a read-write access to the data. An ArrayStore has a lot more options available for configuring. For the full list of them, refer to the ArrayStore reference section.

After you have created a data source configuration object, you need to bind it to your grid. Refer to the Bind Data section to learn how to do this.

Using a LocalStore

This type of store is helpful when you use an HTML5 Web Storage (also known as window.localStorage) for storing your data. To provide a minimal configuration for a LocalStore, specify its type and name options as demonstrated below.

JavaScript
var gridDataSource = {
    store: {
        type: 'local',
        name: 'myLocalStore'
    }
};

In addition, you can specify the store's key option to gain read-write access to data. A LocalStore has many more options available for configuring. For a full list, refer to the LocalStore reference section.

After you have created a data source configuration object, you need to bind it to your grid. Refer to the Bind Data section to learn how to do this.

Using an ODataStore

OData is a universal open protocol for consuming data APIs. The DevExtreme data library provides a special type of store to access OData web services, called ODataStore. The following code is sufficient to provide data for dxDataGrid using an ODataStore.

JavaScript
var gridDataSource = {
    store: {
        type: 'odata',
        url: 'http://url/to/the/source'
    }
};

In addition, you can specify the store's key option to have a read-write access to the data. In some cases, this configuration is not enough for a ODataStore to support proper operation. This may occur due to the same-origin policy restrictions. For more information, read the Note on Same-Origin Policy topic.

An ODataStore has many more options available for configuring. For the full list of them, refer to the ODataStore reference section.

After you have created a data source configuration object, you need to bind it to your grid. Refer to the Bind Data section to learn how to do this.

Using a CustomStore

When you have a custom web service with its own data accessing logic, use a CustomStore to operate data. This type of store requires the implementation of a function for each data access operation. To use a CustomStore in dxDataGrid, implement the load function specifying how data must be loaded from your web service. The following code snippet shows how to do this. Create a Deferred object. If your grid supports filtering, sorting and grouping, obtain grid data transformation settings from the object passed to the load function. Then, get data from your web service. In this example, the getJSON function is used for this purpose. Note that data transformation settings can be passed to your web service as well. After data has been obtained successfully, resolve the Deferred object with received data and an additional object. In this additional object, set the totalCount field to the number of received records. This is needed to support paging in dxDataGrid.

JavaScript
var gridDataSource = {
    load: function (loadOptions) {
        var d = $.Deferred();
        var filterOptions = loadOptions.filter ? loadOptions.filter.join(",") : "";   // Getting filter settings
        var sortOptions = loadOptions.sort ? JSON.stringify(loadOptions.sort) : "";  // Getting sort settings
        var groupOptions = loadOptions.group ? JSON.stringify(loadOptions.group) : ""; // Getting group settings
        var skip = loadOptions.skip; // A number of records that should be skipped 
        var take = loadOptions.take; // A number of records that should be taken
        $.getJSON('http://mydomain.com/MyDataService', {  
            filter: filterOptions,
            sort: sortOptions,
            group: groupOptions,
            skip: skip,
            take: take
        }).done(function (data) {
            ... // process data here
            d.resolve(data, { totalCount: data.length }); 
        });
        return d.promise();
    }
}

You may have noticed that in this code, the total number of grid records is obtained along with data using the getJSON request within the load function. If by any reason you need to obtain this number in an individual request, specify the totalCount function. In this case, use the following code in addition to the code above.

JavaScript
var gridDataSource = {
    load: function (loadOptions) {
        ...
        $.getJSON(...).done(function (data) {
            ...
            d.resolve(data); 
        });
        return d.promise();
    },
    totalCount: function(loadOptions) {
        var d = new $.Deferred();
        var filterOptions = loadOptions.filter ? loadOptions.filter.join(",") : "";  // Getting filter settings
        $.getJSON('http://mydomain.com/MyDataService', {  
            filter: filterOptions,
            needCount: true // You can use this parameter on the server side to ensure that a number of records is required
        }).done(function (data) {
            ...
            d.resolve(data); // data is the number of records
        });
        return d.promise();
    }
};

A CustomStore has many more configuration options than those described in this topic. For a complete list, refer to the CustomStore reference section.

NOTE: You can perform sorting, filtering and paging locally. In this instance, you do not need to pass the corresponding data transformation settings to your web service. Instead, disable the required remote operations by using the grid's remoteOperations option. Moreover, when disabling at least one remote operation, you do not have to specify a total count of records for the grid as well.

After you have created a data source configuration object, bind it to your grid. Refer to the Bind Data section to learn how to do this.

You can see an example of a grid using a CustomStore in the Use Remote Data for DataGrid tutorial.

Bind Data

Regardless of the approach you've chosen to providing data, after implementing a data source, bind it to the dxDataGrid widget using the dataSource option as demonstrated below.

JavaScript
$(function () {
    $("#gridContainer").dxDataGrid({
        dataSource: gridDataSource
    });
});

View Demo