From eea10cfe86a1dc2b014423a30cfa517cdeeeca5f Mon Sep 17 00:00:00 2001
From: Leo Horie <lhorie@klick.com>
Date: Sun, 21 Sep 2014 14:50:14 -0400
Subject: [PATCH] add docs about bidirectional bindings

---
 docs/mithril.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/docs/mithril.md b/docs/mithril.md
index 8047bc58..a70985d7 100644
--- a/docs/mithril.md
+++ b/docs/mithril.md
@@ -3,6 +3,7 @@
 ---
 
 [Usage](#usage)
+[Binding to data](#binding-to-data)
 [Using HTML entities](#using-html-entities)
 [Accessing the real DOM element](#accessing-the-real-dom-element)
 [Persisting config data](#persisting-config-data)
@@ -171,6 +172,39 @@ One caveat of using the CSS syntax is that it clobbers the `style` attribute in
 
 ---
 
+### Binding to data
+
+In order to stay flexible, Mithril doesn't provide helpers for bi-directional bindings out of the box. However, bindings can be implemented easily:
+
+```javascript
+//a data store
+var name = m.prop("")
+
+//binding the data store in a view
+m("input", {oninput: m.withAttr("value", name), value: name()})
+```
+
+In the code above, the `oninput` event handler updates the `name` getter-setter, and the Mithril auto-redrawing system redraws the template in order to update the displayed value. You can read more about the [`m.prop` getter-setter utility here](mithril.prop.md) and the [`m.withAttr` event handler factory here](mithril.withattr.md). You can also [learn how the redrawing system works here](auto-redrawing.md).
+
+Verbosity can be abstracted away using standard refactoring techniques:
+
+```javascript
+//refactor the binding to a simple helper
+var input = function(prop) {
+	return m("input", {oninput: m.withAttr("value", prop), value: prop()})
+}
+
+//a data store
+var name = m.prop("")
+
+//binding the data store in a view
+input(name)
+```
+
+Alternatively, you can also explore other techniques in order to achieve better [performance](http://lhorie.github.io/mithril-blog/asymmetrical-data-bindings.html) and [expressiveness](http://lhorie.github.io/mithril-blog/extending-the-view-language.html).
+
+---
+
 ### Using HTML entities
 
 By default, Mithril escapes HTML strings in order to help prevent XSS attacks.