diff --git a/README.md b/README.md index 4fa9686e..972749c0 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,270 @@ -# Mithril.js - A framework for building brilliant applications +# Introduction -[Installation](docs/installation.md) | [API](docs/api.md) | [Examples](docs/examples.md) | [Changelog/Migration Guide](docs/change-log.md) +- [What is Mithril?](#what-is-mithril) +- [Getting started](#getting-started) +- [Hello world](#hello-world) +- [DOM elements](#dom-elements) +- [Components](#components) +- [Routing](#routing) +- [XHR](#xhr) -Note: This branch is the upcoming version 1.0. It's a rewrite from the ground up and it's not backwards compatible with [Mithril 0.2.x](http://mithril.js.org). You can find preliminary [documentation here](docs) and [migration guide here](docs/change-log.md) +--- -This rewrite aims to fix longstanding API design issues, significantly improve performance, and clean up the codebase. +### What is Mithril? -## Early Preview +Mithril is a modern client-side Javascript framework for building Single Page Applications. +It's small (< 8kb gzip), fast and provides routing and XHR utilities out of the box. -You can install this via NPM using this command: + +
+
+
Download size
+ Mithril (8kb) +
+ Vue + Vue-Router + Vuex + fetch (40kb) +
+ React + React-Router + Redux + fetch (64kb) +
+ Angular (135kb) +
+
+
+
Performance
+ Mithril (6.4ms) +
+ Vue (9.8ms) +
+ React (12.1ms) +
+ Angular (11.5ms) +
+
+
-``` -npm install mithril@rewrite +Mithril is used by companies like Vimeo and Nike, and open source platforms like Lichess. + +If you are an experienced developer and want to know how Mithril compares to other frameworks, see the [framework comparison](http://mithril.js.org/framework-comparison.html) page. + +--- + +### Getting started + +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 (including routing and XHR) but it'll only take 10 minutes. + +Let's create an HTML file to follow along: + +```markup + + + ``` -Examples run out of the box. Just open the HTML files. +--- -## Status +### Hello world -The code is fairly stable and I'm using it in production, but there may be bugs still lurking. +Let's start as small as well can: render some text on screen. Copy the code below into your file (and by copy, I mean type it out - you'll learn better) -Some examples of usage can be found in the [examples](examples) folder. [ThreadItJS](http://cdn.rawgit.com/lhorie/mithril.js/rewrite/examples/threaditjs/index.html) has the largest API surface coverage. +```javascript +var root = document.body -Partial documentation can be found in the [`/docs`](docs) directory +m.render(root, "Hello world") +``` -## Performance +Now, let's change the text to something else. Add this line of code under the previous one: -Mithril's virtual DOM engine is around 500 lines of well organized code and it implements a modern search space reduction diff algorithm and a DOM recycling mechanism, which translate to top-of-class performance. See the [dbmon implementation](http://cdn.rawgit.com/lhorie/mithril.js/rewrite/examples/dbmonster/mithril/index.html) (for comparison, here are dbmon implementations for [React v15.3.2](http://cdn.rawgit.com/lhorie/mithril.js/rewrite/examples/dbmonster/react/index.html), [Angular v2.0.0-beta.17](http://cdn.rawgit.com/lhorie/mithril.js/rewrite/examples/dbmonster/angular/index.html) and [Vue 2](http://cdn.rawgit.com/lhorie/mithril.js/rewrite/examples/dbmonster/vue/index.html). All implementations are naive (i.e. apples-to-apples, no optimizations) +```javascript +m.render(root, "My first app") +``` -## Robustness +As you can see, you use the same code to both create and update HTML. Mithril automatically figures out the most efficient way of updating the text, rather than blindly recreating it from scratch. -There are over 4000 assertions in the test suite, and tests cover even difficult-to-test things like `location.href`, `element.innerHTML` and `XMLHttpRequest` usage. +--- -## Modularity +### DOM elements -Despite the huge improvements in performance and modularity, the new codebase is smaller than v0.2.x, currently clocking at 7.61 KB min+gzip +Let's wrap our text in an `

` tag. -In addition, Mithril is now completely modular: you can import only the modules that you need and easily integrate 3rd party modules if you wish to use a different library for routing, ajax, and even rendering +```javascript +m.render(root, m("h1", "My first app")) +``` + +The `m()` function can be used to describe any HTML structure you want. So if you to add a class to the `

`: + +```javascript +m("h1", {class: "title"}, "My first app") +``` + +If you want to have multiple elements: + +```javascript +[ + m("h1", {class: "title"}, "My first app"), + m("button", "A button"), +] +``` + +And so on: + +```javascript +m("main", [ + m("h1", {class: "title"}, "My first app"), + m("button", "A button"), +]) +``` + +Note: If you prefer `` syntax, [it's possible to use it via a Babel plugin](http://mithril.js.org/jsx.html). + +```jsx +// HTML syntax via Babel's JSX plugin +
+

My first app

