Building Addons

Dexie is designed for being extended by addons.

Methods for Extending Dexie

Dexie.addons

This array contains functions that extends Dexie. An addon may register itself in Dexie.addons by using Dexie.addons.push(fn). Example:

(function(){
    //
    // This addon will add the method notEqualTo() to the WhereClause class.
    //
    // Possible usage sample: db.friends.where("age").notEqualTo(37)
    //
    function NequalAddon (db) {
        db.WhereClause.prototype.notEqualTo = function (value) {
           return this.below(value).or(this._ctx.index).above(value);
        };
    }

    Dexie.addons.push(NequalAddon);
})();

Understanding where Dexie classes reside

Dexie classes such as Collection, Table, WriteableTable are created in the closure scope of the Dexie constructor. To extend the prototypes you must work with an instance of Dexie. See example above.

Overriding existing methods

To override an existing method on any class, you can just change its current value to your own function. A handy function for overriding is the Dexie.override() function. Example:

db.Collection.prototype.each = Dexie.override (db.Collection.prototype.each, function (originalEach) {
    return function () {
        var returnValue = originalEach.apply(this, arguments);
        // Do some more stuff
        return returnValue;
    }
});

Protected methods

The API Reference does not document the protected methods and properties of Dexie. You may however look into the code and find lots of methods and properties with a leading underscore. Your addon may then override protected methods to change the behaviour of the database engine. To see an example of this, look at how Dexie.Observable.js is implemented.

Note: We will try to keep all the not-yet-documented underscore properties and methods backward compatible as much as possible, but it's not a guarantee. To be certain we inform you about important API changes, please let us know about your addon and where to find its source. To be even more certain, let your addon reside under your fork of Dexie.js/addons and keep us updated with pull requests.

When to use prototype and not

All inner classes (Collection, WhereClause, Table, Transaction, etc) use prototype for all its methods. This is because it will optimize instance creations. But the main Dexie class itself does not use prototype for now since instance creation is more rare with the main class which is a typical singleton. Avoiding prototyped methods can simplify the code a little, and that's why it doesnt use prototyped methods.

So to extend or override methods on the main class (Dexie), you should change the property on the given db instance that your addon retrieves in its first argument. For all other internal classes, such as Collection, WhereClause, Table, etc, all methods are prototyped, so you can override the prototype of it.

Creating Subclasses

Another way to extend dexie is to derive from it or make your extension create new classes that derives from existing ones. For example, you could derive from Table or WriteableTable and then override the protected method db._tableFactory() method and create your instance there.

Alternate way of doing an addon

Instead of registering into Dexie.addons, you could instead create a derived class and call it something else. By doing so, the user may choose whether to instanciate a 'clean' Dexie or an instance of your class. Example:

function MyDerivedDexie (dbname) {
    Dexie.call(this, dbname);
    this.anotherProperty = "other prop";
    this.anotherMethod = function () {
        // Do something more
    };
}

To use the addon:

var db = new MyDerivedDexie("DerivedSampleDB");
alert (db.anotherProperty);
db.anotherMethod ();

Creating an AMD based addon

If you write a pure AMD based addon, you should not register it to Dexie.addons but let the module user explicitely provide your addon as an option to the Dexie constructor.

define('Dexie.NequalAddon', ["Dexie"], function (Dexie) {
    function NequalAddon (db) {
        db.WhereClause.prototype.notEqualTo = function (value) {
           return this.below(value).or(this._ctx.index).above(value);
        };
    }
    return NequalAddon;    
}

The module user will then do:

require(['Dexie', 'Dexie.NequalAddon'], function (Dexie, DexieNequalAddon) {
    var db = new Dexie('testdb', {options: addons: [DexieNequalADdon]});
    db.version(1).stores({...});
    db.open();
    ...
});