Making ajax a bit nicer: Client

Since I wanted the same code to work in Node and in the browser, I added a (chainable) HTTP interface that works both with jQuery and Node.js. Here is a usage example:

Client
  .get('http://www.google.com/')
  .data({q: 'hello world'})
  .end(function(err, data) {
    console.log(data);
  });

And the full source code: for jQuery (~40 lines; below) and for Node (~70 lines; w/JSON parsing).

var $ = require('jquery');

function Client(opts) {
  this.opts = opts || {};
  this.opts.dataType || (this.opts.dataType = 'json');
  this.opts.cache = false;
};

Client.prototype.data = function(data) {
  if(!data || Object.keys(data).length == 0) return this;
  if(this.opts.type == 'GET') {
    this.opts.url += '?'+jQuery.param(data);
  } else {
    this.opts.contentType = 'application/json';
    this.opts.data = JSON.stringify(data);
  }
  return this;
};

Client.prototype.end = function(callback) {
  this.opts.error = function(j, t, err) {
    callback && callback(err);
  };
  this.opts.success = function(data, t, j) {
    callback && callback(undefined, data);
  };
  $.ajax(this.opts);
};

module.exports.parse = Client.parse = function(callback) {
  return function(err, response) {
    callback && callback(undefined, response);
  };
};

['get', 'post', 'put', 'delete'].forEach(function(method) {
  module.exports[method] = function(urlStr) {
    return new Client({
      type: method.toUpperCase(), url: urlStr
    });
  };
});

Putting it all together

Now, that's a fairly useful data source implementation; minimal yet useful. You can certainly reuse it with your framework, since there are no framework dependencies; it's all (ES5) standard Javascript.

Defining a data source

Now, let's create a page that allows us to use the datasource to retrieve data. For example, you might want to use the datasource with a model. You may have noticed that I slipped in support for instantiating models from the result (see the this.model parameter in implementation). This means that we can ask the data source to instantiate objects from a given model constructor by passing the model option:

// Find instances of Todo using Todo.find()
Todo.find = new DataSource({
  uri: function(id) {
    return 'http://localhost:8080/api/todo/'
      + (id ? encodeURIComponent(id) : 'search');
  },
  model: Todo
});

As you can see, the uri function simply returns the right URL depending on whether the search is about a specific ID or just a search.

The code also demostrates composition over inheritance. The inheritance-based way of setting up this same functionality would be to inherit from another object that has the data source functionality. With composition, we can simply assign the DataSource to any plain old JS object to add the ability to retrieve JSON data by calling a function.

Building a backend.

The server-side for the datasource can be fairly simple: there are two cases - reading a model by ID, and searching for a model by property.

var http = require('http'),
    url = require('url');
var todos = [
      { id: 1, title: 'aa', done: false },
      { id: 2, title: 'bb', done: true },
      { id: 3, title: 'cc', done: false }
    ],
    server = http.createServer();

var idRe = new RegExp('^/api/todo/([0-9]+)[^0-9]*$'),
    searchRe = new RegExp('^/api/todo/search.*$');

server.on('request', function(req, res) {
  res.setHeader('content-type', 'application/json');
  if(idRe.test(req.url)) {
    var parts = idRe.exec(req.url);
    // return the ID
    if(todos[parts[1]]) {
      res.end(JSON.stringify(todos[parts[1]]));
    }
  } else if (searchRe.test(req.url)) {
    var data = '';
    req.on('data', function(part) {
      data += part;
    });
    req.on('end', function() {
      var search = undefined;
      try {
        search = JSON.parse(data);
      } catch (error) {}
      res.end(typeof(search) === 'undefined' ? undefined : JSON.stringify(
        // search the todos array by key - value pair
        todos.filter(function(item) {
          return Object.keys(search).every(function(key) {
            return item[key] && item[key] == search[key];
          });
        })
      ));
    });
  } else {
    console.log('Unknown', req.url);
    res.end();
  }
});

8. Implementing a model

What's a model? Roughly, a model does a couple of things:

• Data. A model contains data.
• Events. A model emits change events when data is altered.
• Persistence. A model can be stored persistently, identified uniquely and loaded from storage.

That's about it, there might be some additional niceties, like default values for the data.

Defining a more useful data storage object (Model)

Change events

Model accessors (get/set) exist because we want to be able to intercept changes to the model data, and emit change events. Other parts of the app -- mainly views -- can then listen for those events and get an idea of what changed and what the previous value was. For example, we can respond to these:

• a set() for a value that is used elsewhere (to notify others of an update / to mark model as changed)
• a remove() for a value that is used elsewhere

We will want to allow people to write model.on('change', function() { .. }) to add listeners that are called to notify about changes. We'll use an EventEmitter for that.

If you're not familiar with EventEmitters, they are just a standard interface for emitting (triggering) and binding callbacks to events (I've written more about them in my other book.)

Using the Model class

So, how can we use this model class? Here is a simple example of how to define a model:

function Photo(attr) {
  Model.prototype.apply(this, attr);
}

Photo.prototype = new Model();

module.exports = Photo;

Creating a new instance and attaching a change event callback:

var badger = new Photo({ src: 'badger.jpg' });
badger.on('change', function(key, value, oldValue) {
  console.log(key + ' changed from', oldValue, 'to', value);
});

Defining default values:

function Photo(attr) {
  attr.src || (attr.src = 'default.jpg');
  Model.prototype.apply(this, attr);
}

Since the constructor is just a normal ES3 constructor, the model code doesn't depend on any particular framework. You could use it in any other code without having to worry about compatibility. For example, I am planning on reusing the model code when I do a rewrite of my window manager.

Differences with Backbone.js

I recommend that you read through Backbone's model implementation next. It is an example of a more production-ready model, and has several additional features:

• Each instance has a unique cid (client id) assigned to it.
• You can choose to silence change events by passing an additional parameter.
• Changed values are accessible as the changed property of the model, in addition to being accessible as events; there are also many other convenient methods such as changedAttributes and previousAttributes.
• There is support for HTML-escaping values and for a validate() function.
• .reset() is called .clear() and .remove() is .unset()
• Data source and data store methods (Model.save() and Model.destroy()) are implemented on the model, whereas I implement them in separate objects (first and last chapter of this section).

  9. Collections

What's in a collection? A collection:

• contains items (or models)
• emits events when items are added/removed
• is ordered; can be accessed by index via at() and by model ID via get()

In this chapter, we'll write an observable array, and then add some additional niceties on top of it to make it a collection (e.g. something that is specific to storing models).

Storing Models and emitting events

Let's start with the constructor. We want to mixin EventEmitter to add support for events for the collection.

function Collection(models) {
  this.reset();
  models && this.add(models);
}
util.inherits(Collection, events.EventEmitter);

To support passing a set of initial models, we call this.add() in the constructor.

Resetting the collection. Self-explanatory, really. We will use an array to store the models, because collections are ordered rather than indexed; and we will maintain a length property directly for convenience.

Collection.prototype.reset = function() {
  this._items = [];
  this.length = 0;
  this.emit('reset');
};

Adding items. We should be able to call add(model) and emit/listen for an "add" event when the model is added.

Collection.prototype.add = function(model, at) {
  var self = this;
  // multiple add
  if(Array.isArray(model)) {
    return model.forEach(function(m) { self.add(m, at); });
  }
  this._items.splice(at || this._items.length, 0, model);
  this.length = this._items.length;
  this.emit('add', model, this);
};

To support calling add([model1, model2]), we'll check if the first parameter is an array and make multiple calls in that case.

Other than that, we just use Array.splice to insert the model. The optional at param allows us to specify a particular index to add at. Finally, after each add, we emit the "add" event.

Removing items. We should be able to call remove(model) to remove a model, and receive events when the item is removed. Again, the code is rather trivial.

Collection.prototype.remove = function(model){
  var index = this._items.indexOf(model);
  if (index > -1) {
    this._items.splice(index, 1);
    this.length = this._items.length;
    this.emit('remove', model, this);
  }
};

Retrieving items by index and retrieving all items. Since we are using an array, this is trivial:

Collection.prototype.at = function(index) { return this._items[index]; };

Collection.prototype.all = function() { return this._items; };

Iteration

We also want to make working with the collection easy by supporting a few iteration functions. Since these are already implemented in ES5, we can just call the native function, setting the parameter appropriately using .apply(). I'll add support for the big 5 - forEach (each), filter, map, every and some:

['filter', 'forEach', 'every', 'map', 'some'].forEach(function(name) {
  Collection.prototype[name] = function() {
    return Array.prototype[name].apply(this._items, arguments);
  }
});

Sorting

Implementing sorting is easy, all we need is a comparator function.

Collection.prototype.sort = function(comparator) {
  this._items.sort(comparator || this.orderBy);
};

Array.sort is already implemented in ES3 and does what we want: you can pass a custom comparator, or set collection.orderBy to set a default sort function.

Using our observable array

The code above covers the essence of an observable array. Let's look at few usage examples before moving on to a making it a collection.

var items = new Collection();
items.on('add', function(item) {
  console.log('Added', item);
});
setInterval(function() {
  items.add(Math.floor(Math.random() * 100));
  console.log(items.all());
}, 1000);

Creating a collection

A collection is a more specialized form of an observable array. Collections add the ability to hook into the events of the models they contain, and add the ability to retrieve/check for item presence by model id in addition to the position in the array.

get(modelId). Let's implement get(modelId) first. In order to make get() fast, we need a supplementary index. To do this, we need to capture the add() and remove() calls:

Collection.prototype.add = function(model, at) {
  var self = this, modelId;
  // ...
  modelId = model.get('id');
  if (typeof modelId != 'undefined') {
    this._byId[modelId] = model;
  }
};

Collection.prototype.remove = function(model){
  var index = this._items.indexOf(model), modelId;
  // ...
  modelId = model.get('id');
  if (typeof modelId != 'undefined') {
    delete this._byId[modelId];
  }
};

Now get() can make a simple lookup:

Collection.prototype.get = function(id) { return this._byId[id]; };

Hooking into model events. We need to bind to the model change event (at least), so that we can trigger a "change" event for the collection:

Collection.prototype._modelChange = function(key, value, oldValue, model) {
  this.emit(key, value, oldValue, model);
};

Collection.prototype.add = function(model, at) {
  // ...
  model.on('change', this._modelChange);
};

And we need to unbind when a model is removed, or the collection is reset:

Collection.prototype.remove = function(model){
  // ...
  model.removeListener('change', this._modelChange);
};
Collection.prototype.reset = function() {
  var self = this;
  if(this._items) {
    this._items.forEach(function(model) {
      model.removeListener('change', self._modelChange);
    });
  }
  // ...
};

10. Implementing a data cache

There are three reasons why we want a data store:

• To have a central mechanism for saving data.
• To retrieve cached models quickly.
• To prevent duplicate instances of the same model being created.

The first two are obvious: we need to handle saving, and when possible, use caching to make unambiguous retrievals fast. The only clearly unambigous type of retrieval is fetching a model by id.

The last reason is less obvious. Why is it bad to have duplicate instance of the same model? Well, first, it is inefficient to have the same data twice; but more importantly, it is very confusing if you can have two instances that represent the same object but are separate objects. For example, if you have a data cache that always returns a new object rather than reusing an existing one, then you can have situations where you change the model data, or add a model data listener, but this change does not actually work as expected because the object you used is a different instance. We'll tackle this after looking at saving and caching.

Implementing save()

Serializing models into JSON. In order to send the model data, we need the ability to transform a model into a string. JSON is the obvious choice for serializing data. We need to add a additional method to the model:

Model.prototype.json = function() {
  return JSON.stringify(this._data);
};

Mapping to the right backend URL. We also need to know where to save the model:

Model.prototype.url = function(method) {
  return this.prototype.urlRoot +
    (method == 'create' ? '' : encodeURIComponent(this.id));
};

There are three kinds of persistence operations (since reads are handled by the data source):

• "create": PUT /user
• "update": POST /user/id
• "delete": DELETE /user/id

When the model doesn't have a id, we will use the "create" endpoint, and when the model does have id, we'll use the "update"/"delete" endpoint. If you set Model.prototype.urlRoot to "http://localhost/user", then you'll get the urls above, or if your URLs are different, you can replace Model.prototype.url with your own function.

Connecting Model.save() with the DataStore. Reading is done via the data source, but create, update and delete are done via the data store. For the sake of convenience, let's redirect Model.save() to the DataStore:

Model.prototype.save = function(callback) {
  DataStore.save(this, callback);
};

And do the same thing for Model.destroy:

Model.prototype.destroy = function(callback) {
  DataStore.delete(this, callback);
};

Note that we allow the user to pass a callback, which will be called when the backend operation completes.

Managing the model lifecycle

Since the data store is responsible for caching the model and making sure that duplicate instances do not exist, we need to have a more detailed look at the lifecycle of the model.

Instantiation. There are two ways to instantiate a model:

new Model();

The cache should do nothing in this case, models that are not saved are not cached.

DataSource.find(conditions, function(model) { ... });

Here, the models are fetched from the backend using some conditions. If the conditions are just model IDs, then the data source should check the cache first.

When models are instantiated from data with an ID, they should be registered with the cache.

Persistence operations: create, update, delete.

Model.save(); // model.id is not set

Once the backend returns the model id, add the model to the data cache, so that it can be found by id.

Model.save(); // model.id is set

Add the model to the data cache, so that it can be found by id.

Model.delete();

Remove the model from the data cache, and from any collections it may be in.

Data changes. When the model ID changes, the cache should be updated to reflect this.

Reference counting. If you want an accurate count of the number of models, you must hook into Collection events (e.g. add / remove / reset). I'm not going to do that, because a simpler mechanism -- for example, limiting model instances by age or by number -- achieves the essential benefits without the overhead of counting. When ES6 WeakMaps are more common, it'll be much easier to do something like this.

Implementing the data store / cache

DataStore.add(), DataStore.has(), DataStore.save(), DataStore.delete(), DataStore.reference().

The implementation section is still a work in progress, my apologies.

11. Implementing associations: hasOne, hasMany

Defining associations. Associations / relationships are sugar on top of the basic data source implementation. The idea is that you can predefine the associations between models, for example, that a post hasMany comments. This might be described as:

function Post(args) {
  Model.apply(this, args);
  this.definition = {
    tags: Tags,
    comments: Comments
    };
}

We can fetch stuff manually without assocation support. For example, assume that posts.comment_ids is an array of ids:

db.tag(post.comment_ids, function(tags) {
  tags.forEach(function(tag)) {
    // ...
  });
});

But given several levels of nesting (post has comment has author), this gets old pretty fast.

