changes in the docs: rename modules to components, change idiomatic controller and view usage

This commit is contained in:
Leo Horie 2015-04-06 22:41:38 -04:00
parent 0addce57ba
commit d5619d412e
19 changed files with 395 additions and 692 deletions

View file

@ -9,15 +9,15 @@
---
Redraws the view for the currently active module. Use [`m.module()`](mithril.module.md) to activate a module.
Redraws the view for the currently active component. Use [`m.mount()`](mithril.mount.md) to activate a component.
This method is called internally by Mithril's auto-redrawing system. Usually you don't need to call it manually unless you are doing recurring asynchronous operations (i.e. using `setInterval`) or if you want to decouple slow running background requests from the rendering context (see the `background` option in [`m.request`](mithril.request.md).
By default, if you're using either [`m.route`](mithril.route.md) or [`m.module`](mithril.module.md), `m.redraw()` is called automatically by Mithril's auto-redrawing system once the controller finishes executing.
By default, if you're using either [`m.route`](mithril.route.md) or [`m.mount`](mithril.mount.md), `m.redraw()` is called automatically by Mithril's auto-redrawing system once the controller finishes executing.
`m.redraw` is also called automatically on event handlers defined in virtual elements.
Note that calling this method will not do anything if a module was not activated via either [`m.module()`](mithril.module.md) or [`m.route()`](mithril.route.md). This means that `m.redraw` doesn't do anything when instantiating controllers and rendering views via `m.render` manually.
Note that calling this method will not do anything if a component was not activated via either [`m.mount()`](mithril.mount.md) or [`m.route()`](mithril.route.md). This means that `m.redraw` doesn't do anything when instantiating controllers and rendering views via `m.render` manually.
If there are pending [`m.request`](mithril.request.md) calls in either a controller constructor or event handler, the auto-redrawing system waits for all the AJAX requests to complete before calling `m.redraw`.
@ -42,16 +42,17 @@ When the flag is set to "diff", Mithril performs a diff between the old view and
When the flag is set to "none", Mithril skips the next redraw. You don't need to change this flag to something else again later, since Mithril does that for you.
```javascript
var module1 = {}
module1.controller = function() {
//this module will attempt to diff its template when routing, as opposed to re-creating the view from scratch.
//this allows config contexts to live across route changes, if its element does not need to be recreated by the diff
m.redraw.strategy("diff")
}
module1.view = function() {
return m("h1", {config: module1.config}, "test") //assume all routes display the same thing
}
module1.config = function(el, isInit, ctx) {
var Component1 = m.component({
controller: function() {
//this component will attempt to diff its template when routing, as opposed to re-creating the view from scratch.
//this allows config contexts to live across route changes, if its element does not need to be recreated by the diff
m.redraw.strategy("diff")
},
view: function() {
return m("h1", {config: Component1.config}, "test") //assume all routes display the same thing
}
})
Component1.config = function(el, isInit, ctx) {
if (!isInit) ctx.data = "foo" //we wish to initialize this only once, even if the route changes
}
```
@ -63,31 +64,33 @@ Common reasons why one might need to change redraw strategy are:
```javascript
//diff when routing, instead of redrawing from scratch
//this preserves the `<input>` element and its 3rd party plugin after route changes, since the `<input>` 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 Component1 = m.component({
controller: function() {
m.redraw.strategy("diff")
},
view: function() {
return m("div", [
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
]
}
var Component2 = m.component({
controller: function() {
m.redraw.strategy("diff")
},
view: function() {
return m("div", [
m("h1", "Hello Bar"),
m("input", {config: plugin}) //assuming `plugin` initializes a 3rd party library
])
}
})
m.route(document.body, "/foo", {
"/foo": module1,
"/bar": module2,
"/foo": Component1,
"/bar": Component2,
})
```
@ -109,14 +112,14 @@ Common reasons why one might need to change redraw strategy are:
//view
var view = function() {
return [
return m("div", [
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)
Note that the redraw strategy is a global setting that affects the entire template trees of all components 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)
You can also configure individual elements to always be diffed, instead of recreated from scratch (even across route changes), by using the [`ctx.retain` flag](mithril.md#persising-dom-elements-across-route-changes)
@ -177,7 +180,7 @@ where:
**GetterSetter strategy**
The `m.redraw.strategy` getter-setter indicates how the next module redraw will occur. It can be one of three values:
The `m.redraw.strategy` getter-setter indicates how the next component redraw will occur. It can be one of three values:
- `"all"` - recreates the DOM tree from scratch
- `"diff"` - updates only DOM elements if needed