es6 and jsx docs

2017-01-07 14:54:48 -05:00 · 2017-01-07 14:54:48 -05:00 · 6284a3bd86
commit 6284a3bd86
parent 26a5d7d6bb
4 changed files with 250 additions and 7 deletions
--- a/docs/es6.md
+++ b/docs/es6.md
@ -0,0 +1,69 @@
+# ES6
+
+Mithril is written in ES5, and is fully compatible with ES6 as well.
+
+In some limited environments, it's possible to use a significant subset of ES6 directly without extra tooling (for example, in internal applications that do not support IE). However, for the vast majority of use cases, a compiler toolchain like [Babel](https://babeljs.io) is required to compile ES6 features down to ES5.
+
+### Setup
+
+The simplest way to setup an ES6 compilation toolchain is via [Babel](https://babeljs.io/). To install, use this command:
+
+```bash
+npm install babel-cli babel-preset-es2015 transform-react-jsx --save-dev
+```
+
+Create a `.babelrc` file:
+
+```
+{
+  "presets": ["es2015"],
+  "plugins": [
+    ["transform-react-jsx", {
+      "pragma": "m"
+    }]
+  ]
+}
+```
+
+To run Babel as a standalone tool, run this from the command line:
+
+```bash
+babel src --out-dir lib --source-maps
+```
+
+#### Using Babel with Webpack
+
+If you're using Webpack as a bundler, you can integrate Babel to Webpack, however this requires some additional dependencies, in addition to the steps above.
+
+```bash
+npm install babel-core babel-loader --save-dev
+```
+
+Create a file called `.webpack.config`
+
+```javascript
+module.exports = {
+    entry: './src/index.js',
+    output: {
+        path: './bin',
+        filename: 'app.js',
+    },
+    module: {
+        loaders: [{
+            test: /\.js$/,
+            exclude: /node_modules/,
+            loader: 'babel-loader'
+        }]
+    }
+}
+```
+
+---
+
+### Custom setups
+
+If you're using Webpack, you can [follow its excellent guide to add support for ES6](https://webpack.github.io/docs/usage.html#transpiling-es2015-using-babel-loader)
+
+If you want to use Babel as a standalone tool, [here's the instructions for how to set it up](https://babeljs.io/docs/setup/#installation).
+
+[Google closure compiler](https://www.npmjs.com/package/google-closure-compiler) is another tool that supports ES6 to ES5 compilation.
--- a/docs/guides.md
+++ b/docs/guides.md
@ -2,6 +2,8 @@
 	- [Installation](installation.md)
 	- [Introduction](introduction.md)
 	- [Tutorial](simple-application.md)
+	- [JSX](jsx.md)
+	- [ES6](es6.md)
 	- [Testing](testing.md)
 	- [Examples](examples.md)
 - Key concepts
--- a/docs/introduction.md
+++ b/docs/introduction.md
@ -25,7 +25,7 @@ Note: This introduction assumes you have basic level of Javacript knowledge. If

 The easiest way to try out Mithril is to include it from a CDN, and follow this tutorial. It'll cover the majority of the API surface but it'll only take 10 minutes.

-Let's create an HTML file to follow along: 
+Let's create an HTML file to follow along:

 ```markup
 <body></body>
@ -91,7 +91,7 @@ m("main", [
 ])
 ```

-Note: If you prefer `<html>` syntax, [it's possible to use it via a Babel plugin](https://babeljs.io/docs/plugins/transform-react-jsx/).
+Note: If you prefer `<html>` syntax, [it's possible to use it via a Babel plugin](jsx.md).

 ```markup
 // HTML syntax via Babel's JSX plugin
@ -236,8 +236,3 @@ Clicking the button should now update the count.
 We covered how to create and update HTML, how to create components, routes for a Single Page Application, and interacted with a server via XHR.

 This should be enough to get you started writing the frontend for a real application. Now that you are comfortable with the basics of the Mithril API, [be sure to check out the simple application tutorial](simple-application.md), which walks you through building a realistic application.
-
-
-
-
-
--- a/docs/jsx.md
+++ b/docs/jsx.md
@ -0,0 +1,177 @@
+# JSX
+
+- [Description](#description)
+- [Setup](#setup)
+- [JSX vs hyperscript](#jsx-vs-hyperscript)
+- [Converting HTML](#converting-html)
+
+---
+
+### Description
+
+JSX is a syntax extension that enables you to write HTML tags interspersed with Javascript.
+
+```
+var MyComponent = {
+  view: function() {
+    return m("main", [
+      m("h1", "Hello world"),
+    ])
+  }
+}
+
+// can be written as:
+var MyComponent = {
+  view: function() {
+    return (
+      <main>
+        <h1>Hello world</h1>
+      </main>
+    )
+  }
+}
+```
+
+When using JSX, it's possible to interpolate Javascript expressions within JSX tags by using curly braces:
+
+```
+var greeting = "Hello"
+var url = "http://google.com"
+var div = <a href={url}>{greeting + "!"}</a>
+```
+
+Components can be used by using a convention of uppercasing the first letter of the component name:
+
+```javascript
+m.mount(document.body, <MyComponent />)
+// equivalent to m.mount(document.body, m(Component))
+```
+
+---
+
+### Setup
+
+The simplest way to use JSX is via a [Babel](https://babeljs.io/) plugin. To install, use this command:
+
+```bash
+npm install babel-cli babel-preset-es2015 transform-react-jsx --save-dev
+```
+
+Create a `.babelrc` file:
+
+```
+{
+  "presets": ["es2015"],
+  "plugins": [
+    ["transform-react-jsx", {
+      "pragma": "m"
+    }]
+  ]
+}
+```
+
+To run Babel as a standalone tool, run this from the command line:
+
+```bash
+babel src --out-dir lib --source-maps
+```
+
+#### Using Babel with Webpack
+
+If you're using Webpack as a bundler, you can integrate Babel to Webpack, however this requires some additional dependencies, in addition to the steps above.
+
+```bash
+npm install babel-core babel-loader --save-dev
+```
+
+Create a file called `.webpack.config`
+
+```javascript
+module.exports = {
+    entry: './src/index.js',
+    output: {
+        path: './bin',
+        filename: 'app.js',
+    },
+    module: {
+        loaders: [{
+            test: /\.js$/,
+            exclude: /node_modules/,
+            loader: 'babel-loader'
+        }]
+    }
+}
+```
+
+---
+
+### JSX vs hyperscript
+
+JSX is essentially a trade-off: it introduces a non-standard syntax that cannot be run without appropriate tooling, in order to allow a developer to write HTML code using curly braces. The main benefit of using JSX instead of regular HTML is that the JSX specification is much stricter and yields syntax errors when appropriate, whereas HTML is far too forgiving and makes syntax issues difficult to spot.
+
+Unlike HTML, JSX is case-sensitive. This means `<div className="test"></div>` is different from `<div classname="test"></div>` (all lower case). The former compiles to `m("div", {className: "test"})` and the latter compiles to `m("div", {classname: "test"})`, which is not a valid way of creating a class attribute). Fortunately, Mithril supports standard HTML attribute names, and thus, this example can be written like regular HTML: `<div class="test"></div>`.
+
+JSX is useful for teams where HTML is primarily written by someone without Javascript experience, but it requires a significant amount of tooling to maintain (whereas plain HTML can, for the most part, simply be opened in a browser)
+
+Hyperscript is the compiled representation of JSX. It's designed to be readable and can also be used as-is, instead of JSX (as is done in most of the documentation). Hyperscript tends to be terser than JSX for a couple of reasons:
+
+1 - it does not require repeating the tag name in closing tags (e.g. `m("div")` vs `<div></div>`)
+2 - static attributes can be written using CSS selector syntax (i.e. `m("a.button")` vs `<div class="button"></div>`
+
+In addition, since hyperscript is plain Javascript, it's often more natural to indent than JSX:
+
+```
+//JSX
+var BigComponent = {
+  activate: function() {/*...*/},
+  deactivate: function() {/*...*/},
+  update: function() {/*...*/},
+  view: function(vnode) {
+    return [
+      {vnode.attrs.items.map(function(item) {
+        return <div>{item.name}</div>
+      })}
+      <div
+        ondragover={this.activate}
+        ondragleave={this.deactivate}
+        ondragend={this.deactivate}
+        ondrop={this.update}
+        onblur={this.deactivate}
+      ></div>
+    ]
+  }
+}
+
+// hyperscript
+var BigComponent = {
+  activate: function() {/*...*/},
+  deactivate: function() {/*...*/},
+  update: function() {/*...*/},
+  view: function(vnode) {
+    return [
+      vnode.attrs.items.map(function(item) {
+        return m("div", item.name)
+      }),
+      m("div", {
+        ondragover: this.activate,
+        ondragleave: this.deactivate,
+        ondragend: this.deactivate,
+        ondrop: this.update,
+        onblur: this.deactivate,
+      })
+    ]
+  }
+}
+```
+
+In non-trivial applications, it's possible for components to have more control flow and component configuration code than markup, making a Javascript-first approach more readable than an HTML-first approach.
+
+Needless to say, since hyperscript is pure Javascript, there's no need to run a compilation step to produce runnable code.
+
+---
+
+### Converting HTML
+
+In Mithril, well-formed HTML is valid JSX. Little effort other than copy-pasting is required to integrate an independently produced HTML file into a project using JSX.
+
+When using hyperscript, it's necessary to convert HTML to hyperscript syntax before the code can be run. To facilitate this, you can [use the HTML-to-Mithril-template converter](http://arthurclemens.github.io/mithril-template-converter/index.html).