Using LINQ to Indexed DB

While the library is still under development, I want to take some time to explain how you can use this framework, and show how easy it gets to work with the Indexed DB. As mentioned before, the library is based on the on the Promises context. This way we can easily handle all the async callbacks on which the Indexed DB API is based, and provide a uniform object to the developer for handling the results and/or errors. And by using the progress callback, we can provide returning multiple records one by one instead of a whole collection in the complete callback. For more information about promises:

• jQuery promise
• WinJS promise

Another strength of the library is, that you get the opportunity to let it auto build it’s structure. It’s not necessary to provide the database structure. You can just start writing queries, and the library will take care of the creation of tables and indexes. This way it can easily be used for writing POCs or demo applications. This means when ever you are mentioning a string value in the from method that isn’t known in the object store collection, it will be created for you.

But enough about the theory, let us watch some code.

Setting UP Linq2indexeddb

The first thing you need to do is getting the linq2indexeddb library. You can do this by getting the JS script files from codeplex. The only thing you need to make sure is: the sort.js and where.js file need to be in a “Script” folder under the root of the project. These files are used to preform web worker tasks and are hardcoded referenced for now.

Or VS developers can use Nuget Packages:

• http://www.myget.org/feed/Packages/linq2indexeddb (jQuery version)
• http://www.myget.org/feed/Packages/linq2indexeddbmetro (Win8 version, using WinJS)

Once you have the linq2indexeddb library, the next thing you need to do is adding a reference to it in your page. Note, if you are using the jQuery version, you need to add a reference to the jQuery framework first.

using Linq2indexeddb

Once all the references are added, we can start using the library. The first thing you need to do is creating a instance of the linq2indexeddb object. You can do this by calling the linq2indexeddb method on the window object. This method accepts 3 parameters:

• The first one is the name of the database u want to use.
• The second one is a database configuration object. More on that later on the post.
• The last is an Boolean which allows you to enable logging. By default this is disabled

   1: var db = window.linq2indexedDB("dbName", dbConfig, false);

Configuring the database

When opening/creating the database, you can provide a database configuration. Here you can configure the object stores and indexes you want to use. There are several ways to do the configuration, but one thing needs to be provided at all time: the version of the database. This makes sure that the database will have the correct structure we need.

   1: var dbConfig = {};

   2: dbConfig.version = 1;

A second thing we need to do, is providing a way to define the structure. In the current implementation of the library, there are 4 ways to do this. For now I would advise you to use the definition. This doesn’t require you to write the create/delete statements your self. But if you do want to, you can make use of the promises present in the linq2indexeddb.core to create/delete object stores and indexes.

onupgradeneeded

This a function that gets called when the database needs to get updated to the most recent version you provided in the configuration object. 3 parameters are passed to this function:

• Transaction: on this transaction you can create/delete object stores and indexes
  
• The current version of the database
  
• The version the database is upgrading to.

   1: dbConfig.onupgradeneeded = 

   2:     function (transaction, oldVersion, newVersion){

   3:         // Code to upgrade the db structure

   4:     }

The onupgradeneeded callback is the only one that can’t be used in combination with one of the other ways to define the function

schema

The schema is an object which defines the several versions as a key/value. The key keeps the version it targets and in the value an upgrade function. In this function you can add your code to upgrade the database to the version given in the key. The upgrade function has one parameter:

• Transaction: on this transaction you can create/delete object stores and indexes

   1: dbConfig.schema = {

   2:     1: function (transaction){

   3:             // Code to upgrade the db structure to version 1

   4:        }

   5:     2: function (transaction){

   6:             // Code to upgrade the db structure to version 2

   7:        }

   8: }

Note: If the database needs to upgrade from version 0 to 2, the upgrade function of version 1 gets called first. When the upgrade to version 1 is done, the upgrade function of version 2 gets called.

definition

The definition object is the only way to define your database structure without having to write upgrade code. The object keeps a collection of objects which describe what needs to be added or removed for a version. Each object exists out of the following properties:

• Version: The version where for the definitions are.
  
• objectStores: Collection of objects that define an object store
  
  
  
  • name: the name of the object store
    
  • objectStoreOptions
    
    
    
    • autoincrement: defines if the key is handled by the database
      
    • keyPath: the name of the property that keeps the key for the object store
    
    
  • remove: indicates if the object store must be removed
  
  
