In terms of architecture, one of Mithril's main differences is that it does not provide base classes to extend from.
It's often said that frameworks, in contrast to libraries, dictate how code should be written. In this sense, one could argue that Mithril isn't really a framework.
Instead of locking developers down to very specific implementations of design patterns, Mithril's approach is to provide an idiomatic pattern to follow, and tools to aid the developer when required. This approach means that developers can get discoverable codebases without necessarily getting locked into the framework.
-
One related difference is that other frameworks often hard-coded base classes where every conceivable convenience method are inherited by the developer's classes (remember, in Javascript, this can mean copying all of the utility methods over to the child class, regardless of whether they're going to be used or now).
+
One related difference is that other frameworks often have hard-coded base classes where every conceivable convenience method gets inherited by the developer's classes (remember, in Javascript, this can mean copying all of the utility methods over to the child class, regardless of whether they're going to be used or not).
Mithril's on-demand tooling approach means there are no hidden performance costs when implementing core MVC patterns, and there's also no extra learning curve for framework-specific syntax for those patterns.
View Layer Paradigm
-
Some of the older frameworks among the popular ones (out-of-the-box jQuery and Backbone, specifically) take a more procedural paradigm when it comes to the view layer: this means every action requires the developer to write custom view-level code to handle it.
+
Some of the older frameworks among the popular ones (out-of-the-box jQuery and Backbone, specifically) take a more procedural paradigm when it comes to the view layer; this means every action requires the developer to write custom view-level code to handle it.
This can get noticeably bulky when you look at thing like collections: you often need to implement insertion code and deletion code, in addition to a "draw everything" routine for performance. And this is for every list that needs to be displayed in some way.
Mithril's view layer paradigm is designed be declarative, much like HTML, such that the same code implicitly does everything it needs to. As it turns out, this design decision is actually a compromise: it offers the benefit of decreased application code complexity at the cost of some performance loss. However, as the performance tests in the homepage show, this does not necessarily hurt Mithril in a meaningful way.
@@ -82,7 +83,7 @@
Another marking difference is that Backbone is workflow agnostic, that is, there's no one idiomatic way to organize applications. This is good for framework adoption, but not necessarily ideal for team scalability and codebase discoverability.
In contrast, Mithril encourages that applications be developed using the patterns found throughout this guide. This discourages "bastardized" MVC pattern variations and architecturing style fragmentation.
One technical aspect that is also different is that Backbone is heavily event-oriented. Mithril, on the other hand, purposely avoids the observer pattern in an attempt to abolish "come-from hell", i.e. a class of debugging problems where you don't know what triggers some code because of a long chain of events triggering other events.
-
A particularly nasty instance of this problem that sometimes occurs in "real-time" applications is when event triggering chains become circular due to a conditional statement bug, casuing infinite loops and browser crashes.
+
A particularly nasty instance of this problem that sometimes occurs in "real-time" applications is when event triggering chains become circular due to a conditional statement bug, causing infinite loops and browser crashes.
Another significant difference between Backbone and Mithril is in their approach to familiarity: Backbone appeals to people familiar w/ jQuery; Mithril is designed to be familiar to people with server-side MVC framework experience.
Angular
Angular is an MVC framework maintained by Google, and it provides a declarative view layer and an emphasis on testability. It leverages developer experience with server-side MVC frameworks, and in many ways, is very similar in scope to Mithril.
However, using its entire toolset idiomatically can bring lots of benefits: learning to use functional programming in real world scenarios and solidifying good coding practices for OOP and MVC are just some of them.
A Simple Application
-
Getting started is surprisingly boilerplate-free:
+
Once you have a copy of Mithril, getting started is surprisingly boilerplate-free:
While this decision allows better API discoverability, the trade-off is that we're largely giving up on custom constraints and behavior. For example, if we wanted to change the application to make the list be persisted, a native Array would most certainly not be a suitable class to use.
In order to deal with that type of refactoring, one can explicitly decide to support only a subset of the Array API, and implement another class with the same interface as this subset API.
Given the code above, the replacement class would only need to implement the .push() and .map() methods. By freezing APIs and swapping implementations, the developer can completely avoid touching other layers in the application while refactoring.
Hopefully these examples give you an idea of ways requirements can change over time and how Mithril's philosophy allows developers to use standard OOP techniques to refactor their codebases, rather than needing to modify large portions of the application.
Content delivery networks allow the library to be cached across different websites that use the same version of the framework, and help reduce latency by serving the files from a server that is physically near the user's location.
Bower is a package manager for NodeJS. If you're using NodeJS already or planning on using Grunt to create a build system, you can use Bower to conveniently keep up-to-date with Mithril versions.
+
Assuming you have NodeJS installed, you can install bower by typing this in the command line:
+
npm install -g bower
+
And you can download Mithril by typing this:
+
bower install mithril
+
Then, to use Mithril, point a script tag to the downloaded file:
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 8b4b8938..aea3875b 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -16,7 +16,7 @@ However, using its entire toolset idiomatically can bring lots of benefits: lear
## A Simple Application
-Getting started is surprisingly boilerplate-free:
+Once you have a [copy of Mithril](installation.md), getting started is surprisingly boilerplate-free:
```markup
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 00000000..920753b9
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,61 @@
+## Installation
+
+Mithril is available from a variety of sources:
+
+---
+
+### Direct download
+
+You can [download a zip of the latest version version here](http://lhorie.github.io/mithril/mithril.min.zip).
+
+Links to older versions can be found in the [change log](change-log.html)
+
+In order to use Mithril, extract it from the zip file and point a script tag to the `.js` file:
+
+```markup
+
+```
+
+---
+
+### CDNs (Content Delivery Networks)
+
+You can also find Mithril in [cdnjs](http://cdnjs.com/libraries/mithril/) and [jsdelivr](http://www.jsdelivr.com/#!mithril)
+
+Content delivery networks allow the library to be cached across different websites that use the same version of the framework, and help reduce latency by serving the files from a server that is physically near the user's location.
+
+#### CdnJs
+
+```markup
+
+```
+
+#### JsDelivr
+
+```markup
+
+```
+
+---
+
+### Bower
+
+[Bower](http://http://bower.io) is a package manager for [NodeJS](http://nodejs.org/). If you're using NodeJS already or planning on using [Grunt](http://gruntjs.com/) to create a build system, you can use Bower to conveniently keep up-to-date with Mithril versions.
+
+Assuming you have NodeJS installed, you can install bower by typing this in the command line:
+
+```
+npm install -g bower
+```
+
+And you can download Mithril by typing this:
+
+```
+bower install mithril
+```
+
+Then, to use Mithril, point a script tag to the downloaded file:
+
+```markup
+
+```
diff --git a/docs/layout/guide.html b/docs/layout/guide.html
index e33c48fd..8a28f3dd 100644
--- a/docs/layout/guide.html
+++ b/docs/layout/guide.html
@@ -23,6 +23,7 @@