d38119ce by Michael Richards

Update README.md.

1 parent 37b8033f
Showing 1 changed file with 64 additions and 44 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 (1.2KB minified and gzipped), 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 such as [Backbone.js](http://backbonejs.org), [Spine.js](http://spinejs.com) and [Stapes.js](http://hay.github.com/stapes/). 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 ---
6 6
7 Rivets.js is alpha software. While it should work well enough for prototyping and weekend projects, it is still undergoing major development. APIs are subject to change. 7 Describe your UI directly in the DOM using data attributes:
8 8
9 ## Usage 9 <div id='auction'>
10 <h1 data-text='auction.title'></h1>
11 <img data-src='auction.image_url'>
12 <span data-text='auction.timeRemaining | time'></span>
10 13
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. 14 <div class='alert-box' data-show='auction.endingSoon'>
15 <p>Hurry up! This auction is ending soon.</p>
16 </div>
12 17
13 The `bind` function takes two arguments; the parent DOM element that you wish to bind to and a set of context objects. 18 <dl>
19 <dt>Highest Bid:</dt>
20 <dd data-text='auction.bid | currency'></dd>
21 <dt>Bidder:</dt>
22 <dd data-text='auction.bidder'></dd>
23 </dl>
14 24
15 rivets.bind(el, {user: currentUser, item: item}); 25 <dl>
26 <dt>Bids Left:</dt>
27 <dd data-text='user.bidCount'></dd>
28 </dl>
29 </div>
16 30
17 Context objects are referenced in your data-binding declarations using dot-notation: 31 Then tell Rivets.js what model(s) to bind to what part of the DOM:
18 32
19 <input type="text" data-value="user.email"> 33 rivets.bind($('auction'), {auction: auction, user: currentUser});
20 <input type="checkbox" data-enabled="item.active">
21 34
22 Configuring Rivets.js is required before anything can be bound, as binding is dependant on having an adapter defined. Here's a sample configuration for using Rivets.js with Backbone.js. 35 ## Configuring
36
37 Use `rivets.configure` to configure Rivets.js for your app. There are a few handy configuration options, such as setting the data attribute prefix and adding formatters that you can pipe binding values to, but setting the adapter is the only required configuration since Rivets.js needs to know how to observe your models for changes as they happen.
38
39 #### Adapter
40
41 Rivets.js is model interface-agnostic, meaning it can work with any event-driven model by way of defining an adapter. An adapter is just an object that responds to `subscribe`, `read` and `publish`. Here is a sample configuration with an adapter for using Rivets.js with Backbone.js.
23 42
24 rivets.configure({ 43 rivets.configure({
25 adapter: { 44 adapter: {
...@@ -35,46 +54,47 @@ Configuring Rivets.js is required before anything can be bound, as binding is de ...@@ -35,46 +54,47 @@ Configuring Rivets.js is required before anything can be bound, as binding is de
35 } 54 }
36 }); 55 });
37 56
38 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 incoming value from the observed context object. 57 #### Formatters
39
40 rivets.register('active', function(el, value){
41 el.className = value ? 'active' : 'inactive';
42 });
43
44 #### Available bindings:
45 58
46 - **data-text**: one-way binding that sets the node's text. 59 Formatters are simple one-way functions that mutate the incoming value of a binding. You can use them to format dates, numbers, currencies, etc. and because they work in a similar fashion to the Unix pipeline, the output of each feeds directly as input to the next one, so you can stack as many of them together as you like.
47 - **data-html**: one-way binding that sets the node's html content.
48 - **data-value**: two-way binding that sets the node's value.
49 - **data-show**: one-way binding that sets the node's display state.
50 - **data-hide**: one-way inverse binding that sets the node's display state.
51 - **data-enabled**: one-way binding that sets the node's enabled state.
52 - **data-disabled**: one-way inverse binding that sets the node's enabled state.
53 - **data-checked**: two-way binding that sets the node's checked state.
54 - **data-unchecked**: two-way inverse binding that sets the node's checked state.
55 - **data-selected**: two-way binding that sets the node's selected state.
56 - **data-unselected**: two-way inverse binding that sets the node's checked state.
57 - **data-[attribute]**: one-way binding that sets the node's attribute value.
58 60
59 ## Adapters 61 rivets.configure({
62 formatters: {
63 money: function(value){
64 return accounting.formatMoney(value);
65 },
66 date: function(value){
67 return moment(value).format('MMM DD, YYYY');
68 }
69 }
70 });
60 71
61 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. 72 #### Prefix and data preloading
62 73
63 An adapter is just an object that responds to `subscribe`, `read` and `publish`. 74 To prevent data attribute collision, you can set the `prefix` option to something like 'rv' or 'bind' so that data attributes are prefixed like `data-rv-text`.
64 75
65 #### subscribe(obj, keypath, callback) 76 Set the `preloadData` option to `true` or `false` depending on if you want the binding routines to run immediately after the initial binding or not — if set to false, the binding routines will only run when the attribute value is updated.
66 77
67 - **obj**: The model object that we want to subscribe to for attribute changes. These are what get passed in as context objects when calling `rivets.bind`. 78 ## Extending
68 - **keypath**: The attribute name that we want to scope to when subscribing to the model's attribute changes. This would most commonly be a single key or a nested keypath (support for nested keypaths depends on if your model object publishes events on nested attribute changes). You may define and intercept this value in any format, for example if your model object uses `author[profile][bio]` instead of `author.profile.bio`.
69 - **callback**: The function that performs the binding routine. Call this function with the new attribute value.
70 79
71 #### read(obj, keypath) 80 You can extend Rivets.js by adding your own custom data bindings (routines). Just pass `rivets.register` an identifier for the routine and routine function. Routine functions take two arguments, `el` which is the DOM element and `value` which is the incoming value of the attribute being bound to.
72 81
73 - **obj**: The model object that we want to read the attribute from. 82 So let's say we wanted a `data-color` binding that sets the element's colour. Here's what that might look like:
74 - **keypath**: The attribute name that we want to read from the model object.
75 83
76 #### publish(obj, keypath, value) 84 rivets.register('color', function(el, value){
85 el.style.color = value;
86 });
77 87
78 - **obj**: The model object that we want to set the new attribute value on.
79 - **keypath**: The attribute name that we want to set on the model object.
80 - **value**: The new attribute value that we want to set on the model.
...\ No newline at end of file ...\ No newline at end of file
88 #### Available bindings out-of-the-box
89
90 - data-text
91 - data-html
92 - data-value
93 - data-show
94 - data-hide
95 - data-enabled
96 - data-disabled
97 - data-checked
98 - data-unchecked
99 - data-selected
100 - data-[attribute]
...\ No newline at end of file ...\ No newline at end of file
......