+ +
+``` + +--- + +### Components + +A Mithril component is just an object with a `view` function. Here's the code above as a component: + +```javascript +var Hello = { + view: function() { + return m("main", [ + m("h1", {class: "title"}, "My first app"), + m("button", "A button"), + ]) + } +} +``` + +To activate the component, we use `m.mount`. + +```javascript +m.mount(root, Hello) +``` + +As you would expect, doing so creates this markup: + +```markup +
+

My first app

+ +
+``` + +The `m.mount` function is similar to `m.render`, but instead of rendering some HTML only once, it activates Mithril's auto-redrawing system. To understand what that means, let's add some events: + +```javascript +var count = 0 // added a variable + +var Hello = { + view: function() { + return m("main", [ + m("h1", {class: "title"}, "My first app"), + // changed the next line + m("button", {onclick: function() {count++}}, count + " clicks"), + ]) + } +} + +m.mount(root, Hello) +``` + +We defined an `onclick` event on the button, which increments a variable `count` (which was declared at the top). We are now also rendering the value of that variable in the button label. + +You can now update the label of the button by clicking the button. Since we used `m.mount`, you don't need to manually call `m.render` to apply the changes in the `count` variable to the HTML; Mithril does it for you. + +If you're wondering about performance, it turns out Mithril is very fast at rendering updates, because it only touches the parts of the DOM it absolutely needs to. So in our example above, when you click the button, the text in it is the only part of the DOM Mithril actually updates. + +--- + +### Routing + +Routing just means going from one screen to another in an application with several screens. + +Let's add a splash page that appears before our click counter. First we create a component for it: + +```javascript +var Splash = { + view: function() { + return m("a", {href: "#!/hello"}, "Enter!") + } +} +``` + +As you can see, this component simply renders a link to `#!/hello`. The `#!` part is known as a hashbang, and it's a common convention used in Single Page Applications to indicate that the stuff after it (the `/hello` part) is a route path. + +Now that we going to have more than one screen, we use `m.route` instead of `m.mount`. + +```javascript +m.route(root, "/splash", { + "/splash": Splash, + "/hello": Hello, +}) +``` + +The `m.route` function still has the same auto-redrawing functionality that `m.mount` does, and it also enables URL awareness; in other words, it lets Mithril know what to do when it sees a `#!` in the URL. + +The `"/splash"` right after `root` means that's the default route, i.e. if the hashbang in the URL doesn't point to one of the defined routes (`/splash` and `/hello`, in our case), then Mithril redirects to the default route. So if you open the page in a browser and your URL is `http://localhost`, then you get redirected to `http://localhost/#!/splash`. + +Also, as you would expect, clicking on the link on the splash page takes you to the click counter screen we created earlier. Notice that now your URL will point to `http://localhost/#!/hello`. You can navigate back and forth to the splash page using the browser's back and next button. + +--- + +### XHR + +Basically, XHR is just a way to talk to a server. + +Let's change our click counter to make it save data on a server. For the server, we'll use [REM](http://rem-rest-api.herokuapp.com), a mock REST API designed for toy apps like this tutorial. + +First we create a function that calls `m.request`. The `url` specifies an endpoint that represents a resource, the `method` specifies the type of action we're taking (typically the `PUT` method [upserts](https://en.wiktionary.org/wiki/upsert)), `data` is the payload that we're sending to the endpoint and `useCredentials` means to enable cookies (a requirement for the REM API to work) + +```javascript +var count = 0 +var increment = function() { + m.request({ + method: "PUT", + url: "http://rem-rest-api.herokuapp.com/api/tutorial/1", + data: {count: count + 1}, + useCredentials: true, + }) + .then(function(data) { + count = parseInt(data.count) + }) +} +``` + +Calling the increment function [upserts](https://en.wiktionary.org/wiki/upsert) an object `{count: 1}` to the `/api/tutorial/1` endpoint. This endpoint returns an object with the same `count` value that was sent to it. Notice that the `count` variable is only updated after the request completes, and it's updated with the response value from the server now. + +Let's replace the event handler in the component to call the `increment` function instead of incrementing the `count` variable directly: + +```javascript +var Hello = { + view: function() { + return m("main", [ + m("h1", {class: "title"}, "My first app"), + m("button", {onclick: increment}, count + " clicks"), + ]) + } +} +``` + +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](http://mithril.js.org/simple-application.html), which walks you through building a realistic application. diff --git a/docs/generate.js b/docs/generate.js index 819ef0f7..691a1040 100644 --- a/docs/generate.js +++ b/docs/generate.js @@ -8,6 +8,8 @@ try {fs.mkdirSync("../mithril/archive")} catch (e) {} try {fs.mkdirSync("../mithril/archive/v" + version)} catch (e) {} try {fs.mkdirSync("../mithril/archive/v" + version + "/lib")} catch (e) {} try {fs.mkdirSync("../mithril/archive/v" + version + "/lib/prism")} catch (e) {} +try {fs.mkdirSync("../mithril/lib")} catch (e) {} +try {fs.mkdirSync("../mithril/lib/prism")} catch (e) {} var guides = fs.readFileSync("docs/guides.md", "utf-8") var methods = fs.readFileSync("docs/methods.md", "utf-8") @@ -45,7 +47,9 @@ function generate(pathname) { }) // fix links var markedHtml = marked(fixed) .replace(/(\W)Array<([^/<]+?)>/gim, "$1Array<$2>") // Fix type signatures containing Array<...> + var title = fixed.match(/^#([^\n\r]+)/i) || [] var html = layout + .replace(/Mithril\.js<\/title>/, "<title>" + title[1] + " - Mithril.js") .replace(/\[version\]/, version) // update version .replace(/\[body\]/, markedHtml) .replace(/

