diff --git a/docs/mithril.computation.md b/docs/mithril.computation.md
index 5e835b6b..04241a05 100644
--- a/docs/mithril.computation.md
+++ b/docs/mithril.computation.md
@@ -74,6 +74,71 @@ The reason Mithril waits for all asynchronous services to complete before redraw
It's possible to opt out of the redrawing schedule by using the `background` option for `m.request`, or by simply not calling `m.startComputation` / `m.endComputation` when calling non-Mithril asynchronous functions.
+```javascript
+//`background` option example
+var module = {}
+module.controller = function() {
+ //setting `background` allows the module to redraw immediately, without waiting for the request to complete
+ m.request({method: "GET", url: "/foo", background: true})
+}
+```
+
+It's also possible to modify the strategy that Mithril uses for any given redraw, by using [`m.redraw.strategy`](mithril.redraw.md#changing-redraw-strategy). Note that changing the redraw strategy only affects the next scheduled redraw. After that, Mithril resets the `m.redraw.strategy` flag to either "all" or "diff" depending on whether the redraw was due to a route change or whether it was triggered by some other action.
+
+```javascript
+//diff when routing, instead of redrawing from scratch
+//this preserves the `` element and its 3rd party plugin after route changes, since the `` doesn't change
+var module1 = {}
+module1.controller = function() {
+ m.redraw.strategy("diff")
+}
+module1.view = function() {
+ return [
+ m("h1", "Hello Foo"),
+ m("input", {config: plugin}) //assuming `plugin` initializes a 3rd party library
+ ]
+}
+
+var module2 = {}
+module2.controller = function() {
+ m.redraw.strategy("diff")
+}
+module2.view = function() {
+ return [
+ m("h1", "Hello Bar"),
+ m("input", {config: plugin}) //assuming `plugin` initializes a 3rd party library
+ ]
+}
+
+m.route(document.body, "/foo", {
+ "/foo": module1,
+ "/bar": module2,
+})
+```
+
+```javascript
+//model
+var saved = false
+function save(e) {
+ if (e.keyCode == 13) {
+ //this causes a redraw, since event handlers active auto-redrawing by default
+ saved = true
+ }
+ else {
+ //we don't care about other keys, so don't redraw
+ m.redraw.strategy("none")
+ }
+}
+
+//view
+var view = function() {
+ return [
+ m("button[type=button]", {onkeypress: save}, "Save"),
+ saved ? "Saved" : ""
+ ]
+}
+```
+
---
### Integrating multiple execution threads
diff --git a/docs/mithril.prop.md b/docs/mithril.prop.md
index 235abf22..3f66c345 100644
--- a/docs/mithril.prop.md
+++ b/docs/mithril.prop.md
@@ -69,10 +69,11 @@ m.request({method: "GET", url: "/users"})
### Third-party promise library support
-If a promise is passed into `m.prop()`, its value will populate the prop after resolution.
+If a promise is passed into `m.prop()`, a Mithril promise is returned. Mithril promises are also getter-setter functions, which are populated with the resolved value if the promise is fulfilled successfully.
+
Until the promise is resolved, the value of the prop will resolve to `undefined`
-Example using [Q](https://github.com/kriskowal/q)
+Here's an example using the [Q](https://github.com/kriskowal/q) promise library:
```javascript
var deferred = Q.defer()
@@ -82,6 +83,9 @@ users() // undefined
deferred.resolve("Hello")
users() // Hello
+users.then(function(value) {
+ console.log(value) //Hello
+})
```
---
diff --git a/docs/mithril.redraw.md b/docs/mithril.redraw.md
index bf10a4e9..879503ea 100644
--- a/docs/mithril.redraw.md
+++ b/docs/mithril.redraw.md
@@ -31,6 +31,10 @@ If you are developing an asynchronous model-level service and finding that Mithr
If you need to change how Mithril performs redraws, you can change the value of the `m.redraw.strategy` getter-setter to either `"all"`, `"diff"` or `"none"`. By default, this value is set to `"all"` when running controller constructors, and it's set to `"diff"` for all subsequent redraws.
+The strategy flag is meant to only be changed in a context where Mithril auto-redraws. This means `m.redraw.strategy` can be called from controller constructors and from template event handlers. Note that changing this flag only affects the next scheduled redraw.
+
+After the redraw, Mithril resets the value of the flag to either "all" or "diff", depending on whether the redraw was due to a route change or not.
+
```javascript
var module1 = {}
module1.controller = function() {
@@ -39,17 +43,72 @@ module1.controller = function() {
m.redraw.strategy("diff")
}
module1.view = function() {
- return m("h1", {config: module1.config}, "test")
+ return m("h1", {config: module1.config}, "test") //assume all routes display the same thing
}
module1.config = function(el, isInit, ctx) {
- if (!isInit) ctx.data = "foo"
+ if (!isInit) ctx.data = "foo" //we wish to initialize this only once, even if the route changes
}
```
Common reasons why one might need to change redraw strategy are:
-- in order to avoid the full-page recreation when changing routes, for the sake of performance of global 3rd party components
-- in order to prevent redraw when dealing with `keypress` events where the event's keyCode is not of interest
+- in order to avoid the full-page recreation when changing routes, for the sake of performance of global 3rd party components
+
+ ```javascript
+ //diff when routing, instead of redrawing from scratch
+ //this preserves the `` element and its 3rd party plugin after route changes, since the `` doesn't change
+ var module1 = {}
+ module1.controller = function() {
+ m.redraw.strategy("diff")
+ }
+ module1.view = function() {
+ return [
+ m("h1", "Hello Foo"),
+ m("input", {config: plugin}) //assuming `plugin` initializes a 3rd party library
+ ]
+ }
+
+ var module2 = {}
+ module2.controller = function() {
+ m.redraw.strategy("diff")
+ }
+ module2.view = function() {
+ return [
+ m("h1", "Hello Bar"),
+ m("input", {config: plugin}) //assuming `plugin` initializes a 3rd party library
+ ]
+ }
+
+ m.route(document.body, "/foo", {
+ "/foo": module1,
+ "/bar": module2,
+ })
+ ```
+
+- in order to prevent redraw when dealing with `keypress` events where the event's keyCode is not of interest
+
+ ```javascript
+ //model
+ var saved = false
+ function save(e) {
+ if (e.keyCode == 13) {
+ //this causes a redraw, since event handlers active auto-redrawing by default
+ saved = true
+ }
+ else {
+ //we don't care about other keys, so don't redraw
+ m.redraw.strategy("none")
+ }
+ }
+
+ //view
+ var view = function() {
+ return [
+ m("button[type=button]", {onkeypress: save}, "Save"),
+ saved ? "Saved" : ""
+ ]
+ }
+ ```
Note that the redraw strategy is a global setting that affects the entire template trees of all modules on the page. In order to prevent redraws in *some parts* of an application, but not others, see [subtree directives](mithril.render.md#subtree-directives)
diff --git a/tests/mithril-tests.js b/tests/mithril-tests.js
index e70e1bdc..32a1b704 100644
--- a/tests/mithril-tests.js
+++ b/tests/mithril-tests.js
@@ -592,7 +592,6 @@ function testMithril(mock) {
var firstBefore = root.childNodes[0]
m.render(root, [m("a", {key: 2}), m("br"), m("a", {key: 1})])
var firstAfter = root.childNodes[2]
- console.log(root.childNodes)
return firstBefore == firstAfter && root.childNodes[0].key == 2 && root.childNodes.length == 3
})
test(function() {