kristofdegrave

Build automation: Merging and minifying JavaScript files with Ajax Minifier

2012-12-12T06:17:51-08:00

In my Library I have come to the point where it is gets harder and harder to maintain it. I' am currently over the 3000 lines, so it got time to split up my library in separate files and divide it in logical groups. After splitting everything up in separate files, I was looking for away to merge all these files into one file and have the option to minify it. This is also a step I wanted to make, so my lib could get more and more mature. The last thing I wanted was to integrate it with visual studio – which is my IDE that I’m using to develop the library – and be portable. With that last thing I mean I didn’t want to install something on my machine to do the magic.

After some searching I choose the Microsoft Ajax Minified. It comes in a nuget package which makes it easy to install. Next to that it integrates smoothly with visual studio using MS Build Tasks. This means it will merge and minify the files every time I build the project. There is only a little disadvantage where I will start with.

Set-up Ajax minifier

To start, the first thing we need to do after installing the nuget package, is adding the following files to your project (I have added a new folder Build to add them in.)

AjaxMin.dll
AjaxMinTask.dll
AjaxMinTask.targets

All these files can be found in the tools/net40 folder in the nuget package folder of the Ajax minifier

<folder where the solution is located>\packages\AjaxMin.<version>\tools\net40

The disadvantage of this way of working is that you need to copy the above files when getting the latest version of the Ajax minifier from nuget.

The last thing you need to do is editing the .csproj file so it will use the added build task. You can do this by unloading the project. (right click on the project –> Unload project)

Once you have done this, you can right click on your project and choose for edit <project name>.csproj

This will open an XML file containing information about the project. At the end of the file before the project closing tag, you must add the following line.

<Import Project="$(MSBuildProjectDirectory)\Build\AjaxMinTask.targets" />

Save this file and right click on the project again and choose for Reload Project. This will load the project again with the modifications.

Ajax minifier manifest File

Once all this is done, we can add an Ajax manifest file. In this file we can declare which files must be merged and minified. Also we declare the location where these files must be saved. Optionally we can provide some arguments to overwrite the default behavior. More information about the arguments can be found here. Note that these arguments are the same as the arguments you can provide when working with the command line tool.

The location of this manifest file doesn’t matter, but the extension needs to be “.ajaxmin”. For my library I have put this file also in the build folder where all the Ajax minifier files are located. You can also provide multiple output tag so you can create for example a minified and a non minified file.

Bellow you can find an example of an Ajax manifest file.


<?xml version="1.0" encoding="utf-8" ?>
<root> 
  <output path="Scripts\output.js">
    <arguments>-clobber -pretty</arguments>
    <input path="file1.js"/>
    <input path="file2.js"/>
  </output>
</root>

The arguments I am providing are “-clobber” to overwrite files even when they are flagged read-only, “-pretty” this provides a nice formatted JavaScript file that is readable. (not minified)

By default the output files will be added to a content folder in your project (must exist or you will get an error.) If you want to determine the path in your manifest file, then you need to change the AjaxMinTask.targets file we added in the first part. This is also an XML-file containing the build task definition.

In this file you will find a tag called “AjaxMinManifestTask”. On that element you have several attributes and the one we need is Output Folder. In my case the value of it is “$(ProjectDir)”. With this I can address the location in my manifest file starting from the root of my project. As said earlier: the only thing you need to keep in mind is that the folder structure must be present.

When all this is done, the only thing you need to do is build the project, and the files will get created.

Conclusion

Working with the Ajax Minifier gives you a lot of options for minifying and merging your JavaScript files. Next to that it can also minify CSS files. And as seen above with some work you can easily integrate it into the build of your project.

Programming in HTML5 with JavaScript and CSS3 Specialist

2012-11-22T09:48:00-08:00

As of today, I am a Programming in HTML5 with JavaScript and CSS3 Specialist. I took the 70-480 exam and passed with a score of 760. Tough I already have quite some experience with HTML5 and JavaScript, the exam was tougher than I expected. That is why I wanted to make this post so every who is thinking about doing this exam gets a head start. Also every one who wants to do the exam, can do this for free until 31/03/2013. More information about this you can find here.

To start, Microsoft provides a one day online course to prepare for the 70-480. This course can be found on the Microsoft virtual academy. On that site you can find courses for several technologies. These courses are divided into several modules and every module has a survey you can take when you completed the resources provided. This is a good starting point if you want to study for the 70-480, but it is certainly not enough. The course is too brief.

If I look back at the exam, jQuery is very important. In a lot of questions jQuery was used in the code examples and solutions. So make sure you know how jQuery works and how to use it. Also a great part of the questions handled about AJAX request. It is definitely worth to inspect the AJAX implementation of jQuery with all its options and events. I got several questions about it.

A second great part of the questions handled about forms and validations. Make sure you know how regular expressions work. I had at least two questions that handled about choosing the right regex. And to complete the HTML5 element part I got some cases in which I note which HTML5 structure element I should use.

The questions about CSS handled the most about positioning, the box model, display modes, media queries and selectors.

The last part was about JavaScript with the focus on the object oriented aspect and closures. It is also a important to know how event handling works in JavaScript. For the API’s the most important ones are Web workers, local/session storage. It is good to know how they work and how you can use them.

For every one who takes the challenge, I wish you good luck and I hope I provided some useful hints.

IndexedDBViewer: Take a look inside your indexedDB

2012-11-14T03:02:12-08:00

Some days ago I released a new version of the IndexedDBViewer 1.1.0. The IndexedDBViewer is intended for web developers who want to sneak into their indexedDB database. It allows you to inspect the structure of your database as well as the data stored inside this structure. The difference with the previous version is that it no longer needs the jQueryUI library. This way I eliminated at least one reference. The following references are still necessary:

jQuery (version 1.8.2 or higher)
linq2indexedDB (version 1.0.19 or higher)
indexedDBViewer (1.1.0 – JavaScript + css file)

If you are using nuget, you can get all the resource by searching for the indexedDBViewer.

The second major change is that the viewer can easily be added to an existing page. The only thing you need to do is add a div with “indexedDBViewer” as id and data-dbName attribute to pass the database you want to inspect. The rest will be handled by the script in the viewer

   1: <div id="indexedDBViewer" data-dbName="database name"></div>

Once this is done and you navigate to the page with the viewer, you will get the following result

In the bottom you will see the view appear. On the left pane you get an overview of the database structure. This a list with on top the name of the database. Under that you will find child nodes that represent the object stores present in the database. If we descend an other level we can see the indexes present on the object store. If you click on the “+” or “-“ next to the names, you can expand or hide the structure beneath.

If you click on the database name in the navigation pane, you will get information about the database and it’s structure.

In the general block you will see the name of the database and the version it is currently in
The object stores block gives you an overview of all the object stores present and how they are configured.
The indexes block shows all the present indexes and how they are configured.

When you click on one of the object store names in the navigation pane, you will get all the data present in the object store. Because the data is saved as a key/value pair, you will see the key with his corresponding value. If the value is an object or contains objects, then you can inspect them by clicking on the “+” to expand and “-” to hide the details.

If you click on one of the index names in the navigation pane, you will get – similar as for object stores – all the data present in the object store. But in this case you will see a little more. Besides the key of the index and the value you will see the key the value has in the object store. This can be found under the “primary” key column.

As last there are some little extra features:

If you click on the top border of the viewer and drag it up or down, then you can change the height of the viewer.
if you click on the “-” in the right top of the viewer, you can hide the viewer. If you want it to appear again, then you have to click on the “+” on the right bottom of the page.

Conclusion

With this Chrome like indexedDBViewer you can inspect the structure of your database inclusive all data stored within it. This with the advantage that it runs inside the browser, so you can use it cross-browser.

IndexedDB: MultiEntry explained

2012-11-14T03:09:33-08:00

For a long time I was not sure what the purpose of the multiEntry attribute was. Since non of the browsers supported it yet, but since sometime Firefox and even the latest builds of Chrome support it, it all came clear to me. The multiEntry attribute enables you to filter on the individual values of an array.For this reason, the multiEntry attribute is only useful when the index is put on a property that contains an array as value.

When the multiEntry attribute is on true, there will be a record added for every value in the array. The key of this record will be the value of the array and the value will be the object keeping the array. Because the values in the array are used as key, means that the values inside the array need to be valid keys. This means they can only be of the following types:

Array
DOMString
float
Date

So far for the theory, an example will make everything clear.

In the example below I will use an object Blog. A blog contains out of the following properties:

   1: var blog = { Id: 1   2:            , Title: "Blog post"   3:            , content: "content"   4:            , tags: ["html5", "indexeddb", "linq2indexeddb"]};

In the indexeddb we have an object store called blog which has an index on the tags property. The index has the multiEntry attribute turned on. If we would insert the object above, we would see the following records in the index:

key	value
“"html5”	{ Id:1, Title: “Blogpost”, content:”content”, tags: [“html5”, “indexeddb”, “linq2indexeddb”]}
“indexeddb”	{ Id:1, Title: “Blogpost”, content:”content”, tags: [“html5”, “indexeddb”, “linq2indexeddb”]}
“linq2indexeddb”	{ Id:1, Title: “Blogpost”, content:”content”, tags: [“html5”, “indexeddb”, “linq2indexeddb”]}

So for every value in the array of the tags attribute, a record is added in the index. This means when you start filtering, it is possible that the same object can be added to the result multiple times. For example if you would filter on all tags greater then “i”, the result would be 2 times the blog object I use in this example.

Promises: jQuery deferred object vs WinJS Promise

2012-08-09T00:45:25-07:00

When I was adjusting my Linq2IndexedDB library to enable Windows 8 development, I had some little issues porting the jQuery promises to WinJS promises. In this post I will show you some differences I had issues with and how I fixed them.

Passing context

The first problem I ran into: WinJS promises doesn’t support passing a context. Because I don’t take advantage of the context yet, this wasn’t an issue for me yet. I easily solved it by writing a wrapper around the 2 promises. In case of the jQuery promise, the context gets passed. And in case of the WinJS promise, I just ignore it for the moment and hope it will get implemented in the future.

   1: function promiseWrapper(promise) {   2:     if (isMetroApp) {   3:         return new WinJS.Promise(function(completed, error, progress){   4:             promise({   5:                 complete: function (context, args) {   6:                     completed(args);   7:                 },   8:                 error: function (context, args) {   9:                     error(args);  10:                 },  11:                 progress: function (context, args) {  12:                     progress(args);  13:                 }  14:             });  15:         });  16:     } else if (typeof ($) === "function" && $.Deferred) {  17:         return $.Deferred(function (dfd) {  18:             promise({  19:                 complete: function (context, args) {  20:                     dfd.resolveWith(context, [args]);  21:                 },  22:                 error: function (context, args) {  23:                     dfd.rejectWith(context, [args]);  24:                 },  25:                 progress: function (context, args) {  26:                     dfd.notifyWith(context, [args]);  27:                 }  28:             });  29:         }).promise();  30:     }  31: }

Passing multiple parameters

A second problem I had was the fact that the WinJS only allows one argument to be passed when calling a complete, error or progress callback. Because I needed to pass multiple values in my library, I needed to rewrite every complete, error and progress method I called. Instead of just passing multiple arguments to the callback methods, I needed to wrap the arguments into an array so they could be passed as single argument.

But that wasn’t enough. Because the jQuery promise is smart enough to convert an array of arguments into a callback with multiple arguments, I needed to wrap the array of arguments into an other array (If you look in the sample above, you will see in case of the jQuery promise, brackets (‘[]’) were added around the args argument.). I needed to do this, because it was the only way to get the same signature when working with the WinJS & jQuery promise.

   1: promiseWrapper(function (pw) {   2:     pw.complete(context, [arg1, arg2]);   3: });

Progress Event Doesn’t fire in Winjs promise

The last issue I suffered was the fact that a progress event in didn’t fire in some cases. After a little investigation, I came to the conclusion that I was calling the progress event, before the promise object got created. I first noticed this when I was creating a transaction on the IndexedDB API. When a transaction was created, I fired a progress event with the transaction data. In other methods, where I needed the transaction, I used this the progress call to execute my queries. Once the transaction was committed, the complete event got fired. Because the progress call never got called, the query was never executed. This way the transaction was immediately committed and the complete callback got called without any action taken.

To fix this I delayed the progress call a little bit. By adding a setTimeout of 1 ms I noticed my problem was solved, and my progress events got called.

   1: if (isMetroApp) {   2:     setTimeout(function () {   3:         var txn = db.transaction(objectStoreNames, transactionType);    4:         txn.oncomplete = function (e) {   5:             pw.complete(txn, [txn, e]);   6:         };      7:         pw.progress(txn, [txn]);   8:     }, 1);   9: }

Conclusion

As seen above working with the WinJS is a slice different of working with the deferred object in jQuery. But with the given workarounds, it is possible to solve the most issues. I hope that Microsoft will take a look at the jQuery deferred object in the future and add some of the jQuery capabilities (context, multiple arguments) into the WinJS promises. And hopefully the progress bug gets solved, so the ugly setTimeout can disappear in my code.

IndexedDB: Keys: efficiently retrieving data from a database

2012-08-04T04:06:38-07:00

In order to retrieve data efficiently from an IndexedDB database, each record is organized by its key. The only condition for the key is that it is a valid key. A valid key can be one of the following types:

Array (Is only valid when every item inside the array is a valid key and the array doesn’t contains it self. Also all non-numeric properties are ignored and will not affect whether the array is a valid key)
DOMString
Date (The Primitivevalue (internal property) of the date object can’t be NaN)
Float (The key can’t be NaN)

When comparing keys, the order in the list above applies. Array is greater than all DOMStrings, DOMString is greater than …

Comparing arrays is done by comparing the values inside the array (as long that both arrays got values on the position). If the values on the same position differ, then the outcome of that comparison will determine which array is greater. If the values on each position are the same, the length of the array will determine the which one is greater or equal if the arrays have the same length.

Complex Keys

The IndexedDB API also support complex keys. This are keys who refer to properties nested inside an object. This way you are able to filter on data that is available are properties of a nested object. In the example below we have an person object. Besides a name and firstname property it contains an address property. This address property is also an object containing properties like city, street, … If we want to filter data on its city we can do this by defining a key like this “address.city”.

   1: var person = {   2:     name: "name",   3:     firstname: "firstname",   4:     address: {   5:         street: "street",   6:         city: "city"       7:     }   8: }

Since Linq2IndexedDB 1.0.11 this is also supported for all filters, even for filters that don’t take advantage of the IndexedDB API. For this reason it is advised to use the linq2IndexedDB.prototype.utilities.getPropertyValue method to determine the value by it’s property name. Two arguments need to be provided:

first argument is the object containing the data
second argument is the propertyName string. For example “address.city”

The return value of the method is the value at this location if it exists, otherwise undefined will be returned.

Note that this nesting only works for objects. If the property contains an array of objects, you won’t be able to use this way to filter your data.

Object store keys

Inside an object store, keys even have a more special reason of existence. In here keys are used to uniquely identify an object. This means you can never add an object twice with the same key, but this enables you to update and delete objects when you know it’s key. For an object store, there are 2 ways you can provide a key:

Inline key: the key is present inside the object (A KeyPath must be defined on the object store)
External key: the key is provided separately (in most cases the value of the key/value will be a primary type like a string or float)

In both cases you can choose for the option to let the key be generated by the IndexedDB API. You can do this by setting the object store autoIncrement attribute on true when creating the object store. In this case the key will have a numeric value.

Index keys

The keys in for an index are always defined by a KeyPath. These keys can be complex keys as defined in the section “Complex keys” above. Every object in the object store keeping the index that has a value for the key path a record will be added. The key will be the value of the property defined by the key path. For example we have a keyPath “firstname”. In the example below, the key in the index record would be “Kristof” and the value the person object.

   1: var person = {   2:     name: "Degrave",   3:     firstname: "Kristof"   4: }

In the index you can also have 2 special cases. The first one is the unique attribute. This will make sure, that a value for this keyPath can only be defined once in a value of the object store. This constraint will be checked when you add data to an object store. If there is an object present with the same value for that property, an ConstraintError will be thrown.

A second attribute is the multiEntry. This allows to have multiple values for only one key. In stead of adding a new record for every object with the same value, the key is only added once and all the objects that have same value are added to a collection.

Conclusion

Now you should have insight how the keys work inside the IndexedDB API. With the complex keys you will be able to filter on data with nested object, this way you don’t need to provide an object store for every object you want to store. Also the Linq2IndexedDB framework also supports these complex keys and you can even use them in your custom filters.

Linq2IndexedDB: Debugging IndexedDB

2012-08-02T00:52:00-07:00

In my latest version of the Linq2IndexedDB 1.0.7, I added the viewer object. This object allows you to inspect your IndexedDB database and gives you an overview of all the object stores and indexes that are present. It even gives you details about how they are configured and what data they contain. Also using this, you can take a look at your database in various debugging tools like:

Google Chrome Developer tools
Firefox Developer tools
IE Developer tools
Visual Studio

The viewer object contains 4 properties:

configuration: In here you will find the way the Linq2IndexedDB framework is configured. (The same properties as you can define in the configuration object are present + a property indicating if framework is running in auto create mode.)
name: The name of the IndexedDB database
objectStores: A collection of all the object stores that are present in the database
version: The current version of the database

Inside an object store object, we can see the following:

autoIncrement: indicates if the keys for the object store are generated by the IndexedDB API
data: A collection of all the data available in the object store. These data objects are shown as key/value pair objects.
indexes: A collection of all the indexes available on the object store.
keyPath: The property inside the object that keeps the key
name: The name of the object store

The last level we can take a look at, are the indexes. The following information will be provided:

data: A collection of all the data available in the object store. These data objects are shown as key/value pair objects.
keyPath: The property inside the object that keeps the key
multiEntry: Determines if a key is only once defined in the index (which means the value keeps an array of all the values in the object store who match) or the key can be present multiple times (once for every value that matches in the object store.)
name: The name of the index

conclusion

I hope this debugging information can help you speed up your software development and finding bugs while working with the IndexedDB API. The latest version of the framework can be found on codeplex, nuget and MyGet.

Update 28/07/2012

I added a new version of the framework, because there were some little bugs with the viewer. The following things change:

The viewer no longer blocks the deletion or upgrade of the database
The viewer now gets updated when the structure of the database changes
The viewer is default disabled for performance issues. If you want to enable it, add true as 3th argument on the function to create a linq2indexeddb function

   1: var db = $.linq2indexedDB("test", null, true);

Linq2IndexedDB: Custom filters

2012-07-13T13:48:16-07:00

Since the 1.0.5 version of the Linq2IndexedDB framework, I added support for custom filters. And since the 1.0.6 version (released last week) you can add a function to the where clause to filter your data. These functionalities are provided by the framework, because the IndexedDB API only provides a handful filter possibilities. Also you can only use one filter when retrieving data.

Create a custom filter

To create a custom filter, the Linq2IndexedDB framework has an addFilter method. This method can be found in the linq namespace and accepts 3 arguments.

The first argument is a name for the filter, this name will be used when you want to use your filter. Make sure that this name is unique over all the filters, if not an exception will be thrown.
The second argument is a function that will be used to determine if the data is valid or not. When this function gets called 2 arguments will be passed. The first one is the object to validated. The second one is filter metadata. For example this object contains the name of the property you need to filter on, or an additional value provided, … The result of this function must be a Boolean value telling if the provided object is valid or not.
The last argument is also a function and will be used to retrieve additional filter metadata. This function must return a new function with optionally arguments to retrieve the additional in formation. For example this information can be one or more values to use in the IsValid function. When called 3 arguments are passed to this function. The first one is a callback function that needs to be the return value of the function to retrieve the information. The second argument is the queryBuilder object that needs to be passed to the callback method. The third argument is the filterMetaData object. The additional information you retrieve, needs to be added to this object so you can use it later on in the IsValid method. After this is done, this object must also be provided as argument to the callback method.

In the code below I added an example of an equals filter.

   1: linq2indexedDB.prototype.linq.addFilter("equals", function (data, filter) {   2:     return data[filter.propertyName] == filter.value;   3: }   4: , function (callback, queryBuilder, filterMetaData) {   5:     return function (value) {   6:         filterMetaData.value = value   7:         return callback(queryBuilder, filterMetaData);   8:     }   9: });

When all this is done, you can start using this filter just by calling it after the where, or and and method call.

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

Anonymous filters

An other way to add a custom filter is by adding a callback function to the where, or or and method. When this callback function gets called, the object you need to validate is passed as an argument. The result of the callback function must be a Boolean value determining if the object is valid or not

   1: db.linq.from("objectStore").where(function (data) {   2:     return data.Age > 3;   3: }).and(function (data) {   4:     return data.Age < 10;   5: }).select();

conclusion

In the Linq2IndexedDB framework, you now have 2 ways to add custom filters. In the case you use the addFilter method, you can add a custom filter that can be reused and will appear in intellisense so you can easily call it. The other way provides an easy only once use of a filter. In both cases you are now flexible to provide your own filtering.

JSON: serialize and deserialize functions in JavaScript

2012-07-06T04:57:50-07:00

In my Linq2IndexedDB project, I take advantage of the web workers to do all the filtering that the IndexedDB API doesn’t allow (multiple filters, like, inArray, …). For all these filters I have an “isValid” method which determines if the data satisfies the condition. So when I want to use these methods in my background worker, I need to make sure I can call them. For that I have 3 possibilities

Add a copy of all the filters in my background worker file
Include the file where my filters are defined
Serialize and deserialize the “isValid” functions

The first one wasn’t an option for me, because i wanted to keep all filter logic at one place. The second one was an option, but I didn’t want to use multiple JavaScript files for my library. And an other reason why I don’t like the first 2 is because developers would have to change my library if they want to add additional filters. So this left me only with the third possibility.

For this I’ve done some research. I already knew that you could call .toString on a function and this would result into a string representation of the function. And with the Function.call method I would be able to call the function in my background worker. But I didn’t wanted a solution that had to call the Function.call method in the background worker, I wanted to use the .isValid method that was provided in the filter objects. So I dug into the JSON API and found the following solution.

Serialize Objects

The JSON.stringify (the method that turns JavaScript objects into JSON text) accepts 2 arguments. The first argument is the object you want to turn into a JSON text and the second argument accepts a replacer function. This function gets called for every value in the object structure (even for properties in child objects) and accepts a key (name of the property) and a value (the value of the property) argument. The return value of the object is the object that will be stringified. By using this function, I can return the string representation of the function (in case of function) and return the value in the other cases.

   1: JSON.stringify(filters, function (key, value) {   2:     if (typeof value === 'function') {   3:         return value.toString();   4:     }   5:     return value;   6: });

deserialize objects

