docs/_includes/api/plugins.html

{% include anchor.html edit="true" title="Plugins" hash="plugins" %} 

Writing a plugin is easy! The API is:

{% highlight js %}
PouchDB.plugin({
  methodName: myFunction
});
{% endhighlight %}

This will add a `db.methodName()` to all databases, which runs `myFunction`.It will always be called in context, so that within the function, `this` refers to the database object.

There is a [PouchDB Plugin Seed project](https://github.com/pouchdb/plugin-seed), which is the fastest way to get started writing, building and testing your very own plugin.

#### Example Usage:
{% highlight js %}
PouchDB.plugin({
  sayHello : function () {
    console.log("Hello!");
  }
});
new PouchDB('foobar').sayHello(); // prints "Hello!"
{% endhighlight %}

#### Load Plugins from require()

You can load plugins into PouchDB when you load it via `require()`.

{% highlight js %}
var greet = {sayHello: function() { console.log("Hello!"); }};

var PouchDB = require('pouchdb').plugin(greet);

var db = new PouchDB('foobar');
db.sayHello(); // prints "Hello!"
{% endhighlight %}

You can chain plugins, as well:

{% highlight js %}
var greet = {sayHello: function() { console.log("Hello!"); }};
var manners = {thank: function(name) { console.log("Thank you, " + name); }};

var PouchDB = require('pouchdb')
  .plugin(greet)
  .plugin(manners);

var db = new PouchDB('foobar');
db.sayHello(); // prints "Hello!"
db.thank('Mom'); // prints "Thank you, Mom"
{% endhighlight %}

#### Example Plugin: Intercept Updates

A useful feature of plugins is to intercept updates before they are stored in PouchDB. In this way, a plugin might validate that the data is correct for the application, or even alter documents before they are committed to the database.

The best way to intercept all updates to a PouchDB database is to **override the `bulkDocs()` method**. All changes to PouchDB documents ultimately pass through the `bulkDocs()` method. For example, a call to `put()` will become become a `bulkDocs()` call with a "batch" of one document.

Because PouchDB guarantees to plugin authors that all data changes ultimate happen via `bulkDocs()`, it is the ideal place for an application or plugin to intercept updates.

{% highlight js %}
// Keep a reference to the "upstream" function.
var pouchBulkDocs = PouchDB.prototype.bulkDocs;
PouchDB.plugin({bulkDocs: validBulkDocs});

function validBulkDocs(body, options, callback) {
  if (typeof options == 'function') {
    callback = options
    options = {}
  }

  if (Array.isArray(body)) {
    var docs = body;
  } else {
    var docs = body.docs;
  }

  // All documents must have a .name field.
  for (var i = 0; i < docs.length; i++) {
    if (!docs[i].name) {
      var id = doc._id || '(no _id given)';
      return callback(new Error('Document is missing .name field: ' + id));
    }
  }

  // All documents check out. Pass them to PouchDB.
  return pouchBulkDocs.call(this, docs, options, callback);
}
{% endhighlight %}

The above plugin would return an error if anything ever attempts to store an unnamed document, including documents which change during replication.

Note: this is a very, very simple validation example. It does not behave, for example, like the Apache CouchDB `validate_doc_update()` API.