• Stars
    star
    163
  • Rank 231,141 (Top 5 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created over 12 years ago
  • Updated over 8 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Backbone PouchDB Adapter

backbone-pouch Build Status

Backbone PouchDB Sync Adapter

Getting Started

You can use backbone-pouch on the server with node or in the browser:

On the Server

Install the module with: npm install backbone-pouch

var Backbone = require('backbone');
var BackbonePouch = require('backbone-pouch');
Backbone.sync = BackbonePouch.sync();

In the Browser

  1. Download jQuery, Underscore, Backbone and PouchDB
  2. Download backbone-pouch.
  3. In your web page:
<script src="jquery-2.0.0.min.js"></script>
<script src="underscore-min.js"></script>
<script src="backbone-min.js"></script>
<script src="pouchdb-nightly.min.js"></script>
<script src="backbone-pouch.js"></script>
<script>
  Backbone.sync = BackbonePouch.sync();
</script>

Setup backbone-pouch

You can configure Backbone to persist via backbone-pouch per model:

var MyModel = Backbone.Model.extend({
  sync: BackbonePouch.sync(options)
});

Or you might want to set backbone-pouch sync globally:

Backbone.sync = BackbonePouch.sync(defaults);

var MyModel = Backbone.Model.extend({
  pouch: options
});

BackbonePouch.attachments()

You can mixin attachment support into a single model:

var MyModel = Backbone.Model.extend(BackbonePouch.attachments());

Or you may want to mixin attachment support globally:

_.extend(Backbone.Model.prototype, BackbonePouch.attachments());

Note that you have to call the attachments function - don't forget the braces.

You can also pass the PouchDB adapter to BackbonePouch.attachments:

_.extend(Backbone.Model.prototype, BackbonePouch.attachments({
  db: new PouchDB('mydb')
}));

idAttribute

You should adjust the idAttribute, because CouchDB (and therefore PouchDB) uses _id instead of the default id attribute:

Backbone.Model.prototype.idAttribute = '_id';

## Usage ```javascript var MyModel = Backbone.Model.extend({ idAttribute: '_id', sync: BackbonePouch.sync({ db: new PouchDB('mydb') }) }); ```

Query documents of type post

Retrieve single documents with all conflicts. Retrieve collections via Map Reduce, filtering all documents of type post, ordered by position. Limit results to 10.

var Post = Backbone.Model.extend({
  idAttribute: '_id',
  sync: BackbonePouch.sync({
    db: new PouchDB('mydb')
  })
});
var Posts = Backbone.Collection.extend({
  model: Post,
  sync: BackbonePouch.sync({
    db: new PouchDB('mydb'),
    fetch: 'query',
    options: {
      query: {
        include_docs: true,
        fun: {
          map: function(doc, emit) {
            if (doc.type === 'post') {
              emit(doc.position, null)
            }
          }
        },
        limit: 10
      },
      changes: {
        include_docs: true,
        filter: function(doc) {
          return doc._deleted || doc.type === 'post';
        }
      }
    }
  }),
  parse: function(result) {
    return _.pluck(result.rows, 'doc');
  }
});

Global Backbone Sync Configuration

Use mydb as default for all databases. Setup Map Reduce as default query method. Limit resultset to 10. Authors are returnd by name, Posts by date.

Backbone.sync =  BackbonePouch.sync({
  db: new PouchDB('mydb'),
  fetch: 'query',
  options: {
    query: {
      include_docs: true,
      limit: 10
    }
  }
});
Backbone.Model.prototype.idAttribute = '_id';

Then you can define your models and collections as usual and overwrite backbone-pouchdb settings via the pouch property:

var Author = Backbone.Model.extend();
var Authors = Backbone.Collection.extend({
  model: Author,
  pouch: {
    options: {
      query: {
        include_docs: true,
        fun: {
          map: function(doc, emit) {
            if (doc.type === 'author') {
              emit(doc.name, null)
            }
          }
        }
      },
      changes: {
        include_docs: true,
        filter: function(doc) {
          return doc._deleted || doc.type === 'author';
        }
      }
    }
  },
  parse: function(result) {
    return _.pluck(result.rows, 'doc');
  }
});
var Post = Backbone.Model.extend();
var Posts = Backbone.Collection.extend({
  model: Post,
  pouch: {
    options: {
      query: {
        include_docs: true,
        fun: {
          map: function(doc, emit) {
            if (doc.type === 'post') {
              emit(doc.date, null)
            }
          }
        }
      },
      changes: {
        include_docs: true,
        filter: function(doc) {
          return doc._deleted || doc.type === 'post';
        }
      }
    }
  },
  parse: function(result) {
    return _.pluck(result.rows, 'doc');
  }
});

Attachments

Backbone.sync =  BackbonePouch.sync({
  db: new PouchDB('mydb')
});
Backbone.Model.prototype.idAttribute = '_id';
var MyModel = Backbone.Model.extend(BackbonePouch.attachments());
var model = new MyModel();
model.attach(blob);     // store file
model.attachments();    // list files
model.attachment(name); // retrieve file

backbone-pouch helps you with binary attachments by providing convenient methods for retrieving, storing and listing files.

attach(blob, name, type, callback)

Store an attachment.

blob must be a Blob in the browser or a Buffer in node. You can omit name if the blob has a filename property. You can omit type if the blob has a type property.

The callback is invoked with err and result callbacks. After the file is stored, the models _rev property is updated. If the model wasn't saved before, an id will be assigned and it will be created.

attachments(filter)

List attachment names.

The optional filter argument can be used to list only attachments of a certain type.

If the filter argument is a string or a RegExp, it will be matched against the content_type of each attachment and only the matching attachment names will be returned.

If filter is a function, it will be called with the attachments name and its stub.

attachment(name, callback)

Retrieve an attachment blob by name.

callback is called with error and blob arguments.

In the browser a Blob object is returned, a Buffer in node.

## Configuration You can configure every option passed to PouchDB.

Option Inheritance

Options are merged (using Underscores extend) in the following order:

  1. BackbonePouch defaults
  2. BackbonePouch sync options
  3. pouch object
  4. save / get / destroy / fetch options

backbone-pouch Options

These options control the behaviour of backbone-pouch.

db: PouchDB Adapter

Setup a database. This option is mendatory. Must be a PouchDB adapter:

PouchDB('dbname')

See Create a database.

fetch: Fetch Method

Specify the fetch method. Can be either allDocs (default), query or spatial.

Use the default allDocs if you want all documents.

Using query you can use Map-Reduce to query the database.

spatial requires the Spatial query plugin.

listen: Listen for Changes

When this is checked, backbone-pouchdb will listen for changes in the database and update the model / collection on every change. Default is true.

Note that you will need to setup a filter function when used in combination with query fetch method.

options: PouchDB Options

Those options are passed directly to PouchDB.

The keys are PouchDB methods. Possible keys are post, put, remove, get, query, allDocs and spatial.

Refer to the PouchDB API Documentation for more options.

post: Create

Options for document creation. Currently no options supported.

See Create a Document.

put: Update

Options for document update. Currently no options supported.

See Update a Document.

remove: Delete

Options for document delete. Currently no options supported.

See Delete a Document.

get: Retrieve Model

Options for fetching a single document.

  • attachments: Include attachment data.
  • conflicts: If specified conflicting leaf revisions will be attached in _conflicts array.
  • open_revs: Fetch all leaf revisions if open_revs='all'.
  • rev: Fetch specific revision of a document. Defaults to winning revision.
  • revs_info: Include a list of revisions of the document, and their availability.
  • revs: Include revision history of the document.

See Fetch a Document.

Fetch Collections

When fetching collections from views, one might want to parse the result, eg:

parse: function(result) {
  return _.pluck(result.rows, 'doc');
}
allDocs: Retrieve Collection

Options for fetching all documents. This is a built in view which outputs all documents by id.

  • attachments: Include attachment data.
  • conflicts: If specified conflicting leaf revisions will be attached in _conflicts array.
  • descending: Return result in descending order. Default is ascending order.
  • endkey: Endkey of the query.
  • include_docs: Whether to include the document in doc property.
  • key: Key of the query.
  • keys: Multiple keys.
  • limit: Limit the resultset. Default is to return all documents.
  • startkey: Startkey of the query.

See Fetch Documents.

query: Retrieve Collection via Map Reduce

Query options for Map Reduce queries.

  • attachments: Include attachment data.
  • conflicts: If specified conflicting leaf revisions will be attached in _conflicts array.
  • descending: Return result in descending order. Default is ascending order.
  • endkey: Endkey of the query.
  • fun: Map Reduce Function: can be a string addressing a view in a design document or an object with a map and optional reduce property. A map function is required, if you use the query fetch method.
  • include_docs: Whether to include the document in doc property.
  • key: Key of the query.
  • keys: Multiple keys.
  • limit: Limit the resultset. Default is to return all documents.
  • reduce: Whether to include the document in doc property. Default is to reduce if there is a reduce function.
  • startkey: Startkey of the query.

See Query the Database.

spatial: Retrieve Collection via Spatial Index

Options for Spatial query. The spatial query has not been tested. You have to use a PouchDB build with included Spatial plugin.

  • conflicts: If specified conflicting leaf revisions will be attached in _conflicts array.
  • end_range: End range of query
  • include_docs: Whether to include the document on each change. Default is true.
  • start_range: Start range of query
changes: Listen for changes

Options passed to changes feed.

  • filter: Reference a filter function from a design document or define a function to selectively get updates.
  • descending: Return result in descending order. Default is ascending order.
  • conflicts: If specified conflicting leaf revisions will be attached in _conflicts array.
  • continuous: Continuously listen to changes. Default is true.
  • include_docs: Whether to include the document on each change. Default is true.

See Listen to Database Changes.

## Examples Check out the [TODO Application](http://jo.github.io/backbone-pouch/examples/todos) in the `doc/examples` folder.

It`s the standard Backbone TODO example, extended to use backbone-pouch.

Advanced TODO Sync Example

TODO Sync Application is also in the doc/examples folder.

You can setup external CouchDB (with CORS enabled) to sync your local TODO database.

Contributing

  • Install dependencies via npm install
  • Edit backbone-pouch.js
  • Write tap tests
  • Run the tests with npm test
  • Generate the docs with npm run docs. This will render README.md using doc/index.html.jst

To update the Github page, change to the gh-pages branch and merge the doc subtree:

git pull -s subtree origin master

Versioning

backbone-pouch follows semver-ftw. Dont think 1.0.0 means production ready yet. There were some breaking changes, so had to move up the major version.

Release History

  • 1.5.0: Remove Grunt in favour of purism and switch to tap
  • 1.4.0: Update Backbone and Underscore
  • 1.3.0: Do not parse view results, leave that up to the user
  • 1.2.1: Improve option inheritance
  • 1.2.0: Change defaults: do not listen and include_docs
  • 1.1.1: Adapt PouchDB attachment API change with seperate docId and attachment name
  • 1.1: Attachment support
  • 1.0: New chained api, Node support, tests. Support listen to changes feed. Use Grunt.
  • prior 1.0: Experimental version with example TODO apps

License

Copyright (c) 2013-2014 Johannes J. Schmidt, TF
Licensed under the MIT license.

More Repositories

1

couchdb-best-practices

Collect best practices around the CouchDB universe.
CSS
320
star
2

couchdb-bootstrap

Bootstrap CouchDB projects: configure, setup security, deploy ddocs and create users.
JavaScript
115
star
3

docuri

Rich document ids for CouchDB
JavaScript
103
star
4

puret

Puret is a minimal pure translation library for translating database values for Rails 3.
Ruby
74
star
5

pouch-box

Asymmetric encrypted PouchDB, powered by NaCl's curve25519-xsalsa20-poly1305.
JavaScript
67
star
6

grunt-couch

Build and publish Couchapps and CouchDB design documents with grunt. Simple.
JavaScript
46
star
7

couchdb-push

Deploy CouchDB documents from directory, JSON or CommonJS module.
JavaScript
40
star
8

couchdb-compile

Build CouchDB documents from directory, JSON or CommonJS module
JavaScript
38
star
9

pouch-resolve-conflicts

Assist in CouchDB conflict resolution
JavaScript
34
star
10

quilt

Access CouchDB from filesystem
Ruby
21
star
11

session25519

Derive Curve25519 encryption keys and ed25519 signing keys from username and password via BLAKE2s hash and scrypt.
JavaScript
20
star
12

roy-replicator

Node implementation of CouchDB replicator. For educational purposes.
JavaScript
20
star
13

mouch

Couchapp Purism
Ruby
19
star
14

couchmagick

Couchmagick runs ImageMagicks convert on CouchDB documents. Reliable.
JavaScript
17
star
15

couch-daemon

High-level os daemon API for CouchDB.
JavaScript
14
star
16

webcryptobox-js

Tiny utility library for asymetric encryption via WebCrypto with zero dependencies.
JavaScript
14
star
17

couchdb-worker

A worker module that manages state.
JavaScript
13
star
18

git-relax

Proof of Concept for a sync solution based on Git and Apache CouchDB
Shell
12
star
19

couchdb-configure

Configure CouchDB from file, node module or directory.
JavaScript
12
star
20

http-image-size

Detect image dimensions over http.
JavaScript
10
star
21

hello-gjs-npm

Example application demonstrating the use of Babel and Rollup to create an NPM installable and -runnable Gjs executable from ES2015 project source
JavaScript
10
star
22

couchdb-secure

Write couchdb security object from file or directory.
JavaScript
9
star
23

worker-fetch-tweets

Fetch tweets and store them in a CouchDB.
JavaScript
8
star
24

couch-box

Asymmetric encrypted CouchDB documents, powered by NaCl's curve25519-xsalsa20-poly1305.
JavaScript
7
star
25

massage-couch

Massage CouchDB documents with an os daemon worker.
JavaScript
7
star
26

microcouch-rs

A minimal Pouch-like implementation of a CouchDB compatible embeddable couch. Work in progress.
Rust
5
star
27

multipart-related

Parse `multipart/related` responses in the browser
JavaScript
5
star
28

connect-nano

req.nano, which passes session cookies to CouchDB and back again.
JavaScript
5
star
29

microcouch-js

A minimal Pouch-like implementation of a CouchDB compatible in-browser couch, for educational purpose.
JavaScript
4
star
30

couchdb-ensure

Create database unless it exists.
JavaScript
4
star
31

couch64

Handle base64 encoding and decoding inside CouchDB, eg. in list functions.
JavaScript
4
star
32

webcryptobox-rs

Utility library and CLI for WebCrypto compatible encryption
Rust
4
star
33

webcryptobox

WebCrypto compatible encryption libraries and CLIs
4
star
34

worker-generate-previews

CouchDB worker to generate previews from pdf
JavaScript
4
star
35

worker-generate-thumbnails

CouchDB worker which generates image thumbnails.
JavaScript
3
star
36

couch-daemon-bridge

Use CouchDBs os_daemons with node.
JavaScript
3
star
37

pouchdb-live-query

Provide a view which keeps itself up to date by listening to the changes feed.
JavaScript
3
star
38

global-couch-stream

Readable changes feed stream from all databases
JavaScript
3
star
39

sync-tank

Describing strategies for migrations in a distributed CouchDB world.
CSS
3
star
40

minip

Mini P is a simple database that can replicate with CouchDB.
JavaScript
3
star
41

worker-generate-stills

CouchDB worker which generates stills from videos.
JavaScript
3
star
42

i18n-tools

Tools for merging, collecting and converting i18n translations.
Ruby
3
star
43

couch-nacl-permit

Handle database permits, which encrypts a database key with a session key. For use with couch-box.
JavaScript
2
star
44

couchmagick-stream

Pipe CouchDB documents through ImageMagicks convert.
JavaScript
2
star
45

couchdb-cors-config

JavaScript
2
star
46

coup.js

Tiny script plays client side with CouchDB rewrites, lists and shows.
JavaScript
2
star
47

worker-convert

CouchDB worker which converts images
JavaScript
2
star
48

couchdb-create-index

Create CouchDB index from file or directory.
JavaScript
2
star
49

couchdb-bulk

Pipe line-seperated JSON into CouchDB
JavaScript
2
star
50

worker-fetch-json

A hoodie worker that fetches a remote JSON and inserts it into a document.
JavaScript
2
star
51

couchnacl

Use TweetNaCl.js from inside CouchDB
JavaScript
2
star
52

googlefontcssmerge

Download google font css with different user agents and combine src attributes.
JavaScript
2
star
53

couchdb-global-changes-stream

Multiplexed persisted global couchdb changes stream across all databases.
JavaScript
2
star
54

dimensionist

CouchDB daemon to extract dimensions from image attachments.
JavaScript
2
star
55

rouchdb

Minimal CouchDB compatible database written in Rust.
Rust
2
star
56

googlefontcss64

Download Google fonts and print base64 embedded style definitions.
JavaScript
2
star
57

couchdb-global-changes-rs

A global changes feed CLI in Rust [experimental]
Rust
1
star
58

urs

Ultra Responsive Slider
JavaScript
1
star
59

autoprogettazione-dinamica

JavaScript
1
star
60

tita

Things I Threw Away
HTML
1
star
61

gtk-rs-with-icons-resource

Demo project about how to work with icons and gresources on Rust GTK.
Rust
1
star
62

couchdb-flatpak-example

Example Flatpak application with CouchDB included
Shell
1
star
63

nosta

Skeleton for a small single page application based on dynamic imports
JavaScript
1
star
64

filander

Helps dealing with files and directories
Ruby
1
star
65

grunt-init-couch

Create a Couch project with grunt-init, including Nodeunit unit tests.
JavaScript
1
star
66

lena

Slick minimalistic Content Management System for artists and others.
JavaScript
1
star
67

worker-attachments

General attachments CouchDB worker.
JavaScript
1
star
68

trovebox-uploader

Upload images to trovebox like a pro
Ruby
1
star
69

tfcss

Use Cascading Style Sheets in Ruby.
Ruby
1
star
70

enzo-mari

Enzo Mari's Tavolo Rettangolare in your own dimensions
JavaScript
1
star
71

shnell

Server Setup and Configuration tools
Ruby
1
star