These past few weeks, there's been a lot of activity in the Mithril mailing list and in the issue tracker surrounding performance. It kinda started with this link, a benchmark of various virtual DOM operations, in which Mithril was doing poorly compared to other virtual dom libraries.

This naturally surprised a lot of the community since Mithril had been shown to perform well on an earlier TodoMVC benchmark (lower is better). As it turns out, according to the author of the vdom benchmark, the metrics he was using are bad, but nevertheless, members of the Mithril community started tinkering with Mithril's codebase and we now have a whole bunch of performance improvements in various stages of progress (some landed, some still being tuned), and the end result is that thanks to the efforts of G00fy-, Alex Galays and others, the next release of Mithril will fix weaknesses that made it choke on that benchmark, and we'll have a faster framework. Big shout out to everyone who is contributing!

But anyways, all of the talk about performance made think a little bit about performance in general, and it made me remember my foolish younger self, who would naively try to optimize code that really didn't need it. Hopefully you know better, but in any case, read on.

When does performance matter

Obviously performance improvements in a framework are always welcome.

One might be tempted to think that optimizing a framework falls under the category of premature optimization, and that Donald Knuth's "Premature optimization is the root of all evil" quote is wrong. After all, all the work that goes into optimizing a framework happens before even a single line of your code runs, right?

But the reality is that a lot of the time, performance only starts mattering late in the game. Prototype.js used to be a major Javascript framework, but one of the defining moments for jQuery was release 1.1.3, which introduced a 800% (!) performance improvement over its previous version, effectively bringing the performance topic to the center of the stage for selector engines.

But by then, there were several players in the arena (Prototype, jQuery, MooTools, Dojo, to name a few), and the semantics of CSS selectors were well established.

One could argue that a similar thing happened with browsers themselves, when Chrome came into the picture with its V8 engine, basically forcing all the other browsers to up their performance games. By that time, the semantics of the Javascript language were also standardized.

What these examples illustrate is that performance optimization happens late, when the race of who has better features starts to stagnate.

Performance isn't a vaccuum

In corporate projects, there's a similar trend of lateness: requirements change, deadlines loom, and performance optimization efforts are things that you are forced to do in the rush to get ready to ship.

It's often possible to get around a performance problem by changing your approach altogether. An example of this can be found in the Mithril docs: if your user does not need to be innundated with data in a grid, then taking steps to decrease cognitive load (e.g. paginating, filtering, etc) will also make the performance problem go away. Interestingly, when we have the foresight to mitigate cognitive load of a huge grid, we call it good usability design. When we don't have this foresight, then it's a performance problem. And it happens late because the lack of foresight leads to building something naively, and the problem only becomes apparent after dumping a bunch of data through the system.

We can say that implementing pagination and filtering is optimizing early, but remember that the problem only became apparent in hindsight. Religiously applying this optimization to every new grid can add another problem: complexity where it's not needed.

At my previous job, we had a peculiar case of this: one mission critical view was a fully dynamic grid that could be filtered in every conceivable way, so that people could filter not only rows but also columns. It was an extremely flexible interface for sure, but it was also nearly impossible to maintain. The solution? It turned out that using highly-specialized Trello-style views allowed for effective slicing and organizing of data for important use cases.

It's interesting to note that it takes some lateral thinking to go from a performance problem to a usability problem, and similarly to go from a complexity problem to a usability one.

Sometimes you can feed parameters back from your performance problem into your solution - iterating through usability improvements, for example. Sometimes the spec is too strict and you don't get too much wiggle room. But the key is that by the time an effort to optimize performance starts, you should have very concrete requirements and concrete goals.

When we try to naively tackle performance early - think perf'ing if statements vs switch statements in some random place in the codebase - we're effectively doing the same as the fully dynamic grids from my previous example: It adds complexity but it doesn't necessarily improve anything. You need to have a bigger picture to macroscopically measure the impact of a change. If there's no competition to beat, if the user can't notice the speed boost, performance optimization can be a waste of time and a creator of code debt.

The other day, a co-worker was asking me for some help porting an HTML5 drag-n-drop file upload directive from Angular to Mithril.

At a glance it may seem like a pretty difficult task for a backend guy who just started learning Mithril. As it turns out, there's a lot domain-specific knowledge required, but the Mithril aspect is not particularly daunting.

So, let's see how this would work. First, let's get the plain vanilla drag-n-drop to work outside of Mithril.

The drag-n-drop API requires some amount of setup to get going. On the UI side, we want to visually indicate to the user that they have dragged something over a droppable area (and likewise, reset the visuals if the user drops or drags away from the droppable area). In addition we want to run something once a file is dropped.

So for starters, we need to define events to handle all of these cases.

var element = document.body //let's just use body for now

element.addEventListener("dragover", activate)
element.addEventListener("dragleave", deactivate)
element.addEventListener("dragend", deactivate)
element.addEventListener("drop", deactivate)
element.addEventListener("drop", update)
window.addEventListener("blur", deactivate)

function activate(e) {
    e.preventDefault()
}
function deactivate() {}
function update(e) {
    e.preventDefault()
}

The boilerplate above takes care of setting up all the relevant event handlers, but for now each event just calls empty functions. The activate and update functions need to call preventDefault in order for drag and drop to work correctly.

Let's make things a bit more functional. Since the files are only available once the update event is triggered, we need to expose the data with another event handler:

function dragdrop(element, options) {
    options = options || {}

    element.addEventListener("dragover", activate)
    element.addEventListener("dragleave", deactivate)
    element.addEventListener("dragend", deactivate)
    element.addEventListener("drop", deactivate)
    element.addEventListener("drop", update)

    function activate(e) {
        e.preventDefault()
    }
    function deactivate() {}
    function update(e) {
        e.preventDefault()
        if (typeof options.onchange == "function") {
            options.onchange((e.dataTransfer || e.target).files)
        }
    }
}

Now we can start using our dragdrop function instead of needing to type all that boilerplate all the time:

dragdrop(document.body, {
    onchange: function(files) {
        console.log(files)
    }
})

Next, we need to create a function to upload files. In an MVC setting, this kind of concern belongs in the model layer. So let's create a model method to deal with file uploads.

var Uploader = {}

Uploader.upload = function() {
    //todo: upload files
}

Let's suppose that we want to POST the files to the URL /api/files. The problem is that you can't just serialize a file into a regular HTTP request. Instead, we need to use the HTML5 FormData class, which creates an object that can be sent via XMLHttpRequest, but encodes the request as multipart/form-data. In order to ajax a FormData instance instead of serializing data as JSON, we need to override m.request's default serialize option:

Uploader.upload = function(files) {
    var formData = new FormData
    for (var i = 0; i < files.length; i++) {
        formData.append("file" + i, files[i])
    }

    return m.request({
        method: "POST",
        url: "/api/files",
        data: formData,
        //simply pass the FormData object intact to the underlying XMLHttpRequest, instead of JSON.stringify'ing it
        serialize: function(value) {return value}
    })
}

Now we are able to take our dragdrop function and use it with our model entity:

dragdrop(document.body, {onchange: Uploader.upload})

You can verify that the code is working by dropping a file onto the page, and inspecting the request object.

Integrating to Mithril

In Mithril, templates are made out of virtual DOM elements (i.e. javascript objects that represent DOM elements).

The DOM elements themselves are only accessible from config functions in views. Let's hook our dragdrop function into a config:

//an uploader module
var uploader = {}

uploader.controller = function(options) {
    return options
}

uploader.view = function(ctrl) {
    return m(".uploader", {
        config: function(element, isInitialized) {
            if (!isInitialized) {
                dragdrop(element, {onchange: ctrl.onchange})
            }
        }
    })
}

All we're doing here is calling the dragdrop function as we did before, but passing another event handler to it. This event handler will be defined by a parent component.

Now this module can be used by another components:

var demo = {}

demo.controller = function() {
    return {
        title: m.prop("Upload something"),
        uploader: submodule(uploader, {
            onchange: Uploader.upload
        })
    }
}

demo.view = function(ctrl) {
    return [
        m("h1", ctrl.title()),
        ctrl.uploader(),
        m("p", "more stuff")
    ]
}

m.module(document.body, demo)

Notice we're using the submodule helper from this article to cut down on the amount of noise.

You can see a running example of this code here

Conclusion

As you play with this code, you'll likely want to add styling for when the user drags a file over the drop area, as well as remove the style when the user drag away from the drop area. This can be accomplished by adding and removing CSS classes in the activate and deactivate functions. I'm leaving this as an exercise to the reader.

In this article we saw how we can work our way from a simple library to full Mithril integration. Understanding this workflow is a key in learning how to integrate third-party libraries to Mithril, how to write reusable components and how to organize the flow of data across different components.

And hopefully you've also learned a thing or two about the nuts and bolts of the cool and flashy HTML 5 drag-n-drop API.

One requirement that I commonly run into is the ability to filter a list of things. Not just filtering an array, but filtering in the sense of a user specifying some criteria, and a list of things on screen updating to become more relevant as a result. Think Google's search result page.

In this article we'll look at one way of implementing a client-side filter.

