From 24b7150b3cebed65c1801ddef3a820ba38132955 Mon Sep 17 00:00:00 2001 From: Leo Horie Date: Sun, 15 Jan 2017 10:35:29 -0500 Subject: [PATCH] tweaks in docs --- docs/animation.md | 2 ++ docs/es6.md | 2 +- docs/framework-comparison.md | 19 ++++++++------ docs/jsx.md | 2 +- docs/route.md | 49 +++++++++++++++++++++++++++++++++--- docs/style.css | 1 + docs/testing.md | 2 +- 7 files changed, 62 insertions(+), 15 deletions(-) diff --git a/docs/animation.md b/docs/animation.md index 2c1f51b6..28c99be1 100644 --- a/docs/animation.md +++ b/docs/animation.md @@ -94,6 +94,8 @@ We can verify that both the enter and exit animations work by mounting the `Togg m.mount(document.body, Toggler) ``` +Note that the `onbeforeremove` hook only fires on the element that loses its `parentNode` when an elements gets detached from the DOM. This behavior is by design and exists to prevent a potential jarring user experience where every conceivable exit animation on the page would run on a route change. If your exit animation is not running, make sure to attach the `onbeforeremove` handler as high up the tree as it makes sense to ensure that your animation code is called. + --- ### Performance diff --git a/docs/es6.md b/docs/es6.md index 2f629223..3c19613f 100644 --- a/docs/es6.md +++ b/docs/es6.md @@ -5,7 +5,7 @@ --- -Mithril is written in ES5, and is fully compatible with ES6 as well. +Mithril is written in ES5, and is fully compatible with ES6 as well. ES6 is a recent update to Javascript that introduces new syntax sugar for various common cases. It's not yet fully supported by all major browsers and it's not a requirement for writing application, but it may be pleasing to use depending on your team's preferences. 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. diff --git a/docs/framework-comparison.md b/docs/framework-comparison.md index 4beb034a..aba09d7c 100644 --- a/docs/framework-comparison.md +++ b/docs/framework-comparison.md @@ -16,15 +16,15 @@ The reality is that most modern frameworks are fast, well-suited to build comple As a rule of thumb, if your team is already heavily invested in another framework/library/stack, it makes more sense to stick with it, unless your team agrees that there's a very strong reason to justify a costly rewrite. -If you're starting something new, do consider giving Mithril a try, if nothing else, to see how much value Mithril adopters have been getting out of 8kb (gzipped) of code. +However, if you're starting something new, do consider giving Mithril a try, if nothing else, to see how much value Mithril adopters have been getting out of 8kb (gzipped) of code. Mithril is used by many well-known companies (e.g. Vimeo, Nike, Fitbit), and it powers large open-sourced platforms too (e.g. Lichess, Flarum). --- ## Why use Mithril? -In one sentence: because **Mithril is pragmatic**. If you don't believe me, take 10 minutes to go over the [guide](introduction.md) to see how much it accomplishes, compared with official guides for other frameworks. +In one sentence: because **Mithril is pragmatic**. The 10 minutes [guide](introduction.md) is a good example: that's how long it takes to get working knowledge of Mithril's virtual DOM system, XHR and routing tools. -Mithril is all about getting stuff done. It comes out of the box with a compact set of tools that you'll likely need for building Single Page Applications, and no distractions. The Mithril API is small and focused, and it's designed to leverage previous knowledge - e.g. view language is Javascript, HTML attributes have no syntax caveats, Promises are Promises, hyperscript selectors mirror CSS and is JSX-compatible, `m.request` option names mirror [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) - all of this so you can get up to speed fast. +Mithril is all about getting work done efficiently. Doing file uploads? [The docs show you how](request.md#file-uploads). Authentication? [Documented too](route.md#authentication). Exit animations? [You got it](animation.md). No extra libraries, no magic. --- @@ -38,9 +38,9 @@ React and Mithril share a lot of similarities. If you already learned React, you - They both organize views via components - They both use Javascript as a flow control mechanism within views -The most obvious difference between React and Mithril is in their scope. React is a view library, so a typical React-based application relies on third-party libraries for routing, XHR and state management. Using a library oriented approach allows developers to customize their stack to precisely match their needs. The not-so-nice way of saying that is that React-based architectures can vary wildly from project to project. +The most obvious difference between React and Mithril is in their scope. React is a view library, so a typical React-based application relies on third-party libraries for routing, XHR and state management. Using a library oriented approach allows developers to customize their stack to precisely match their needs. The not-so-nice way of saying that is that React-based architectures can vary wildly from project to project, and that those projects are that much more likely to cross the 1MB size line. -Mithril has built-in modules for common necessities such as routing and XHR, and the [guide](simple-application.md) demonstrates idiomatic usage. This approach is preferable for teams that value consistency and ease of onboarding. +Mithril has built-in modules for common necessities such as routing and XHR, and the [guide](simple-application.md) demonstrates idiomatic usage. This approach is preferable for teams that value consistency and ease of onboarding. ### Performance @@ -94,11 +94,11 @@ Idiomatic React requires working knowledge of JSX and its caveats, and therefore ### Documentation -React documentation is clear and well written, and includes a good API reference, tutorials for getting started, as well as pages covering various advanced concepts. +React documentation is clear and well written, and includes a good API reference, tutorials for getting started, as well as pages covering various advanced concepts. Unfortunately, since React is limited to being only a view library, its documentation does not explore how to use React idiomatically in the context of a real-life application. As a result, there are many popular state management libraries and thus architectures using React can differ drastically from company to company (or even between projects). Mithril documentation also includes [introductory](introduction.md) [tutorials](simple-application.md), pages about advanced concepts, and an extensive API reference section, which includes input/output type information, examples for various common use cases and advice against misuse and anti-patterns. It also includes a cheatsheet for quick reference. -Unfortunately, since React is limited to being only a view library, its documentation does not explore how to use React in the context of a real-life application. As a result, there are many popular state management libraries and as a result, architectures using React can differ drastically from company to company (or even between projects). +Mithril documentation also demonstrates simple, close-to-the-metal solutions to common use cases in real-life applications where it's appropriate to inform a developer that web standards may be now on par with larger established libraries. --- @@ -149,6 +149,9 @@ Angular 2 documentation provides an extensive introductory tutorial, and another Mithril documentation includes [introductory](introduction.md) [tutorials](simple-application.md), pages about advanced concepts, and an extensive API reference section, which includes input/output type information, examples for various common use cases and advice against misuse and anti-patterns. It also includes a cheatsheet for quick reference. +Mithril documentation also demonstrates simple, close-to-the-metal solutions to common use cases in real-life applications where it's appropriate to inform a developer that web standards may be now on par with larger established libraries. + + --- ## Vue @@ -194,6 +197,6 @@ Both Vue and Mithril have good documentation. Both include a good API reference However, due to Vue's many-ways-to-do-one-thing approach, some things are not adequately documented. For example, there's no documentation on hyperscript syntax or usage. -Mithril documentation typically errs on the side of being overly thorough if a topic involves things outside of the scope of Mithril. For example, when a topic involves a 3rd party library, Mithril documentation walks through the installation process for the 3rd party library. +Mithril documentation typically errs on the side of being overly thorough if a topic involves things outside of the scope of Mithril. For example, when a topic involves a 3rd party library, Mithril documentation walks through the installation process for the 3rd party library. Mithril documentation also often demonstrates simple, close-to-the-metal solutions to common use cases in real-life applications where it's appropriate to inform a developer that web standards may be now on par with larger established libraries. Mithril's tutorials also cover a lot more ground than Vue's: the [Vue tutorial](https://vuejs.org/v2/guide/#Getting-Started) finishes with a static list of foodstuff. [Mithril's 10 minute guide](introduction.md) covers the majority of its API and goes over key aspects of real-life applications, such as fetching data from a server and routing (and there's a [longer, more thorough tutorial](simple-application.md) if that's not enough). diff --git a/docs/jsx.md b/docs/jsx.md index b439c867..bf72b39a 100644 --- a/docs/jsx.md +++ b/docs/jsx.md @@ -10,7 +10,7 @@ ### Description -JSX is a syntax extension that enables you to write HTML tags interspersed with Javascript. +JSX is a syntax extension that enables you to write HTML tags interspersed with Javascript. It's not part of any Javascript standards and it's not required for building applications, but it may be more pleasing to use depending on your team's preferences. ```jsx var MyComponent = { diff --git a/docs/route.md b/docs/route.md index d8566215..6e0ff744 100644 --- a/docs/route.md +++ b/docs/route.md @@ -486,9 +486,7 @@ m.route(document.body, "/secret", { "/secret": { onmatch: function() { if (!isLoggedIn) m.route.set("/login") - }, - render: function() { - return m(Home) + else return Home } }, "/login": Login @@ -497,7 +495,50 @@ m.route(document.body, "/secret", { When the application loads, `onmatch` is called and since `isLoggedIn` is false, the application redirects to `/login`. Once the user pressed the login button, `isLoggedIn` would be set to true, and the application would redirect to `/secret`. The `onmatch` hook would run once again, and since `isLoggedIn` is true this time, the application would render the `Home` component. -For the sake of simplicity, in the example above, the user's logged in status is kept in a global variable, and that flag is merely toggled when the user clicks the login button. In a real life application, a user would obviously have to supply proper login credentials, and clicking the login button would trigger a request to a server to authenticate the user. +For the sake of simplicity, in the example above, the user's logged in status is kept in a global variable, and that flag is merely toggled when the user clicks the login button. In a real life application, a user would obviously have to supply proper login credentials, and clicking the login button would trigger a request to a server to authenticate the user: + +```javascript +var Auth = { + username: "", + password: "", + + setUsername: function(value) { + Auth.username = value + }, + setPassword: function(value) { + Auth.password = value + }, + login: function() { + m.request({ + url: "/api/v1/auth", + data: {username: Auth.username, password: Auth.password} + }).then(function(data) { + localStorage.setItem("auth-token": data.token) + m.route.set("/secret") + }) + } +} + +var Login = { + view: function() { + return m("form", [ + m("input[type=text]", {oninput: m.withAttr("value", Auth.setUsername), value: Auth.username}), + m("input[type=password]", {oninput: m.withAttr("value", Auth.setPassword), value: Auth.password}), + m("button[type=button]", {onclick: Auth.login, "Login") + ]) + } +} + +m.route(document.body, "/secret", { + "/secret": { + onmatch: function() { + if (!localStorage.getItem("auth-token")) m.route.set("/login") + else return Home + } + }, + "/login": Login +}) +``` --- diff --git a/docs/style.css b/docs/style.css index ae6a7f5d..d60e7a79 100644 --- a/docs/style.css +++ b/docs/style.css @@ -31,6 +31,7 @@ h1 + ul li {list-style:none;margin:0;padding:0;} h1 + ul li:last-child {border-bottom:0;} h1 + ul ul {margin:0 0 10px;padding:0 0 0 15px;} h1 + ul ul li {border:0;} +h1 + ul strong + ul {border-left:3px solid #1e5799;} @media (max-width: 767px) { main section {margin:0;} diff --git a/docs/testing.md b/docs/testing.md index 52ef79e9..6004524a 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -40,7 +40,7 @@ npm test Generally speaking, there are two ways to write tests: upfront and after the fact. -Writing tests upfront requires specifications to be frozen. Upfront tests are a great way of codifying the rules that a yet-to-be-implemented API must obey. However, writing tests upfront is not a suitable strategy if you don't know exactly what your code will look like, if the scope of the API is not well known or if it's likely to change (e.g. based on previous history at the company). +Writing tests upfront requires specifications to be frozen. Upfront tests are a great way of codifying the rules that a yet-to-be-implemented API must obey. However, writing tests upfront may not be a suitable strategy if you don't have a reasonable idea of what your project will look like, if the scope of the API is not well known or if it's likely to change (e.g. based on previous history at the company). Writing tests after the fact is a way to document the behavior of a system and avoid regressions. They are useful to ensure that obscure corner cases are not inadvertedly broken and that previously fixed bugs do not get re-introduced by unrelated changes.