Kendo

  • Kendo UI
  • Demos
  • Roadmap
  • Download Beta

Skin

  • Framework
  • UI Widgets
  • Integration

      Information This example is bound to XML in the following format:

      XML Format

      <book cover="javascript-the-good-parts.png">
          <title>JavaScript: The Good Parts</title>
          <author>Douglas Crockford</author>
          <url>http://www.amazon.com/…</url>
      </book>
      see the full XML

      Note: Security restrictions in Chrome prevent this example from working when the page is loaded from the file system (via file:// protocol).

      • 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.