improve docs
This commit is contained in:
Leo Horie
parent
33dcf641fc
commit
6a9bfdca88
2 changed files with 62 additions and 22 deletions
|
|
@ -2,13 +2,31 @@
|
|||
|
||||
---
|
||||
|
||||
Components are the building blocks of Mithril applications: they allow developers to encapsulate functionality into reusable units.
|
||||
- [Rendering components](#rendering-components)
|
||||
- [Optional controller](#optional-controller)
|
||||
- [Controller as a class constructor](#controller-as-a-class-constructor)
|
||||
- [Notes on the view function](#notes on the view function)
|
||||
- [Parameterized components](#parameterized-components)
|
||||
- [Nesting components](#nesting-components)
|
||||
- [Dealing with state](#dealing-with-state)
|
||||
- [Stateless components](#stateless-components)
|
||||
- [Stateful components](#stateful-components)
|
||||
- [Parameterized initial state](#parameterized-initial-state)
|
||||
- [Data-driven component identity](#data-driven-component-identity)
|
||||
- [Unloading components](#unloading-components)
|
||||
- [Nested asynchronous components](#nested-asynchronous-components)
|
||||
- [Limitations and caveats](#limitations-and-caveats)
|
||||
- [Opting out of auto-redrawing](#opting-out-of-auto-redrawing)
|
||||
- [Signature](#signature)
|
||||
---
|
||||
|
||||
Components are building blocks for Mithril applications. They allow developers to encapsulate functionality into reusable units.
|
||||
|
||||
---
|
||||
|
||||
### Rendering components
|
||||
|
||||
In Mithril, a component is nothing more than an object that has a `controller` and a `view` functions.
|
||||
In Mithril, a component is nothing more than an object that has a `view` functions and, optionally, a `controller` function.
|
||||
|
||||
```javascript
|
||||
var MyComponent = {
|
||||
|
|
@ -20,13 +38,45 @@ var MyComponent = {
|
|||
}
|
||||
}
|
||||
|
||||
m.mount(document.body, MyComponent) // renders <h1>Hello</h1>
|
||||
m.mount(document.body, MyComponent) // renders <h1>Hello</h1> into <body>
|
||||
```
|
||||
|
||||
The `controller` function creates an object that is meant to contain methods for a view to call. Those methods (and the `controller` function itself) may call model methods, and the controller may be used to store contextual data returned from model methods (for example, a [promise](mithril.deferred.md) from a [request](mithril.request.md)).
|
||||
The `controller` function, if present, creates an object that is meant to contain methods for a view to call. Those methods (and the `controller` function itself) may call model methods, and the controller may be used to store contextual data returned from model methods (for example, a [promise](mithril.deferred.md) from a [request](mithril.request.md)), or a reference to a view model.
|
||||
|
||||
The `view` function creates a representation of a template that may consume model data and call controller methods to affect the model.
|
||||
|
||||
```javascript
|
||||
//a simple MVC example
|
||||
|
||||
//a sample model that exposes a value
|
||||
var model = {count: 0}
|
||||
|
||||
var MyComponent = {
|
||||
controller: function(data) {
|
||||
return {
|
||||
increment: function() {
|
||||
//This is a simplication for the sake of the example.
|
||||
//Typically, values are modified via model methods,
|
||||
//rather than modified directly
|
||||
model.count++
|
||||
}
|
||||
}
|
||||
},
|
||||
view: function(ctrl) {
|
||||
return m("a[href=javascript:;]", {
|
||||
onclick: ctrl.increment //view calls controller method on click
|
||||
}, "Count: " + model.count)
|
||||
}
|
||||
}
|
||||
|
||||
m.mount(document.body, MyComponent)
|
||||
|
||||
//renders:
|
||||
//<a href="javascript:;">Count: 0</a>
|
||||
//
|
||||
//the number increments when the link is clicked
|
||||
```
|
||||
|
||||
Note that there's no requirement to tightly couple a controller and view while organizing code. It's perfectly valid to define controllers and views separately, and only bring them together when mounting them:
|
||||
|
||||
```javascript
|
||||
|
|
@ -48,9 +98,7 @@ There are three ways to render a component: via [`m.route`](mithril.route.md) (i
|
|||
|
||||
When a component is rendered, the `controller` function is called, then the `view` function is called. The return value of the `controller` function is passed to `view` as its first argument.
|
||||
|
||||
---
|
||||
|
||||
### Optional controller
|
||||
#### Optional controller
|
||||
|
||||
The `controller` function is optional and defaults to an empty function.
|
||||
|
||||
|
|
@ -65,9 +113,7 @@ var MyComponent = {
|
|||
m.mount(document.body, MyComponent) // renders <h1>Hello</h1>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Controller as a class constructor
|
||||
#### Controller as a class constructor
|
||||
|
||||
A controller can also be used as a class constructor (i.e. it's possible to attach properties to the `this` object within the constructor, instead of returning a value.
|
||||
|
||||
|
|
@ -84,9 +130,7 @@ var MyComponent = {
|
|||
m.mount(document.body, MyComponent) // renders <h1>Hello</h1>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Notes on the view function
|
||||
#### Notes on the view function
|
||||
|
||||
The `view` function does not create a DOM tree when called. The return value of the view function is merely a plain Javascript data structure that represents a DOM tree. Internally, Mithril uses this data representation of the DOM to probe for data changes and update the DOM only where necessary. This rendering technique is known as *virtual DOM diffing*.
|
||||
|
||||
|
|
@ -447,7 +491,7 @@ There are [different ways to organize components](#application-architecture-with
|
|||
|
||||
---
|
||||
|
||||
### Nested component limitations and caveats
|
||||
### Limitations and caveats
|
||||
|
||||
There are a few caveats when nesting components:
|
||||
|
||||
|
|
|
|||
|
|
@ -291,14 +291,12 @@ m("a[href='/dashboard']", {config: m.route}, "Dashboard");
|
|||
|
||||
The `config` mechanism can also be used to put focus on form inputs, and call methods that would not be possible to execute via the regular attribute syntax.
|
||||
|
||||
It is only meant to be used to call methods on DOM elements that cannot be called otherwise.
|
||||
|
||||
It is NOT a "free out-of-jail card". You should not use this method to modify element properties that could be modified via the `attributes` argument, nor values outside of the DOM element in question.
|
||||
|
||||
Also note that the `config` callback only runs after a rendering lifecycle is done. Therefore, you should not use `config` to modify controller and model values, if you expect these changes to render immediately. Changes to controller and model values in this fashion will only render on the next `m.render` or `m.mount` call.
|
||||
|
||||
You can use this mechanism to attach custom event listeners to controller methods (for example, when integrating with third party libraries), but you are responsible for making sure the integration with Mithril's autoredrawing system is in place. See the [integration guide](integration.md) for more information.
|
||||
|
||||
You can also use it to attach events to other elements (for example, `window.onresize`), but you should remove such event handlers via `ctx.onunload` to avoid surprises.
|
||||
|
||||
---
|
||||
|
||||
#### Persisting config data
|
||||
|
|
@ -578,13 +576,11 @@ where:
|
|||
|
||||
The `config` mechanism can also be used to put focus on form inputs, and call methods that would not be possible to execute via the regular attribute syntax.
|
||||
|
||||
It is only meant to be used to call methods on DOM elements that cannot be called otherwise.
|
||||
|
||||
It is NOT a "free out-of-jail card". You should not use this method to modify element properties that could be modified via the `attributes` argument, nor values outside of the DOM element in question.
|
||||
|
||||
Also note that the `config` callback only runs after a rendering lifecycle is done. Therefore, you should not use `config` to modify controller and model values, if you expect these changes to render immediately. Changes to controller and model values in this fashion will only render on the next `m.render` or `m.mount` call.
|
||||
|
||||
You can use this mechanism to attach custom event listeners to controller methods (for example, when integrating with third party libraries), but you are responsible for making sure the integration with Mithril's autoredrawing system is in place. See the [integration guide](integration.md) for more information.
|
||||
|
||||
You can also use it to attach events to other elements (for example, `window.onresize`), but you should remove such event handlers via `ctx.onunload` to avoid surprises.
|
||||
|
||||
- **DOMElement element**
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue