Telerik UI for Windows 8 HTML

The main settings needed for binding the DataSource control to remote data are contained in the DataSource.transport and DataSource.schema options. They are responsible for:

  • transport: Specifies the settings for loading and saving data. This can be a remote or local/in-memory data. It includes specifying the URL of the source of data, the parameters to pass, the expected data type, etc. In other words, these are the settings to use for retrieving the data.

  • schema: Responsible for describing the raw data format, or in other words, settings for processing the raw data, once it is retrieved. These include: specifying the field from the response containing the data items of interest or the groups of data items, specifying the field containing aggregates for the data, and providing a model for the returned data.

There is a third property related to remote data retrieval, that you may find useful when working with OData services—the type one which can be used to specify a predefined type of transport. Currently, only "odata" is supported as a value.

Configuring Data Transport

Overview

To configure remote web service binding, use the transport option during initialization.

Configuring the Transport Option Copy imageCopy
var dataSource = new Telerik.Data.DataSource({
    transport: {
        //use the read option for specifying a location to read data from
        read: {
            url: "http://search.twitter.com/search.json",
            dataType: "json", //explicitly specify the expected format of the data
            data: {
                //specify additional data to be sent to the remote service
                //value can also be a function that returns the actual value to be sent
                q: "telerik"
            }
        }
    }
});

Once the DataSource has been created with transport options, calling the read() method will cause the component to make a web request to the remote service. The read() method is asynchronous and returns a WinJS.Promise object that can be used to wait for the returned result.

Note

Note that the read() method is automatically called when the DataSource is bound to a Telerik control and there is no need to call it, unless the Telerik control is initialized with the autoBind property set to false. The only cases when the read() method should be called are when the autoBind property is set to false or when the data from the DataSource will be used outside of a Telerik control.

Calling the read() Method Manually Copy imageCopy
//use the then() callback of the Promise object returned from read()
dataSource.read().then(function () {
    //use data here
    var data = dataSource.view;
});

Properties

Here is a description of the transport options.

The parameterMap property of the transport object can be specified for modifying the parameters that are sent to the remote endpoint. It is often used to encode the parameters in JSON format. The property expects a function with a single options parameter. The parameter should contain key/value pairs that represent the request. One or more of the following keys will be present (depending on the configuration and current request type):

  • aggregate: An object containing the current aggregate info. Present if there are any aggregates, and serverAggregates is set to true.

  • group: An object containing the current filter info. Present if the data source is grouped and serverGrouping is set to true.

  • filter: An object containing the current filter info. Present if the data source is filtered and serverFiltering is set to true.

  • page: The current page. Present if serverPaging is set to true.

  • pageSize: The current page size. Present if serverPaging is set to true.

  • skip: a A number indicating how many records to skip from the beginning (related to the current page). Present if serverPaging is set to true.

  • sort: An array containing the current sorting info. Present if the data source is sorted and serverSorting is set to true.

  • take: The same as pageSize. Present if serverPaging is set to true.

The function should return another object, whose keys specify the parameter names and the values that are sent.

Setting up the Parameter Map Copy imageCopy
var myDataSource = new Telerik.Data.DataSource({
    transport: {
        parameterMap: function (options) {
            return {
                pageIndex: options.page,
                size: options.pageSize,
                //calls a custom function to convert to another format
                orderBy: convertSort(options.sort)
            }
        }
    }
});

To be able to read data from the remote service, you should configure the read set of options of the transport object, namely:

  • cache: a boolean property indicating whether the browser should cache the requested pages.

  • contentType: represents the content-type HTTP header sent to the server.

  • data: The data to be sent to the server. For more information see the jQuery.ajax documentation.

  • dataType: The type of data that you're expecting back from the server. For example, "json".

  • type: The type of request to make ("POST", "GET", "PUT" or "DELETE"), default is "GET".

  • url: The remote URL to call when retrieving new data.

Configuring the read Property Copy imageCopy
var dataSource1 = new Telerik.Data.DataSource({
    transport: {
        read: {
            url: "http://api.geonames.org/wikipediaSearchJSON",
            data: {
                q: "bulgaria",
                username: "demo"
            },
            cache: false
        }
    },
    schema: {
        data: "geonames"
    }
});

Additionally to transport, the type property of the DataSource can be used to specify a predefined type of transport. Currently, only "odata" is supported.

Using Transport Type Copy imageCopy
var dataSource2 = new Telerik.Data.DataSource({
    type: "odata",
    transport: {
        read: "http://odata.netflix.com/Catalog/Titles"
    }
});

Describing fetched data