It's the age-old problem of dealing with callbacks - which turns out to be pretty trivial once you add a couple of control flow patterns to your repertoire. The fundamental ones are "series", "parallel" and "parallel but with limited concurrency". If you are unfamiliar with those, go read Chapter 7 - Control Flow of my previous book.

Don't pretend to have a blocking API. Some frameworks have taken the approach that they pretend to provide a blocking API by returning a placeholder object. For example:

var comments = post.get('comments');
// we do not have the data for comments,
// but we'll return a placeholder object for it

This is a very, very leaky abstraction. It just introduces complexity without really solving the issue, which is that you have to wait for the database to return results. I'd much rather allow the user to set a callback that gets called when the data has arrived; with a little bit of control flow you can easily ensure that the data is loaded - or build a higher level mechanism like we will be doing.

APIs that appear not to incur the cost of IO but actually do are the leakiest of abstractions (Mikeal Rogers). I'd much rather opt for the simple callback, since that allows me to explictly say that a piece of code should run only when the required data has arrived.

Building a nicer API for fetching associated records

Now, I don't want to do this either:

post.get('tags', function(tags) {
  post.get('comments').each(function(comment) {
    comment.get('author', function(comments) {
      // ...
    });
  });
});

Instead, I think the right pattern (as advocated in my previous book) is to tell the system what I want and pass a single callback that will run when the data is loaded:

post.with(['tags', 'comments.author'], function(post) {
  // post.tags; post.comments and post.comments[0..n].author should now be loaded
});

Basically, you tell the API what you want as the input, and give it a callback to run when it has done your bidding.

Implementation. How can we build this? It is basically an API that takes a bunch of paths, looks up the metadata, makes data source calls to fetch by ID, and stores the data on the model, and then calls the continuation callback.

The implementation section is still a work in progress, my apologies.

12. Views - Templating

What's in a template?

I would classify templating systems not based on their input, but based on their output:

• as simple functions
• as functions and metadata
• as objects with lifecycles

The simplest systems make string interpolation and array iteration more convenient. More complicated ones generate metadata that can be used as an input for other systems.

The simplest templating system

A template is the part of the view object that is responsible for generating HTML from input data. In other words, a template is a function which takes a single argument: base (context) and returns a string of HTML.

function itemTemplate(base) {
  return [
    '<li>',
      '<div class="todo', (base.done ? ' done' : ''), '">', base.text, '</div>',
    '</li>'
  ].join('');
}

Of course, writing templates with this syntax is generally not preferred. Instead, templating libraries are used in order to get the best of both worlds: the nicest possible template definition syntax, and the performance of using native JS operations. Templating syntax should have no performance impact - you should always precompile your templates into their optimal JS equivalents.

The optimal output for simple templates

In theory, unless a templating library does something extremely unusual, all of the templating libraries should have similar performance: after all, they only perform string interpolation on an input and ought to compile to similar compiled JS output.

Sadly, in the real world very few templating languages actually compile to the optimal markup. Have a look at the results from this benchmark:

I'm not discussing the causes here, because even with the slowest templating engine, the rendering itself doesn't have a significant impact in terms of total time (since even the slowest engines can cope with hundreds of template renders per 16 ms). In other words - despite large differences (up to two orders of magnitude) in microbenchmarks - generating HTML from a compiled template is unlikely to be a bottleneck no matter how slow it is, except on mobile browsers.

Outputting metadata / objects with lifecycles

As I noted in the overview chapter for the view layer, the key difference between view layer implementations is their update granularity: whether views are redrawn as a whole (view-granular) or can be rendered at element-granularity or string-granularity.

View-granular systems can just use the simple output where a compiled template is represented as a function that takes a set of data and returns a string. Element-granular and string-granular view layers need more metadata, because they need to convert the bindings into code that keeps track of and updates the right parts of the view.

Hence, element-granular and string-granular rendering requires a templating system that outputs objects / metadata in addition to strings. Notice that this doesn't generally affect what features are supported in the templating language: it just affects how granular the updates are and the syntax for defining things like event handlers.

Templating language features

Let's have a look at some common templating language features. Sadly, I don't have the time right now to write a templating system - as cool and fun that would be, I'm pretty sure it would be a low payoff in terms of writing a book.

String interpolation allows us to insert values into HTML. Dependending on the update granularity, the tokens can be updated either only by re-rendering the whole view, or a single element, or by updating the content of the element with string-granular updates.

<div>
   Hello {{ name }}!
</div>

Escaping HTML. It is generally a bad practice not to escape the values inserted into HTML, since this might allow malicious users to inject Javascript into your application that would then run with the privileges of whomever is using the application. Most templating libraries default to escaping HTML. For example, mustache uses {{name}} for escaped HTML and {{{name}}} ("triple mustache") for unescaped strings.

Simple expressions. Expressions are code within a template. Many templating libraries support either a few fixed expressions / conditions, or allow for almost any JS code to be used as an expression.

 <li><div class="todo {{ done? }}">{{ text }}</div></li>

I don't have a strong opinion about logic-in-views vs. logicless views + helpers. In the end, if you need logic in your views, you will need to write it somewhere. Intricate logic in views is a bad idea, but so is having a gazillion helpers. Finding the right balance depends on the use case.