• indexes: Collection of objects that define an index
  
  
  
  • objectStoreName: the name of the object store where the index needs to be created on
    
  • propertyName: the name of the property where for we want to add an index
    
  • indexOptions
    
    
    
    • unique: defines if the value of this property needs to be unique
      
    • multirow: Defines the way keys are handled that have an array value in the key
    
    
  • remove: indicates if the index must be removed
  
  
• defaultData: Collection of default data that needs to be added in the version
  
  
  
  • objectStoreName: the name of the object store where we want to add the data
    
  • data: the data we want to add
    
  • key: the key of the data
    
  • remove: indicates if the data needs to be removed

   1: dbConfig.definition= [{

   2:     version: 1,

   3:     objectStores: [{ name: "ObjectStoreName"

   4:                        , objectStoreOptions: { autoIncrement: false

   5:                                              , keyPath: "Id" } 

   6:                    }]

   7:     indexes: [{ objectStoreName: "ObjectStoreName"

   8:                   , propertyName: "PropertyName"

   9:                   , indexOptions: { unique: false, multirow: false } 

  10:               }],

  11:     defaultData: [{ objectStoreName: ObjectStoreName

  12:                       , data: { Id: 1, Description: "Description1" }

  13:                       , remove: false },

  14:                   { objectStoreName: ObjectStoreName

  15:                       , data: { Id: 2, Description: "Description2" }

  16:                       , remove: false },

  17:                   { objectStoreName: ObjectStoreName

  18:                         , data: { Id: 3, Description: "Description3" }

  19:                         , remove: false }]

  20: }];

onversionchange

This a function that gets called when the database needs to get updated to the most recent version you provided in the configuration object. But in contrast to the onupgradeneeded callback, this function can be called multiple times. For example if an database is upgrading from version 0 to version 2, the onversionchange will be called 2 times. Once for version 1 and once for version 2.  2 parameters are passed to the function:

• Transaction: on this transaction you can create/delete object stores and indexes
  
• The version of the database it is upgrading to.

   1: dbConfig.onversionchange = 

   2:     function (transaction, version){

   3:         // Code to upgrade the db structure

   4:     }

Querying data

Once the database structure is created, we can start querying on it. On the linq2indexeddb object we have a field linq which holds all the linq functionality. The first method you always need to call is the from method. This method excepts only one parameter, the name of the object store we want to work on. Once we have this we can start inserting, updating, deleting and selecting data from it.

   1: // inserting data, key is optional

   2: db.linq.from("objectstore").insert({}, key);

   3: // updating data, key is optional

   4: db.linq.from("objectstore").update({}, key);

   5: // removing data

   6: db.linq.from("objectstore").remove(id);

   7: // clears all data from the object store

   8: db.linq.from("objectstore").clear();

   9: // gets a single record by his key

  10: db.linq.from("objectstore").get(key);

  11: // selects all objects

  12: db.linq.from("objectstore").select();

But the library also provides ways to filter data. This can be done by calling the where method. This accepts the name of the property we want to filter on as parameter. On this you can call the filter you want to add. For now these are limited to the following:

• equals(value)
  
• between(value1, value2, value1included, value2included)
  
• greaterThen(value, valueIncluded)
  
• smallerThen(value, valueIncluded)
  
• inArray(arrayOfObjects)
  
• like(value)

So if we want to select all the objects which have a field called '”property” and have the value “value” we write the following query:

   1: db.linq.from("objectstore").where("property").equals("value").select()

If you want to add multiple filters you need to do the following:

   1: db.linq.from("objectstore")

   2:        .where("property").equals("value")

   3:        .and("anotherproperty").greaterThen(4)

   4:        .select()

You are also able to sort your data:

• orderBy(propertyName)


• orderByDesc(propertyName)

   1: db.linq.orderBy("property").select()

As last, the library also enables you to get only a subset of the properties stored in the objects

   1: db.linq.from("objectstore").select(["property1", "property2"])

Conclusion

This was a brief introduction of the functionalities of the linq2indexeddb library. In future post I will go more in-depth into the advanced functionalities like linq2indexeddb.core. If you have any suggestions, bugs, additions,… about the library, feel free to contact me. Hope you enjoy using the library.