When binding to remote data, the schema property is used to describe the raw data returned from the source. It exposes the following options:

  • aggregates: specifies the field from the response which contains the aggregate results. If set to a function - the function will be called to return the aggregate results for the current response, e.g:

    Setting Response Aggregates Container with a String Copy imageCopy
    schema: {
        aggregates: "aggregates" // aggregate results are returned in the "aggregates" field of the response
    }
    
    Setting Response Aggregates Container with a Function Copy imageCopy
    schema: {
        aggregates: function(response) {
            return response.aggregates;
        }
    }
    

    The valid aggregate results should look like this:

    Model of the Aggregates Results Copy imageCopy
    {
        fieldName: {
            functionName1: functionValue1,
            functionName2: functionValue2
        }
    }
    
    Real Example of Aggregates Results Copy imageCopy
    {
        unitsInStock: {
            count: 2000
        },
    
        unitPrice: {
            max: 250,
            min: 20
        }
    }
    
  • data: Specifies the field from the response which contains the data items. If set to a function - the function will be called to return the data items for the current response.

    Setting Response Data Container with a String Copy imageCopy
    schema: {
        data: "items" // data items are returned in the "items" field of the response
    }
    
    Setting Response Data Container with a Function Copy imageCopy
    schema: {
        data: function(response) {
            return response.items;
        }
    }
    
  • errors: Specifies the field from the response which contains any errors. If set to a function - the function will be called to return the errors for the current response (if present). If there are any errors the error event of the DataSource will be raised.

    Setting Response Errors Container with a String Copy imageCopy
    schema: {
        errors: "exceptions" // errors are returned in the "exceptions" field of the response
    }
    
    Setting Response Errors Container with a Function Copy imageCopy
    schema: {
        errors: function(response) {
            return response.errors;
        }
    }
    
  • groups: Specifies the field from the response which contains the groups. If set to a function - the function will be called to return the groups for the current response. Used instead of the schema.data setting if remote grouping operation is executed.

    Setting Response Groups Container with a String Copy imageCopy
    schema: {
        groups: "groups" // errors are returned in the "exceptions" field of the response
    }
    
    Setting Response Groups Container with a String Copy imageCopy
    schema: {
        groups: function(response) {
            return response.groups;
        }
    }
    

    The returned groups should conform to the following format:

    Model of the Groups Results Copy imageCopy
    [{
        aggregates: {
            field1Name: {
                function1Name: function2Value,
                function2Name: function2Value
            },
            field2Name: {
                function1Name: function1Value
            }
        },
        field: fieldName, // the field name on which is grouped
        hasSubgroups: true, // false if there are not sub group items and this is the top most group
        items: [
        // either the inner group items (if hasSubgroups is true) or the data records
        {
            aggregates: {
                //nested group aggregates
            },
            field: nestedGroupFieldName,
            hasSubgroups: false,
            items: [
            // data records
            ],
            value: nestedGroupValue
        },
        //nestedgroup2, nestedgroup3, etc.
        ],
        value: value // value of the field on which is grouped
    }
    // group2, group3, etc.
    ]
    
  • model: Describes the Model of the DataSource, which provides the ability to define schema for the fields. You can add validation to them, specify which ones are editable, nullable, etc. For example:

    Setting up Data Model Copy imageCopy
    var dataSource = new Telerik.Data.DataSource({
        schema: {
            model: {
                id: "ProductID",
                fields: {
                    ProductID: {
                        //this field will not be editable (default value is true)
                        editable: false,
                        // a defaultValue will not be assigned (default value is false)
                        nullable: true
                    },
                    ProductName: {
                        validation: {
                            //set validation rules
                            required: true
                        }
                    },
                    UnitPrice: {
                        //data type of the field {Number|String|Boolean|Date} default is String
                        type: "number",
                        // used when new model is created
                        defaultValue: 42,
                        validation: {
                            required: true,
                            min: 1
                        }
                    }
                }
            }
        }
    });
    
  • parse: The name of a function which will be executed before the server response is used. Appropriate for preprocessing or parsing of the server response.

    Using a Parse Function Copy imageCopy
    schema: {
        parse: function(response) {
            // perform some processing over the response
            return processResponse(response);
        }
    }
    
  • total: The field from the response which contains the total number of data items. If set to a function - the function will be called to return the total number of data items for the current response. If not specified the length of the Array returned by schema.data will be used.

    Setting Response Total Container with a String Copy imageCopy
    schema: {
        total: "count" // total number of data items is returned in the "count" field of the response
    }
    
    Setting Response Total Container with a Function Copy imageCopy
    schema: {
        total: function (response) {
            return response.items.length;
        }
    }
    
  • type: Specifies the response - "xml" or "json". The default value is "json".

    Setting Response Type Copy imageCopy
    schema: {
        type: "xml"
    }
    
Caution

The transport, schema and type properties can be specified during initialization only. They are read-only after the DataSource instance is created.