## m
---
- [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)
- [Destructors](#destructors)
- [Persisting DOM elements across route changes](#persisting-dom-elements-across-route-changes)
- [SVG](#svg)
- [Dealing with focus](#dealing-with-focus)
- [Dealing with sorting and deleting in lists](#dealing-with-sorting-and-deleting-in-lists)
- [Component shorthand](#component-shorthand)
- [Signature](#signature)
- [The `config` attribute](#the-config-attribute)
---
This is a convenience method to compose virtual elements that can be rendered via [`m.render()`](mithril.render.md).
You are encouraged to use CSS selectors to define virtual elements. See "Signature" section for details.
---
### Usage
You can use simple tag selectors to make templates resemble HTML:
```javascript
m("br"); //yields a virtual element that represents
m("div", "Hello"); //yields
Hello
m("div", {class: "container"}, "Hello"); //yields
Hello
```
Note that the output value from `m()` is not an actual DOM element. In order to turn the virtual element into a real DOM element, you must call [`m.render()`](mithril.render.md).
```javascript
m.render(document.body, m("br")); //puts a in
```
You can also use more complex CSS selectors:
```javascript
m(".container"); //yields
m("#layout"); //yields
m("a[name=top]"); //yields
m("[contenteditable]"); //yields
m("a#google.external[href='http://google.com']", "Google"); //yields Google
```
Each `m()` call creates a virtual DOM element, that is, a Javascript object that represents a DOM element, and which is eventually converted into one.
You can, of course, nest virtual elements:
```javascript
m("ul", [
m("li", "item 1"),
m("li", "item 2"),
]);
/*
yields
item 1
item 2
*/
```
---
The CSS selector syntax (e.g. `a#google.external[href='http://google.com']`) is meant to be used for declaring static attributes in the element, i.e. attribute values that don't change dynamically when the user interacts with the app.
The `attributes` argument (i.e. the second parameter in the `m("div", {class: "container"}, "Hello")` example) is meant to be used for attributes whose values we want to dynamically populate.
For example, let's say that you're generating a link from an entry that comes from a web service:
```javascript
//assume the variable `link` came from a web service
var link = {url: "http://google.com", title: "Google"}
m("a", {href: link.url}, link.title); //yields Google
```
Here's a less trivial example:
```javascript
var links = [
{title: "item 1", url: "/item1"},
{title: "item 2", url: "/item2"},
{title: "item 3", url: "/item3"}
];
m.render(document.body, [
m("ul.nav",
links.map(function(link) {
return m("li",
m("a", {href: link.url}, link.title)
);
})
)
]);
```
yields:
```markup
```
As you can see, flow control is done with vanilla Javascript. This allows the developer to abstract away any aspect of the template at will.
---
Note that you can use both Javascript property names and HTML attribute names to set values in the `attributes` argument, but you should pass a value of appropriate type. If an attribute has the same name in Javascript and in HTML, then Mithril assumes you're setting the Javascript property.
```javascript
m("div", {class: "widget"}); //yields
m("div", {className: "widget"}); //yields
m("button", {onclick: alert}); //yields , which alerts its event argument when clicked
//note this uses the Javascript syntax (uppercase "O") for `readonly`
//in order to set the boolean javascript property instead of the HTML attribute
m("input", {readOnly: true}); //yields
//using the HTML attribute name will call `setAttribute`, which may not be what you want
m("input", {readonly: false}); //yields , which is still readonly
```
---
Note that you can use JSON syntax if the attribute name you are setting has non-alphanumeric characters:
```javascript
m("div", {"data-index": 1}); //yields
```
You can set inline styles like this:
```javascript
m("div", {style: {border: "1px solid red"}}); //yields
```
Note that in order to keep the framework lean, Mithril does not auto-append units like `px` or `%` to any values. Typically, you should not even be using inline styles to begin with (unless you are dynamically changing them).
Mithril also does not auto-camel-case CSS properties on inline style attributes, so you should use the Javascript syntax when setting them via Javascript objects:
```javascript
m("div", {style: {textAlign: "center"}}); //yields
m("div", {style: {cssFloat: "left"}}); //yields
//this does not work
m("div", {style: {"text-align": "center"}});
m("div", {style: {float: "left"}});
```
You can find the [Javascript syntax for all the CSS rules here](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Properties_Reference).
You can, however, use CSS syntax when defining style rules as inline strings:
```javascript
m("div[style='text-align:center']"); //yields
```
One caveat of using the CSS syntax is that it clobbers the `style` attribute in the DOM element on redraws, so this syntax is not appropriate if you need to use it in conjunction with 3rd party tools that modify the element's style outside of Mithril's templates (e.g. via `config`, which is explained below)
---
### 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).
Note that Mithril always considers the model layer data to be canonical. This means that in the code below, the input on screen will overwritten by the model data any time a redraw happens:
```javascript
//note that we are not updating the value of the `name` getter-setter via an event handler
//redraws will always overwrite the current UI value with the value of `name()`
m("input", {value: name()})
```
Expressiveness can be achieved using standard refactoring techniques:
```javascript
//refactor the binding to a simple helper
var binds = function(prop) {
return {oninput: m.withAttr("value", prop), value: prop()}
}
//a data store
var name = m.prop("")
//binding the data store in a view
m("input", binds(name))
```
Here's an example of a more aggressive refactor:
```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.
```javascript
m("div", "×") //becomes
×
```
You can unescape trusted HTML strings by using [`m.trust`](mithril.trust.md)
```javascript
m("div", m.trust("×")) //becomes