Kendo

  • Kendo UI
  • Demos
  • Roadmap
  • Download Beta

Skin

  • Framework
  • UI Widgets
  • Integration

    Rank Rating Title Year
    • Description
    • View Code
    • Configuration (14)
    • Methods (14)
    • Events (2)

    The DataSource component is an abstraction for using local (arrays of JavaScript objects) or remote (XML, JSON, JSONP) data. It fully supports CRUD (Create, Read, Update, Destroy) data operations and provides both local and server-side support for Sorting, Paging, Filtering, Grouping, and Aggregates.

    It is a powerful piece of the Kendo UI Framework, dramatically simplifying data binding and data operations.

    Getting Started

    Creating a DataSource bound to local data

    var movies = [ {
          title: "Star Wars: A New Hope",
          year: 1977
       }, {
         title: "Star Wars: The Empire Strikes Back",
         year: 1980
       }, {
         title: "Star Wars: Return of the Jedi",
         year: 1983
       }
    ];
    var localDataSource = new kendo.data.DataSource({data: movies});

    Creating a DataSource bound to a remote data service (Twitter)

    var dataSource = new kendo.data.DataSource({
        transport: {
            read: {
                // the remote service url
                url: "http://search.twitter.com/search.json",
                // JSONP is required for cross-domain AJAX
                dataType: "jsonp",
                // additional parameters sent to the remote service
                data: {
                    q: "html5"
                }
            }
        },
        // describe the result format
        schema: {
            // the data which the data source will be bound to is in the "results" field
            data: "results"
        }
    });

    Binding UI widgets to DataSource

    Many Kendo UI widgets support data binding, and the Kendo UI DataSource is an ideal binding source for both local and remote data. A DataSource can be created in-line with other UI widget configuration settings, or a shared DataSource can be created to enable multiple UI widgets to bind to the same, observable data collection.

    Creating a local DataSource in-line with UI widget configuration

    $("#chart").kendoChart({
        title: {
            text: "Employee Sales"
        },
        dataSource: new kendo.data.DataSource({
            data: [
            {
                employee: "Joe Smith",
                sales: 2000
            },
            {
                employee: "Jane Smith",
                sales: 2250
            },
            {
                employee: "Will Roberts",
                sales: 1550
            }]
        }),
        series: [{
            type: "line",
            field: "sales",
            name: "Sales in Units"
        }],
        categoryAxis: {
            field: "employee"
        }
    });

    Creating and binding to a sharable remote DataSource

    var sharableDataSource = new kendo.data.DataSource({
        transport: {
            read: {
                url: "data-service.json",
                dataType: "json"
            }
        }
    });
    // Bind two UI widgets to same DataSource
    $("#chart").kendoChart({
        title: {
            text: "Employee Sales"
        },
        dataSource: sharableDataSource,
        series: [{
            field: "sales",
            name: "Sales in Units"
        }],
        categoryAxis: {
            field: "employee"
        }
    });
    $("#grid").kendoGrid({
        dataSource: sharableDataSource,
            columns: [
            {
                field: "employee",
                title: "Employee"
            },
            {
                field: "sales",
                title: "Sales",
                template: '<#= kendo.toString(sales, "N0") #>'
        }]
    });
    No code
    aggregate: Array|Object(default: undefined)
    Sets fields on which initial aggregates should be calculated

    Example

    // calculates total sum of unitPrice field's values.
    [{ field: "unitPrice", aggregate: "sum" }]
    data: Array
    The data in the DataSource.
    filter: Array|Object(default: undefined)
    Sets initial filter

    Example

    // returns only data where orderId is equal to 10248
    filter: { field: "orderId", operation: "eq", value: 10248 }
    // returns only data where orderId is equal to 10248 and customerName starts with Paul
    filter: [ { field: "orderId", operation: "eq", value: 10248 },
              { field: "customerName", operation: "startswith", value: "Paul" } ]
    group: Array|Object(default: undefined)
    Sets initial grouping

    Example

    // groups data by orderId field
    group: { field: "orderId" }
    // groups data by orderId and customerName fields
    group: [ { field: "orderId", dir: "desc" }, { field: "customerName", dir: "asc" } ]
    page: Number(default: undefined)
    Sets the index of the displayed page of data.
    pageSize: Number(default: undefined)
    Sets the number of records which contains a given page of data.
    schema: Object
    Set the object responsible for describing the raw data format

    Example

    var dataSource = new kendo.data.DataSource({
         transport: {
           read: "Catalog/Titles",
         },
         schema: {
             data: function(data) {
                 return data.result;
             },
             total: function(data) {
                 return data.totalCount;
             },
             parse: function(data) {
                 return data;
             }
         }
     });
    data: Function
    Should return the deserialized data.
    group: Function
    Used instead of data function if remote grouping operation is executed. Returns the deserialized data.
    parse: Function
    Executed before deserialized data is read. Appropriate for preprocessing of the raw data.
    total: Function
    Should return the total number of records.
    serverAggregates: Boolean(default: false)
    Determines if aggregates should be calculated on the server.
    serverFiltering: Boolean(default: false)
    Determines if filtering of the data should be handled on the server.
    serverGrouping: Boolean(default: false)
    Determines if grouping of the data should be handled on the server.
    serverPaging: Boolean(default: false)
    Determines if paging of the data should be handled on the server.
    serverSorting: Boolean(default: false)
    Determines if sorting of the data should be handled on the server.
    sort: Array|Object(default: undefined)
    Sets initial sort order

    Example

    // sorts data ascending by orderId field
    sort: { field: "orderId", dir: "asc" }
    // sorts data ascending by orderId field and then descending by shipmentDate
    sort: [ { field: "orderId", dir: "asc" }, { field: "shipmentDate", dir: "desc" } ]
    transport: Object
    Sets the object responsible for loading and saving of data. This can be a remote or local/in-memory data.
    dialect: Function
    Convert the request parameters from dataSource format to remote service specific format.

    Example

    var dataSource = new kendo.data.DataSource({
         transport: {
           read: "Catalog/Titles",
           dialect: function(options) {
              return {
                 pageIndex: options.page,
                 size: options.pageSize,
                 orderBy: convertSort(options.sort)
              }
           }
         }
     });
    read: Object|String
    Options for remote read data operation or the URL of the remote service

    Example

    // settings various options for remote data transport
    var dataSource = new kendo.data.DataSource({
        transport: {
            read: {
                // the remote service URL
                url: "http://search.twitter.com/search.json",
                // JSONP is required for cross-domain AJAX
                dataType: "jsonp",
                // additional parameters sent to the remote service
                data: {
                    q: function() {
                        return $("#searchFor").val();
                    }
                }
            }
        }
    });
     // consuming odata feed without setting additional options
     var dataSource = new kendo.data.DataSource({
         type: "odata",
         transport: {
             read: "http://odata.netflix.com/Catalog/Titles"
         }
     });
    data: Object|Function
    Additional data to be send to the server
    dataType: String
    The type of data that you're expecting back from the server
    url: String
    The remote service URL
    • aggregate (val) : Array
      Get current aggregate descriptors or applies aggregates to the data.

      Example

      dataSource.aggregate({ field: "orderId", aggregate: "sum" });

      Parameters

      val: Object|Array (optional)
      Aggregate(s) to be applied to the data.
      Returns
      Array Current aggregate descriptors
    • aggregates () : Array
      Get result of aggregates calculation
      Returns
      Array Aggregates result
    • data (value) : Array
      Get data return from the transport

      Parameters

      value
      Returns
      Array Array of items
    • fetch ()
      Fetches data using the current filter/sort/group/paging information. If data is not available or remote operations are enabled data is requested through the transport, otherwise operations are executed over the available data.
    • filter (val) : Array
      Get current filters or filter the data.

      Supported filter operations/aliases are:

      • Equal To: "eq", "==", "isequalto", "equals", "equalto", "equal"
      • Not Equal To: "neq", "!=", "isnotequalto", "notequals", "notequalto", "notequal", "not", "ne"
      • Less Then: "lt", "<", "islessthan", "lessthan", "less"
      • Less Then or Equal To: "lte", "<=", "islessthanorequalto", "lessthanequal", "le"
      • Greater Then: "gt", ">", "isgreaterthan", "greaterthan", "greater"
      • Greater Then or Equal To: "gte", ">=", "isgreaterthanorequalto", "greaterthanequal", "ge"
      • Starts With: "startswith"
      • Ends With: "endswith"
      • Contains: "contains", "substringof"

      Example

      dataSource.filter({ field: "orderId", operation: "eq", value: 10428 });
      dataSource.filter([
           { field: "orderId", operation: "neq", value: 42 },
           { field: "unitPrice", operation: "ge", value: 3.14 }
      ]);

      Parameters

      val: Object|Array (optional)
      Filter(s) to be applied to the data.
      Returns
      Array Current filter descriptors
    • group (val) : Array
      Get current group descriptors or group the data.

      Example

      dataSource.group({ field: "orderId" });

      Parameters

      val: Object|Array (optional)
      Group(s) to be applied to the data.
      Returns
      Array Current grouping descriptors
    • page (val) : Number
      Get current page index or request a page with specified index.

      Example

      dataSource.page(2);

      Parameters

      val: Number (optional)
      The index of the page to be retrieved
      Returns
      Number Current page index
    • pageSize (val) : Number
      Get current pageSize or request a page with specified number of records.

      Example

      dataSource.pageSiza(25);

      Parameters

      val: Number (optional)
      The of number of records to be retrieved.
      Returns
      Number Current page size
    • query (options)
      Executes a query over the data. Available operations are paging, sorting, filtering, grouping. If data is not available or remote operations are enabled data is requested through the transport, otherwise operations are executed over the available data.

      Example

      
      // create a view containing at most 20 records, taken from the
      // 5th page and sorted ascending by orderId field.
      dataSource.query({ page: 5, pageSize: 20, sort: { field: "orderId", dir: "asc" } });
      // moves the view to the first page returning at most 20 records
      // but without particular ordering.
      dataSource.query({ page: 1, pageSize: 20 });

      Parameters

      options: Object (optional)
      Contains the settings for the operations. Note: If setting for previous operation is omitted, this operation is not applied to the resulting view
    • read (additionalData)
      Read data from transport

      Parameters

      additionalData
    • sort (val) : Array
      Get current sort descriptors or sorts the data.

      Example

      dataSource.sort({ field: "orderId", dir: "desc" });
      dataSource.sort([
           { field: "orderId", dir: "desc" },
           { field: "unitPrice", dir: "asc" }
      ]);

      Parameters

      val: Object|Array (optional)
      Sort options to be applied to the data
      Returns
      Array Current sort descriptors
    • total ()
      Get the total number of records
    • totalPages () : Number
      Get the number of available pages.
      Returns
      Number Number of available pages.
    • view () : Array
      Returns a view of the data with operation such as in-memory sorting, paring, grouping and filtering are applied. To ensure that data is available this method should be use from within change event of the dataSource.

      Example

      dataSource.bind("change", function() {
        renderView(dataSource.view());
      });
      Returns
      Array Array of items
    change
    Fires when data is changed
    error
    Fires when an error occurs during data retrieval.
    • Home
    • Kendo UI
    • Demos
    • Roadmap
    • Blogs
    • Forums
    • Documentation
    • FAQ
    • About
    • Follow us on Twitter
    • Subscribe to our RSS feed

    Kendo UI is powered by Telerik

    Copyright © 2011 Telerik Inc. All rights reserved.