8da89728 by Michael Richards

Update README.md to reflect the new API.

1 parent 13a1c411
Showing 1 changed file with 30 additions and 20 deletions
1 # Rivets.js 1 # Rivets.js
2 2
3 Rivets.js is a declarative, observer-based DOM-binding facility that plays well with existing frameworks and supports multiple contexts. It aims to be lightweight, extensible, and configurable to work with any event-driven model. 3 Rivets.js is a declarative, observer-based DOM-binding facility that plays well with existing frameworks and supports multiple contexts. It aims to be lightweight (1.2KB minified and gzipped), extensible, and configurable to work with any event-driven model.
4 4
5 ## Disclaimer 5 ## Disclaimer
6 6
...@@ -8,9 +8,33 @@ Rivets.js is alpha software. While it should work well enough for prototyping an ...@@ -8,9 +8,33 @@ Rivets.js is alpha software. While it should work well enough for prototyping an
8 8
9 ## Usage 9 ## Usage
10 10
11 No contrived example here yet, but the `rivets` module is simple. It exposes a single `bind` function that takes three arguements; the parent DOM element that you wish to bind to, an adapter interface, and a set of context objects. 11 No contrived example here yet, but the `rivets` module is simple. It exposes three main functions; a `configure` function that is used to set configuration options and the adapter interface, a `register` function that is used to register custom data bindings and a `bind` function that is used to bind a set of context objects to a DOM element.
12 12
13 rivets.bind(el, adapter, {user: currentUser, item: item}); 13 The `bind` function takes two arguements; the parent DOM element that you wish to bind to and a set of context objects.
14
15 rivets.bind(el, {user: currentUser, item: item});
16
17 Configuring Rivets.js is required before anything can be binded, as binding is dependant on having an adapter defined. Here's a sample configuration for using Rivets.js with Backbone.js.
18
19 rivets.configure({
20 adapter: {
21 subscribe: function(obj, keypath, callback) {
22 obj.on('change:' + keypath, function(m, v) { callback(v) });
23 },
24 read: function(obj, keypath) {
25 obj.get(keypath);
26 },
27 publish: function(obj, keypath, value) {
28 obj.set(keypath, data);
29 }
30 }
31 });
32
33 To add custom data bindings, use the `register` function and pass in an identifier for the binding as well as the binding function. Binding functions take two arguments; `el` which is the DOM element and `value` which is any new incomming value from the observed context object.
34
35 rivets.register('active', function(el, value){
36 el.className = value ? 'active' : 'inactive';
37 });
14 38
15 #### Available bindings: 39 #### Available bindings:
16 40
...@@ -29,23 +53,9 @@ No contrived example here yet, but the `rivets` module is simple. It exposes a s ...@@ -29,23 +53,9 @@ No contrived example here yet, but the `rivets` module is simple. It exposes a s
29 53
30 ## Adapters 54 ## Adapters
31 55
32 Rivets.js is model interface-agnostic, meaning that it can work with any event-driven model by way of defining an adapter. The following standard adapter observes `change:[attribute]` style events and works with frameworks like [Backbone.js](http://documentcloud.github.com/backbone/), [Spine.js](http://spinejs.com/) and [Stapes.js](http://hay.github.com/stapes/) with minimal alterations for each. If your model's events API differs, it's trivial to write an adapter that will work with your own model objects. 56 Rivets.js is model interface-agnostic, meaning it can work with any event-driven model by way of defining an adapter. This makes it trivial to set up Rivets.js to work with frameworks like [Backbone.js](http://documentcloud.github.com/backbone/), [Spine.js](http://spinejs.com/) and [Stapes.js](http://hay.github.com/stapes/) with minimal configuration.
33 57
34 An adapter is an object that responds to `subscribe`, `read` and `publish`. 58 An adapter is just an object that responds to `subscribe`, `read` and `publish`.
35
36 backboneAdapter = {
37 subscribe: function(obj, keypath, callback) {
38 obj.on('change:' + keypath, function(m, v) { callback(v) });
39 },
40
41 read: function(obj, keypath) {
42 obj.get(keypath);
43 },
44
45 publish: function(obj, keypath, value) {
46 obj.set(keypath, data);
47 }
48 }
49 59
50 #### subscribe(obj, keypath, callback) 60 #### subscribe(obj, keypath, callback)
51 61
......