Telerik UI for Windows 8 HTML

From Q3 2013 on, Telerik DataSource features a new transport type which allows it to seamlessly bind to a local database created using Telerik Data Storage. By tying the two controls together, you eliminate the need of writing queries to the database. This way, you can bind all Telerik controls, that use the DataSource component (RadGrid, RadChart, etc.), directly to an existing local data storage created by the Data Storage component. This article explains how to set up DataSource to work with Telerik Data Storage and describes some specifics that you should have in mind.

Binding DataSource to a Telerik Data Storage Local Database

Follow the steps below to achieve integration between DataStorage and DataSource components.

  1. Create and populate a database using Data Storage. You must have a storage already created since DataSource can work only with an already existing database.

    You can learn more about creating and populating a database using Data Storage here: Getting Started with Data Storage.

  2. Specify the custom transport name. Set the type property of the DataSource instance to "dataStorage". This will instruct the DataSource that it needs to connect to a Data Storage database.

    Set DataSource Type Copy imageCopy
    dataSource: {
        type: "dataStorage",
        ....
    }
  3. Set up read operations. For simple scenarios that use a single table from the database, you can just set the transport.data.dbName and transport.data.tableName properties to the names of the existing database and the table that you are going to read from, respectively.

    Set read Option Copy imageCopy
    read: {
        data: {
            dbName: "ProductDB",
            tableName: "Products"
        }
    }

    If you need to join tables, you can also set the joinedTables property to an array of objects. Each object should represent a table that you are going to join to the current table. The objects should list the following options: destinationTableName (the table which you are joining to the current one), sourceColumn (the column from the current table that you are using for the join), destinationColumn (the column from the destination table that you are using for the join).

    Set read Option with Joined Tables Copy imageCopy
    read: {
        data: {
            dbName: "ProductDB",
            tableName: "Products",
            joinedTables: [
            {
                destinationTableName: "Categories",
                sourceColumn: "catId",
                destinationColumn: "categoryId"
            }]
        }
    }
    Important

    Because of a specific in the DataStorage table joins, currently, you must ensure that the two tables that you are joining do not have fields with matching names. This is done in two parts:

    • Make sure the fields that you define do not have identical names in the two joined tables.

    • Set the serializeObject property of the Telerik.Data.Database that you have created to false. Otherwise, a field will be added to each table, having one and the same name.

    Note

    When joining tables, create, update and delete operations will be performed only on the initial table, specified in the read options.

  4. Set up create, update and delete operations. For this purpose, you just need to set the transport.data.dbName and transport.data.tableName properties for each operation.

    Set create/update/destroy Options Copy imageCopy
    create: {
        data: {
            dbName: "ProductDB",
            tableName: "Products",
        }
    },
    update: {
        data: {
            dbName: "ProductDB",
            tableName: "Products",
        }
    },
    destroy: {
        data: {
            dbName: "ProductDB",
            tableName: "Products",
        }
    }
  5. Enable sorting, filtering and paging. To offload these operations to the Data Storage, set the serverSorting, serverFiltering and serverPaging properties to true. You can predefine filter and sort expressions, as well as page size and page index and they will be passed to the Data Storage.

    Set filter/sort/page Options Copy imageCopy
    serverSorting: true,
    serverFiltering: true,
    serverPaging: true 
    Set filter/sort/page Expressions Copy imageCopy
    sort: { field: "unitPrice", dir: "asc" },
    filter: { field: "unitPrice", operator: "gte", value: 10 },
    pageSize: 10,
    page: 2 
    Note

    Grouping and aggregates cannot be performed by the Data Storage, since grouping produces a different output in SQLite context. Therefore, you cannot set the serverGrouping and serverAggregates properties of the DataSource to true in this scenario.

  6. Define a model. In order for most operations to work correctly, you must define a model for your data using the schema.model. The model must define an id field (schema.model.id) if you want to perform CRUD operations.

    Define a Model Copy imageCopy
    schema: {
        model: {
            id: 'id',
            fields: {
                id: { editable: false },
                productName: { type: "string" },
                categoryName: { type: "string" },
                unitPrice: { type: "number" }
            }
        }
    }

You can see the entire DataSource definition in the code snippet below.

DataSource Definition Copy imageCopy
var ds = new Telerik.Data.DataSource({
    type: "dataStorage",
    transport: {
        read: { //needed to be able to fetch data
            data: {
                dbName: "ProductDB",
                tableName: "Products",
                joinedTables: [
                {
                    destinationTableName: "Categories",
                    sourceColumn: "catId",
                    destinationColumn: "categoryId"
                }]
            }
        },
        create: { //needed to be able to insert new records
            data: {
                dbName: "ProductDB",
                tableName: "Products",
            }
        },
        update: { //needed to be able to update existing records
            data: {
                dbName: "ProductDB",
                tableName: "Products",
            }
        },
        destroy: { //needed to be able to delete records
            data: {
                dbName: "ProductDB",
                tableName: "Products",
            }
        }
    },
    schema: {
        model: {
            id: 'id', //required for CRUD operations
            fields: {
                id: { editable: false }
            }
        }
    },
    //optionally enable sorting, filtering and paging directly in the database
    serverSorting: true,
    serverFiltering: true,
    serverPaging: true,
    //optional sort and filter expressions
    sort: { field: "unitPrice", dir: "asc" },
    filter: { field: "unitPrice", operator: "gte", value: 10 },
    //optional paging settings
    pageSize: 10,
    page: 2
});

Now, you can simply assign this DataSource instance to a data-bound Telerik control, for example RadGrid, and it will be bound to the data provided by Data Storage.

See Also