Skip to content

Building Addons

David Fahlander edited this page May 16, 2014 · 22 revisions

Dexie is designed for being extended by addons.

Methods for Extending Dexie

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 enable operations like db.friends.where("age").notEqualTo(37)
    //
    function NequalAddon (db) {
        /// <param name="db" type="Dexie"></param>
        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.each = Dexie.override (db.Collection.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.

When to use prototype and not

The Dexie class itself does not use prototype for now. So to extend or override Dexie methods, you should change the property on the db instance. 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";
}

Dexie.derive(MyDerivedDexie).from(Dexie).extend({
    anotherMethod: function () {
        // Do something more
    }
});

To use the addon:

var db = new MyDerivedDexie("DerivedSampleDB");
alert (db.anotherProperty);
db.anotherMethod ();
Clone this wiki locally