Debugging IndexedDB Applications

IndexedDB is a
W3C Working Draft that enables JavaScript developers to store, search, and retrieve data on the user’s local client,
even when
Internet connectivity is disabled. This blog post describes IDBExplorer, a tool we use internally to debug IndexedDB applications. IDBExplorer lets you view
database schemas, object store content, and index details.

Exploring the tool with an example IndexedDB App

To illustrate, I created an application that tracks my New
Year’s resolutions using IndexedDB. It stores and accesses my resolutions locally (on the system browsing the Web page)
and lets me add or edit them. The “Done That!” button removes the selected resolution from the list and removes its internal
representation from the database.

IndexedDB defines a database as a container of information. Each database contains object stores, which are
repositories for JavaScript objects. Each object contains attributes which can be queried using the API. If you’re familiar
with relational databases, object stores can be equated to tables and each JavaScript object in an object store represents
a record. However, the objects stored in an IndexedDB object store are treated as opaque entities. In addition, these objects
do not have to contain the same properties.

If a JavaScript object is analogous to a relational database record, then the properties of that object can be thought of
as columns (or fields) in a table. As a result, IndexedDB allows you to define indexes that identify object properties that
can be used to search the records in an object store. Thus, indexes allow you to traverse and search IndexedDB data using
the attribute values on a JavaScript object.

IndexedDB allows each Domain to have multiple databases. This
example uses one database: “NewYear.” The app stores my resolutions in an object store named “Resolutions” inside the
NewYear database. Each resolution is a JavaScript object with the following attributes:

• priorityId: Separates resolutions into different priorities
• name: Name of the resolution
• occurrenceId: Tracks how frequently the action of the resolution must be performed
• dueDate: Completion date of the resolution
• createdDate: Internal date when the resolution was added to the object store
• categoryId: Defines the type of activity for a resolution

Notice that not all attributes are visible from the application’s UI. In some cases, they are only internally used (e.g.
createdDate).

Here’s how the IDBExplorer tool displays the contents of the “Resolutions” object store:

The “Resolutions” object store also contains an index on the priorityId attribute named “priorityId,” which allows
the app to query objects using the priorityId property. The descriptions for the each priorityId value can
be found inside the “Priorities” object store and the descriptions for the occurrenceId values can be found inside
the “Occurrences” object store. Likewise, the descriptions for the categoryId values can be found inside the “Categories”
object store.

The tool uses a tree hierarchy to illustrate these relationships:

The IDBExplorer tool shows there are five resolutions in my database (two high priority tasks, two medium priorities, and
one low priority).

Using the application, I can add a new resolution:

The app retrieves the values for Occurrence, Priority, and Category fields from their respective object
stores using cursors and displays them to the user. The IDBExplorer tool lets you see how these values exist in the object
store. For example, selecting the Categories object store displays the available categories and their descriptions:

You can update a resolution by selecting it in the “WorkOn” screen and choosing “Edit.” After making any changes, selecting
the “Update” button will commit the changes and update the values in the “Resolutions” object store.

Using IDBExplorer in your Applications

You can include the IDBExplorer tool in your Metro style app or Web site. However, we recommend you not deploy the tool with
your app.

To add the tool to your site, copy and unzip the content of the
IDBExplorer package into your site. Your application will need to link to the IDBExplorer.html file contained inside
the IDBExplorer folder using either an iframe element or a new window.

In our example, we decided to host IDBExplorer inside an iframe element. . However, for normal development we recommend hosting
this URI inside a new window. This will allow you to have a side-by-side experience when debugging your database and application
without affecting your site’s user interface.

When hosting IDBExplorer, you need to pass the database name using the query string. In this example, this was done using
the src attribute of the iframe element:

<iframe
id="debuggerId" class="debuggerContainer"
src="IDBExplorer/IDBExplorer.html?name=NewYear"></iframe>

When planning to host this functionality in a Metro style app, remember that Metro-style apps run fullscreen. As a result,
you should navigate to this URL, rather than opening a new window (you will need to add a Back button to the IDBExplorer.html
file in order to be able to return to your application). Alternatively, you can add an iframe element and display the tool
in it.

Enjoy the tool and let us know what you think!

—Israel Hilerio, Ph.D., Principal Program Manager, Internet Explorer

IEBlog