The next thing we want to do, is deserialize the function again. Like the stringify method, the parse method (returns a JSON string into a JavaScript objects) also a callback (reviver) method as second argument. This method also gets called for every key and value for every level of the result. In this callback you can reform generic objects into instances of pseudo classes, strings into dates, strings into functions, …

   1: JSON.parse(filtersString, function (key, value) {   2:     // reform your objects here   3: });

Once I have the string representation of the function, I can start rebuilding that function. This is done by creating a new Function Object. The constructor of the Function objects accepts 2 arguments, a list of arguments for the function you want to create and the string representation of the body of the function you want to create.

   1: new Function(arguments, functionBody);

So if we put those 2 together we get the following:

   1: JSON.parse(filtersString, function (key, value) {   2:     if (value    3:         && typeof value === "string"    4:         && value.substr(0,8) == "function") {   5:         var startBody = value.indexOf('{') + 1;   6:         var endBody = value.lastIndexOf('}');   7:         var startArgs = value.indexOf('(') + 1;   8:         var endArgs = value.indexOf(')');   9:    10:         return new Function(value.substring(startArgs, endArgs)  11:                           , value.substring(startBody, endBody));  12:     }  13:     return value;  14: });

Detecting if the value is a function, is done by checking if the value is a string and starts with the word ‘function’. If this is the case, we will determine the arguments and the function body so we can pass it to the Function constructor. Retrieving the arguments of the new function is done by taking the string value between the first ‘(‘ and ‘)’. Retrieving the function body is done by getting the string value between the first ‘{‘ and the last ‘}’. Passing these 2 values to the constructor of the function will create a new function. This is the value that gets returned in case of a function. In all other cases we just return the value.

Conclusion

By using the stringify and parse method of the JSON API you can provide a generic way to serialize and deserialize your objects. Serializing functions can easily be done by calling the toString method on the function and deserializing a function can be done by using the Function constructor which is present in the JavaScript language.

Linq2IndexedDB: Release 1.0.3

2012-06-10T00:32:30-07:00

This weekend I released a new version of the Linq2IndexedDB. The major changes in this release is a broader support of browsers. Because of the release of a new version of the IndexedDB spec some changes were made. The biggest change of them all is the transactionType. In previous versions this was a number (READ_ONLY = 0, READ_WRITE = 1, VERSION_CHANGE = 2), but this has changed into string values (“readonly”, “readwrite”, “versionchange”). Also these values aren’t available any more under the IDBTransaction interface.

Since this release the Linq2IndexedDB library now also supports browsers that doesn’t implement the IndexedDB specification yet. The only condition is they support the obsolete WebSQL spec. This means that Opera and Safari are now supported by the Linq2IndexedDB due the IndexedDB shim written by nparashuram who is also a contributor to the Linq2IndexedDB project.

With the release of the Windows 8 Release Preview, a new version of Internet Explorer 10 was released. Next to the change I described in the beginning of this post, IE10 Release Preview now uses the window.indexeddb implementation and no longer uses the ms prefix (window.msIndexedDB). The only disadvantage is they do not implement the autoIncrement and multiEntry attribute yet.

Next to the changes made to the Linq2IndexedDB library, I’ve started building on a new project: an IndexedDBViewer. This allows you easy access to the database structure and the contents of the object stores. The only thing you need to provide is the name of the IndexedDB you want to inspect. The only thing you need to keep in mind is that this IndexedDB viewer must be added to the Web app. This is necessary because you can only access the IndexedDB databases defined within your origin (domain).

All these changes are now available on MyGet:

and on NuGet:

All the sources of these projects can be found on CodePlex.

Using LINQ to Indexed DB

2012-05-11T13:37:46-07:00

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:

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

2012-04-26T05:26:38-07:00

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:

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

2012-04-08T00:36:27-07:00

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 viewmodelself.newTodoItem = ko.observable(new TodoItem());// Not possible on the localDataSource only on the remoteself.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 validationupshot.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 operationsself.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

// Operationsself.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>

Upshot.js & knockout.js: The HTML5 client for WCF RIA services

2012-04-13T13:23:04-07:00

As Microsoft is leaving the Silverlight track and more and more focusing on HTML5 for cross browser support, solutions are coming for several existing frameworks. One of the things I’ve been looking at is the possibility to reuse your existing RIA services ,who you currently use for your Silverlight application, and port them to HTML5 enabled website.

The HTML client for ria services started as an jQuery plugin called Ria.js. Currently this project is hosted into the ASP.NET Single Page Application. This is a new project template for building single page applications. The advantage of these kind of application is that they run completely in the browser, this way it’s pretty easy to enable your application to be used offline.

The JS client framework used for communicating with the server is Upshot.js. This framework provides a rich context for the object used on the client side, this includes change tracking, paging, sorting, … More information of this subject can be found on the Denver Developers blog. If you prefer watching a live demo, Steve Sanderson gave one at TechDays Netherlands.

While searching on the net for some more information, I noticed that the most examples focus on the use of Web API for communication with the server. Next to the standard Web API provider for upshot, there is also support for RIA and OData. Since my post is handling RIA services, I‘ll be handling the riaDataProvider.

Building a live demo

Perquisite:

VS 2011 beta: http://www.microsoft.com/visualstudio/11/en-us/downloads
WCF Ria Services V1.0 SP1: http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=28357
WCF Ria Services SDK: http://www.microsoft.com/download/en/details.aspx?id=26939

So lets get started by creating a new MVC4 project:

If we press the OK button, we can choose which MVC4 project template we want to use. In our case we choose for the Single Page Application.

This template includes already some models, controls and views, but when we open up the scripts folder, we will see the script references for upshot.js, knockout.js, … Everything we need for building an HTML5 application with a rich context. But these frameworks evolve fast and thank god we have a thing called Nuget so we can easily update to the latest version. So this will be the next step in my tutorial, updating to the latest version of the single page application. Search for SinglePageAppliction in your Nuget packet management explorer or type the following in your package manager explorer:

Install-Package SinglePageApplication.CSharp

Once this is done, we need to add the reference to the ServiceModel so we can use the domainService class of the RIA services. The following references need to be added (note that these references come from the latest version of the WCF Ria Services SDK V1, C:\Program Files (x86)\Microsoft SDKs\RIA Services\v1.0\Libraries\Server):

System.ServiceModel.DomainServices.Hosting
System.ServiceModel.DomainServices.Server

And one reference from the SP2 of the WCF Ria Services SDK V1, C:\Program Files (x86)\Microsoft SDKs\RIA Services\v1.0\Toolkit\Libraries\Server\SP2\

Microsoft.ServiceModel.DomainServices.Hosting

After adding the references, we need to configure our DomainServices. First thing we need to do is adding a new configuration section for the DomainService

<configSections>  <sectionGroup name="system.serviceModel">    <section name="domainServices" type="System.ServiceModel.DomainServices.Hosting.DomainServicesSection,       System.ServiceModel.DomainServices.Hosting, Version=4.0.0.0,       Culture=neutral, PublicKeyToken=31bf3856ad364e35"       allowDefinition="MachineToApplication" requirePermission="false" />  </sectionGroup></configSections>

Next we add a new httpModule for the DomainService to the system.web section

<system.web>  <httpModules>    <add name="DomainServiceModule" type="System.ServiceModel.DomainServices.Hosting.DomainServiceHttpModule,       System.ServiceModel.DomainServices.Hosting, Version=4.0.0.0,       Culture=neutral, PublicKeyToken=31bf3856ad364e35" />  </httpModules></system.web>

In the system.webServer section, we add a new module for the DomainService

<system.webServer>  <validation validateIntegratedModeConfiguration="false" />  <modules runAllManagedModulesForAllRequests="true">    <add name="DomainServiceModule" preCondition="managedHandler" type="System.ServiceModel.DomainServices.Hosting.DomainServiceHttpModule,        System.ServiceModel.DomainServices.Hosting, Version=4.0.0.0,        Culture=neutral, PublicKeyToken=31bf3856ad364e35" />  </modules></system.webServer> 

As last we add the following system.serviceModel config section. Most important thing here is that we add a JSON endpoint, and on this endpoint we add the attribute transmitMetadata=”true” so the metadata is send to our HTML client.

<system.serviceModel>  <domainServices>    <endpoints>      <add name="JSON"  type="Microsoft.ServiceModel.DomainServices.Hosting.JsonEndpointFactory,        Microsoft.ServiceModel.DomainServices.Hosting, Version=4.0.0.0,        Culture=neutral, PublicKeyToken=31bf3856ad364e35"        transmitMetadata="true" />    </endpoints>  </domainServices>  <serviceHostingEnvironment aspNetCompatibilityEnabled="true"        multipleSiteBindingsEnabled="true" /></system.serviceModel>

Once all the references and configuration sections are added, we can start to code. The first thing we do is adding a new class and let it derive from DomainService.

using System.Collections.Generic;using System.Linq;using System.ServiceModel.DomainServices.Hosting;using System.ServiceModel.DomainServices.Server;using SPAWithRiaServices.Models; namespace SPAWithRiaServices.Services{    /// <summary>    /// Domain Service responsible for todo items.    /// </summary>    [EnableClientAccess]    public class TodoItemDomainService : DomainService    {        [Query(IsDefault = true)]        public IQueryable<TodoItem> GetTodoItems()        {            IList<TodoItem> todoItems = new List<TodoItem>();             todoItems.Add(new TodoItem()                 { TodoItemId = 1, Title = "Todo item 1", IsDone = false });            todoItems.Add(new TodoItem()                 { TodoItemId = 2, Title = "Todo item 2", IsDone = false });            todoItems.Add(new TodoItem()                 { TodoItemId = 3, Title = "Todo item 3", IsDone = false });            todoItems.Add(new TodoItem()                 { TodoItemId = 4, Title = "Todo item 4", IsDone = false });             return todoItems.AsQueryable<TodoItem>();        }    }}

The TodoItem Class looks as follows:

using System.ComponentModel.DataAnnotations; namespace SPAWithRiaServices.Models{    public class TodoItem    {        [Key]        public int TodoItemId { get; set; }        [Required]        public string Title { get; set; }        public bool IsDone { get; set; }    }}

Now we can go to edit the views. The first view we need to change is the _Layout.cshtml in the shared folder. In here we delete the following line:

<script src="@System.Web.Optimization.BundleTable.Bundles.ResolveBundleUrl("~/Scripts/js")"></script>

And add the following references instead:

<script src="~/Scripts/jquery-1.6.2.js"         type="text/javascript"></script><script src="~/Scripts/modernizr-2.0.6-development-only.js"         type="text/javascript"></script><script src="~/Scripts/knockout-2.0.0.debug.js"         type="text/javascript"></script><script src="~/Scripts/upshot.js"         type="text/javascript"></script><script src="~/Scripts/upshot.compat.knockout.js"         type="text/javascript"></script><script src="~/Scripts/upshot.knockout.extensions.js"         type="text/javascript"></script><script src="~/Scripts/native.history.js"         type="text/javascript"></script><script src="~/Scripts/nav.js"         type="text/javascript"></script>

In the index.cshtml in the home folder, we add the following:

The configuration for using upshot

<script type='text/javascript'>    upshot.dataSources = upshot.dataSources || {};        upshot.dataSources.GetTodoItems = upshot.RemoteDataSource({        providerParameters: {             url: "/SPAWithRiaServices-Services-TodoItemDomainService.svc",             operationName: "GetTodoItems"         },        provider: upshot.riaDataProvider,        bufferChanges: true,        dataContext: undefined,        mapping: {}    });</script>

The knockout view

<ol data-bind="foreach: todoItems">    <li><strong data-bind="text: Title"></strong>        <label>            <input data-bind="checked: IsDone" type="checkbox" />            Done        </label>    </li></ol>

And as last the ViewModel definition

<script type="text/javascript">    function TodoItemViewModel() {        // Data        var self = this;        self.dataSource = upshot.dataSources.GetTodoItems.refresh();        self.localDataSource = upshot.LocalDataSource({                                     source: self.dataSource                                  , autoRefresh: true });        self.todoItems = self.localDataSource.getEntities();    }     $(function () {        ko.applyBindings(new TodoItemViewModel());    });</script>

When you run the application now, you should see the todo items appear on your screen with a little delay.

Conclusion

In your HTML applications you can take advantage of your existing RIA services with a minimum of effort. For now the possibilities are limited, but I think in the future we will be able to use all features as they are present in SL. By adding the transmitMetadata attribute to our JSON endpoint, it isn’t necessary to define the model again on the client side.

Developing metro apps (HTML & JS): My point of view

2012-03-28T01:31:18-07:00

Last Friday I attended the first windows 8 developer day in Belgium. A great opportunity to learn a bit more about developing Metro apps. One of the demos given by Giorgio Sardo showed how easy a HTML 5 application could be copied and pasted into a Metro app without having to rework even a single line of code. At first sight this looks pretty amazing, but I got me thinking.
The first thing I noticed is the fact that the HTML 5 application was actually a game. That is one of the reasons it could be easily ported to a Metro app. If we would want to port a business app like an e-commerce site, that wouldn’t be so easy. One of the important issues when developing Metro apps is the design. The philosophy of Microsoft when designing an application is that all applications have a similar look & feel and should react on the same way.
Almost all websites are designed for a single resolution and that is in contrast with the Metro philosophy where all apps should optimize their viewport for every screen. This means you’ll have to redesign your application so it changes its content to fit to the screen. Also you should implement the capabilities to change the view depending on the position of your device (landscape or portrait mode) and the multitask options which allows you to run multiple applications side by side.
Next to the Metro design these Metro apps should at least have some specific windows 8 features like redefined search and sharing capabilities. It's only at this point you really start to take advantage of some of the new windows 8 features. But the most important thing you should implement is the live tile. This must engage the user to consume your application. You can do this by providing the user real-time information about your app.
A second consideration is the fact when you just copy and paste your web application, you don’t take advantage of all the possibilities present in WinRT. With WinRT you can make calls to the operating system. For example you can access the webcam, save a file to the file system; share data … Developing Metro apps with JavaScript also brings the WinJS namespace. In here we find the Promise object that enables an easy way for the developer to handle asynchronous calls. Because all calls that take more than 50ms are preformed asynchronous by default, this can come in handy when you are making WinRT calls.
After the theoretical part, it was time for the real work: an App-a-thon. Here we got the possibility to put all our theoretical knowledge into practice. Together with 4 RealDolmen colleagues (Maarten Balliauw, Xavier Decoster, Wesley Cabus and Angelo Trotta) we developed a metro Nuget Package Explorer. This allows the users to view NuGet repositories and their package details. All this information gets retrieved from the given feeds and gets stored in an IndexedDB for performance. The application is completely build in HTML5 and uses JavaScript for the logic.
Surprisingly, developing this application went pretty fast. I took some time to adjust to the fact your writing a client application with JavaScript, but all knowledge about JavaScript in the past, could be reused pretty easy. There was one thing we were struggling with. When working with the promises you have to be very careful to call objects in the UI-thread, otherwise you can get some strange exceptions.
Conclusion
After a whole day Windows 8, I really excited to start develop metro apps. Enabling developers to develop a metro app in HTML/JS was definitely a good choice Microsoft made. This way a whole new group of developers can start building Metro apps. But the business has to be aware that you can’t just copy and paste your web app in a Metro project and call it Metro app. Metro apps have a philosophy and that should be respected. Also it would be a shame if you wouldn’t take advantage of all the new features that Metro apps provide.
I’m looking forward to the next app-a-thon and hope that our team can come together again to win the contest this time. (Ended second last time.)
Currently I’m trying to port our Linq2IndexedDB project to use the WinJS promises instead of the jQuery promise. I hope to announce this feature in the near future.

JavaScript: Change entered character in keypress event

2012-03-10T02:13:47-08:00

Recently I came across a problem with a numeric input field. For globalization issues a decimal had to be separated by a comma instead of a dot. So there were 2 solutions in this case. I could prevent users from typing in the dot, or I could replace the dot by a comma when typed. I went for the second one, because on the numeric keypad you only have a dot. So this way it would be easier for the users to input the decimal. It also works the same as applications like Excel who change the dot to a comma to if your regional settings are set that way.

At first sight this looked like an easy chore. In most cases the keypress or keydown event gets handled and the keyCode of the dot gets blocked. Instead the comma is added at the end of the current value of the input field.

   1: // All decimal input fields have a class named 'number'   2: $('input.number').each(function (){   3:     $(this).keypress(function(e){   4:         // '46' is the keyCode for '.'   5:         if(e.keyCode == '46' || e.charCode == '46'){    6:             //Cancel the keypress   7:             e.preventDefault();    8:             // Add the comma to the value of the input field   9:             $(this).val($this.val() + ',');  10:         }  11:     });  12: });  13:  

In most cases this will do, but when users start editing the decimal, troubles arrive. When the user types a dot inside the number, the comma will be added at the end of the number. But this isn’t what the user wants. He wants to have the comma placed on the location where he type the dot. After some googling, I found the following solution:

   1: // All decimal input fields have a class named 'number'   2: $('input.number').each(function () {   3:     $(this).keypress(function(e){   4:         // '46' is the keyCode for '.'   5:         if(e.keyCode == '46' || e.charCode == '46'){   6:           // IE   7:           if(document.selection){   8:                 // Determines the selected text. If no text selected,   9:                 // the location of the cursor in the text is returned  10:                 var range = document.selection.createRange();  11:                 // Place the comma on the location of the selection,  12:                 // and remove the data in the selection  13:                 range.text = ',';  14:           // Chrome + FF  15:           }else if(this.selectionStart || this.selectionStart == '0'){  16:                 // Determines the start and end of the selection.  17:                 // If no text selected, they are the same and  18:                 // the location of the cursor in the text is returned  19:                 // Don't make it a jQuery obj, because selectionStart   20:                 // and selectionEnd isn't known.  21:                 var start = this.selectionStart;  22:                 var end = this.selectionEnd;  23:                 // Place the comma on the location of the selection,  24:                 // and remove the data in the selection  25:                 $(this).val($(this).val().substring(0, start) + ','  26:                  + $(this).val().substring(end, $(this).val().length));  27:                 // Set the cursor back at the correct location in   28:                 // the text  29:                 this.selectionStart = start + 1;  30:                 this.selectionEnd = start +1;  31:             }else{  32:                 // if no selection could be determined,   33:                 // place the comma at the end.  34:                 $(this).val($(this).val() + ',');               35:             }  36:             return false;  37:         }  38:     });  39: });

What we do is use the provided functionalities in the browsers for detecting selections in an input field. If no text is selected, the range will return the location of the cursor inside the input field. This way we can provide the correct implementation. So even when text is selected and the dot key is pressed, the selected text will be replaced by the comma.

LINQ to Indexed DB

2012-02-23T09:43:09-08:00

Since I started experimenting with the Indexed DB API, I have been searching for a simple way to add, retrieve, change, … data. In the beginning I wrote a little framework that provided some methods to retrieve, add, … data without having to think how to setup a connection. For experimenting this was enough, but when I started to build some demo apps, I noticed a needed a more generic way to do my CRUD operations.

So I start searching the internet for frameworks around the Indexed DB API’s. One project I found very interesting. It was the one of nparashuram. He was started with a Linq 2 Indexed DB Framework. Everything was still very basic, but it was well structured. Also it was only compatible with Firefox and Chrome, but not with the IE prototype and IE 10. So I contacted nparashuram and we decided to keep working on it together.

The framework is based on promises. This way we can easily handle the async calls which the Indexed DB API uses. We also use it as return value of the query you make. This way you can easily decide whether you want to use the complete method or the on progress method when retrieving multiple records. Also I believe this will be a programming model which we will see more and more in the future. Certainly if we want responsive applications.

The framework takes away the complexity of opening a database, creating transactions, … the only thing you need to worry about is how to structure your database and how to query. It also provides a way of creating the database structure while querying. This way you don’t have to create object stores or define the structure. Just inserting data to an object store, the object store will be created if not present.

The code of the framework can be found on codeplex and works as an extension on the jQuery framework. If you have some feature request you can add them here. Or you can contact me if you have some questions about it.

Keep following my blog or codeplex for new features and samples on this framework.

Web worker: running js tasks in the background

2012-02-17T09:39:44-08:00

Since JavaScript is more and more used for building applications, rather than providing extra features, you need to take care you don’t freeze the UI. This is one of the reasons why the W3C introduced the web worker API. This API provides a way to run JavaScript in a thread different form the UI thread. This way long running code such as sorting large array’s, won’t freeze the the UI or make your application unresponsive. Generally, workers are expected to be long-lived, have a high startup performance cost and a high per-instance memory cost.

workers

When we want to run code in a thread different from the UI thread, then we need to put this code in separate file. This file, will then be called by the worker to run in another thread. The only thing you need to do in the in the code that will run in another thread is calling postMessage method whenever you want to send data to the UI-thread.

Continuous worker

This code will start running when ever a worker with that file is instantiated and will continue running.

Example of a file (prime.js) to run in the background:

   1: var n = 1;   2: prime: while(true){   3:     n += 1;   4:     for (var i = 2; i <= Math.sqrt(n); i += 1){   5:         if (n % i == 0){   6:             continue prime;   7:         }   8:     }   9:     // Found prime  10:     postMessage(n)  11: }

This code will send a message to the UI thread every time a prime is found.

   1: // Starts a new worker   2: var worker = new Worker('prime.js');   3: worker.onmessage = function (event){   4:     // event.data contains a prime   5:     document.getElementById("result").textContent = event.data   6: }

The code above is used to create a new worker. The worker will execute the code in the prime.js file in a thread separate from the UI. In our case, the code will start calculating which numbers are primes.

The onmessage event on the worker gets triggered every time the postMessage method is called inside the worker thread. This way we can display the prime on the screen.

dedicated Worker

This worker will only start executing when you call the postMessage method on the worker.

Example of a file (sort.js) to run in the background:

   1: onmessage = function (event) {   2:     var data = event.data.data;   3:     var propertyName = event.data.propertyName;   4:     var sortedData = data.sort(JSONComparer(propertyName).sort);   5:     postMessage(sortedData);   6:     return;   7: };   8:     9: function JSONComparer(propertyName) {  10:     return {  11:         sort: function (valueX, valueY) {  12:                 return ((valueX[propertyName] == valueY[propertyName])   13:                         ? 0 : ((valueX[propertyName] > valueY[propertyName]) ? 1 : -1));  14:         }  15:     }  16: }

The onmessage method will handle a postMessage send to the worker. This will start the work you want to execute. In this case the code will sort an array of JSON objects on a given property. When the array and the propertyName is provided as data in the postMessage method, The data will get sorted on the property with the given propertyName. When the sort is completed, the sorted array will be send to the UI.

   1: var worker = new Worker("sort.js");   2: var data = [{ name: "test2" }, [{ name: "test4" }, [{ name: "test1" }, [{ name: "test3" }]   3: worker.onmessage = function (event) { /* event.data contains the sorted Array */) };   4: worker.postMessage({ data: data, propertyName: "name"});

With the postMessage method we can provide the data that is needed to sort an array. When the sorting is completed and the postMessage method in the background thread is called, the onmessage function will be triggered in the UI thread so we can process the sorted array.

More information about workers can be found here.

Indexed DB: To provide a key or not to provide a key

2012-02-04T00:41:02-08:00

I am currently busy writing a little framework around the Indexed DB API to make it easier to use Indexed DB. One of the things I was struggling with was when the key parameter must or mustn’t be provided. So I tested every possible combinations.

For this I created 4 object stores with different combinations:

Object store 1: KeyPath: “Id”, autoIncrement = true
Object store 2: KeyPath: undefined, autoIncrement = true
Object store 3: KeyPath: “Id”, autoIncrement = false
Object store 4: KeyPath: undefined, autoIncrement = false

Next, I tried adding four different combinations, and here are the results.

Add/Put parameters		Object store configuration
Value	Key	Object store 1	Object store 2	Object store 3	Object store 4
{ Name: "test" }	undefined	successful	successful	failed	failed
{ Id: 1, Name: "test" }	undefined	successful	successful	successful	failed
{ Name: "test" }	1	failed	successful	failed	successful
{ Id: 1, Name: "test" }	1	failed	successful	failed	successful

Conclusion

When a KeyPath is defined, the key parameter must be undefined
When no KeyPath is defined and there is no autoIncrement, a key must be provided
When no KeyPath is defined and there is autoIncrement, a key can be provided
When a KeyPath is defined and there is no autoIncrement, an attribute with the name of the KeyPath must be present.

Indexed DB: Defining your structure, the new way

2012-07-24T11:02:24-07:00

Some months ago I posted a blog post about defining your database structure. Because Indexed DB is still in draft, specifications can change from time to time. This is the case for the way you want to define your database structure. As I am typing now the only browser that is currently implementing this new specification is FireFox Nightly.
The way you create object stores and indexes hasn’t changed, but the way you can change it did. Changing your database structure still happens in a VERSION_CHANGE transaction, but the developer won’t be able to manually create a new VERSION_CHANGE transaction. Instead, the version of database you want to use needs to be provided when opening a database connection. When the database doesn’t have the version you requested, an onupgradeneeded event will occur. In this event you will be able to handle all your database changes like creating and deleting objectstores, creating and deleting indexes, …
But this all means that the SetVersion method for creating a VERSION_CHANGE transaction will become obsolete. So this means you will always have to define your database structure before you can start using them, even for indexes.
So how does this new way look like?

var req = window.indexedDB.open(databaseName, databaseVersion);
req.onsuccess = function (e) {
    // Opening of the databas in the given version was succesfull
}
 
req.onerror = function (e) {
    // Error while opening the database
}
 
req.onupgradeneeded = function (e){
    // Event for handeling the database structure changes
}
 
req.onblocked = function (e){
    // Handles the database open request while the database gets upgraded
}

The onblocked event was also added with the onupgradeneeded event. The onblock event will handle attempts to open the database while the database is upgrading to a more recent version. This way you can notify the user the request was blocked and they need to retry later.

As last there is an onversionchange event added on the databse object. This event will be called when the database is about to upgraded to a newer version. This way you’ll be able to close your current connection so you don’t get an error later on.

var req = window.indexedDB.open(databaseName, databaseVersion);
  
req.onsuccess = function (e) {
    req.result.onversionchange = function(){
        // Close your connection
    }  
}

Offline Application Caching: Make your web application offline available

2012-01-12T09:38:19-08:00

In my previous post I have been talking about IndexedDB, an in-browser database. This means, once we can persist data on the client, it’s possible to make our web application offline available. For this we have the offline application caching API.

When we want to take our application offline, the first thing we need to do is creating a manifest file. The main function of this file is describing which files have to be offline available. These files will be downloaded when the users visits the web application for the first time. Also when the manifest file has been changed since the last visit, these files will be downloaded again.

Manifest file

The beginning of the manifest file is always the same:

CACHE MANIFEST

Below this it’s recommended to place a comment with some kind of version number/date. This is necessary when you want to force the browser to download the files again because you changed one or more files. This is because browsers will only update their application cache when the manifest file is changed and not if one of the resources described in the file change. This means whenever you change a file described in the manifest file, you should update the version number in a comment.

# v3 2012-01-11

Now we have three parts in the manifest file. The first one is the explicit section. This means all files that are described in this section will be downloaded. This is also the default section, so it isn’t necessary to provide the ‘CACHE:’ title explicitly. Note that the colon after the title of the section is required. In the explicit section all kinds of files are allowed, for example: html files, images, js files, … Every resource you want to describe, takes one line.

CACHE:
/Detault.htm
/Scripts/jquery-1.7.1.min.js
/Css/ui-lightness/jquery-ui-1.8.16.custom.css
/Css/ui-lightness/images/ui-bg_diagonals-thick_18_b81900_40x40.png

The next part of the manifest file will describe which files should never be cached. This is the case for pages who relay on code that is executed on the server. For example a logon page. In this section you can use the “*” character as wildcard.That’s a fancy way of saying that anything that isn’t in the appcache can still be downloaded from the original web address, as long as you have an internet connection. This also means all resources on the webpage will be cached, even if they are hosted on an other domain.

The wildcard is important if we want to provide an “open-ended” offline web application. This is common for large web applications, whom we want to make offline available such as Wikipedia.

NETWORK:
/Logon.apsx
/Secure
*

The last part of the file will describe the fallback mechanisms. If you are working offline, and you request a resources that isn’t offline available, the configured resources will be shown.

FALLBACK:
/ /HTML/Offline.htm

Offline available webpages

All webpages we want to use offline need the manifest attribute with a reference to the manifest file. This way the browser knows where he can locate the file describing the offline resources.

<html manifest="/cache.manifest">

It doesn’t matter where the manifest file is located on the server. The only thing you need is the correct path to it. There are 2 extensions that are commonly used for the manifest file. These are “.manifest” and “.appcache”. It doesn’t matter which one you use, as long as the extensions are recognized by your webserver. In IIS 7.0 or higher the a MIME-type for .manifest exists.

If u are using an Apache webserver, you can use the AddType directive in your side-wide httpd.conf by adding the following lines:

AddType text/cache-manifest .appcache "access plus 0 seconds" AddType text/cache-manifest .manifest "access plus 0 seconds"

To avoid the risk of caching the manifest files, it is a good idea to set expires headers on your web server for manifest files so they expire immediately. In Apache you can configure this as follows:

ExpiresByType text/cache-manifest "access plus 0 seconds"

For IIS 6.0 you can find the explanation here.

Application cache events

The offline application cache API is also provided with some events:

Event	Description
Checking	Fires when the browsers notices a manifest attribute in the html tag, even in case you already visited the page
Downloading	Fires if the browser starts downloading the files described in the manifest file
Progress	Fires periodically while downloading.Contains information about the number of files that have been downloaded and the number of files that are still queued
Cached	Fires when all the files in the manifest file are downloaded. The web app is now fully cached and ready to use offline. This is only the case if it’s the first time data from the manifest file is downloaded.
Noupdate	Fires if you visit an offline-enabled page and the manifest file hasn’t changed.
Updateready	Fires when downloading of the files described in the manifest file was successful. The new version web app is now fully cache. This is the case if the data from the manifest file has ever been downloaded in the past.
Error	Fires when ever something goes wrong. Possible causes: - HTTP error 404 (Page not found) - HTTP error 410 (Permanently Gone) - Page failed to download properly - Manifest file changed while updating - Browser failed to download one of the resources listed in the manifest file
Obsolete	The manifest was not found. Possible causes: - HTTP error 404 (Page not found) - HTTP error 410 (Permanently Gone) This means the application cache has been deleted.

It’s a best practice to call the window.applicationCache.SwapCache() method when the Updateready event is fired. This forces the browser to switch to the most recent application cache. If you forget to do this, the user needs to reload the webpage in order to take advantage of the new version.

Browser State

In the window object we have an interface “NavigatorOnline” which provides us information about the state of the browser. If the attribute “onLine” is false, we can be sure the browser is definitely offline. In case the attribute is true, the browser might be online, but that isn’t for sure.

window.navigator.onLine

There are also 2 events. The online and offline event that are fired when the browser either goes online or offline. You can attach the events on the following ways:

using the addEventListener on the window, document or document.body
Setting the .ononline or .onoffline properties on document or document.body to a JS function. (For some reason the window.ononline and window.onoffline will not work)
By specifying the ononline or onoffline attributes on the <body> element in the HTML.

Note when using the first 2 solutions, you can only attach the events after the page load event.

Indexed DB: Reading multiple records

2012-01-02T01:49:04-08:00

In my previous post I have been talking about reading data. Today, I’ll be talking about reading multiple records at once. Here for we will use a cursor. A cursor is a transient mechanism used to iterate over multiple records in a database. The storage operations of the cursor can be used on the underlying index or an object store.

In the IDBObjectStore interface, we have the openCursor method to create a new cursor for retrieving data. In the IDBIndex interface, we have 2 ways to create a new cursor. These methods are openCursor to retrieve the values from the index and openKeyCursor to retrieve the keys. There are 2 optional parameters that can be provided when calling these methods. The first parameter is an IDBKeyRange, with this we will narrow the result by defining the bounds of the keys we want to retrieve. The second parameter is the direction the cursor must navigate trough the results.

IDBKeyrange

A key range is a continuous interval over some data type used for keys. A key range can have one of the following situations:

lower bounded: The keys must have a value smaller than the provided lower bound

upper bounded: The keys must have a value larger than the provided upper bound

lower and upper bounded: The keys must have a value between the lower and the upper bound

unbounded: All keys will be valid

Single value: The key must be the provide value

The upper and lower bound can be open, this means the value of the bound won’t be included, or closed, this means the value of the bound will be included.

More information about the IDBKeyRange interface can be found here. You will also find some more information about the methods to create a key rage. If you want to use an unbounded key range, you don’t need to provide a key range.

Retrieving data with a cursor

As for all actions preformed on the database a transaction is also needed in case of reading data with a cursor.

   1: var txn = dbconnection.transaction([“ObjectStoreName”]);   2: var objectStore = txn.objectStore(“ObjectStoreName”);   3: var cursorReq;   4: // IE 10, Chrome and Firefox implementation   5: if(window.msIndexedDB || window.mozIndexedDB || window.webkitIndexedDB){   6:     cursorReq = store.openCursor();   7: }   8: // IE Indexed DB Prototype implementation   9: else{  10:     cursorReq = store.openCursor(IDBKeyRange.lowerBound(0));  11: }  12:    13: handleCursor(cursorReq, txn, success, error);

First things first, we define the cursor. One of the first thing you notice is that the IE Indexed DB prototype requires a key range. This means it won’t be possible to use the unbounded key range. Because I’m using an auto increment key for my object store, I can take use of the lowerbound method to create a key range from 0 to forever. After the cursor is defined, I use a method to handle the reading of the cursor.

   1: function handleCursor(cursorReq, txn, success, error){   2:     cursorReq.onsuccess = function (event) {   3:         if (event.result) {   4:             var cur = event.result;   5:             if (cur) {   6:                 cursor_get_record(cur);   7:             }   8:         }   9:         else if (cursorReq.result) {  10:             var cur = cursorReq.result;  11:             // Present the data  12:             cur.continue();  13:         }  14:     cursorReq.onerror = error  15: }

Again the IE Indexed DB prototype has a different implementation for handling a cursor. I’ll start with explaining the correct way. If the request object contains a result. If this is empty, you reached the end of the cursor. If the result is an object, the value of the current record in the cursor can be found in the value field. When you handled the value, you can navigate to the next record in the cursor by calling the continue function on the result object.

When working with the Indexed DB prototype, you have to make another approach. That’s why I created a recursive function for it. (cursor_get_record). The only parameter I need to pass is the result object I get out of the parameter that is provided when the call for the cursor was successful.

   1: function cursor_get_record(cur){     2:     cur.move();    3:     if(cur.value)   4:     {   5:         // Present the data   6:         cursor_get_record(cur);   7:     }   8: }

With the move method we fetch the next record from the cursor. If the cursor contains a value, you can handle it and afterwards you call the current method to fetch the next record of cursor.

Indexed DB: Reading data

2011-12-03T06:28:17-08:00

Finally we get to the part where we can see the results of our Indexed DB tutorial. For the last few moths we have been structuring our database, adding data and now I’ll show how you can read data from an Indexed DB. For this we have 2 approaches. First one is retrieving a single record and the other way is retrieving a collection of records by a cursor.

In this post I’ll handle the retrieving of a single record. A post about retrieving data with a cursor will appear in the near future.

Retrieving data from an object store

In the IObjectStore interface we have an get method to retrieve data. This method must be provided with a key we want to search on. The key parameter can be a valid key or a key range. In case you don’t provide a valid key, a DATA_ERR exception will be thrown.

In the first situation a record of the object store will be retrieved where the given key is the same as the key of the key/value pair. In the other situation, the first record will be retrieved that matches one of the keys defined in the key range. If no record gets found, the result will be undefined. If you are using the Indexed DB prototype on IE 9, you’ll get an “Object with specified key not found.” error in stead of an result.

Time for some code:

When we want to read data, we need to create a transaction. This we do on the same way as for adding data. The only difference is we can use the IDBTransaction.READ_ONLY mode. This is the type that will be used as default when we create a transaction.

   1: var txn = dbconnection.transaction([“ObjectStoreName”]);   2: var objectStore = txn.objectStore(“ObjectStoreName”);

The result of the get method is a IDBrequest object. When this is successful, the record is added to the result.

   1: var getReq = store.get(key);   2: getReq.onsuccess = function(event) {    3:     var result;   4:     // IE 9 implementation   5:     if(event.result){   6:         result = event.result;   7:     }   8:     // IE 10, Chrome and Firefox implementation   9:     else if (getReq.result){  10:         result = getReq.result;  11:     }  12:     // Code to present the result on your screen  13: };

Retrieving data from an Index

In a previous post I have been talking about Indexes. Indexes make it possible to look up data from the object store by fields of the value object. By example: we have an object store person. In this object store we store persons. A person object has a first name and a last name field. By creating an index with a key path “last name”, we make it possible to retrieve data from the object store by providing the last name of the person.

In the IDBIndex interface we have the get method to retrieve a record from the object store, and the GetKey method to retrieve the key of the record from the object store. In both cases a key must be provided. This key parameter can be a valid key or a key range. For the rest every thing works the same as for retrieving data from an object store.

One think you need to keep in mind. In the Indexed DB prototype on IE9 the get and getKey method work different. In this case the getKey method retrieves the data and the get method the key of the record.

   1: var txn = dbconnection.transaction([“ObjectStoreName”]);   2: var objectStore = txn.objectStore(“ObjectStoreName”);   3: var index = store.index(“IndexName”);   4: var getReq = index.getKey(key);   5:     6: getReq.onsuccess = function(event) {    7:     var result;   8:     if(event.result){   9:         result = event.result;  10:     }  11:     else{  12:         result = getReq.result  13:     }  14:     // Code to present the result on your screen  15: };

Indexed DB: Manipulating data

2011-11-09T04:20:01-08:00

The first thing we need to do when we want to read data, is to make sure we have data available in our database. So this post will handle inserting and updating data into the database.

For inserting data we have 2 possibilities: we have an add and a put method available. Both methods take the same parameters, but there is a slight difference between them. When we use the add method, we need to be sure that no other object with the same key is already added in the database. If it does, an constraint error (CONSTRAINT_ERR) will occur. So the add method will only be used when we want to add data that won’t be overwritten when it is already present with the same key in the database.

The put method we will usually use when we want to update data. If the data isn’t present yet with the same key, the data will be inserted. If you want some more information about the steps for storing a record into an object store, you can find this here on the W3C specs site.

Make sure when you are starting a new transaction to manipulate data, you will use a read_write transaction. Otherwise you will receive an READ_ONLY_ERR when calling the methods.

The put and the add method are both available in the IObjectStore interface. This means once we have created the transaction where we will work in, we need to retrieve the object store we want to work on. We do this by calling the ObjectStore method on the transaction. The only thing we need to pass is the name of the object store.

var txn = dbconnection.transaction([“ObjectStoreName”]
, IDBTransaction.READ_WRITE);
var objectStore = txn.objectStore(“ObjectStoreName”);

Once we have the object store object, we can start adding data to it. The result of the add operation is an IDBRequest object. This means the onsuccess will be called when the operation was successful and an onerror will be called when something went wrong.
When the onsuccess function gets called, the result of this action will be the key of the object in the object store

var addresult = objectStore.add(data);
addresult.onsuccess = function (event) {
      // Adding data is successful
      // Commit the transaction when using IE9
      var key;

      // IE 9 implementation
      if(event.result){
            key = event.result
      }
      // IE 10, Chrome and Firefox implementation
      else if (addresult.result){
            key = addresult.result;
      }
};
addresult.onerror = function (event) {
      // Handle the error
}

If we use a put for adding or changing data, we get the same structure only we will use the put method instead.

var putresult = objectStore.put(data);
putresult.onsuccess = function (event) {
      // Putting data is successful
      // Commit the transaction when using IE9
};
putresult.onerror = function (event) {
      // Handle the error
}

Now that we have added some data to our database, we can start retrieving it and present it to our users…

Indexed DB: Deleting your database

2011-11-04T06:44:43-07:00

In a previous post I have been talking about creating and deleting a database. The creation/opening of a database is supported in all the major browsers, but deleting isn’t. Only Internet Explorer currently supports deleting your database trough the IDBFactory interface.

Because we have been playing for a while now, it’s interesting we can delete our database so we can rebuild it from scratch without having to use a new name for our database. I’m only used to work on windows machines, so the solution I will propose will probably only work under windows. If you are using an other operating system, it will work on the same way, but you’ll have to look where you can find the databases.

Firefox

The Indexed DB databases of Firefox can be found on the following location:

<location of the windows user profiles>\<account name>\AppData\Roaming\
Mozilla\Firefox\Profiles\<some random characters>.default\IndexedDB

In my case this is:

C:\Users\kristof\AppData\Roaming\Mozilla\Firefox\Profiles\ tvv6t475.default\indexedDB

You will find a folder with your current domain. Delete these folder, and you can start all over again. In my case, I get the following:

http+++localhost+50350

I have to notice that the AppData folder is a hidden folder, so it is possible you won’t see it when going to your user profile directory.

Chrome

The Indexed DB databases of Chrome can be found on the following location:

<location of the windows user profiles>\<account name>\AppData\Local\Google\
Chrome\User Data\Default\IndexedDB

In my case this is:

C:\Users\kristof\AppData\Local\Google\Chrome\User Data\Default\IndexedDB

You will find a folder and a file with your current domain. Delete these files, and you can start all over again.

In my case I get the following:

folder: http_localhost_50350.indexeddb.leveldb
file: http_localhost_50350.indexeddb