Generally, templating engines support {{if expr}} and {{else}}for checking whether a value is set to a truthy value. If the templating library doesn't support logic in views, then it usually supports helpers, which are external functions that can be called from the template and contain the logic that would otherwise be in the template.

Displaying a list of items. There are basically two ways, and they correspond to how sets of items are represented in the model layer.

The first option corresponds to observable arrays: you use an expression like each to iterate over the items in the observable array:

{{view App.TodoList}}
<ul>
  {{each todos}}
    {{view App.TodoView}}
     <li><div class="todo {{ done? }}">{{ text }}</div></li>
    {{/view}}
  {{/each}}
</ul>
{{/view}}

The second option corresponds with collections of models, where the view is bound to a collection and has additional logic for rendering the items. This might look something like this:

{{collectionview App.TodoList tag=ul collection=Todos}}
   <li><div class="todo {{ done? }}">{{ text }}</div></li>
{{/collectionview}}

Observable arrays lead to less sophisticated list rendering behavior. This is because each is not really aware of the context in which it is operating. Collection views are aware of the use case (since they are components written for that specific view) and can hence optimize better for the specific use case and markup.

For example, imagine a chat message list of 1000 items that is only updated by appending new messages to it. An observable array representing a list of messages that contains a thousand items that are rendered using a each iterator will render each item into the DOM. A collection view might add restrictions about the number of items rendered (e.g. only showing the most recent, or implementing incremental rendering by only rendering the visible messages in the DOM). The observable array also needs to keep track of every message, since there is no way of telling it that the messages, once rendered, will never be updated. A collection view can have custom rendering logic that optimizes the renderer based on this knowledge.

If we choose the "each" route for collections, then optimizing rendering performance becomes harder, because the mechanism most frameworks provide is based on rendering every item and tracking every item. Collection views can be optimized more, at the cost of manually writing code.

Nested view definition

Templating libraries usually only support defining one template at a time, since they do not have an opinion about how templates are used in the view layer. However, if the output from your templating system is a set of views (objects / metadata) rather than a set of templates (functions that take data arguments), then you can add support for nested view definition.

For example, defining a UserInfo view that contains a UserContact and UserPermissions view, both of which are defined inside the App.UserInfo view:

{{view App.UserInfo}}
<ul>
  <li>User information</li>
  {{view App.UserContact}}
    ...
  {{/view}}
  {{view App.UserPermissions}}
    ...
  {{/view}}
</ul>
{{/view}}

This means that the output from compiling the above markup to object/metadata info should yield three views: UserInfo, UserContact and UserPermissions. Nested view definition is linked directly with the ability to instantiate and render a hierarchy of views from the resulting object; in the case above, the UserInfo view needs to know how to instantiate and render UserContact and UserPermissions in order to draw itself.

In order to implement this, we need several things:

• A template parser that outputs objects/metadata
• A view layer that is capable of rendering child views from templates
• Optionally, the ability to only render the updated views in the hierarchy

The first two are obvious: given markup like the one in the example, we want to return objects for each view. Additionally, views that contain other views have to store a reference to those views so that they can instantiate them when they are drawing themselves.

What about the ability to only render the updated views in the hierarchy? Well, imagine a scenario where you need to re-render a top-level view that contains other views. If you want to avoid re-rendering all of the HTML, then you have two choices:

• Write the render() function yourself, so that it calls the nested render() functions only when relevant
• After the initial render, only perform direct updates (e.g. via element-granular or string-granular bindings)

The first option is simpler from a framework perspective, but requires that you handle calls to render() yourself. This is just coordination, so not much to discuss here.

The second option relies on adding metadata about which pieces of data are used in the views, so that when a model data change occurs, the right views/bound elements can be updated. Let's have a look at how this might be done next.

Adding metadata to enable granular (re)-rendering

The basic idea here is to take one set of strings (the names/paths to the model data in the global scope), and translate them into subscriptions on model changes (e.g. callbacks that do the right thing). For example, given this templating input:

{{view}}
   Hello {{ window.App.currentUser.name }}!
{{/view}}

... the output should be a view object, a template and a event subscription that updates the piece of the DOM represented by the {{window.App.currentUser.name}} token. References to items can be considered to be dependencies: when a observed value changes, then the element related to it should change. They might result in a subscription being established like this:

Framework
  .observe('window.App.currentUser.name')
  .on('change', function(model) {
    $('#$1').update(model);
  });

Where $('#$1') is an expression which selects the part to update. I am glossing over the implementation of the DOM selection for the piece of DOM. One way that might be done - in the case of a element-granular view layer - would be to create a templating function that wraps those updateable tokens with a span tag and assigns sequential ID numbers to them:

<div id="$0">
   Hello <span id="$1">Foo</span>!
</div>

The id attributes would need to be generated on demand when the view is rendered, so that the code that subscribes to the change can then refer to the updateable part of the string by its ID. For string-granular updates, the same would be achieved by using <script> tags, as discussed in the overview chapter for the view layer.

