Update README.md to reflect the new API.
Showing
1 changed file
with
29 additions
and
19 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 | |||
34 | An adapter is 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 | 57 | ||
45 | publish: function(obj, keypath, value) { | 58 | An adapter is just an object that responds to `subscribe`, `read` and `publish`. |
46 | obj.set(keypath, data); | ||
47 | } | ||
48 | } | ||
49 | 59 | ||
50 | #### subscribe(obj, keypath, callback) | 60 | #### subscribe(obj, keypath, callback) |
51 | 61 | ... | ... |
-
Please register or sign in to post a comment