First we need to decide roughly where we can separate concerns: usually the most logical way of breaking up the view is to have one template for the list of things and another for the filters, plus a top level component to glue everything together. But once we've decided that, there are many different ways in which we could actually implement our components, and some ways lend themselves to be more tightly coupled than others. Ideally, we'd like the sub-components to be as agnostic about the rest of the world as possible. Conversely, we want the top level component to specify what sub-components exist and how they interact with each other.

One may argue that then, the top component is tightly coupled. That's true and in fact it's a necessity: there's simply no way to have decoupled components talking to each other without some mechanism that ties them together into a context. This is the purpose of the top component.

Anyways, let's start by creating skeletons for our components.

//top level component
var things = {}

things.controller = function() {}
things.view = function(ctrl) {
    return m(".row", [
        m(".col-md-2", [
            filter.view(ctrl.filter)
        ]),
        m(".col-md-10", [
            list.view(ctrl.list)
        ])
    ])
}

//filter
var filter = {}
filter.view = function() {}

//list
var list = {}
list.view = function() {}

Notice that the structural grid markup is in the top level component (I'm using Bootstrap CSS classes in this case). As you get into refactoring more repetitive templates, you might be tempted to start putting this type of code in the subtemplates, but from a maintenance perspective, it's a lot easier to reason about the structure of the grid when the entire structure is in one place, rather than scattered around different functions. In addition, having this markup at the top level template means that each of our subtemplates is clean (and therefore easier to reuse)

Also, note that we're using ctrl.filter and ctrl.list in the view even though we haven't defined them yet. We'll get to these later on.

The list

The list will need to be populated with data. So let's create a model to handle that:

var Thing = {}
Thing.list = function() {
    return m.request({method: "GET", url: "/api/things"})
}

Next, we use a controller to expose this data to a view.

list.controller = function(options) {
    this.items = Thing.list()
    this.visible = options.visible
}

The Thing.list method ajaxes some JSON data and returns a promise that asynchronously resolves to the response data. So in the view, ctrl.items will hold the data that came back from the web service.

The visible property will be used to determine which of the items are visible on screen. This function will be passed to Array.prototype.filter, so it'll take an item as the argument and expect a boolean as the return value.

Next, let's create the template to display our list:

list.view = function(ctrl) {
    return m("table", [
        ctrl.items().filter(ctrl.visible).map(function(item) {
            return m("tr", [
                m("td", item.id),
                m("td", item.name)
            ])
        })
    ])
}

The code above creates a table and iterates over the array in items. It filters out items based on the ctrl.visible function and displays table rows for the items that are visible.

The filter

Let's create a search input.

filter.controller = function(options) {
    this.searchTerm = m.prop("")
}

Here we created a controller that has a member called searchTerm. We'll be using this getter-setter to store the value of the search input.

Next, let's create the template for the filter.

filter.view = function(ctrl) {
    return m("input", {oninput: m.withAttr("value", ctrl.searchTerm)})
}

The code above simply defines a text input that populates ctrl.searchTerm as the user types. By using m.withAttr, we extract the value attribute of the input and pass it as the argument to ctrl.searchTerm when an oninput event is triggered.

Putting things together

Let's go back to our top level controller. Here we need to instantiate each of our sub-module controllers.

things.controller = function() {
    var ctrl = this

    ctrl.list = new list.controller({
        visible: function(item) {
            return item.name.indexOf(ctrl.filter.searchTerm()) > -1
        }
    })

    ctrl.filter = new filter.controller()
}

As you may recall, we needed to define ctrl.filter and ctrl.list, because we were using them in the top level template as the controllers for the sub-views.

Another thing to remember was that the list controller can receive a visible argument. This option determines how the items in the list are filtered.

The implementation of visible is straightforward: if the item name contains the search term, then the item is visible.

We can now run our code:

//model
var Thing = {}
Thing.list = function() {
    return m.request({method: "GET", url: "/api/things"})
}

//top level component
var things = {}

things.controller = function() {
    var ctrl = this

    ctrl.list = new list.controller({
        visible: function(item) {
            return item.name.indexOf(ctrl.filter.searchTerm()) > -1
        }
    })

    ctrl.filter = new filter.controller()
}
things.view = function(ctrl) {
    return m(".row", [
        m(".col-md-2", [
            filter.view(ctrl.filter)
        ]),
        m(".col-md-10", [
            list.view(ctrl.list)
        ])
    ])
}

//filter
var filter = {}
filter.controller = function(options) {
    this.searchTerm = m.prop("")
}
filter.view = function(ctrl) {
    return m("input", {oninput: m.withAttr("value", ctrl.searchTerm)})
}

//list
var list = {}
list.controller = function(options) {
    this.items = Thing.list()
    this.visible = options.visible
}
list.view = function(ctrl) {
    return m("table", [
        ctrl.items().filter(ctrl.visible).map(function(item) {
            return m("tr", [
                m("td", item.id),
                m("td", item.name)
            ])
        })
    ])
}

//run
m.module(document.body, things)

"Pshaw, I could write that in less lines of code!"

Our example is admittedly pretty simple, and it's very much possible to merge everything into the things module and end up with less code than we did. Likewise, it's also possible to add more code to make modules more pure and abstract.

The point of this article, though, is primarily to show one way of breaking larger modules into smaller ones. Organizing code in the way we did allows us to reuse the sub-components: the filter module is only concerned with what the user types in the search input, and the list module can be filtered in any way we desire. The things module is what glues the sub-components together and specifies how they interact with each other in the context of things.

If you've been passing instances of parent controllers to child components, now you know how to re-organize code in a less tightly coupled way.

Today's article will be about a short and sweet idiom.

In Mithril modules, controllers are class constructors, which means that in order to manually use them, you need to instantiate them.

This is required in order to provide contextualization to modules (i.e. the ability to say when a module gets created and when it gets destroyed), but having to remember to pass controller instances to views can get a little cumbersome once you start breaking down a big app into a lot of modules:

var root = {}

root.controller = function() {
    this.search = new search.controller()
    this.filters = new filters.controller()
    this.list = new list.controller()
}

root.view = function(ctrl) {
    search.view(ctrl.search)
    filters.view(ctrl.filters)
    list.view(ctrl.list)
}

A simple way to optimize this is to use partial application to pre-bind a controller instance:

var submodule = function(module, args) {
    return module.view.bind(this, new module.controller(args))
}

This returns a view function with the controller already passed into it. We can then create references to that in the root controller instead:

root.controller = function() {
    this.search = submodule(search)
    this.filters = submodule(filters)
    this.list = submodule(list)
}

root.view = function(ctrl) {
    ctrl.search(),
    ctrl.filters(),
    ctrl.list()
}

Just remember that controllers should never be instantiated from views (as per the documentation), which means you should never call submodule from a view.

Shouldn't we be using view-models?

If you read that documentation page through to the end, you'll see I talk about moving logic out of controllers into view models.

But that doesn't mean controllers should just be abolished altogether. One case where nesting components is necessary is when dealing with dynamic or extensible component placement, i.e. when you have a container module where different modules might be dropped in. The classical example is a dashboard where users can customize what widgets show up.

The benefit of using the trick above is that you only need one variable to hold your module instance instead of two:

//without using the partial application trick
var dashboard = {}

dashboard.controller = function(innerModule) {
    this.innerController = new innerModule.controller()
    this.innerView = innerModudle.view
}

//using it
var dashboard = {}

dashboard.controller = function(innerModule) {
    this.innerView = submodule(innerModule)
}

I hope you'll find this trick useful.

Any time we start learning something new, we are bound to stumble and make mistakes along the way. In this article, we'll look at some common issues that I've seen people run into when they were getting into Mithril.

1. Using jQuery

It's surprisingly tempting to use jQuery to manipulate the DOM from a controller or even a view-model, especially for those without experience in MVC frameworks. I've talked about jQuery's scalability problem before. The gist is that jQuery DOM manipulation implicitly puts UI state data in the DOM itself, and as applications grow larger, it becomes harder and harder to reason about that state, and the tendency to build more functionality on top of it causes the application to become brittle and hard to modify.

Another problem with mixing jQuery is that it creates a tight coupling between the data and the presentation layer, making both harder to test in isolation.

The alternative to using jQuery is to apply the same MVC concepts that you would see in server-side frameworks: have data live in the model layer, and explicitly derive the state of the view from the data. I've talked about using view-models for separating ORM classes from UI state within the model layer. Moving away from jQuery is simply an exercise in applying the same workflow as you would in your traditional server-side MVC framework of choice, and being mindful of the existence and the nature of UI state.

With all of this said, you can use jQuery to augment the behavior of an element via the config attribute. Just avoid doing it in controllers and view-models.

2. Misunderstanding dynamic scoping

Let's face it, the this keyword is confusing. Many seasoned developers still struggle with it, especially when you start adding nested anonymous functions, partial application, and functions-as-arguments into the picture. It's a good idea to consider using idioms without language-specific caveats to help ease new developers into the codebase.

One common way to make this more junion-friendly is to use the var self = this idiom. Be aware though that self is just as non-descriptive as a variable name as this and it can yield somewhat repetitive code.

The best thing to do to avoid this confusion as a team grows is to avoid using it altogether. Here's an example that uses this:

var home = {}
home.vm = {
    init: function() {
        this.name = "foo"
    }
}

Here's an alternative way of writing the snippet above using the easier-to-understand lexical scoping:

var home = {}
home.vm = {}
home.vm.init = function() {
    home.vm.name = "foo"
}

The structure of the data is now much more obvious, albeit at the expense of adding some repetition in the form of explicit home.vm references everywhere.

Here's a cleverer way of writing it that reduces repetition:

var home = {}
new function(vm) {
    vm.init = function() {
        vm.name = "foo"
    }
}(home.vm = {})

3. Backwards controllers

Controllers are a scoping mechanism. They are responsible to defining what is accessible by the view: what data can be iterated over, how is that data sliced from the server-side data set, what operations can be performed on this data. People are often confused about the role of controllers because its primary responsibity (scoping) is actually a form of state, but one that doesn't really fit in the model layer. Misunderstanding the role of controllers often lead people to put all non-ORM state in the controller itself, for the sake of "consistency" (a pattern colloquially known as "fat controllers").

While fat controllers aren't necessarily bad per se, they can lead to some problems if you're not careful with their lifecycles. As a rule of thumb, controller classes should never be instantiated from a view.

It's technically possible to have controllers that get reconsctructed by views on every redraw (using anonymous stateless objects is an example of it), but the extra abstraction layer provided by OOP classes lulls developers into the common OOP pattern of encapsulating state within the class itself.

Since controllers in Mithril modules are nothing more than Javascript constructor functions, they can be as thin or as fat as a developer wants. The problem begins when a developer starts holding state in fat controllers for convenience instead of putting that state in view-models, and then proceeds to instantiate the constructor function from a view. Typically in Mithril, controllers are only meant to be initialized once in their lifecycle, but view functions run every time an event is triggered. When a controller is initialized by the view, it resets its internal state, which is almost never what the developer wants. So just don't do it.

Another related issue that comes up often is incidental complexity arising from adding a controller for its own sake. This happens most commonly when someone has a list of things and they want to wrap each item in its own module. Remember that controllers are a scoping mechanism: items in a list are already scoped and ready to be consumed by views, so adding another layer of controllers adds unnecessary boilerplate.

If you're running into issues with managing the lifecycle of sub-components that represent items in a list, then you probably should consider view model maps instead. You can skip implementing the sub-module controller until your sub-module actually does need to be scoped on its own for another page where the sub-module exists but the list module does not.

4. Premature optimization

A relatively common mistake is creating gigantic DOMs, and then spending inordinate amounts of time trying to one-up the framework's rendering algorithm. The performance of all algorithms degrade as the size of data increases, and even the fastest algorithms can only run as fast as the hardware they run on. Rendering tens of thousands of elements on a page will be slow with any framework.

Rather than spending time fighting against the global nature of Mithril's virtual dom diff algorithm, it's usually more productive to think of ways to reduce the size of the DOM. Large tables are a classic example: their rendering performance degrade linearly as more rows and columns are displayed, but no human being can reasonably wade through thousands of rows filled with tabular data. Rather than spending time fighting the rendering algorithm (which is not even the culprit of the slowness), it's a lot more productive to implement pagination and search / filtering: doing so improves performance (both on redraws AND on page load), AND it improves usability as well.

Conclusion

Many mistakes that people make when starting out with Mithril are often related to years of old habits, or by lack of experience with javascript (or even programming in general). While there will inevitably those who misunderstand one or another small aspect of Mithril itself, I think the minimalist nature of the framework and the amount of documentation and public forums available are sufficient enough that the only problems left to pay attention to are those related to the general programming discipline. I hope this article helps you hone high-level application development skills, regardless of whether you end up using Mithril ten years from now or not.

Fat javascript-driven applications usually have two types of data: domain data and application data.

Domain data is what users care about: user records, articles, projects, whatever. By definition, domain data is what makes an application useful; most user actions in an application revolve around reading and writing domain data.

Application data, on the other hand, is data about the state of the application itself: is this modal popup open, what filter is currently applied to this grid, should a loading icon be showing up right now, what was the original value of this input if I hit the cancel button to reset it?

Newer frameworks have started adopting the idea of view-models to deal with application state. I talked about it previously here. The summary is that UI state is almost never a concern for the model entities that deal with domain data, and we often need to keep them separated somehow.

One challenge that people face when building complex apps is that it's inherently difficult to separate application state concerns from domain data concerns when working with lists of things. Lists can be sorted, filtered, sliced and spliced, and keeping a second list in sync is not trivial.

Today we're going to look at a pattern that I recently started using at work to help fix this problem.

Let's imagine that we're working with some user records:

var users = [
    {id: 1, name: "John", email: "john@example.com"},
    {id: 2, name: "Mary", email: "mary@example.com"},
    {id: 3, name: "Bob", email: "bob@example.com"}
]

And let's say we have an interface that displays all user names and there's a "more" button beside each user that displays the rest of the user information.

var app = {}
app.controller = function() {
    this.users = users
}
app.view = function(ctrl) {
    return m("ul", [
        ctrl.users.map(function(user) {
            return m("li", [
                m("a[href='javascript:;']", {
                    onclick: function() {user.showEmail = !user.showEmail}
                }, user.name),
                user.showEmail ? m("div", user.email) : ""
            ])
        })
    ])
}
m.module(document.body, app)

In the snippet above, we loop through the list of users and display a list, which contains a name in a link. Clicking the link toggles the div with the email.

It's tempting to just put the show/hide flag in the user record itself as I did above, but imagine that a month down the road, your boss comes back and asks you to change the div into a form that lets users edit a user record. Now all of a sudden, there's a whole lot of additional application state that you weren't expecting: you need to put the temporary input value somewhere in case a user cancels out, you need a flag to indicate whether a loading icon should appear while the item is saving, you need to display an error if something goes wrong, etc. So now our user records store all sorts of not-really-user-related properties, and this was just one "small" change in the app! It's scary to realize how one little harmless hack can quickly snowball into a huge mess of mixed concerns.

Some might be wondering why we aren't just using the DOM to store this application state, as one would do with jQuery. The problem with having UI state live implicitly in the DOM is that you don't have a single source of canonical data, which makes it difficult to understand where a change begins and where it ends as it ripples through the system. Imagine the same scenario as above, in a jQuery codebase. You could start storing all the UI state I described directly in the DOM, but what if the data comes from the server, and your boss asks it to be filterable via a search input? How complicated does your code need to be now in order to re-render the rest of the grid while keeping the state of an active form intact? Ultimately what ends up happening is an exponential growth of custom code to handle every possible corner case that arises from the growing number of interactions between different use cases, all of which needs to be revised yet again when the next feature gets introduced. This simply doesn't scale.

Let's take a step back and think about the data structures.

var users = [
    {id: 1, name: "John", email: "john@example.com"},
    {id: 2, name: "Mary", email: "mary@example.com"},
    {id: 3, name: "Bob", email: "bob@example.com"}
]

As we saw earlier, our data is a relatively simple data structure, but let's break this down further. There's a list, and inside of the list, there's a bunch of objects. Each object has a bunch of properties, one of which (id) is a unique identifier value.

We want to map a varying number of UI-related properties to each record in this list, without polluting the records themselves.

And as it turns out, javascript has a data structure that is perfect for this task: objects. With it, we can build a lazy map, that is, a map that populates each key-value pair with a defined child structure on demand.

var viewModelMap = function(signature) {
    var map = {}
    return function(key) {
        if (!map[key]) {
            map[key] = {}
            for (var prop in signature) map[key][prop] = m.prop(signature[prop]())
        }
        return map[key]
    }
}

The helper above is a factory that takes as input a signature object with getter-setter properties attached to it, and returns a function. The returned function takes as an input a key, and returns a clone of the signature object, initialized with the values from the signature. Here's an example of how to use it:

var formVMs = viewModelMap({
    isEditing: m.prop(false),
    tempValue: m.prop(""),
    error: m.prop("")
})

var vm1 = formVMs(1)
vm1.isEditing() // false
vm1.isEditing(true) // true

var vm2 = formVMs(2)
v1 === v2 // false

var vm1again = formVMs(1)
vm1 === vm1again // true
vm1again.isEditing() //true

Above, formVMs returns clones of the signature object corresponding to the number that we pass in. Calling it more than once for a single key returns the same object, with its state preserved.

We can now plug this back into our example from earlier:

var app = {}
app.controller = function() {
    this.users = users

    this.usersVM = viewModelMap({
        isEditing: m.prop(false),
        tempValue: m.prop(""),
        error: m.prop("")
    })
}
app.view = function(ctrl) {
    return m("ul", [
        ctrl.users.map(function(user) {
            var vm = ctrl.usersVM(user.id)
            return m("li", [
                m("a[href='javascript:;']", {
                    onclick: function() {vm.isEditing(!vm.isEditing())} //toggle div
                }, user.name),
                vm.isEditing() ? m("div", user.email) : ""
            ])
        })
    ])
}
m.module(document.body, app)

Notice that we copied the view model map to our controller, and that we replaced user.showEmail with vm.isEditing. Each view model maps to a user id.

Now the user records are kept clean of UI state, and the view model is easily extensible (just add more properties to the signature).

Conclusion

Linus Torvalds once said that mediocre programmers think in terms of code, but great programmers think in terms of data structures and how they interact with one another. In this article, we applied his lesson to our problem, using common techniques that should be familiar to most programmers: using functions as factories, using objects as maps, lazy initialization, etc.

Thinking in terms of data structures is a good piece of advice. For a lot of programmers, it's easy to eagerly jump into coding as soon as a problem presents itself, but taking that extra time upfront to design a good structure for our data can pay off enormously. Designing our code around the structure of data means that keeping data clean and organized is a top priority. This makes it easier to inspect it during maintenance, and paradoxically, tends to produce more discoverable code than when we spend all our energy crafting clever code paths (at least in my own experience).

You might have heard of something called the paradox of choice. We might think that having many options to choose from is a good thing, but given many similar choices, what actually happens often is that we end up spending so much time trying to analyze them, that we end up wasting more time than if we were to just randomly pick one. This phenomenon is also known as choice paralysis.

There's a similar phenomenon, known as information overload, that is similar in the way that it overwhelms us with information about a particular topic. The problem with information overload is that while all the presented information is ostensibly correct, it's also mostly irrelevant for the task at hand.

Frameworks are often difficult to learn due to similar cognitive patterns: a newbie comes in to a documentation side and is confronted with a variety of classes and methods that are all useful in one context or another, but it's not immediately obvious how they relate to the newbie's particular problem. When every problem that a developer encounters requires yet another dig through the documentation in order to learn some new incantation, or to remember what its syntax was, productivity is lost.

So, in order to not get in people's ways, it's important that frameworks and libraries try to minimize the amount of cognitive load they put on developers.

One trick that jQuery used to ease people into its vast API was function overloading:

//set the color of one element
$("#foo").css("color", "red")

//get the color
$("#foo").css("color")

//set the color on many elements
$("h1").css("color", "red")

You don't need to remember if the method is called getCss, or readCSS, and whether the counterpart is setStyle or setCSS (and did you noticed the uppercase?). There's not a different API if you're setting styles on one vs many elements. It's just css all the time.

Compare it to Prototype.js, arguably the most popular javascript framework at the time jQuery came out:

//set the color of one element
$("foo").setStyle({color: "red"})

//get the color
$("foo").style.color

//set the color of many elements
$$("h1").invoke("setStyle", {color: "red"})

You can clearly see why jQuery is still loved by many, and why Prototype.js fell by the sidelines. Having APIs that are easy to remember and that adapt to similar but slightly different use cases help the framework become transparent so that the developer can then focus on their own problems rather than be fighting against framework syntax.

Mithril also uses this design trick to help newbies ease into its API:

//I just want a div
m("div")

//but it has text
m("div", "Hello world")

//actually, I need to toggle a class on it too
m("div", {class: isActive ? "active" : ""}, "Hello world")

Another slightly different example is m.route. It has three overloads that do fairly different things: define routes, redirect, and make links routed. This may seem weird at a glance, but it's an example of being answer-oriented. When it comes to routing, these are three common questions: "how do I define a bunch of routes?", "how do I redirect to a route?", and "how do I make my link go to a routed path instead of a regular URL?". Having the answer always be the same (i.e. "use m.route") means less names to memorize.

Mithril also takes it a step further and makes it easy for developers themselves to create predictable APIs with m.prop. We previously saw this in the uniform access principle article.

var name = m.prop("")

//set the value
name("John")

//get the value
console.log(name()) // "John"

In a follow-up article, we also saw another subtle place where Mithril encourages good API design:

var User = function(data) {
    this.firstName = m.prop(data.firstName)
    this.lastName = m.prop(data.lastName)
}

//automatically convert response objects to User instances
m.request({method: "GET", url: "/users", type: User})

While this isn't technically function overloading per se, it uses the options argument pattern to provide an extensible map of parameters, so that it's easy to set as many or as few of the input parameters as you're able to. The options argument pattern effective makes every permutation of parameters a valid overload.

But more importantly, it makes the argument list for every model entity predictable: You don't need to remember the order of arguments, and knowing how to create one type of entity is enough knowledge to guess how to create others.

Which brings us to another aspect of predictable APIs: consistency

Again, jQuery is a great example of this:

//how I set some css?
$("#foo").css("color", "red")

//attributes?
$("#foo").attr("title", "hello")

//data?
$("#foo").data("name", "john")

You can look at a method and guess (most likely correctly) how the other ones work.

Interfaces, interfaces

Being conscious of consistency can make a significant difference in how one organizes code.

From my experience, I think it takes a bit of a mental shift to go from writing single-purpose application code to writing multi-purpose libraries. Single-purpose code doesn't strictly require much thought in terms of its API because it is typically only a consumer: it may assemble a bunch of different things, but it's rarely (if ever) used to compose into more than one bigger system.

But as systems get more complex the line between single-purpose application code and multi-purpose library code starts to blur: we often start needing reusable application-level agglomerations of code in order to avoid problems like code duplication (i.e. two or more pieces of code that do almost the same thing, but not quite).

Striving for consistency implicitly means developers need to be aware of what code is already there in order to follow convention. This is, I think, where the mental shift happens. With many frameworks, conventions are baked into the boilerplate, but then teams without a good code review workflow start writing in whatever style they prefer and end up with a wild west of code when all these pieces start to come together into bigger things two years later.

As it turns out, for years OOP has offered tools like interfaces to help us improve code consistency. Even though Javascript isn't a statically typed OOP language, we can borrow some of these ideas.

Here's an example of some code I use at work, to illustrate:

var select2 = {}
select2.config = function(options) {
    var type = options.type, prop = options.binds
    return function(element, isInitialized) {
        if (!isInitialized) {
            $(element).select2({
                ajax: {
                    url: type.url,
                    data: function(term) {
                        return {ForAutoCompleter:true, Keyword: term}
                    },
                    results: function(data) {
                        return {results: data.Entries.map(function(item) {
                            var instance = new type(item)
                            return {id: type.id(instance), text: type.label(instance), data: instance}
                        })}
                    }
                }
            })
            .on("change", function(e) {
                m.startComputation()
                prop(e.added ? e.added.data : null)
                m.endComputation()
            })

            var item = prop()
            if (item) {
                $(element).select2("data", {id: type.id(item), text: type.label(item)})
            }
        }
    }
}

The code above is an integration helper for the select2 autocompleter library. The exact details of the implementation aren't that important for this discussion. What we're really interested in is in seeing how it ties in to a larger system.

Let's imagine we have a model entity User:

//in the model
var User = function(data) {
    this.id = m.prop(data.id)
    this.name = m.prop(data.name)
}
User.url = "/users"
User.id = function(user) {return user.id()}
User.text = function(user) {return user.name()}

This User class implements an interface: it has a static url property and two methods id and text which dereference a system ID and a user-friendly identifier for the User class. I might then later implement the same interface for a Project class, such that I can generically retrive the url, id and readable name for a project.

As I mentioned, Javascript doesn't have the concept of OOP interfaces, or generics, but if it was a statically typed OOP language, the interface would look something like this:

interface IEntity<T> {
    static string url;
    static number id(T entity);
    static string name(T entity);
}

The way to use the select2 widget is to pass it a model entity like User and a m.prop getter-setter, like this:

var vm = {
    user: m.prop()
}

//in the view
m("input", {config: select2.config({binds: vm.user, type: User})})

//if we select a user from the dropdown, then `vm.user()` will point to it

The selec2.config accepts a type parameter to which I can pass anything that implements the IEntity interface. It then internally takes care of hooking up the select2 plugin so that it reads the proper id and text fields from an ajax request that is made to the appropriate url.

The helper also accepts a binds property, which is expected to be an m.prop getter-setter, and the helper bi-directionally binds the dropdown's selected value to the getter-setter.

So when it all comes together, we are then able to freely swap out what model entity populates the options for the select2 widget, and when a user picks an option from the dropdown, we can put the selected item in any getter-setter (or anything that behaves like one).

//this is what a project autocompleter might look like
m("input", {config: select2.config({binds: vm.project, type: Project})})

//or a booking autocompleter
m("input", {config: select2.config({binds: vm.booking, type: Booking})})

//or an article autocompleter
m("input", {config: select2.config({binds: vm.article, type: Article})})

The end result of having defined an interface is that we don't need to go look up the select2 documentation or copy-paste a bunch of options every time we create a dropdown. Instead, the widget API behaves more like an agnostic shell, much like generic collections that you might see in a statically typed language.

Creating a predictable access pattern via the IEntity interface also lets us pivot in interesting directions. What if we wanted a dropdown that showed all the users, but only for a single project? Easy, create a factory:

//in the model
var projectUser = function(projectID) {
    var ProjectUser = function(data) {
        return new User(data)
    }
    ProjectUser.url = "/projects/" + projectID + "/users"
    ProjectUser.id = User.id
    ProjectUser.text = User.text

    return ProjectUser
}

//in the view
m("input", {config: select2.config({binds: vm.user, type: projectUser(projectID)})})

The projectUser creates a class that implements IEntity. We can be sure that it will work with the autocompleter because it fulfills the contract specified by IEntity, and we can easily tell what the scope of the dropdown will be just from looking at the url field.

Naming is hard

We can take consistency further in other directions: for example, if we needed to create a date picker widget, it would also needs to bind to a getter-setter.

So why not call the argument for that binds as well? Naming bi-directional binding arguments the same across the board makes the API more discoverable than, say, having specially crafted event handler names for every single widget.

//easy to guess if everything else uses the name `binds` as a convention
m("input", {config: datepicker.config({binds: vm.date})})

//not so easy to guess
m("input", {config: datepicker.config({value: vm.date(), ondatechange: m.withAttr("value", vm.date)})})

When we start bringing all of our conventions together, the end result becomes familiar:

//define a component view
select2.view = function(options) {
    return m("input", {config: select2.config(options)})
}

//use the component
select2.view({binds: vm.user, type: User})

If you've dabbled with components, you already know how use functions named view. We just saw what binds does, and we also saw what kinds of things can be plugged into type. So now, you could stumble across code like the following and immediately understand it, even without having seen any documentation:

datepicker.view({binds: vm.date})

Obvious is relative

But just because binds and IEntity make sense to us now, it doesn't mean that they will be obvious to someone who's not familiar with them. Documentation is still a key piece in a predictable system. Co-workers leave for greener pastures, teams grow. If your system is non-trivial and needs to last longer than even just a couple of years, it's foolish to ignore the dynamic nature of the world.

Naming conventions such as binds can be documented in a style guide that shows examples of usage for various widgets that already use the convention.

//call the `.view` method of a component from your templates in order to include them
//widgets can read and write from getter-setters via the `binds` parameter

select2.view({binds: vm.user, type: User})

datepicker.view({binds: vm.date})

It's also good practice to document how to create a trivial binds implementation, so that others can learn how to extend the system within the conventions.

//here's how a create a `binds` option for bi-directional bindings
var getterSetter = m.prop()

//asks user to change the value of a getter-setter if one is not provided
var example = function(options) {
    if (!options.binds()) {
        options.binds(prompt("Set a value:"))
    }
}

example({binds: getterSetter})

You can document interfaces by describing their API, and by showing examples of an implementation, as well as consumption:

/*
interface IEntity<T> {
    static string url;
    static number id(T entity);
    static string name(T entity);
}
*/

//User implements IEntity
var User = function(data) {
    this.id = m.prop(data.id)
    this.name = m.prop(data.name)
}
User.url = "/users"
User.id = function(user) {return user.id()}
User.text = function(user) {return user.name()}

//-----------------------------------------
//consuming the interface (real world case)
select2.view({binds: vm.user, type: User})

//-----------------------------------------
//consuming the interface (simple example of generic code)
function consume(type, value) {
    console.log("url:", type.url, "id:", type.id(value), "text:", type.text(value))
}
consume(User, new User({id: 1, name: "John"}))
consume(Project, new Project({id: 1, name: "John's Project"}))

//exercise: make `ThirdPartyEntity` work w/ `consume`
consume(ThirdPartyEntity, new ThirdPartyEntity({ThirdPartyEntityID: 1, Description: "3rd party entity"}))

Conclusion

We can make complex systems less complex by creating consistent patterns, and documenting these patterns effectively.

Code grows and rots, so it's important to plan ahead.

I once read a theory that developers hit walls of complexity every time they increase the size of their codebases by an order of magnitude (i.e. the idea is that a junior developer might find it hard to expand their simple procedural programs past 3000 lines, and that developers hit another wall of complexity at 30,000 lines, and again at 300,000 and so on)

My own theory is that the these walls appear when the volume of complexity of a codebase exceeds the volume of complexity solved by the libraries it uses. For example, jQuery is undoubtedly useful when dealing with browser quirks, but once an application grows over a few thousand lines of code, unstructured jQuery code simply becomes too difficult to maintain, and you start needing the discipline of a framework to organize code. But when you're at tens of thousands of lines of code, you start to run out of entity types to CRUD, and your application growth starts to build on top of existing concepts. This is when you need the mental shift from being a library consumer to being a reusable component author, but with a focus on the interacting parts within the application (as opposed to generic one-glove-fit-all open source libraries).

Hopefully the ideas we saw in this article will help you tame complexity if you need to scale past the hundreds of lines of code wall.

Short on time? See it in action here

Apps with terse code have a special place in my heart. Note that I said terse, not clever. Cleverness is a tendency to sacrifice code clarity and readability in order to push code size to be smaller (think code golfing). Being terse, on the other hand, is the practice of seeking simplicity in order to make code easier to understand. It implies looking for elegant solutions and avoiding over-engineering.

One such app that looks particularly impressive is this spreadsheet, written in a mere 30 lines of vanilla javascript.

I decided to write a version of it using Mithril. It may seem silly to require a framework (even if it's a really small one) to do something that has been proven to be doable without one, but the purpose of this exercise is precisely to get an idea of how much boilerplate would be required in order to implement the app using the Mithril framework.

This is an important consideration. Frameworks usually require boilerplate code in order to work, and frameworks like Angular can get notoriously verbose. Verbosity can add various costs to development: extra typing required, steep learning curves, more mental baggage to carry when reading code.

//A simple, production-quality AngularJS factory
(function() {
    function something($http) {
        //code here
    }

    something.$injector = ["$http"]

    angular.module("spreadsheet").factory(something)
})()

Mithril positions itself as a minimalist framework. Minimalism can be a slippery slope. It's easy to make a "minimalist" framework that defers all the hard work to the application developer, but the real goal of minimalism in the context of frameworks is to enable developers to simplify their own codebases in addition to being a simple framework. So let's see how Mithril fares.

The model layer

Here's a port of the spreadsheet code to Mithril.

The data variable is the in-memory data store. It reads from localStorage on page load and it's used throughout the code to store the current state of the spreadsheet data. It's a map of values, whose keys are expect to be named after their cells (e.g. data["a1"], data["b3"], etc)

var data = JSON.parse(localStorage["spreadsheet"] || "{}")

The update function computes an expression if it's a string that starts with "=". Then it saves the computed value to both in the in-memory map and localStorage. Here, again, cells are named by combining the letters for the x axis and the numbers from the y axis (e.g. "a1")

function update(cell, value) {
    if (value != null && value[0] == "=") {
        try { with (data) data[cell] = eval(value.substring(1)) } catch (e) {}
    }
    else data[cell] = isNaN(+value) ? value : +value
    localStorage["spreadsheet"] = JSON.stringify(data)
}

The view layer

The grid function creates a table and accepts an arbitrary Mithril template as an argument, which is cloned for every cell in the table.

function grid(withCell) {
    for (var rows = [], i = 0; i < 27; i++) {
        for (var cols = [], j = 0; j < 17; j++) {
            var letter = String.fromCharCode("a".charCodeAt(0) + j - 1)
            cols.push(m("td", i && j ? withCell(letter + i) : i || letter))
        }
        rows.push(m("tr", cols))
    }
    return m("table", m("tbody", rows))
}

The view function is the main template. It creates a grid of text inputs, each of which has bindings to synchronize their values to a slot in the data map.

The cellName argument is the name of the corresponding cell. The name of the very first cell is "a1", the one beside that is "a2", and so on.

function view() {
    return grid(function(cellName) {
        return m("input", {
            onchange: m.withAttr("value", update.bind(this, cellName)),
            value: data[cellName] || ""
        })
    })
}

Finally, the last line tells Mithril to run the application:

m.module(document.body, {controller: function() {}, view: view})

You may have noticed the empty controller. There's only a single writing method in the model (update), and we're calling it directly from the view to cut down on boilerplate.

As you can see, the code isn't that complicated: there's a map of values whose keys are the names of the cells. Whenever an input changes, its respective value is computed (if it's an evalable expression), and then saved to its respective slot in the data map (and also to localStorage). Then Mithril redraws and puts the UI back in sync with the data.

And this port only takes 28 lines of code, just like the original. Not bad.

Extending the application

We saw that porting the vanilla app to Mithril yields very little boilerplate, while keeping code quite readable. But the real test for terseness is whether we can build more functionality on top of it: clever code is full of obscurities and it's hard to understand and modify, but elegant code should be easy to refactor.

Conveniently, we can put our code to the test, because this spreadsheet app can use some improvements. As you might already know, the whole point of a spreadsheet is that they are supposed to be reactive. If the value of a3 is "=a1+a2", then changing the value of a1 should also change a3.

Currently our app simply overwrites the expression so once it's computed, we lose its formula.

Here's a rewrite that fixes that.

The first major change is that our update function is now broken out into three parts:

• the update function takes care of saving to the in-memory data store and to localStorage as before (but it no longer performs the evaluation of expressions)
• the compute function takes care of the expression evaluation logic
• and finally, the computable function is a value object factory. If the input to this function is a number or a string, it simply returns that value, but if the input is an evalable expression (i.e. a string beginning w/ = and followed by a javascript expression), it returns a String object with a custom valueOf method that computes its evalable expression when called.

function computable(value) {
    var output = new String(value)
    output.valueOf = compute.bind(this, value)
    return isNaN(+value) ? output : +value
}
function compute(value) {
    if (value != null && value[0] == "=") {
        try { with (data) return eval(value.substring(1)) } catch (e) {}
    }
    else return value
}
function update(cell, value) {
    data[cell] = computable(value)
    localStorage["spreadsheet"] = JSON.stringify(data)
}

Breaking out compute from update is a fairly standard type of refactorization: we're simply decoupling code for better separation of concerns and better reusability.

The creation of the computable factory is the key refactorization: a computable enables us to store expressions that can evaluate their values on demand. This function is used by the update function to store computable values in our in-memory data store, and it's also used at the very beginning of the script to turn the deserialized localStorage data into computable value objects.

var data = JSON.parse(localStorage["spreadsheet"] || "{}")
for (var cell in data) data[cell] = computable(data[cell])

A computable value object is an immutable object that behaves mostly like a javascript primitive number or string, with one exception: when we attempt to use a computable entity in a mathematical expression, it implicitly calls the custom valueOf method and uses the evaluated expression instead of using the string value. This allows expressions like a1+a2 to perform mathematical computations seamlessly regardless of whether a1 and a2 are numbers or computables. And since computables can evaluate to expressions that reference other computables, they can recursively cascade a data change through a complex web of computable expressions.

Here are some tests to demonstrate the expected behavior of the computable value object:

computable(1) == 1 // true
computable("hello") == "hello" // true
computable("=1+1").toString() == "=1+1" // true
computable("=1+1").valueOf() == 2 // true

data.a1 = 1
computable("=a1+2") + 3 == 6 //true

data.a1 = 1
data.a2 = computable("=a1+2")
computable("=a2+3") + 4 == 10 //true

In the last two tests you can see how tightly integrated to the language valueOf is. The toString and valueOf methods are implicitly called by Javascript whenever type casting is implied. Computable expressions take advantage of this language feature to implement reactivity.

The second major change is that now there's a formula input at the top. This UI addition lets us see and edit the un-evaluated expression for any given cell.

You can see how the bindings for this input work by looking at the view function:

function view() {
    return [
        m("input.formula", {
            onchange: m.withAttr("value", update.bind(this, cell())),
            value: data[cell()] || ""
        }),
        grid(function(cellName) {
            var value = compute(data[cellName]) || ""
            return m("input", {
                onkeydown: move,
                onfocus: cell.bind(this, cellName),
                onchange: m.withAttr("value", update.bind(this, cellName)),
                value: value,
                style: {textAlign: isNaN(value) || value === "" ? "left" : "right"}
            })
        })
    ]
}

The cell variable is simply a view-model getter-setter that holds the name of a cell.

The "input.formula" element has a binding that references the cell getter-setter: when this input is changed, we update the data for the cell referenced by cell(). The value for this input is simply the string value of the data slot referenced by cell().

In addition, each input in the grid now has a onfocus handler that sets the value of cell to their respective cell names. In short, focusing on a cell displays the uncomputed value for that cell.

Finally, one handy UI improvement was added: the app is now keyboard-aware. Pressing the arrows on the keyboard now moves focus around the grid. This happens thanks to the onkeypress event handler move.

function move(e) {
    var td = e.target.parentNode, tr = td.parentNode, table = tr.parentNode
    if (e.keyCode == 37) return highlight(tr.childNodes[Math.max(1, td.cellIndex - 1)].firstChild)
    else if (e.keyCode == 38) return highlight(table.childNodes[Math.max(1, tr.rowIndex - 1)].childNodes[td.cellIndex].firstChild)
    else if (e.keyCode == 39) return highlight(tr.childNodes[Math.min(tr.childNodes.length - 1, td.cellIndex + 1)].firstChild)
    else if (e.keyCode == 40) return highlight(table.childNodes[Math.min(table.childNodes.length - 1, tr.rowIndex + 1)].childNodes[td.cellIndex].firstChild)
    else m.redraw.strategy("none")
}
function highlight(cell) {
    cell.focus()
    cell.selectionEnd = cell.value.length
    return false
}

There's also a one-liner in view that takes care of text alignment of numbers vs text, but other than that, that's pretty much it. These few UI improvements add 16 lines to the code (more than half of the original size!), but I'd argue that being able to navigate a spreadsheet with the keyboard and quickly be able to tell apart text from numbers are important features to have - if you disagree, you can reduce the code size by 16 lines and still have a reactive spreadsheet :)

Once you understand the computable value object, the rest of the application is fairly straightforward: it boils down to the basic principle of data flowing from the model to the view, and then using event handlers to push changes back to the model.

We already covered in other articles some reasons as to what makes this Mithril app clean (despite it having non-trivial functionality like focus-aware reactivity), but it's worth mentioning them again:

• Mithril's "call-me-when-you-need" approach to tooling and the well-defined flow of data makes it easy to spend time thinking about the problem domain, rather than wasting time on framework-specific concepts.
• Explicit data bindings (as opposed to cookie-cutter binding tools like ng-model) allow a greater degree of flexibility when connecting form elements to model data slots, which paradoxically results in less complexity.
• The ability to idiomatically have procedural code live in functions in the view layer lets us express DOM actions without a lot of boilerplate integration code
• Idiomatic Mithril code takes the concept of design patterns to heart: we implement patterns of code in their simplest form, rather than creating bulky classes named after patterns.

Another thing that is worth noting (especially for those who are averse to Mithril's templating syntax), is that even though this app literally fills the page with DOM elements, there's very little "markup" code. This illustrates well the fact that, in non-trivial applications, logic often dominates in terms of code volume. A lot of boilerplate in other frameworks come from shuffling logic around in order to keep HTML "clean" in a way that is reminicent of zero sum games (i.e. get clarity over here at the expense of added complexity over there). We've learned long ago to forego normalization purity in databases in favor of a pragmatic middle ground, and I think this app is an example that shows that pragmatism is a good design driver in frontend as well.

This article was adapted from an essay in the mailing list

Last week we saw how we can animate things with Velocity.js. A related topic that came up on the Mithril bug tracker (and that keeps coming up every once in a while) is the topic of application state (as opposed to data state). Today we'll explore that topic:

Let's imagine we have a button, and that when we click on that button, a panel shows up. When we click on the button again, the panel disappears. In jQuery, we can code this in an action-centered way: "on click, show". Mithril, however, (and for that matter, most MVC frameworks) encourages us to be data-centered: "if this flag is set, show". This means that when we are debugging, instead of having to use PhantomJS to emulate a user clicking through our app to get to a specific state in our application, we can always render the exact UI state that we want if we have our data setup in just the right way. And since data is easy to manipulate via plain javascript, the entire testing workflow is also a lot easier as a result.

But a "this panel is open" flag is not really a "model" value in the traditional sense. It doesn't map to "Users" or "Projects", or to anything else that we might want to store in a database. It's merely data about the UI. This type of data is also known as application state.

Many people get confused when they need to decide where this application state should go. Should it go in the controller? Should it be hidden in the view layer behind a helper function?

The answer is that it is state after all, so it should be in the model layer.

The rationale for this goes back to the definition of MVC:

• the Model layer is responsible for application data, business rules and logic.
• the View is responsible for displaying data
• the Controller is a mechanism that translates user input into commands for the model layer

A little bit of history

In classic MVC (the original Smalltalk one), the Model layer notifies the view of changes to data; the view can send messages to the controller to tell the app to do things; the controller then manipulates the model, which then notifies the view, ad infinitum. The controller may also modify the view without assistance from the Model layer (for example to show a loading icon.) In this original implementation, all layers could contain code: the view could subscribe to model events via the observer pattern, and likewise, the model could trigger events via the same mechanism.

Since then, a lot of twists have been made: we adapted the pattern from the realm of desktop apps to the realm of server-side architectures, and from there to thick client-side architectures. Somewhere along the lines, we started to conflate the View layer with HTML, the Model layer with database tables, and reached the conclusion that anything that is neither HTML nor SQL related must be part of the Controller layer.

In server-side architectures, application state largely became conflated with URLs (so much so, that POST-only URLs are still considered bad practice, since they make it hard to reach certain states). Client-side MVC became prominent precisely because URLs were not enough to express all possible states in heavily AJAX-driven applications. So as complexity grew, we started to see a sort of limbo with application state that didn't fit into a URL, and that didn't really fit anywhere else either (given the cookie-cutter molds that frameworks provided us).

One of the things I'm trying to do with Mithril is encourage people to go back to the basics and realize that a lot of the assumptions and cloudiness surrounding MVC is actually wrong: the view layer isn't HTML-only, the model layer isn't supposed to be solely about ORM classes, controllers aren't supposed to be a pool where we dump things that we don't know how to fit into the rest of the framework.

Going back to the topic of application state: state is just data. Meta data, but still data. Here's an example to illustrate that point: sortable tables. You have a table full of data, you click on a header, it sorts by that header. What if you want to permalink this configuration? Often, we modify the app so that the sorting options are part of the URL. But what if we need to embed this table in another page that makes use of the URL for something else? Or what if the URL is too long? We can keep refactoring and refactoring for every new requirement, but at the end of the day, you have to save the sorting options somewhere.

Of the three layers in MVC, the Model is the one that we really should be using for that. Note that the model layer doesn't necessarily need to save things to a database on the server. If we now go backwards cutting off requirements, we can make a model entity that saves to localStorage, or heck, even to just memory, if the application state is transient enough to be discardable at page unload.

If we structure our code this way from the beginning, then we have a clear API to use the application state in our controllers and views, and we can isolate the exact persistence implementation details to the model layer.

Enter view models

Some newer frameworks (most notoriously .NET MVC) introduce the concept of "View Models", i.e. Model layer entities that exist exclusively to store UI state. They are different from traditional MVC models because by definition, they are tightly tied to specific view components.

Using a singleton is perhaps the simplest way of implementing a View Model:

app.widget1State = {isPressed: m.prop(false)}

/*...*/
m("button", {
  onmousedown: function(){ app.widget1State.isPressed(true) },
  onmouseup: function(){ app.widget1State.isPressed(false) }
})

I use m.prop above to ensure we can refactor the View Model (here, the m.prop getter-setter is an in-memory data storage mechanism; we could later replace it with a custom getter-setter function that saves to localStorage, or the database server, or what have you, because it follows the uniform access principle)

View Models are meant to store application state (e.g. if there's a field and a cancel button, and we need to store the temporary value while editing), and regular Models are meant to store data state (e.g. the value after you save that field). You don't really want to store stuff like valueBeforeEdit and currentValue in your data model class; these are details that only exist because of the UI requirements for a cancel button and are not something that your data model should care about. Similarly, the sorting options of our sortable table and the flag for whether a panel is visible are both cases of application state, so they should live in a view model.

Scoping view models

Normally, for complex pages, it might be tempting to make one big view model to drive the whole page, but it often makes more sense to scope one view model to each component on a page. It's not uncommon that you might need to reference one view model from an unrelated component, but these are uni-directional desired dependencies.

For example, if our sortable table has edit buttons that open up a modal dialog w/ a form, these buttons might set a value in the form's view model. However, this dependency is desired because we want the form dialog to be tied to the button. And since a view model is largely a data storage mechanism, we can still use it in other unrelated scenarios without worrying about the sortable table view model.

Having a single monolithic view model makes it harder to pull out components and reuse them elsewhere without bringing a lot of unrelated baggage with it.

Conclusion

Hopefully this essay can help you figure out where to put what kind of code. A lot of it is more a matter of understanding the MVC pattern and organizing the code in a pragmatic way, as opposed to inventing a "Mithril way" of forcing things to work around dogmatic assumptions that we bring over from our experiences with other frameworks. At the end of the day, the MVC pattern is supposed to be helping us, not getting in our way.

Some people have asked me how they could get animations to work with Mithril, so today we'll look at how to run some simple Velocity.js-powered animations in Mithril templates.

Velocity.js is a library that allows us to run Javascript-based animations which perform on par with CSS transitions (and which work in IE). It's designed to be a drop-in replacement for jQuery's animate method, but it can also be used as a standalone library (i.e. without jQuery).

The easiest way to get started with it is to include a reference to it from a CDN:

<script src="//cdn.jsdelivr.net/velocity/1.0.0/velocity.min.js"></script>

Calling Velocity as standalone library typically looks like this:

Velocity(theElement, {opacity: 0})

The code above should hopefully be self-explanatory: it animates the opacity of an element from its current value to zero. So, assuming it started at opacity: 1, then it performs a fade-out effect.

Let's create a contrived mini-application so we can hook up some animations. First let's define some data:

//model
var people = [
    {id: 1, name: "John"},
    {id: 2, name: "Mary"},
    {id: 3, name: "Bob"}
]

Next, let's create a view to display a list of people:

//view
var view = function() {
    return m("ul", [
        people.map(function(person) {
            return m("li", person.name)
        })
    ])
}

And finally, let's add a bit of functionality: removing a person when its list item is clicked.

//controller
var controller = function() {
    this.remove = function(person) {
        people.splice(people.indexOf(person), 1)
    }
}

//view
var view = function(ctrl) {
    return m("ul", [
        people.map(function(person) {
            return m("li", {
                key: person.id,
                onclick: ctrl.remove.bind(this, person)
            }, person.name)
        })
    ])
}

One thing to notice is that we added a key attribute to the <li>. This is usually good practice if you delete list items because it allows Mithril's virtual DOM diffing engine to be smarter about DOM reuse by providing referential metadata.

Putting it all together:

//model
var people = [
    {id: 1, name: "John"},
    {id: 2, name: "Mary"},
    {id: 3, name: "Bob"}
]

//controller
var controller = function() {
    this.remove = function(person) {
        people.splice(people.indexOf(person), 1)
    }
}

//view
var view = function(ctrl) {
    return m("ul", [
        people.map(function(person) {
            return m("li", {
                key: id,
                onclick: ctrl.remove.bind(this, person)
            }, person.name)
        })
    ])
}

//run the app
m.module(document.body, {controller: controller, view: view})

As we saw earlier, in order to create an animation with Velocity, we need to pass a DOM element as the first argument. In Mithril, templates like the view function above are merely javascript functions that spit out javascript objects, but we can get a handle to the real DOM element by declaring a config attribute.

The config callback gets called after rendering occurs, when all the DOM elements generated by the template are guaranteed to be attached to the HTML document. It is meant to be used for arbitrary DOM manipulation.

var fadesIn = function(element, isInitialized, context) {
    if (!isInitialized) {
        element.style.opacity = 0
        Velocity(element, {opacity: 1})
    }
}

var view = function(ctrl) {
    return m("ul", [
        people.map(function(person) {
            return m("li", {
                key: id,
                onclick: ctrl.remove.bind(this, person),
                config: fadesIn
            }, person.name)
        })
    ])
}

In the snippet above, we defined a new helper function called fadesIn, which we use as a config callback for the li. It sets the list item's opacity to zero, and then animates it back to 1 (i.e. it fades the element in)

The element argument is, as the name suggests, the <li> element.

The second argument, isInitialized is a flag that is set to false on initial rendering, and true for subsequent renders. As you can see, we used it to run the animation only when the element gets created, as opposed to running it every time a redraw occurs.

The third argument is an object that can be used to store element-specific data between redraws. You can read more about it here

With this config callback in place, you should now see the list items fade in when the page loads.

What about fading out?

Fading out is not that much harder to implement, but there's a cognitive dissonance caveat associated with it that often confuses people.

When Mithril redraws, views always look at the current state of the data to figure out what DOM elements should or should not be in the document. But fading out after removing an element from the model breaks that thought model: by definition, an animation starts and ends at different times, so if we remove a person from the list, the system would need to know somehow that its corresponding <li> element should stay in the document for the duration of the animation, even though the person was already removed from our data object at the beginning of the animation.

But because we're using a third-party library to integrate animations to Mithril, the framework would not be able to hide some of the complexities that come with the asynchronous nature of the animations. For example, what is the framework supposed to do with a DOM element if an animation is cancelled mid-way? Should it force you to rollback the deletion in the data model? Should it assume that you will clean up the DOM element manually? If you allow the framework to remove it for you, it might do it too early (e.g. if a redraw happens during a animation), but if you forget to remove it manually or mark it for removal, there's no way the system would know when to handle it, and the element would just sit there forever.

A simpler solution to this conundrum is to shift back in time and allow the animation to happen before the destructive data change happens, and only then, allow the removal of the person to happen atomically in our model layer. Here's a helper that runs the animation before the removal:

var fadesOut = function(callback) {
    return function(e) {
        //don't redraw yet
        m.redraw.strategy("none")

        Velocity(e.target, {opacity: 0}, {
            complete: function() {
                //now that the animation finished, redraw
                m.startComputation()
                callback()
                m.endComputation()
            }
        })
    }
}

The snippet above defines a helper function called fadesOut, which returns an event handler that runs an animation, and then runs an arbitrary callback when the animation finishes.

The m.redraw.strategy("none") line tells Mithril that we don't want to redraw when the event handler returns (because at that point, nothing has changed yet).

The complete callback that we pass to Velocity.js is an asynchronous 3rd party callback, so there we call m.startComputation and m.endComputation to tell Mithril that we want to potentially redraw. Notice that we are not calling m.redraw because that function forces a redraw to happen immediately. We might conceivably want to run AJAX requests or other asynchronous operations in the callback function, so we need to use m.startComputation and m.endComputation to allow Mithril to wait for those asynchronous operations to complete.

Using the fadesOut helper is simple: just wrap it around the remove function.

var view = function(ctrl) {
    return m("ul", [
        people.map(function(person) {
            return m("li", {
                key: id,
                onclick: fadesOut(ctrl.remove.bind(this, person)),
                config: fadesIn
            }, person.name)
        })
    ])
}

Now we have list items that fade in on page load, and fade out when we click on them. Here's the entire code so far.

//model
var people = [
    {id: 1, name: "John"},
    {id: 2, name: "Mary"},
    {id: 3, name: "Bob"}
]

//controller
var controller = function() {
    this.remove = function(person) {
        people.splice(people.indexOf(person), 1)
    }
}

//view
var view = function(ctrl) {
    return m("ul", [
        people.map(function(person) {
            return m("li", {
                key: person.id,
                onclick: fadesOut(ctrl.remove.bind(this, person)),
                config: fadesIn
            }, person.name)
        })
    ])
}

//view helpers
var fadesIn = function(element, isInitialized, context) {
    if (!isInitialized) {
        element.style.opacity = 0
        Velocity(element, {opacity: 1})
    }
}
var fadesOut = function(callback) {
    return function(e) {
        //don't redraw yet
        m.redraw.strategy("none")

        Velocity(e.target, {opacity: 0}, {
            complete: function() {
                //now that the animation finished, redraw
                m.startComputation()
                callback()
                m.endComputation()
            }
        })
    }
}

//run the app
m.module(document.body, {controller: controller, view: view})

What about page changes?

The code above works well for actions within a single page, but what if we want to run animations when jumping between routes?

As per the documentation, config: m.route is the idiomatic way of creating routed links, but there's nothing stopping us from using a custom config function instead, if we want to run animations before leaving a page. Here's how one might go about implementing it:

//helper
var fadesOutPage = function(element, isInitialized, context) {
    if (!isInitialized) {
        element.onclick = function(e) {
            e.preventDefault()
            Velocity(document.getElementById("container"), {opacity: 0}, {
                complete: function() {
                    m.route(element.getAttribute("href"))
                }
            })
        }
    }
}

//in the templates
m("#container", {config: fadesIn}, [
    m("a[href='/foo']", {config: fadesOutPage}, "go to foo")
])

As you can see, the code is strikingly similar what we have been doing before.

The fadesIn helper makes the page fade in when it loads, as it did before.

On the link, we defined an onclick handler that calls Velocity to run some animations on the container element and then redirect using m.route after the animation is done. One difference is that defining an event handler within a config callback doesn't require us to call m.redraw.strategy("none"). Recall that config is designed to be used for integrating non-Mithril code to Mithril templates, and in this case the onclick handler is just plain vanilla javascript, which doesn't do any auto-redrawing. In addition, we don't need to call m.startComputation and m.endComputation either because the m.route() redirect forces the page to redraw anyways.

Note that we could have used onclick as we did with fadesOut, instead of config - There's really no hard rules for whether you should use one or the other. In this article, I used onclick for fadesOut to make it clear that there's a cause-effect relationship between clicking and fading and removing a person, and I used config for fadesOutPage to make it look consistent with the way regular {config: m.route} links do. But as we saw, the default rendering strategy when we attach an onclick in the template required us to add some extra code to prevent auto-redrawing from happening in that particular event handler. The rule of thumb is that an onclick handler auto-redraws by default (for the sake of convenience in the data-model-updating case), whereas config has auto-redrawing turned off by default (for convenience in the free-reign-over-the-DOM case). As we saw, it's perfectly possible to change these defaults, so just use your best judgement to decide what option makes your code the most readable.

As you may know, Mithril is a pretty minimalist framework, which allows sugar functionality to be created by the community.

A recurring mantra in Mithril is that if something is too noisy or repetitive, you can put the verbosity in a function and call that instead. Today we'll look at a somewhat surprising extension point, but one that is extremely powerful: wrapping around the m method.

First let's create a basic wrapper:

var mx = function(selector, attrs, children) {
    return m(selector, attrs, children)
}

As you can see, this doesn't really do anything new. The key here, though, is that it allows us to programmatically edit the attributes before creating the virtual dom element via m.

Let's create a simple collection of attribute transformers:

var customAttrs = {
    cautions: function(callback) {
        this.onclick = function(e) {
            if (prompt("Are you sure?")) callback(e)
        }
    },
    toggles: function(flag) {
        if (!this.style) this.style = {}
        this.style.display = flag ? "block" : "none"
    }
}

An attribute transformer is simply a method that is meant to be called on a attribute that modifies it. In the example above, cautions adds an onclick handler that prompts the user before running a callback. toggles shows or hides an element based on a flag.

We can now extend mx to tap into our collection:

var mx = function(selector, attrs, children) {
    for (var attrName in attrs) {
        if (customAttrs[attrName]) customAttrs[name].call(attrs, attrs[attrName]) 
    }
    return m(selector, attrs, children)
}

What we're doing in the code above is look for attribute names that exist in the customAttrs dictionary. If one does, we call that function using the attrs object as the this object.

Now we can easily bind our custom attribute transformers to a template:

var buttonVisible = m.prop(false)
var myView = function() {
    return [
        m("a", {onclick: buttonVisible.bind(this, !buttonVisible())})
        mx("button", {toggles: buttonVisible, cautions: ctrl.selfDestruct}, "Press if evil plans are foiled")
    ]
}

In the code above, the button becomes visible when the buttonVisible getter-setter is set to true, and on click, it prompts the user to confirm that they do, in fact, want to call selfDestruct.

Handling conflicts

A clever reader might notice that this transformer suffers from one problem - it can clobber attributes. For example:

mx("button", {cautions: ctrl.remove, onclick: ctrl.doSomethingElse}, "Remove")

In the snippet above, cautions assigns a function to the onclick attribute, which means that ctrl.doSomethingElse does not run when we click on the button.

Fortunately, javascript is a dynamic language, which allows us to use monkeypatching to easily solve this problem:

var monkeypatch = function(f1, f2) {
    return function() {
        var output1, output2
        if (typeof f1 == "function") output1 = f1.apply(this, arguments)
        if (typeof f2 == "function") output2 = f2.apply(this, arguments)

        //make compatible w/ event handler `return false` behavior
        return output1 === false || output2 === false ? false : undefined
    }
}
var customAttrs = {
    cautions: function(callback) {
        this.onclick = monkeypatch(this.onclick, function(e) {
            if (prompt("Are you sure?")) callback(e)
        })
    }
}

This preserves an existing onclick if it already exists, so that if the new onclick gets called, both the existing onclick and the callback run one after the other. We can easily tweak the order of execution for event handlers by simply changing the order of the parameters, and we can even replace monkeypatch altogether with different helpers to achieve more advanced event handler coordination (e.g. preventing a handler from running based on the return value of another.)

Conclusion

By wrapping around the m function, we are able to add custom functionality to templates using the same familiar syntax as regular HTML attributes.

Not only can we mix and match different units of functionality in a single DOM element, but we can also maintain control over how they interact with each other, even in the hairiest scenarios.

And this is only the beginning. We saw that the mx wrapper we saw above only passes attributes to the list of transformers. But it's perfectly possible to expand this method and make it also introspect the selector parameter, as well as the virtual element that is returned from the wrapped m call, and even the children virtual elements, so we can create flexible transformers that act differently based on various criteria.

Here's an example that makes a good exercise to the reader: bi-directional bindings. Try creating a transformer called binds, which can read and write to a m.prop getter-setter, and that can correctly attach itself to a virtual element, considering that you need to read the value attribute in text inputs, but you need to read the checked attribute for checkboxes and radio boxes, and so on.

Or try writing one that replaces an empty child list with a "there are no items" text node. Or one that changes the output of the selector a[href]'s into the equivalent of [href="javascript:;"]. There's an endless amount of niceties that you can add to improve the developer ergonomics of the system.

And we can use the same system to add non-trivial functionality. The fact that we can tap into Mithril's config attribute from transformers means that, in addition to being able to modify virtual elements on the fly, we can also wrap around 3rd-party library integration boilerplate while keeping the ability of managing element lifecycles. In other words, we can have complex widgets with nice syntax. And we can still mixin transformers. And we still have the ability to introspect and edit components after inclusion if needed.

Before I leave you with this cool new technique, remember that with great power comes great responsibility. A wrapper's job is to hide complexity, and in this case there's two interfaces to consider: how we use the wrapper in templates and how easy it is to add transformers to the system. In addition, you also need to be aware of the cost of the wrapper's complexity itself. You are responsible for deciding how often your version of mx is called and how much "magic" that wrapper performs, given that the cost of the wrapper is multiplied by the number of times you call it.

Generally speaking, the cost of a wrapper - even a complex one - is surprisingly negligible. (Fun fact: Mithril's templating engine is fast even though m() uses regular expressions!) However, calling a carelessly slow implementation of mx for every element in a page that has tens of thousands of elements is bound to cause problems. If push comes to shove, there are ways to get around performance problems of that nature, but it's always better to put some thought in the design phase than to fix mistakes in the maintenance phase.

Anyways, I hope this article gives you some ideas on how to make your templates cleaner and your experience with Mithril templating even more pleasant.