PhoneGap: Building native mobile apps with HTML5

PhoneGap is an HTML5 app platform which allows you to develop an application in HTML5 and run it as an native app on your mobile device. PhoneGap does this by running the application in a web browser control in the background. So when the user starts navigating trough your application, PhoneGap will intercept this and navigate to the files which are stored locally on the phone. This way there is no need to have an connection to the internet to run the application. But PhoneGap offers more then only building an HTML5 app. Because most of the HTML5 specifications aren’t implemented in mobile browsers yet, PhoneGap provides an framework, which allows you to access features of the mobile device. For example the camera, file system, contacts, …

Because all these features are OS depended (even device depended sometimes, certainly for Android), there is for every OS an different implementation of the PhoneGap framework. This is because the JS framework which is provided will make calls to a dll (in case of Windows Phone), .jar (in case of Android), …to access the specific features of the mobile device. An overview of all the features can be found here. It gives you also an overview on which platforms the features are supported. The documentation of the API can be found here.

Getting started

Because I am an .NET developer, my starting point will be developing an PhoneGap application for Windows Phone. Further on, I will show how you can reuse your code to target other platforms. The first things you need so we can get started is:

• The Windows Phone SDK (This will install everything you need to develop a Windows Phone Application. Incl. Visual Studio if it isn’t installed on your computer.)
  http://www.microsoft.com/download/en/details.aspx?id=27570
• The PhoneGap SDK (The 1.6.0 is already released, but I had some issues with it so I recommend to use the 1.5.0 version for now)
  https://github.com/phonegap/phonegap/zipball/1.5.0
  • The above link is an zip file. When downloaded, extract this file
  • In the extracted folder, navigate to phonegap-phonegap-<xxx>/lib/Windows and copy the following files:

Cordova-1.4.1-Custom.zip
Cordova-1.4.1-Starter.zip
Cordova-1.5.0-Custom.zip
Cordova-1.5.0-Starter.zip

• Navigate to C:\Users\<UserName>\Documents\Visual Studio 2010\Templates\ProjectTemplates\Silverlight for Windows Phone and past the files of the previous step in here. (If the folder Silverlight for Windows Phone doesn’t exist, Create it)

Now, when we start up Visual Studio, we will see the PhoneGap templates appear under the Silverlight for Windows Phone folder.

Developing A phoneGap Application

Now everything is installed, we can start to develop our application. I’ll choose for the Cordova-1.5.0-Starter, this way I’m using the almost latest version of PhoneGap and the framework is already referenced. This will result in the follow structure.

In the GapLib folder we will find a dll. This dll is used to provide access to the native features of the phone. This way we can call for example the camera trough the PhoneGap JS framework. This framework is present in the www folder. This is the API we will use in our application.

All files we want to use in out PhoneGap application need to be added to the www folder. When the PhoneGap application starts up, the first thing it will look for is the index.html file. So make sure it’s always present in the www folder. One of the first lines in the index.html file is the following:

   1: <meta name="viewport" 

   2:       content="width=device-width

   3:              , height=device-height

   4:              , initial-scale=1.0

   5:              , maximum-scale=1.0

   6:              , user-scalable=no;" />

his makes sure the application is always shown maximized and uses the whole view port.

If you want to make use of the PhoneGap functionalities, you can do this once the device ready has fired. This event gets triggered once all PhoneGap functionalities are loaded.

   1: document.addEventListener("deviceready",onDeviceReady,false);

   2:  

   3: // once the device ready event fires, you can safely do your thing!

   4: function onDeviceReady()

   5: {

   6:     console.log("Device ready, you can now access the PhoneGap library.");

   7: }

Deploying to other platforms

You have two ways to deploy your HTML5 application to other platforms. One is to install the environments of the other platforms and including your www folder in the PhoneGap template of the other platform or use the PhoneGap build service. In both cases you need to make sure the Cordova.js file of the specific platform is referenced. This means if you include the www folder of your windows phone application into the template of an android application, you need to use the Cordova.js file which is provided by the template and not the one you used for Windows Phone)development. If you do so, you will notice the device ready event will not fire and the PhoneGap functionality won’t work. If you are working with jQuery mobile, you can get page navigation error when navigating with jQuery mobile.