([^<]+?)<\/h5>/gim, function(match, id, text) { // fix anchors diff --git a/docs/index.md b/docs/index.md index d6d41ddc..63ec90da 100644 --- a/docs/index.md +++ b/docs/index.md @@ -60,7 +60,7 @@ Let's create an HTML file to follow along: ```markup - + + ``` --- @@ -19,7 +19,7 @@ If you're new to Javascript or just want a very simple setup to get your feet we ```bash # 1) install -npm install mithril@rewrite --save +npm install mithril --save npm install webpack --save @@ -55,7 +55,7 @@ npm init --yes Then, to install Mithril, run: ```bash -npm install mithril@rewrite --save +npm install mithril --save ``` This will create a folder called `node_modules`, and a `mithril` folder inside of it. It will also add an entry under `dependencies` in the `package.json` file @@ -178,7 +178,7 @@ Live reload is a feature where code changes automatically trigger the page to re ```bash # 1) install -npm install mithril@rewrite --save +npm install mithril --save npm install budo -g # 2) add this line into the scripts section in package.json diff --git a/docs/layout.html b/docs/layout.html index 86cc52ac..8d700312 100644 --- a/docs/layout.html +++ b/docs/layout.html @@ -9,7 +9,8 @@
-

Mithril [version]

+ ≡ +

Mithril [version]

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/style.css b/docs/style.css index 5d122052..de95df75 100644 --- a/docs/style.css +++ b/docs/style.css @@ -10,6 +10,7 @@ h2 {font-size:22px;margin:45px 0 15px;} h3 {font-size:20px;margin:45px 0 15px;} h4 {font-size:18px;margin:30px 0 15px;} h5 {font-weight:bold;margin:15px 0 15px;} +h1 img {transform:rotate(180deg);vertical-align:middle;width:20px;} h1 small {font-size:16px;} p {margin:0 0 15px;} pre,code {background:#eee;font-family:monospace;font-size:14px;} @@ -35,10 +36,17 @@ h1 + ul ul {margin:0 0 2px;padding:0 0 0 15px;} h1 + ul ul li {border:0;} h1 + ul strong + ul {border-left:3px solid #1e5799;} +.hamburger {display:none;} + @media (max-width: 767px) { + .hamburger {display:block;font-size:30px;padding:0 10px;position:fixed;right:0;top:0;} + .hamburger:hover {text-decoration:none;} main section {margin:0;} + header section {margin:0 0 20px;position:static;width:auto;} + h1 + ul {background:#eee;border:1px solid #ccc;box-sizing:border-box;display:none;height:100%;margin:0;overflow:auto;padding:20px;position:fixed;right:0;top:0;width:100%;} h1 + ul + hr {display:block;} - header section,h1 + ul {margin:0 0 20px;position:static;width:auto;} + .navigating h1 + ul {display:block;} + .navigating {overflow:hidden;} } @media (max-width: 1024px) { table,table tbody,table tr,table th,table td {display:block;} @@ -62,3 +70,7 @@ h1 + ul strong + ul {border-left:3px solid #1e5799;} #vue ~ table td:nth-child(1):before {content:"Vue:";} #comparisons ~ table td:nth-child(2):before {content:"Mithril:";} } +@media print { + nav,h1 + ul {display:none;} + main section {margin:0;} +} diff --git a/package.json b/package.json index 1c0bcaca..7e7a4032 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "A framework for building brilliant applications", "author": "Leo Horie", "license": "MIT", - "main": "index.js", + "main": "mithril.js", "repository": "lhorie/mithril.js", "scripts": { "dev": "node bundler/cli browser.js -o mithril.js -w", @@ -18,7 +18,7 @@ "posttest": "npm run lint || true", "cover": "istanbul cover --print both ospec/bin/ospec", "preversion": "npm run test", - "version": "npm run build && git add mithril.js mithril.min.js", + "version": "npm run build && npm run gendocs && git add mithril.js mithril.min.js", "postversion": "git push --follow-tags" }, "devDependencies": { @@ -26,9 +26,6 @@ "istanbul": "^0.4.3", "marked": "^0.3.6" }, - "publishConfig": { - "tag": "rewrite" - }, "bin": { "ospec": "./ospec/bin/ospec", "bundle": "./bundler/bin/bundle"