Telerik UI for Windows 8 HTML

Binding RadGrid to a Telerik Data Storage allows your grid control to work offline. The following help article will provide instructions and explanations on the specific settings you need to apply to RadGrid's dataSource to bind it to a Telerik Data Storage.

This topic contains the following sections.

Creating a Database with Telerik Data Storage

Create a schema for the database: RadGrid does not have a built-in logic for generating unique ids when creating a new entry. Usually, you will have to provide your own logic that generates ids and run it in RadGrid's onsave event handler. However, if you are using the Telerik Data Storage for storing your data, you can use the autoIncrement logic of the database to generate the ids. In order for the autoIncrement feature to work, you need to create a database with a schema object. In Code Listing 1 you can see a sample database schema. The important thing here is to set an id field with a type of "number" and the identity and autoIncrement properties set to true.

Code Listing 1: Sample Database Schema Copy imageCopy
var schemaDB = {
    tables: [{
        name: 'GridData',
        columns:
        [
            {
                name: "id",
                type: "number",
                identity: true,
                autoIncrement: true
            },
            { name: "name", type: "string" },
            { name: "jobTitle", type: "string" },
            { name: "birthDate", type: "date" },
            { name: "hireDate", type: "date" }
        ]
    }]
};

Create a database using the schema: To create a database programmatically, use the Telerik.Data.Database.open(databaseName, storage, schema) method. It creates the database with the given schema or opens a connection to it if it already exists. You should create or open the database before the scheduler control is initialized. When using the auto increment Data Storage feature, it is advisable to set the serializeObject property value to false. This is necessary because if the data is saved serialized, the database will not return the generated id when you request data from the database.

Code Listing 2: Initializing and Opening a Database Copy imageCopy
db = Telerik.Data.Database.open("GridDB", "local", schemaDB);
db.serializeObject = false;

Connecting RadGrid's DataSource to Data Storage

Set a dataSource type and configure the transport property: You need to configure RadGrid's dataSource to work with Telerik Data Storage. The first step is to set the dataSource.type property to "dataStorage". Then, you need to configure the dataSource.transport settings for the CRUD operations you will need to do with your RadGrid. Basically, you need to provide a database name and a database table to each CRUD operation. Here is a link to an article with а detailed explanation on how to configure the dataSource.transport to work with Data Storage: Using DataSource with Data Storage. Code Listing 3 provides an example configuration of the transport property that works with the database that was created in the previous section.

Code Listing 3: Configuring RadGrid DataSource to Work with Data Storage Copy imageCopy
type: "dataStorage",
transport: {
    read: {
        data: {
            dbName: "GridDB",
            tableName: "GridData"
        }
    },
    create: {
        data: {
            dbName: "GridDB",
            tableName: "GridData"
        }
    },
    update: {
        data: {
            dbName: "GridDB",
            tableName: "GridData"
        }
    },
    destroy: {
        data: {
            dbName: "GridDB",
            tableName: "GridData"
        }
    }
}

Provide a schema and model for the RadGrid: In order for the dataSource to work properly, you need to provide a schema with a model. The fields you provide in the model have to match the names of the fields you have in your data. The other important thing is to add an id to the schema. Each entry must have a unique id for the various RadGrid features to work properly. By default, the entry edit form generates an id value of 0 and you have to replace this value in the onsave event handler, so that newly generated entries have unique id. In the current scenario we will use the Data Storage's auto increment id feature to generate unique ids. This feature requires an id with a value of null to be passed to the data storage. To ensure that the generated id is null, you need to specify that the field in the schema.model is nullable by setting the nullable property value to true.

Code Listing 4: Setting RadGrid DataSource Schema Copy imageCopy
schema: {
    model: {
        id: "id",
        fields: {
            id: { from: "id", type: "number", nullable: true },
            name: { from: "name", validation: { required: true } },
            jobTitle: { from: "jobTitle", validation: { required: true } },
            birthDate: { from: "birthDate", type: "date" },
            hireDate: { from: "hireDate", type: "date" }
        }
    }
}

Below you can see the whole configured dataSource object for reference. It is exposed in a namespace so you can use it in RadGrid mark-up declaration.

Code Listing 5: Sample DataSource Object Copy imageCopy
WinJS.Namespace.define("Grid.Data", {
    dataSource: new Telerik.Data.DataSource({
        type: "dataStorage",
        transport: {
            read: {
                data: {
                    dbName: "GridDB",
                    tableName: "GridData"
                }
            },
            create: {
                data: {
                    dbName: "GridDB",
                    tableName: "GridData"
                }
            },
            update: {
                data: {
                    dbName: "GridDB",
                    tableName: "GridData"
                }
            },
            destroy: {
                data: {
                    dbName: "GridDB",
                    tableName: "GridData"
                }
            }
        },
        schema: {
            model: {
                id: "id",
                fields: {
                    id: { from: "id", type: "number", nullable: true },
                    name: { from: "name", validation: { required: true } },
                    jobTitle: { from: "jobTitle", validation: { required: true } },
                    birthDate: { from: "birthDate", type: "date" },
                    hireDate: { from: "hireDate", type: "date" }
                }
            }
        }
    })
});

The last step is to create a RadGrid control with the configured dataSource. You have to enable editing and set an editing mode. You can also hide the id field from the user by configuring the columns property. Code Listing 6 provides an example RadGrid configuration.

Code Listing 6: RadGrid Mark-up Copy imageCopy
<div id="grid" data-win-control="Telerik.UI.RadGrid" data-win-options="{
        height: 500,
        dataSource: Grid.Data.dataSource,
        columns: [
            { field: 'name', title: 'Name' },
            { field: 'jobTitle', title: 'Job Title' },
            { field: 'birthDate', title: 'Birth Date' },
            { field: 'hireDate', title: 'Hire Date' }
        ],
        editable: {
            enabled: true,
            mode: 'row',
            create: true,
            update: true,
            destroy: true
        }
    }"></div>