To avoid having to type the fully qualified name of the model data that we want to bind to, views can add a default scope in the context of their bindings:

{{view scope="window.App.currentUser"}}
   Hello {{ name }}!
{{/view}}

This addition makes the subscription strings less verbose.

This is the gist of granular re-rendering. There are additional things to consider, such as registering and unregistering the listeners during the view life cycle (e.g. when the view is active, it should be subscribed; when it is removed, it should be unsubscribed). Additionally, in some cases there is an expression that needs to be evaluated when the observed value changes. These are left as an exercise to the reader, at least until I have more time to think about them.

13.Views - Behavior: binding DOM events to HTML and responding to events

In this chapter, I will discuss the things that need to happen in order to respond to user events:

• attaching listeners to DOM nodes in the HTML in order to react to user events
• handling cross-view communication
• abstracting common behavior in views

Different kinds of UI interactions

Additing interactivity is about taking a DOM event and responding to it by doing something in the model layer and the view layer. Let's look at a few different kinds of interactions using Gmail as an example, and see how they might affect the state of the application (e.g. the model/view layers).

	Model data change. Here, the user interaction results in a model property being set. For example, in Gmail, click a message to star it. This might result in message.starred being set to true. Assuming that the view layer receives change events from the model, any views showing that message can then update themselves.
	Single view state change. Here, it is less clear which model is associated with the change. For example, in Gmail, click a collapsible section to show/hide it. This is naturally expressed as a property of the view instance.
	Multiple view state change. In this case, we want a single action to influence multiple views. For example, in Gmail, change the compactness of the app display density. This will cause all views to adjust their display density, making them visually more compact. There are two ways this might be implemented: by sending a transient message to which all views react, or by having a setting in the global scope that all views poll/subscribe to.
	Page state transition. What makes page state transitions different from the others is that it involves a wholesale change in the page. Views might be destroyed or hidden, and new views swapped in place of them. For example, in Gmail, click on "Compose" to start writing a new message, which loads up the message editor.

Binding DOM events to the View

What the examples above try to show is that in order to respond to user actions, we need to do two things:

• Listen to DOM events
• Given the event, figure out what action makes sense

Listening to DOM events is all about the lifecycle of our view. We need to make sure that we attach the DOM listeners when the element containing the view is inserted into the DOM and removed when the element is removed. In essence, this requires that we delay event registration and make sure it each handler is attached (but only once), even if the view is updated and some elements within the view are discarded (along with their event handlers).

Figuring out what action makes sense is part app programming, part framework capabilities. Whether we are using model-backed views or markup-driven views, we still want to make the most common operations simple to do by providing access to the related information. The rest is app-specific.

Options for specifying the event-to-handler relations

Since the DOM only has a element-based API for attaching events, there are only two choices:

• DOM-based event bindings.
• Framework-generated event bindings.

DOM-based event bindings basically rely on DOM properties, like the element ID or element class to locate the element and bind events to it. This is fairly similar to the old-fashioned $('#foo').on('click', ...) approach, except done in a standardized way as part of view instantiation. Here is an example:

View.template = '<div>\
    <input type="checkbox" class="select">\
    <img class="toggleStar">\
    <a class="hide">Hide</a>\
  </div>';

View.events = {
  'click .select': function() {
    Emitter.emit('intent:message:select', this.model);
  },
  'click .toggleStar': function() { this.model.toggleStar(); },
  'click .hide': 'hide',
};

Framework-generated event bindings allow you to bind event handlers to HTML without explicitly providing a element ID or selector for the view. Here is an example:

{{#view Foo}}
<div>
  <input type="checkbox"
    {{onclick="Emitter.emit('intent:message:select', this.model);"}}>
  <img {{onclick="this.model.toggleStar();"}}>
  <a {{onclick="this.hide();"}}>Hide</a>
</div>
{{/view}}

Both of these are obviously just ways to call the DOM API to add event listeners to elements. The difference is that DOM-selector-based event bindings can be implemented much more simply. The framework-generated event bindings require that the framework generates selectors to attach the event bindings, and that the metadata for what events to listen to and what to do needs to be extracted out of the template into metadata or a view object.

I find it fairly hilarious that we've basically come full circle: when JS launched, it began with onclick handlers inside HTML. Then people started hating on JS within HTML. And now, we're back to defining onclick handlers; except that now those onclick handlers actually get compiled into JS objects that represent the DOM that are managed by a framework.

Of course, things are a bit different on this iteration: the patterns used are more sophisticated, we pass a custom scope to the event handler, the bindings for the onclick handlers are more intelligent, and binding/unbinding events is handled by the framework. There is a certain declarativeness to writing onclick handlers this time around. But still, I find it funny.

Implementing event bindings

There is a reason why many frameworks make a view represent a single element: it makes binding events a lot easier if you can instantiate the element early on. The initial render workflow looks something like this:

var el, buffer, view;
if(rerender) {
  view.unBindEvents(el);
  destroyElement(el);
}
buffer = view.renderToBuffer();
el = view.attachToDom(buffer);
bindEvents(el);

I'm sorry I need to gloss over the details a bit, I will update this section later on. The gist of the render process is that views go through a number of states:

• Not instantiated
• Instantiated and rendered to buffer
• Attached to the DOM
• Destroyed

Event bindings need to keep track of the view's state to ensure that the events are bound when a DOM element exists (since the only way to bind events is to have a DOM element for it).

How would this look in terms of code? For DOM-based bindings, something like this:

View.prototype.render = function() {
  var template = TemplateEngine.compile(this.template);
  template(this.data);
  this.attach(el, View.events);
};

View.prototype.attach = function(el, events) {
  events.forEach(function(selector) {
    var parts = selector.split(' ', 2),
        callback = events[selector];
    $(el).on(parts[0], parts[1], callback);
  });
};

Here, we are simply taking View.events which is presumed to be a hash of event selectors and their associated callbacks, and using jQuery to attach those events.

The implementation is essentially identical for the framework-generated bindings. Instead of using CSS classes, the event selectors are based on the markup that the template engine generated. The only difference is that the hash of event selectors comes from the templating engine rather than from the View object:

View.prototype.render = function() {
  var meta = TemplateEngine.compile(this.template);
  meta.template(this.data);
  this.attach(el, meta.events);
};

View.prototype.attach = function(el, events) {
  // ... see above
};

14. Consuming events from the model layer

There are two areas of interest in the chapter, both of which fall under the larger issue of generating and consuming events:

Re-rendering views in response to data changes. When data changes, we get a change event from the model layer. In response, we would like to re-render all the views that were affected by the change.

Communication between views. Some actions - like the example in Gmail where you change the display density - require that multiple views change in response to the same user event. We need to pick a nice way to represent these changes, and trigger the right changes.

These are both coordination problems. We want to specify that when A happens, B and C should also happen. In essence, we are trying to bridge the gap between concrete DOM events and event handlers spread across multiple views:

[Events] < - > [Event handlers / actions]

Let's assume that we are trying to implement the following interaction: "when a user selects a message, the top menu should change and the message should appear as selected in the message list view". In this scenario, we are changing a piece of data and asking for that change to be communicated to multiple views.

There are several ways we could do this:

Directly in the select event handler. The naive and obvious way would be to write code in the list that explicitly calls the interested parties.

MessageView.onSelect = function() {
  message.setSelected(true);
  list.check(message.id);
  menu.update(message);
  // one call for each other view that cares about this operation
};

However, the problem is that this is highly brittle since the views are tightly coupled: the message view knows about the message model, the list view and the menu view.

Using a mediating controller One way is to use a mediating controller, which refers to the objects directly. This looks something like this:

MessageView.onSelect = function() {
  controller.selectMessage();
};

Controller.selectMessage = function(message) {
  message.setSelected(true);
  list.check(message.id);
  menu.update(message);
  // one call for each other view that cares about this operation
};

Now, instead of views knowing about each other, they only need to know about a controller. Putting the code in a controller centralizes the coordination, but the code is still ugly and fragile: since that code explicitly refers to each view, removing or breaking one view can potentially break the whole re-render. It's still the same code, you just moved it into a different object; this is just as fragile as without a mediating controller (since the controller can't work without both views), though it is a bit more reusable since you can swap the controller.

Using observables. Another alternative is to use observables. When someone selects a message, we can reflect that either as a property of the message ("selected") or as part of a collection ("selectedMessages"):

• Observable properties. Selection is reflected as a property on the model. Views subscribe to changes on that particular property and update themselves based on changes to that property.
• Observable collections. Selection is reflected as a collection on the current page, or a property on a controller. Views subscribe to changes on that particular collection or controller property to update themselves.

Here is how this might look as code:

MessageView.onSelect = function() {
  AppModule.FooController.set('currentFoo', this);
  // currentFoo is a observable property
  // each otherView observes it, and performs
  // actions based on change events
};

// init is called when the other view is created
OtherView.init = function() {
  Framework
    .observe('AppModule.FooController.currentFoo')
    .on('change', function(model) {
      OtherView.update(model);
    });
};

While the views don't know about each other, they still know about the controller. Furthermore, the properties of the controller become an implicit API between the views. I say implicit, because the controller doesn't know it's being used for this purpose. So instead of having an explicit controller function that knows about the views, you now have a controller property that is the API for making calls between views and for passing state between views. You haven't gotten rid of "views knowing about the controller"; it's just that the views are now also responsible for registering callbacks on the controller properties.

Of course, in the case of one view, another dependent view and one controller this isn't too bad. But the problem is that as the number of views, controllers and interrelationships increase, the number global state properties and dependencies on various pieces of state increases.

Using global events. We can also implement this using a global event dispatcher / event aggregator. In this case, selection is reflected as an global event. When the user selects a message, a global event is emitted. Views subscribe to the selection event to be notified and can publish messages via the global event emitter instead of knowing about each other.

MessageView.onSelect = function() {
  global.emit('message_selected', this);
};

OtherView.init = function() {
  global.on('message_selected', function(model) {
    message.setSelected(true);
  });
};

The global event emitter is the single source of events for the views. Views can register interest in a particular event on the global event emitter, and models can emit events on the global event emitter when they change. Additionally, views can send messages to each other via the global event emitter without having an observable property change.

Observables and event emitters: two different schemas for specifying interest

Basically, the choice boils down to either having views send message to each other, or having views observe models. These options look different, but fundamentally they are the same thing, just using a different schema.

Observables:

function() { ... }.observe('App.Todos');

Event emitters:

Todos.on('change', function() { ... });

But really, the only difference is what the schema is. With observables, we specify interest in a change by using the name of the source object in the global scope. With event emitters, we specify interest by the type of the message. Let's look at those two again:

Observables:

global.observe('App.Todos:change', function(model) { /* ... */ });

Event emitters:

App.Todos.on('change', function(model) { /* ... */ });

Now, with a minor change, the two patterns look a lot more similar. The difference is that in one, the standard way to say we want to be informed about a change is to use the name of source object vs. in the other, we subscribe via the type of the message.

The "views observe models directly" and "models publish to a global EventEmitter" both introduce a level of indirection between model change events and view re-renders. This is good, because it means that there is no code that specifically refers to particular views - if a view is removed or doesn't work, then only it will be affected.

However, these two approaches have different implications.

Observables vs. event emitters

Observables Observables are the way in which markup-driven views (e.g. view systems with a templating system emphasis) implement re-rendering on demand. There are two parts to this system: the name resolution / event attachment system which, given a input like this:

Framework.observe('App.Todos', function() { ... });

... will attach the callback function to 'App.Todos' when App.Todos is instantiated (and re-attach the callback function when that object is replaced).

Once the events are attached, the second part of the system needs to determine which views have changed in response to the data change event. This is basically a process of taking the event and matching it against the currently active observers on a global level, and then triggering the observer callbacks where appropriate.

Global events. Here, we introduce a single shared eventemitter which acts as a broker for events. Each view expresses interest in a particular set of events by subscribing on the global event emitter. When an event which needs to be handled by multiple views occurs, a global event is emitted. The advantage here is decoupling, since none of the views need to know about each other: they just know about the global eventemitter and how to handle a particular event.

Three choices: transient, model, and collection events

Whether you pick event emitters or observables, you still are left with the choice between three ways in which user actions can be represented in your app. You can represent an action - like changing the display density or selecting an item - as:

• A transient event. In this case, there is no property or collection associated with the change. Any views that are subscribed to notifications about the event will have their event handlers triggered.
• A model change event. Here, the result of the action is that a property on a model changes. This causes change events for that property, which then trigger the event handlers/callbacks for interested models.
• A collection change event. You might represent the user action as a change on a collection or an observable array. The set of items is changed by the user action, and this triggers interested listeners in the view layer to update their contents. Using a collection makes it easy to find out which model(s) are selected, which is useful in cases (like the selection example).

Observables generally do not support triggering transient events, since they are based on the idea that everything is a property of a model or observable array. While model and observable array changes generally cover most actions, it may be that some actions are best represented as transient events. For example, clicking a user in a list to bring up an edit dialog might be better implemented as a transient event rather than, say, a list click event handler that is tightly coupled to a particular dialog.

With observables, every interaction, event if it is limited to a single activity, will exist as a property on the model or collection (unless the developer goes outside the framework). This is a disadvantage: each interaction adds to the global complexity of models.

With event emitters, you tend to perform the same model/collection binding by having views that are bound to either a collection or a model:

• Model bound views
• Collection/observable array bound views

Model-bound views take a single model, and represent it in the DOM. Change events from that view trigger updates in the DOM.

Collection-bound views represent a set of models or data items in a more complex set of markup. They may implement additional functionality that allows them to efficiently render a set of items. For example, updating a row in a table should only update that row, rather than the whole table. This allows the collection-bound view to potentially be more efficient at the cost of requiring the programmer to think about performance more.

Which one should I pick?

The observables basically make the choice to have the data accessed by its global name (which is used to establish subscriptions).

The global events approach makes the choice of having the data be pushed via a global intermediary; each view only knows about this intermediary and instead of referring to things by their name in the global scope, the event data is received directly with the event.

Observables abstract out the instantiation of the object they refer to, since you can start observing on an object even if it does not exist. However, the same applies to the global event emitter: you can register a event listener for an event even if that event is not triggerable.

Basically, these are equivalent approaches, using different naming schemes. I would prefer a naming scheme that is based on the event type, rather than one that is based on the location of the data in the global scope.

Referring to things by their location in the global scope creates a dependency: that particular variable has to be set in order to receive data. Worse yet, a view that explicitly accesses the state (e.g. via some global name) now depends on that global state (e.g. MyApp.MyModule.currentFoo) to be set up. While this is easy to write, it makes the view progressively harder to test and harder to reuse.