When using the PhoneGap build service, the first thing you need to do is creating an account. Once you have this, you can create an new application. Here you need to provide the following:

• The name of the application


• Choose upload an archive or index.html file


• The file you need to provide is a zip of your www folder where your application is present. Note: make sure the Cordova.js, Cordova-1.5.0.js or phonegap.js file aren’t present in the zip. Otherwise the correct version of these files for the specified platform, aren’t included. In that case, your application might not work on the other platforms.


• When the file is uploaded and you click on create, you can let the build service do his magic. After some minutes, you will have the possibility of downloading the packages for the other platforms.

The build service supports the following platforms:

• iOs


• Android


• Windows Phone (very recently)


• Blackberry


• webOS


• Symbian

 

Conclusion

The PhoneGap API makes it easier to build your native mobile application once (in HTML) and deploy it to multiple platforms. This is a cheap way if you want to provide native apps in several platforms whiteout building it from scratch in his native language. Of course, you can’t expect that the PhoneGap has the same performance as your real native app would have. Also not all functionality is fully supported on every platform, so make sure you check this before implementing it in your application.

The last thing I want to point out is the experience you get of this kind of application. Because this targets multiple platforms, it can’t provide the platform specific experience like transitions when navigating, the styling, … This is one of the compromises you need to make if you want to reuse your code.

CRUD operations with WCF Ria Services, Upshot and Knockout

In my previous post, I showed you how to retrieve data with upshot using WCF Ria Services. Today I’m extending this example with simple CRUD operations, including validation. If you want to see this sample in action, I have added it to codeplex. You can find it here.

Server side

We will start at the server side, because this needs the least adjustments. Just like the Silverlight client, you can use the CUD operations by the naming convention (“InsertClassname”, “UpdateClassename” or “DeleteClassname”). Or by using the “insert”, “update” or “delete” attribute on the corresponding attributes. In my example I have done both. Once all this is done, the server side is configured.

[Insert]

public void InsertTodoItem(TodoItem todoItem)

{

    // Insert code

}

[Update]

public void UpdateTodoItem(TodoItem todoItem)

{

    // Update code

}

[Delete]

public void DeleteTodoItem(TodoItem todoItem)

{

    // Delete code

}

Client side

All changes made on the client side are by default immediately persisted to the server, however the upshot framework provides a way to buffer the changes. These changes will only be persisted to the server when the commitChanges method is called. If you want to undo the changes you made, you can call the revertChanges method. This way the situation will be the same as the last commit of the data. If you want to use the buffer functionality, you can do this by putting the bufferChanges property on true in the data source configuration object.

upshot.dataSources.GetTodoItems = upshot.RemoteDataSource({

    providerParameters: { 

        url: "/Ria4HTML-Services-TodoItemDomainService.svc",

        operationName: "GetTodoItems" 

    },

    provider: upshot.riaDataProvider,

    bufferChanges: true,

    entityType: "TodoItem:#Ria4html.Models",

    mapping: TodoItem

});

