Telerik UI for Windows 8 HTML

The Telerik Data Storage ships in a separate installation from the Telerik UI for Windows 8 HTML suite. This article will explain how to add the Data Storage reference to your application and then, how to use it to build data-oriented applications.

Installing the Data Storage

From Q3 2013, the Data Storage SDK is installed through the default Telerik UI for Windows 8 HTML installer, so you do not need to take any specific steps to install the component.

Referencing the Data Storage in Your Project

To add the Telerik Data Storage to an app, do the following:

  1. Once the Data Storage SDK is installed, you can open a new or existing project, right-click the References folder and select Add Reference from the context menu.

  2. In the References dialog select Telerik Data Storage for Windows 8 HTML. Note that this will automatically add a reference to Microsoft Visual C++ Runtime Package. This SDK is needed because the Telerik Data Storage runs native C++ code.

  3. In the <head> tag of the current page, add the following reference:

    HTML Copy imageCopy
    <script src="///Telerik.Storage.HTML/js/Telerik.Data.js"></script>

To deploy an application successfully on any machine, you must select the right Solution Platform since the Data Storage component uses native code that is CPU architecture dependent and must be rebuilt for all architectures (x86, ARM, x64). To do this, you need to open the Configuration Manager dialog that is accessible from Build\Configuration Manager... menu item of Visual Studio 2012. You must ensure that all projects in your solution use the same platform.

When you publish your application in the Windows Store, you need to build and deploy .appx packages for all platform configurations. This is the common requirement for all Windows Store applications that use native components. For more information, read this article on MSDN: Creating an app package.

Using the Data Storage in JavaScript/HTML projects

The lightweight JavaScript wrapper library over Telerik’s Data Storage engine defines the Telerik.Data namespace. In this namespace, developers can apply CRUD operations using the Database object, that tracks the internal state of the database and persisted data. The following steps are required in order to create a database and apply CRUD operations to it:

Create a Database

You can create a database calling the open(databaseName, location, schema) static method of the Database class, passing the name, the location and a schema object of the database. Here is a list of the three parameters with brief descriptions:

  • databaseName: This parameter is mandatory and represents the name of the database. If no database with this name exists, a new database will be created and if such a database already exists, it will be opened.

  • location: This parameter is optional. It holds the location where the database file will be stored. Possible locations for database file are : "local", "roaming" and "temporary". These locations correspond to the three data stores in Windows Store applications. For more information on the subject, go to Managing application data.

  • schema: This parameter is optional and defines the structure of the database with tables, columns and indices. Defining a database schema provides a set of clearly defined benefits. You can find more information regarding the schema definition in this article: Providing a Schema to a Data Storage Database

Example Copy imageCopy
var db ="MyDBName", "roaming" );

This will create a new database in the roaming data store. If the database name matches an existing database, it will be opened.

Populate the Database

To insert tables in the database and rows into these tables, use the insert(tableName, object) method. tableName here stands for the string name of the table into which you want to insert the object. The method will create a table with the given name that will hold the object's data, passed as a second parameter. The only requirement for the objects used for table creation is the field with name "id" that keeps an integer value. This will be the primary key of this table.

Example Copy imageCopy
var person = { firstName: "Hardy", age: 12, inserted: new Date(), id: 1 };
db.insert("persons", person);

As a result of this example a new table with name "persons" and fields "firstName", "age", "inserted" and "id" will be created. If the table already exists, the object will be added to the existing table.

It is a usual practice to persist a collection of objects, one by one, by calling the insert method of the database multiple times.

Syncing Changes and Closing the Database Connection

In order to persist changes into the database, the asynchronous method sync() should be called as follows:

Example Copy imageCopy
db.sync(); //call this to apply any CRUD operations done on the database

All the changes applied to the database should be finalized by calling the close() method at the time the application is suspended or closed. Its invocation aborts any pending operations and release all unmanaged resources, associated with the database object. This method is also necessary especially in case of error handling.

Example Copy imageCopy
db.close(); //release all unmanaged resources

In most scenarios it is important to make your database object long-lived. The Telerik.Data.Database object can easily be persisted across multiple db.sync() and db.query() statements. Thus, you ensure all database reads and writes go through the same database object. This is an important aspect of making multiple queries—your database object needs to be shared. Otherwise, the underlying WinRT objects referenced by multiple Telerik.Data.Database objects form a race condition on the same SQLite database file.

Update Data in the Database

To update data from an existing record, call the update(tableName, data) method. The first argument it accepts is the name of the table to update and the seconds—the updated data record. The Data Storage matches the passed object with the corresponding row in the database using its id.

Example Copy imageCopy
var person={ firstName: "Hardy", age:12, inserted: new Date(), id: 1 };
db.update("persons", person);
db.sync().then(function () {

This logic will find the item with id=1 in the "persons" table and will apply the new values to it. Then, the changes will be synced and the database connection will be closed.

Removing Records from the Database

To remove an existing record, use the remove(tableName, data) method. It accepts as first argument the name of the table from which you are going to delete a record. The second parameter can be:

  • The id of the record to be deleted.

  • The whole data object, containing the id value.

Example Copy imageCopy
var person = { firstName: "Hardy", age: 12, inserted: new Date(), bool: true, id: 1 };
db.remove("persons", { id: 1 });
db.remove("persons", person);

db.sync().then(function () {

Both lines using the remove method will remove the record with id=1 from the "persons" table.

Select Data from the Database

To select the appropriate data from the database use the query(sqlStatement, parameter) asynchronous method. The sqlStatement is a string parameter, containing an SQL statement. parameter is optional and must be an array of values that will be used as paramaters in the query.

Example Copy imageCopy
db.query("select * from persons").then(function (result) {
//do something with the result object

//apply parameterized query
db.query("select * from persons as x where = @p1", [1]).then(function (result) {
//do something with returned result list

The first query returns the entire persons table data. The second query returns a single record from the persons table that has an id=1.

In order to prevent the application from a crash, use the Promise.done() method for error handling as follows:

Example Copy imageCopy
db.query("select * from persons").done(function (result) {
//changes are persisted successfully
//todo : do something with result object
}, function (error) {
if (error && error.message) {
//todo: handle error according to the error object content

Note that for most scenarios using the fluent API of Data Storage. It guides you through all operations used for data selection and is easier to read and maintain. To learn more about performing read operations using Data Storage's fluent API, go to: Read Operations.

Getting a Scalar Value from the Database

To execute a statement that returns a scalar value as a result of an aggregation operation use the queryScalar(scalarSQL) asynchronous method. scalarSQL is an SQL query that returns a scalar result (e.g. count) or no result.

Example Copy imageCopy
db.queryScalar("select count(*) from persons").then(function (result) {
//do something with scalar result

db.queryScalar("drop table persons").then(function () {

Demo Application

To see the Telerik Data Storage at work, you can run the demo application available in your account. There you will see different Telerik controls bound to data from the Data Storage, including a RadGrid with an external edit form.

To get the application, follow the steps below.

  1. Go to your Telerik account.

  2. Click on the Products & Subscriptions link and then click the DevCraft Ultimate link or the Windows 8 product link.

  3. On the next page click the Download Installer and other resources button.

  4. Locate Telerik UI for Windows 8 HTML in the displayed list of products and click the Browse all product files link.

  5. From the displayed list, click on HTML Data Storage Demo, which will download a .zip file with the Data Storage example application.

  6. Make sure you check the ReadMe.txt file before you try to run the application.

See Also