In the data source configuration object, we also need to provide an entityType and a mapping if we want create new entities on the client side. The mapping contains a JavaScript object that is represents the viewmodel for creating a new entity of the provided entityType. The entityType contains the classname + namespace of the objects on the server side. (Naming convention: <Classname>:#<namespace>)

function TodoItem(properties) {

    var self = this;

    properties = properties || {};

    self.TodoItemId = ko.observable(properties.TodoItemId || 0);

    self.Title = ko.observable(properties.Title);

    self.IsDone = ko.observable(properties.IsDone);

    upshot.addEntityProperties(self); // add properties managed by upshot

};

Todoitem is an example of a mapping object. The only thing we need to do to allow entity tracking, is adding the entity to upshot. This is done by calling the addEntityProperties method with the viewmodel as parameter. When this is done, the entity will be known in upshot and will be persisted to the server when saved.

Now we can start building up our viewmodel

function TodoItemViewModel(dataSource) {

    var self = this;

    self.dataSource = upshot.dataSources.GetTodoItems.refresh();

    self.localDataSource = upshot.LocalDataSource({ 

            source: self.dataSource

          , autoRefresh: true 

    });

    // Public data properties

    self.todoItems = self.dataSource.getEntities();

}

This was the situation we currently have when we just want to retrieve data. So lets start implementing our CUD operations.

Inserting Data

The first thing we will do if we want to start inserting data is adding a new instance of the mapping viewmodel to the TodoItemView model.

// Creates a new TodoItem and adds it to the viewmodel

self.newTodoItem = ko.observable(new TodoItem());

// Not possible on the localDataSource only on the remote

self.validationConfig = $.extend(

    {}

  , self.dataSource.getEntityValidationRules()

  , { submitHandler: handleSubmit}

);

var handleSubmit = function () {

    // Add new TodoItem to data source

    self.todoItems.unshift(self.newTodoItem()); 

    // Revert form to blank state

    self.newTodoItem(new TodoItem());     

}

Next, we add a validationConfig to the viewModel, this way we can enable client validation. The extend method of jQuery is used to merge multiple objects into the object provided in the first parameter. In this case we are merging the validation rules and an success handler. When using upshot, the rules of validation are added in the metadata and will be retrieve by calling the getEntityValidationRules method on the data source with the data.

If all validations are satisfied the submit handler will get called. In here we will add the new created object (values are filled up due the 2way binding of knockout). to the TodoItem collection of the viewmodel. Next we need to instantiate the newTodoItem property again with a new instance of TodoItem.

Now all the logic is implemented for inserting data, the only thing left to do is adding a view for inserting the data. Note that the autovalidate attribute has to be set on true for every field you want to validate. If you don’t enable this, you will have to call the validate method on each field manually.

<form data-bind="validate: validationConfig, with: newTodoItem">

    <fieldset>

        <table>

            <caption>TodoItem Information</caption>

            <tr>

                <th>Title</th>

                <td><input data-bind="value: Title, autovalidate: true"

                           name="Title" /></td>

            </tr>

            <tr>

                <th>Is done</th>

                <td><input data-bind="checked: IsDone, autovalidate: true"

                           name="IsDone" type="checkbox" /></td>

            </tr>

            <tr>

                <th>Action</th>

                <td><button class="addButton" type="submit">add</button></td>

            </tr>

        </table>

    </fieldset>

</form>

Important: If you want to use validation in combination with RIA services without manually providing the metadata, then you can only apply the binding when the data from the server is retrieved. If you don’t do this, no validation rules will get found when the validationConfiguration object is created. This way the validation rules will always be satisfied (since there are none) and the new entity will be added. So the solution is to provide a success callback on the refresh of the data source.

// necessary for validation

upshot.dataSources.GetTodoItems.refresh({}, function () {

    ko.applyBindings(new TodoItemViewModel());

});

UPDATING DATA

Since we use knockout.js for databinding all changes will be detected automatically and upshot will make sure the entitystate is adjusted as we start changing the entities. 

Removing data

Removing data is done by calling the deleteEntity method on the data source. For this we need to pass the entity we want to delete as parameter. On our view model we can provide a method for handling the delete of an entity

// Public operations

self.removeTodoItem = function (todoItem) {

    self.dataSource.deleteEntity(todoItem);

};

In our view we can then add a button that will handle the deletion of the item. By binding the removeTodoItem function on the parent, the current todoItem will be passed as parameter and will get deleted.

<ol data-bind="foreach: todoItems">

    <li>

        <strong data-bind="text: Title"></strong>

        <button class="removeButton" 

                data-bind="click: $parent.removeTodoItem">remove</button>

    </li>

</ol>

If you are working in buffermode, the entity will still appear in the list. This is because the entity is only deleted on the data source, and will only disappear when you save the changes. If you want to have it disappear immediately, you will have to provide a filter.

BufferMode

The last thing I want to add is how to manually commit or revert changes when the bufferMode is on. This is done by calling the commitChanges or revertChanges method on the data source. In the viewmodel we can provide to methods who enable this functionality

// Operations

self.saveAll = function () { self.dataSource.commitChanges() }

self.revertAll = function () { self.dataSource.revertChanges() }

In the view we can then add 2 buttons to save/revert our changes.

<button data-bind="click: saveAll">Save all</button>

<button data-bind="click: revertAll">Revert all</button>