Simple Thoughts RSS Feed

About

Uzi Kilon

Lead UI Engineer and a Software Architect

Over 20 years of professional experience, writing complex web applications, and still learning something new every single day.
Currently working as a UI engineer for Dropbox in TLV.
Previously at Okta, Yammer (Acquired by Microsoft), Splunk and Yahoo.

A lucky husband of Hilit and a proud father of Elia and Naomi.

On my free time I practice my guitar skills

Lessons Learned

Fri, 02 Oct 2015 00:00:00 GMT

It’s been a while since I have posted here, mostly because we are busy building things at Okta. In the past while I have been building our UI framework and generalizing UI components, and thought I should share some high level bullet points of my experience.

1. You are building a framework

Unless you are building a small website, no matter if you’re using backbone, angular, ember, react, vanilla JS or whatever MVC framework the cool kids are using nowadays, in order to have a consistent user experience, without a significant amount of copy/paste boilerplate code, you need to have a solid framework layer. It’s easy to think (as I have) that “we are focusing on building a great product, not a framework” and it couldn’t be more true. However, in order to build a great product, you need a great framework to support you. The investments we made in our framework turned to be a key component in enabling us to move fast, without compromising quality.

2. Abstracting 3rd party widgets is probably a good idea

No matter how stable and mature your 3rd party dependencies are, and how great the developers are, APIs change. By abstracting external dependencies you gain the flexibility of upgrading even a major version, without refactoring a large amount of code. The best way to avoid major refactoring when that happens, (or to get stuck on an older version), is to have your own internal layer of abstraction around it. After all, it’s a know fact that all problems in computer science can be solved by another layer of abstraction except for the problem of too many layers of abstraction.

3. Documentation and code review help spreading the word

It’s really awesome to be generalizing code and writing frameworks around common patterns, but it doesn’t help a lot if the other developers in your org are not aware of it. We’ve found that the combination of code review, and a centric doc site help a lot with training and exposing what features are available. A rotation between developers to help extending the framework is a win win as well: developers get to better know the framework and it’s internals, while the framework gets more contributions.

4. Tests are crucial to success

As any large software application, it would have been impossible to maintain our application without a good amount of tests which validate that:

The code does what you think it does
Side effects are easier to catch.
Future development can be done (in less horror)

Our UIs have proven to be incredibly stable when it comes to regressions, and this is mostly due to our investment in unit tests and end-to-end tests.

5. Cleaning up after generalizing is a good idea

Typically, we decide to generalize a pattern after we are sure we will use it more than once. This way we can assure we are generalizing the right thing, and not what we assume is the right thing. In order to keep the codebase clean and honest, its important to go back to the previous implementations and apply the new pattern. This solves two main problem:

It assures that we correctly solved the problem
It assures that the next developer running into the same problem will not copy/paste an obsolete/one-off solution

6. You are, by definition, writing tomorrow’s legacy code

It’s impossible follow trends and rewrite your whole application using the new shiny framework that pops up every other week (Heck, The angular 1.x app you wrote last year is considered legacy code today). Instead, we focus on choosing tools that promotes practices we have learned to be useful, with current technology. With the pace the industry is moving forward, future challenges are likely to be along the line of “how to stay current”. There’s no answer to that challenge, but modularity has to be a key component.

If you want to be working with a company which faces these sort of challenges, We are hiring!

Running Jasmine Tests With PhantomJS

Mon, 07 Jan 2013 00:00:00 GMT

I finally got to mess around with PhantomJS and Jasmine, and couldn’t find a resource that gives clear, concise, accurate information, without language specific or build tool specific coupling, so I decided to write it myself. Fortunately, it is way simpler than I thought.

PhantomJS

PhantomJS is a standalone, cross platform command line application which does not require any specific server environment or programming language support.

Running the Tests

In order to run our jasmine test suite on the command line, all we need is:

PhantomJS Installing PhantomJS from phantomjs.org is fairly trivial (at least on a mac).
A URL to our Jasmine test suite We already covered jasmine test suites, so we have a URL to a jasmine test suite.
A script that loads our URL and parses the results Fortunately, PhantomJS provides a working jasmine runner example - all we have to do is download it and use it.

Once we got these, all we have to do is run the following command: phantomjs /path/to/run-jasmine.js http://localhost/js/test/unit/ It doesn’t take more than a few seconds(!) and we are provided with the test results.

This is it. Now, lets run it with our build tool.

* For the purpose of this article, lets assume PhantomJS is installed on the system, our jasmine runner is located at /path/to/run-jasmine.js and our jasmine test suite is located at http://localhost/js/test/unit/

Hooking with Build Tools

GNU Make

Adding the following target to Makefile and running make js_unit_test should do the trick:

js_unit_test:
	@phantomjs /path/to/run-jasmine.js http://localhost/js/test/unit/

Rake (Ruby Make)

Adding the following task to Rakefile and running rake js_unit_test should do the trick:

task :js_unit_test do
  exec 'phantomjs /path/to/run-jasmine.js http://localhost/js/test/unit/'
end

Apache Ant

Adding the following target to build.xml running ant js_unit_test should do the trick:

<target name="js_unit_test" description="Runs Javascript Unit Tests">
    <exec executable="phantomjs" failonerror="true">
       <arg line="/path/to/run-jasmine.js" />
       <arg line="http://localhost/js/test/unit/" />
    </exec>
</target>

Others

Adding this to any build tool should be as simple as it gets. The script will exit with 0 code on success, and 1 on failure, which is what most build tools need to know.

Conclusions

Following three simple steps enables us run our unit tests on a real WebKit based browser from the command line - no programming required. This method is NOT specific to AMD test suites. The URI could have a file:// scheme rather than http://

Keep it Simple, Stupid!

Thu, 15 Nov 2012 00:00:00 GMT

A while back I wrote a blog post on coupling and the observer pattern. Looking back, I did a pretty poor job describing what it wrong about it. I will attempt to correct this.

We all want simple and descriptive code. Code that is self documented. Code that makes sense, Code that tells us a story. Lets look at a kind of code I have seen many times, in many different variations, using observer based asynchronous javascript code:

var ListView = {
  init: function () {
    this.feed.onItemsReady(this.onFeedItemsReady)
  },
  onFeedItemsReady: function (items) {
    // do something
  }
  // ...
}

At first, this looks descriptive, and it is, kinda. It’s an object describing the implementation of a publisher it is observing. That doesn’t sound right. It is telling us about the implementation details and why it is doing things rather than what this object is responsible for and what it is doing. We already know all that! In their book, Design Patterns Explained: A New Perspective on Object-Oriented Design, Alan Shalloway and James Trott describe objects in OOP as “something with responsibilities”:

The best way to think about what an object is, is to think of it as something with responsibilities. A good design rule is that objects should be responsible for themselves and should have those responsibilities clearly defined. This is why I say one of the responsibilities of a student object is knowing how to go from one classroom to the next. I can also look at objects using the framework of Fowler’s perspectives:

At the conceptual level, an object is a set of responsibilities.

At the specification level, an object is a set of methods that can be invoked by other objects or by itself.

At the implementation level, an object is code and data.

Unfortunately, object-oriented design is often taught and talked about only at the implementation level — in terms of code and data — rather than at the conceptual or specification level.

Ideally we want our code to describe the conceptual level and what the object is. Unfortunately, in the example above we are describing the implementation level, which is a shame. A slightly better implementation of the above object could look like this:

var TweetListView = {
  init: function () {
    this.feed.onItemsReady(this.renderTweetList)
  },
  renderTweetList: function (tweets) {
    // do something
  }
  // ...
}

This code tells us by convention that this object is a presentation of a tweet list, and that the callback being called when items are ready will render a list of tweets. Obviously this is just a minor change in conventions and in most cases refactoring our design will take more than just renaming a bunch of variables and methods, but even with this minor change I think this code tells us a better story.

3 Tips For Writing Better Backbone Views

Sun, 11 Nov 2012 00:00:00 GMT

One of the good things about Backbone.js is it doesn’t tell us how to do things. It leaves it for us to decide what are the best practices for writing views (or any components). This is also one of the worst things about Backbone. it makes it almost too easy to take the wrong path, and write views that will be hard to maintain. The principle we should follow when writing a view is to keep it encapsulated, and keep it as “dumb” as possible - a view should know only the bare minimum it needs to know in order to do it’s job, and do bare minimum it has to do.

Here are 3 simple tips that can help us achieve this:

1. Don’t Access Variables Out Of The View Scope

var View = Backbone.View.extend({
  initialize: function () {
    this.model = window.App.myModel
    this.model.fetch()
    //...
  }
})

While its tempting to write a view such as the above, it introduces some problems. The view needs to know about the window.App and it manipulates a model’s state. We have tight coupling. It violates the single responsibility principle: the view should be responsible only to render itself, but when it accesses the global scope, finds a model and operates a fetch on it, it becomes responsible for application state. Writing a unit test can quickly show us how coupled it is: we will need to mock window.App, add a mock model to it, make sure it fetches, etc.

A better pattern would be to take care of these in the views parent (controller/route)

var myView = new View({ model: window.App.myModel })
window.App.myModel.fetch()

In this example, we are passing a fully baked model, leaving only the rendering job to the view.

2. Write The Template Inline

There are three base techniques for writing and storing backbone/underscore templates:

1. In our main html file, in a script tag:

<script type="text/template" id="pod">
  <h2><%= title %></h2>
  <p><%= body %></p>
</script>
<script src="view.js"></script>

// view.js
var View = Backbone.View.extend({
  template: _.template($('#pod').html())
})

By using the script tag, we are telling the browser to not render this element. By choosing a script type that doesn’t have a matching interpreter, we ensure this script will not run.

2. In an external file, loading over network, with dependency management utilities such as requireJS

<%= title %> <%= body %>

// view.js
define(['text!templates/pod.html'], function (pod) {
  var View = Backbone.View.extend({
    template: _.template(pod)
  })
})

3. In our view declaration, as a string.

// view.js
var View = Backbone.View.extend({
  template: _.template(`
    <%= title %>
    <%= body %>
  `)
})

Option #1 has tight coupling between our view and the main DOM, and I wouldn’t recommend using it. Option #2 and #3 are both good. I tend to prefer #3 for a few reasons:

Its simple. No magic is happening.
Everything is in one file, which makes it easy to develop
No editor highlights html in a javascript string, so we are “forced” to write short and clean templates.

3. Render UI Upon Data Change, Not User Interaction

The flow is : User interaction -> data change -> view render. For instance, if we are writing a play/pause toggle button in an audio player, the flow would be:

The user hits ‘play’
The model (data) state changes to ‘playing’
The view renders in ‘playing’ mode

Following this pattern ensures that changes to the state triggered from other sources (such as fast forward, new playlist, network error, etc.) will toggle our button to do the right thing. In other words, we have a single source of truth: whenever our model changes we know we should render our button.

The code can look like:

var PlayPauseButton = Backbone.View.extend({
  tagName: 'li',
  className: 'icon',
  initialize: function () {
    this.model.on('change:status', this.render, this)
  },
  render: function () {
    this.$el.removeClass('icon-play').removeClass('icon-pause')
    this.$el.addClass('icon-' + (this.isPlaying() ? 'pause' : 'play'))
  },
  events: {
    click: function () {
      this.model.set('status', this.isPlaying() ? 'paused' : 'playing')
    }
  },
  isPlaying: function () {
    return this.moedl.get('status') === 'playing'
  }
})

Conclusions

Keeping decoupled and encapsulated views helps us writing a sane, maintainable application.
Following some best practices makes it very easy to do so. We all used the lack of time as an excuse to explain the poor quality of our code (at least I did), but in most cases, writing good code doesn’t take more time.

Usability Testing As a Part of Code Review

Tue, 16 Oct 2012 00:00:00 GMT

Code review is one of the most powerful tools we, developers, have in our toolkit. There are plenty of resources providing information on the value code review can add to any development team. However, most of the resources I have read, describe how to use code reviews as a tool to find bugs, or architectural issues that are hard to find in an automated way.

It’s also a known argument that code is read much more often than it is written and that it’s harder to read code than to write it, so, our common sense should indicate that writing clear and obvious code can provide a lot of value to our readers, our fellow programmers.

Usability Testing

I’ve recently read the book ”Don’t Make Me Think”, by Steve Krug, which is considered by many as the bible for usability on the web (and if you haven’t read it yet, you should. It’s a great read). The key concept could be best described in Steve’s own words:

It means that as far as is humanly possible, when I look at a Web page it should be self-evident. Obvious. Self-explanatory. I should be able to “get it”—what it is and how to use it—without expending any effort thinking about it.

And while I was reading this, I was thinking, why is code any different? Why should we spend all this time reading legacy code, trying to figure it out, when the code author could write it in a clearer way, easier to understand.

Consider the challenges in reading someone else’s code:

Did they use code conventions you are familiar with?
Did they write clear interfaces?
Did they use well known design patterns?
Did they name variables in a clear, non-ambiguous way?
Is the code explicit rather than implicit?
Is the implementation easy to explain? If not, why not?
Is it complicated? If it is, does it have to be?

Point is, there’s a lot into reading code, and it gets even more complex when style and requirements change over time.

Then it accrued to me that there is nothing that holds us from testing the usability of our code. A proposal on how this process could work:

Code Usability Testing

As a part of code review:

Find two or three developers in your company, some that are unfamiliar with your code. Better if you can find new developers, or developers from a different team than yours.
Give them a task. Ask them to implement something using your code, or to tweak your code in some way
Ask them to share their process of thoughts with you, as they are trying to accomplish the task
Refuse to provide any help. Let them figure it out
Observe their work, and keep notes

This practice should not take a lot of time. It should not take more than 30 minutes for each engineer participating, depending on the size of your commit. Then it will take you up to 30 more minutes to analyze the results. The obvious problems will be very easy to identify, and the rest could be ignored, until the next review. I’m sure these extra (tops) 2 hours will provide tons of useful information on how to make your code simpler clearer and overhaul better.

Just keep in mind to stay open and don’t take it personally. We have to always keep in mind that what’s obvious to us may not be obvious to everybody.

Usability testing is probably the easiest way to tell us if we’re doing it right clear, and what should be tuned.

Testing Backbone + RequireJS Applications with Jasmine

Thu, 23 Aug 2012 00:00:00 GMT

In my previous post, I covered the structure of a Backbone.js application using RequireJS. The next thing (or if you are a TDD fan, the first thing) we do is to run some tests on it. According to Coda Hale:

Writing tests for your code may not reduce the number of bugs, but it will make fixing the bugs you inevitably find easier.

Obviously, we can take advantage of the AMD architecture, to help us write modular tests (or “specs” in the BDD language). To get a better sense of the challenges and different approaches in unit testing, I wrote the exact same tests three times using three different testing frameworks: Jasmine, Mocha and QUnit.

The Concept

The concept is fairly simple. We want to test each one of our modules (Models, Collections, Views) and validate they behave as expected. We will have one html file, on SpecRunner javascript file, which will initialize the test suite, and a spec file per AMD module.

Since the concept and the implementation are so similar for the 3 frameworks, I’ll focus on Jasmine in this post. the code for the 3 of them is available in the GitHub repo.

index.html

This is how our Jasmine html file looks like. there’s not a lot I can say about this.

I added a hidden (or almost hidden) element with the id “sandbox” where all the DOM elements will be appended to while testing, each view test will append itself into this element, and will remove itself when done testing. I kept this element visible with very little height so a selector such as jQuery.is(“:visible”) will be valid. There are many other ways to accomplish this.

Jasmine Spec Runner
<script src="/js/lib/require-2.0.5.js" data-main="SpecRunner"></script>

SpecRunner.js

Our spec runner is where the magic happens. It is responsible to

Load the dependancies (core libraries, testing libraries)
Configure the testing environment
Load the test suites
Run the test engine

Configure RequireJS

One important bit is we would like to keep our require.config with the same paths as our app, so we won’t need to change anything within our application modules. we will add an extra path to our spec (tests) folder, and keep the previous baseURL and paths identical to our app.js. Because our baseURL is /js/, all the other paths will be relative to that. One more thing I added is a cache buster to all the module urls using the urlArgs parameter. It’s a good idea to have this in the test environment, so we don’t need to worry about browser caching.

require.config({
  baseUrl: '/js/',
  urlArgs: 'cb=' + Math.random(),
  paths: {
    jquery: 'lib/jquery-1.8.0',
    underscore: 'lib/underscore-1.3.3',
    backbone: 'lib/backbone-0.9.2',
    'backbone.localStorage': 'lib/backbone.localStorage',
    jasmine: '../test/lib/jasmine',
    'jasmine-html': '../test/lib/jasmine-html',
    spec: '../test/jasmine/spec/'
  },
  shim: {
    underscore: {
      exports: '_'
    },
    backbone: {
      deps: ['underscore', 'jquery'],
      exports: 'Backbone'
    },
    'backbone.localStorage': {
      deps: ['backbone'],
      exports: 'Backbone'
    },
    jasmine: {
      exports: 'jasmine'
    },
    'jasmine-html': {
      deps: ['jasmine'],
      exports: 'jasmine'
    }
  }
})

Configure and execute the test engine

Next, we will load our main dependencies using require() and setup Jasmine, require() our specs, and run Jasmine’s test engine.

require(['underscore', 'jquery', 'jasmine-html'], function (_, $, jasmine) {
  var jasmineEnv = jasmine.getEnv()
  jasmineEnv.updateInterval = 1000
  var htmlReporter = new jasmine.HtmlReporter()
  jasmineEnv.addReporter(htmlReporter)
  jasmineEnv.specFilter = function (spec) {
    return htmlReporter.specFilter(spec)
  }
  var specs = []
  specs.push('spec/models/TodoSpec')
  specs.push('spec/views/ClearCompletedSpec')
  specs.push('spec/views/CountViewSpec')
  specs.push('spec/views/FooterViewSpec')
  specs.push('spec/views/MarkAllSpec')
  specs.push('spec/views/NewTaskSpec')
  specs.push('spec/views/TaskListSpec')
  specs.push('spec/views/TaskViewSpec')

  $(function () {
    require(specs, function () {
      jasmineEnv.execute()
    })
  })
})

The structure of a test suite

Jasmine, like most frameworks has a ‘beforeEach’ and ‘afterEach’ methods, which will run before and after each test. In this spec, we test our ‘remaining items counter’ view, so, in our beforeEach method, we want to initialize the view and the todos collection the view consumes. The afterEach will remove the view from the DOM.

Jasmine also integrates spies that permit many spying, mocking, and faking behaviors.

Async

One significant difference between Jasmine and Mocha is the way Jasmine handles async specs. Instead of using a done() function in the test’s signature, Jasmine uses run(), wait(), and waitFor(). At first, this looked over complicated to me when compared to mocha’s simple approach, but once I got used to it, I’ve learned to appreciate the flexibility it gives you. For instance, in these cases your spec (or before/after) has more than one async call. I know what you’re thinking. You should never have more than one async call per spec. I agree, but life is not ideal, and implementations shouldn’t set the limits.

Since a test suite will never be a dependency, and the Jasmine’s describe() method, that defines a test suite, already has a modular structure, there is not real need of wrapping it in a define statement.

describe('View :: Count Remaining Items', function () {
  beforeEach(function () {
    var flag = false,
      that = this
    require(['models/Todo', 'views/CountView'], function (Todo, View) {
      that.todos = new Todo.Collection()
      that.view = new View({ collection: that.todos })
      that.mockData = {
        title: 'Foo Bar',
        timestamp: new Date().getTime()
      }
      $('#sandbox').html(that.view.render().el)
      flag = true
    })
    waitsFor(function () {
      return flag
    })
  })

  afterEach(function () {
    this.view.remove()
  })

  describe('Shows And Hides', function () {
    it('should be hidden', function () {
      expect(this.view.$el.is(':visible')).toEqual(false)
    })
    it('should toggle on add', function () {
      this.todos.add(this.mockData)
      expect(this.view.$el.is(':visible')).toEqual(true)
    })
  })

  describe('Renders Text', function () {
    it('should be empty', function () {
      expect(this.view.$el.text()).toEqual('')
    })
    it('should re-render on add', function () {
      this.todos.add(this.mockData)
      expect(this.view.$el.text()).toEqual('1 item left')
      this.todos.add([this.mockData, this.mockData])
      expect(this.view.$el.text()).toEqual('3 items left')
    })
  })
})

You get the point. The full running Jasmine test suite of the Todos app can be found here. The source code for this test suite can be found here

Edit, Jan 2013: Pointed by Andreas Boehrnsen, a better way to write the specs would be to define the dependencies in a define block.

define(['models/Todo', 'views/CountView'], function (Todo, View) {
  return describe('View :: Count Remaining Items', function () {
    beforeEach(function () {
      that.todos = new Todo.Collection()
      that.view = new View({ collection: that.todos })
      that.mockData = {
        title: 'Foo Bar',
        timestamp: new Date().getTime()
      }
      $('#sandbox').html(that.view.render().el)
    })
    // ...
  })
})

The async part remains a good tool to have for other async cases.

Conclusions

RequireJS not only help handle dependencies and code organization in applications, it also makes testing easier and more fun. Modular code is clearly broken in to “units” which makes it very easy to unit test.

Build Backbone Apps Using RequireJS

Fri, 17 Aug 2012 00:00:00 GMT

Backbone gives us a very powerful set of tools. It gives us models, views, and routes - all event driven, consistent and beautifully embrace underscore.js functionality. Being a library rather than a framework, Backbone doesn’t give us application structure. That “glue” we need too initialize the app and glue all the pieces together. Since coding is by far easier than explaining, I programmed a Todos app in order to demonstrate how this can be done with Asynchronous Module Definition (AMD) using RequireJS.

AMD

This is what the RequireJS guys say about AMD:

The AMD format comes from wanting a module format that was better than today’s “write a bunch of script tags with implicit dependencies that you have to manually order” and something that was easy to use directly in the browser. Something with good debugging characteristics that did not require server-specific tooling to get started. It grew out of Dojo’s real world experience with using XHR+eval and and wanting to avoid its weaknesses for the future. It is an improvement over the web’s current “globals and script tags” because:

Uses the CommonJS practice of string IDs for dependencies. Clear declaration of dependencies and avoids the use of globals.

IDs can be mapped to different paths. This allows swapping out implementation. This is great for creating mocks for unit testing. For the above code sample, the code just expects something that implements the jQuery API and behavior. It does not have to be jQuery.

Encapsulates the module definition. Gives you the tools to avoid polluting the global namespace.

Clear path to defining the module value. Either use “return value;” or the CommonJS “exports” idiom, which can be useful for circular dependencies.

It is an improvement over CommonJS modules because:

It works better in the browser, it has the least amount of gotchas. Other approaches have problems with debugging, cross-domain/CDN usage, file:// usage and the need for server-specific tooling.

Defines a way to include multiple modules in one file. In CommonJS terms, the term for this is a “transport format”, and that group has not agreed on a transport format.

Allows setting a function as the return value. This is really useful for constructor functions. In CommonJS this is more awkward, always having to set a property on the exports object. Node supports module.exports = function () {}, but that is not part of a CommonJS spec.

In general, the AMD pattern allows us to keep a file for each module in our app (a module could be a model, a view or any encapsulated part of the application), manage dependencies, and maintain a well organized codebase.

If you are anything like me, you would think that while this is great for development, loading modules or assets over http in run time is extremely wasteful and slow. Luckily the guys at requireJS had that in mind, and came out with an optimization process, that alongside with almond.js combine and minify the whole codebase to one minified javascript file for deployment. We will cover that later.

Initializing the Application

We start our app with a very simple index.html file. The only important part of the file is this line:

<script src="require-2.0.5.js" data-main="app.js"></script>

It tells the browser to load RequireJS, and it tells requireJS where to find the bootstrap javascript file. As you can probably guess, app.js is responsible for initializing the application.

app.js

First we define paths to our external libraries, so in the code you require jquery and not lib/jquery-1.8.0 etc. This way, if you want to update libraries versions, or do stuff like replacing jQuery with zepto, or underscore with lodash, all you need to do is modify the relevant line of code, in the ‘paths’ section.

Then we want to shim our dependencies. The first challenge is neither underscore or backbone are AMD compatible. Luckily, the requireJS guys thought about this and introduced a new way to ”shim” dependencies in the 2.0x release.

require.config({
  baseUrl: '/js/',
  paths: {
    jquery: 'lib/jquery-1.8.0',
    underscore: 'lib/underscore-1.3.3',
    backbone: 'lib/backbone-0.9.2',
    'backbone.localStorage': 'lib/backbone.localStorage'
  },
  shim: {
    underscore: { exports: '_' },
    backbone: { deps: ['underscore', 'jquery'], exports: 'Backbone' },
    'backbone.localStorage': { deps: ['backbone'], exports: 'Backbone' }
  }
})

Next, lets got to the main app:

require(['jquery', 'backbone', 'models/Todo', 'views/MasterView']
  , function($, Backbone, Todo, MasterView) {
  var Router = Backbone.Router.extend({
    routes: { "": "main" },
    main: function() {
      var tasks = new Todo.Collection();
      var view = new MasterView({collection: tasks});
      tasks.fetch({ success: function(tasks){
        $("#container").html(view.render().el).show();
      }
    });
  }
});

This is pretty straight forward. We declare what are the direct dependencies for this module, and initialize the router.

Models and Views

As it seems, the files I am loading (other than libraries) are my one model and the master view.

/js/models/Todo.js

define(['underscore', 'backbone.localStorage'], function (_, Backbone) {
  var Todo = Backbone.Model.extend({
    defaults: { title: '', timestamp: 0, completed: false },
    validate: function (attrs) {
      if (_.isEmpty(attrs.title)) {
        return 'Missing Title'
      }
    }
  })
  var Todos = Backbone.Collection.extend({
    localStorage: new Backbone.LocalStorage(window.store || 'Todos'),
    // for testing purposes
    model: Todo,
    completed: function () {
      return this.where({ completed: true })
    },
    remaining: function () {
      return this.where({ completed: false })
    },
    comparator: function (model) {
      return model.get('timestamp')
    }
  })
  return { Model: Todo, Collection: Todos }
})

One thing you should notice about AMD modules is the return signature. Inside the module we have a sandbox we can use for private methods and variables. the only parts that will be accessible are what we are returning. In this case we are returning an object literal that contains both a model and a collection “classes” representing todos. I found this pattern useful, since models and collections are tightly coupled by definition.

The same apply for views:

/js/views/MasterView.js

define([
  'backbone',
  'views/TaskList',
  'views/NewTask',
  'views/MarkAll',
  'views/FooterView'
], function (Backbone, TaskList, NewTask, MarkAll, FooterView) {
  var View = Backbone.View.extend({
    className: 'masterView',
    initialize: function () {
      this.children = {
        taskList: new TaskList({ collection: this.collection }),
        newTask: new NewTask({ collection: this.collection }),
        markAll: new MarkAll({ collection: this.collection }),
        footerView: new FooterView({ collection: this.collection })
      }
      this.$el.hide()
      this.$el.append(this.children.newTask.render().el)
      this.$el.append(this.children.markAll.render().el)
      this.$el.append(this.children.taskList.render().el)
      this.$el.append(this.children.footerView.render().el)
    },
    render: function () {
      this.$el.show()
      return this
    }
  })
  return View
})

This goes on an on. You can browse the code at GitHub to review the rest of it.

Optimization

Once we are done with our basic app, we have 17 http requests for javascript libraries or assets. The next thing we want to do is optimize and combine the codebase into one file. We will do it using r.js which is a part of the RequireJS release. The dependencies for that are node.js and npm (we will load the other dependancies using npm install). We will create a build.js file with the following syntax:

;({
  baseUrl: '.',
  mainConfigFile: 'app.js',
  name: 'app',
  out: 'app.min.js',
  logLevel: 0,
  preserveLicenseComments: false
})

Or if we chose to use almond.js: (Note that our main app moved from main to include, and almond gets the main slot)

;({
  baseUrl: '.',
  mainConfigFile: 'app.js',
  name: '../node_modules/almond/almond',
  include: 'app',
  out: 'app.min.js',
  logLevel: 0,
  preserveLicenseComments: false
})

What we did here, is to tell the optimizer what is our app URL, what file contains require.config, in what module to start, and where to output it (and a couple of optional semantic configuration bits such as keeping copyright comments and the log level)

The benefit of using almond.js is it compiles all to one file and eliminates the need to asynchronously load anything. You get for pretty much free leaner code - because you don’t use require.js anymore, and less http request - because you load one file other than two. The tradeoff is it eliminates the option to have a hybrid app where you load some modules asynchronously (a good example is remote apis such as google maps, etc.)

There’s a nice build.js example on the r.js repository with all the details you can dream of.

The last thing we do is run the build command in our root folder:

npm install # to install dependencies
node_modules/.bin/r.js -o js/build.js

Now, we have an optimized file. The last thing we want to do is replace the script tag that loads RequireJS with:

<script src="require-2.0.5.js" data-main="app.min.js"></script>
<!-- Or if we used almond.js: -->
<script src="app.min.js"></script>

Conclusion

Using AMD to create a modular backbone app is easy. it helps to:

Manage dependencies
Keep the code organized
Have separate files for each module

And with all that, when optimized does not impact performance.

Javascript RPN Calculator

Tue, 26 Jun 2012 00:00:00 GMT

RPN (Reverse Polish Notation) is a mathematical notation wherein every operator follows all of its operands, which was designed to reduce computer memory access and utilize the stack to evaluate expressions.

The syntax looks like:

rpn('3 3 +') // => 3 + 3 => 6
rpn('2 2 + 3 *') // => (2 + 2) * 3 => 12
rpn('2 2 3 + *') // => (2 + 3) * 2 => 10
rpn('2 2 3 3 / * /') // => ((3 / 3) * 2) / 2 => 1

A typical interview question would be to implement a RPN calculator since it is simple enough to resolve in less than an hour and it tests our ability to notice a problem that cries out for a stack based solution. It also tests our absence from the “Introduction to Algorithms” course in college. Obviously there are other algorithms to implement RPN, such as recursion, but using a stack will be more efficient: a stack will take O(n) times rather than O(n2) for recursion.

Of course, this has very little to do with UI programing, but we are dealing with interview questions. The way to implement it is to iterate over our expression, add each member to a stack, and when the member is an operation, calculate the previous 2 members with that operator.

A javascript implementation can look like:

function rpn(input) {
  var ar = input.split(/\\s+/),
    st = [],
    token
  while ((token = ar.shift())) {
    if (token == +token) {
      // numeric
      st.push(token)
    } else {
      var n2 = st.pop(),
        n1 = st.pop()
      st.push(eval(n1 + token + n2))
    }
  }
  return st.pop()
}

We can later add validation, so our final version looks like:

function rpn( input ) {
  var ar = input.split( /\\s+/ ),
      st = [],
      token;
  while( token = ar.shift() ) {
    if ( token == +token ) {
      st.push( token );
    } else {
      var n2 = st.pop(),
          n1 = st.pop();
      var re = /^\[\\+\\-\\/\\\*\]$/;
      if( n1 != +n1 || n2 != +n2 || !re.test( token ) ) {
        throw new Error( 'Invalid expression: ' + input );
      }
      st.push( eval( n1 + token + n2 ) );
    }
  }
  if( st.length !== 1 ) {
    throw new Error( 'Invalid expression: ' + input );
  }
  return st.pop();
}

This post is for self reference ;)

PubSub / Observer Pattern and Coupling

Thu, 14 Jun 2012 00:00:00 GMT

PubSub (or the observer pattern) is obviously the hottest pattern in client side development, and I would like to take a shot at trying to refine the best practices for using it in a flexible and robust way.

The definition provided in the original Gang of Four book on Design Patterns states:

“Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified and updated automatically”

As in any design pattern, an important part is to keep the application loosely coupled and with high cohesion. Technically, every event listener uses the PubSub pattern. Consider this jQuery DOM listener:

$('div#foo').delegate('a', 'click', function () {
  // do your stuff
})

In this example we are observing the state of an object (a DOM element) and whenever it changes, we can update the application based on that state change. What’s not great about this example is there is tight coupling between our main app (the listener) and the DOM. If we would like to add another set of elements that will trigger the same action, we will need to define another subscriber (client) and redefine the updating procedure. (imagine a video player we would like to be able to play/pause using different buttons or even a different input sources). This limits our flexibility, and could lead to quite painful maintainability. The observer pattern is widely used with models and views in MVC applications. In some system, there’s stuff like this as a part of the view:

// ...
onAfterFetch: function(data) {
 // do something with data
},
onItemsReady: function(items){
 items.each(function(item) {
     // do something
 });
},
// ...

These are explicit callbacks for events/actions triggered by the model. While this works, it breaks the rule of encapsulation and delegated responsibilities. This type of programming creates tight coupling between the view and the model: not only the view is aware of the model internals (does it have to be fetching? could we be pushing stuff into the model?), the view updates itself upon model actions and not upon model state/content changes. Pretty soon we will need to update our view on many different model “actions” that causes the same state change.

Once again, this works, but leaves a lot of loose ends and makes the code less flexible and harder to maintain. Whenever we want to refactor the model and modify a method that has to do with state, we will need to update all of the subscribers, so not only it promotes tight coupling and weak cohesion, it also ends up being more complicated, since a view is now aware of the internals of a model.

A better approach is to subscribe only to the state of the data, ignoring the internal of the model which caused the data to change.

Consider this example, where our view represents a field called “name” in the model and has to keep it up to date:

var MyView = Backbone.View.extend({
  initialize: function () {
    this.model.on('change:name', this.render, this)
  },
  render: function () {
    var name = this.model.get('name')
    // do something with our new name
  }
})

In Backbone, a view observers the model data state, and when it changes it may decide to update itself. Note that is this example, the only 2 things the view knows (or cares) about the model are:

It has an ‘on’ method where you can subscribe to changes in the model’s state
It has a ‘get’ method where you can access model properties (fields).

Using this loose coupling technique, the view does not have any insight to the model internals, and only aware of the part of the interface it has to be aware of. This makes it easier for us to later change the model, for instance: use another fetching technique (polling / web sockets / pushing from an external client), or any change to the model internals, without having to modify the clients at all.

I’m giving Backbone as an example for a good practice, but there are many other tools and libraries that promotes good techniques, and you could easily write your own stuff, keeping this in mind.

To sum things up, the fact that we have an event driven system, and we use the observer pattern, doesn’t mean we are doing it right. We need to pay attention we keep our modules encapsulated and that our application stays loosely coupled.

The Zen of Javascript

Mon, 07 May 2012 00:00:00 GMT

I ran across PEP 20 — The Zen of Python by Tim Peters, and figured very little needs to be changed to make it a valid javascript zen:

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren’t special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently. Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one— and preferably only one —obvious way to do it.
Although that way may not be obvious at first unless you’re Dutch Doug.
Now is better than never.
Although never is often better than right now.
If the implementation is hard to explain, it’s a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea — let’s do more of those! let’s fake those!

Why Good Programmers Are Lazy and Dumb

Wed, 18 Apr 2012 00:00:00 GMT

I ran into an old post by Philipp Lenssen on how good programmers are lazy and dumb. I totally agree with the title and most of the content. However, I believe that the lazy and dumb engineers are the better ones for a different reason:

Lazy: Because code is liability, and by writing a lot of code, you are taking upon yourself (or your team) liability to test, maintain, document and improve it. A lazy developer will first look for an existing solution that already has all the above and which is qualified to solve the aimed problem.

Dumb: Because a dumb developer writes code that is simple enough, for dumb engineers, just as he is, to be able to understand and work with. “Smart” engineers tend to write sophisticated programs that nobody but them or the like of them can understand. I guess it makes them feel smart. Dumb engineers look for simple, encapsulated, loosely coupled solutions that anybody can understand.

Reinventing the Wheel

Sun, 01 Apr 2012 00:00:00 GMT

I ran into this old post by Jeff Atwood, that makes a good point. Reinventing the wheel is most probably the best way to learn about “wheels”, and about the problems they designed to solve. There is no better way to learn about anything than actually implementing it.

However, consider a project that, say, 3 engineers are working on, and each one of them reinvents a different “wheel”? Here’s what will happen:

Engineer #1 will write a HTTP server
Engineer #2 will write a RoR like backend MVC framework
Engineer #3 will write a jQuery like dom abstraction JS library

You see where this is getting… There are at least two main problems here:

This project will probably be buggy, will take forever to develop, and will be impossible to maintain.
The next engineer coming after you, is more likely to have experience with jQuery than in your home brewed fooQuery.js and will probably have more desire to gain expertise with jQuery over your amazing home brewed library.

Basically the more code we own, the more liability we have to maintain, test, debug, fix, improve, write documentation etc. Given the limited resources we all have, the last thing we need is to own more code.

This is especially true when all the above problems are already solved with efficient, fully tested, fully documented open source projects we can use. for free. with communities and all the other good stuff that comes with open source projects.

This is exactly the reason why engineers should own or participate in pet projects. A pet project is the perfect place where its not only okay to reinvent the wheel - it is desired — this is exactly the room to do crazy things, experiment, learn, and develop your professional skills.

Software Engineering Interview Questions

Sat, 31 Mar 2012 00:00:00 GMT

Edit, 6/26/2012: This post is my personal rant about interview questions. If you got here looking for actual programming interview questions, I can recommend these books: Cracking the Coding Interview and Programming Interviews Exposed. These books helped many engineers getting their dream jobs.

It’s no secret I’ve been in a bunch of of interviews in the past few years, both as an interviewer and as a candidate. When it comes to tech interview questions, to simplify things, I can break it into 3 major types:

Implementation questions
Architecture/design questions
“Problem solving” questions

The first type intends to check your experience with current industry standard tools. For instance, as a javascript engineer you will be asked about specific jQuery method, what problem it designed to solve, and how you can effectively use it, how a web browser works, or what is the HTTP protocol.

The second type intends to check your software design skills, and your ability to design a complex application. As a front end engineer, you will probably asked about MVC concepts, RESTful architecture, or design patterns.

The third type intends to check how well you handle with random problems you didn’t expect. However, in many cases, this part is a tricky, and mostly out of scope. It’s not that I don’t think a good engineer should have strong “problem solving” skills. I do. I just think most of these “problems” you are being asked about has nothing to do with what most of us actually do on a daily basis.

In my past interviews I was asked algorithmic questions, mathematical/geometry questions and physics questions. Hell, I’m surprised I wasn’t asked to solve rocket science problems. After all, my “problem solving skills” are being measured. When an interviewer asks a front-end engineer questions that yield for BST traversal, how to test and optimize algorithms, or how to calculate the distance in pixels between a mouse click and each dom element on a given page, they probably:

Want to check what you remember from your undergrad CS classes
Did not read the part of your resume that says you don’t have a CS academic background
Have no idea what front end engineers do
All of the above

In either case, you are probably being asked the wrong questions. Don’t get me wrong, algorithms are a fascinating part of computer science, and it is important to understand the basics, but at the end of the day what most engineers struggle with most time is NOT algorithms, but software architecture. We all know that poor performance can be tuned, and fortunately, we also know that poor architecture can not be easily tuned.

Most of the modern engineering challenges are not to write the perfect algorithm to begin with, since you don’t have the perfect understanding of your problems set to begin with. The challenge is to abstract the algorithms in such way it will be easy to later improve/replace them without rewriting big parts of the application.

So, if in a 4 hours session with 4 different interviewers you are were asked a bunch of “problem solving” question, and you weren’t great at it, there’s no reason to worry. Your interviewer, which is probably an experienced engineer knows there’s no reason to worry about this.

However, if MOST of your interview questions were about “problem solving”, and you sucked at it, don’t feel too bad about yourself. You do not want to work for that company to begin with. Such interview is most likely a disclosure that this company (or team) has no idea what the challenges in modern software engineering are, and they are most likely wasting their time solving the wrong problems (which were probably solved before). You do not want to work there.

Backbone.js Poller

Thu, 23 Feb 2012 00:00:00 GMT

Lets say you have a Backbone.js based messaging system on your application, and you want to stay synced with the server so you could alert your users when a new message arrives. You would like to call the server once every couple of seconds and ask for status updates. Or maybe your model represents an on going background task, you want to poll for status updates. You could start with something basic such as:

function poll(collection, delay) {
  setInterval(function () {
    collection.fetch({ data: { foo: 'bar' } })
  }, delay)
}

This works, but has some flaws:

You may end up running simultaneous requests hitting the browser’s allowed connection per host limit (typically 6, 2 on IE7, according to browserscope)
Nothing prevents you from running the function multiple time with the same collection
You can’t easily stop the process, and abort running requests
It doesn’t handle cases where we want to stop polling a model on a condition (say, when it’s task is done)

This may results in unnecessary load on the server side

You could run the next request only upon successful fetch request, and write something like this:

function poll(collection, delay) {
  collection.fetch({
    data: { foo: 'bar' },
    success: function () {
      setTimeout(function () {
        poll(collection, delay)
      }, delay)
    }
  })
}

This solves the first problem bit doesn’t help other issues. It takes a little more than that, and starts smelling like a special helper is needed. You could add a poll() and unpoll() methods to your base models or collections using inheritance or mixin. I wouldn’t like to promote such approach since it breaks the model’s interface and introduces tight coupling between the model and application state. This easily becomes a slippery way down to maintenance hell. A better pattern would be to use an external helper that will keep our interfaces clean and our models stateless and decoupled.

I ended up writing a Backbone Poller, A polling helper utility for Backbone.js. a basic usage for our messaging system will could like

var inbox = new InboxCollection()
var poller = Backbone.Poller.get(inbox, {
  delay: 2000,
  data: { sort: 'date desc' }
})
poller.on('success', function () {
  // do something on every successful fetch
})
poller.start()

A more advanced usage for our long going offline task could look like

var options = {
  delay: 2000,
  // when this becomes false the poller will stop
  condition: function (model) {
    return model.get('done') !== true
  }
}
var task = new OfflineTaskModel()
var poller = Backbone.Poller.get(task, options)
poller.on('complete', function () {
  // task is done, do something
})
task.set('command', 'some-long-procedure')
task.save(
  {},
  {
    success: function () {
      poller.start()
    }
  }
)

The code and examples are available under the MIT license in github.

Book Review: RESTful Web Services

Sun, 12 Feb 2012 00:00:00 GMT

I’m working on a project that includes writing a client for a fairly sophisticated RESTful API.

To get some better understanding of both client and server RESTful philosophy I purchased and read RESTful Web Services by Leonard Richardson, Sam Ruby (O’Reilly Media, 2008).

I tend to agree with the foreword by David Heinemeier Hansson: “Every developer working with the Web needs to read this book.”

The web is RESTful and therefor, when working with the web one shall at least understand RESTful concepts.

This book is doing a great job describing to details the concepts of addressability, statelessness, connectedness, and the uniform interface, and clarifying why they are important fundamentals of the web. It gives a great overview of HTTP, URIs, Design of a REST server and client.

If I had to take one thing from the book, I would take the importance of state management. It is crucial to understand where the state of the application belongs to. Saving the application state on the back-end breaks the stateless nature of a web app, and could end up with an application that is hard to maintain and scale. Keeping the state in the client side (or even better - in the URI), and keeping a sane, loosely coupled design leads to scalable web application.

One thing I was not very impressed with are the code examples. I skipped most of them, since I didn’t buy this book to learn how to implement a REST server using RoR or Django, but choosing XHTML as the document format is very odd, and using a <div> or a <span> to represent semantic data is even odder. Calling HTML5 XHTML5 is annoying, but given this was published in 2008 I given it the benefit of the doubt.

Bottom line, this was a good read and I highly recommend it. If you are looking for a book to give you some detail oriented overview of REST concepts, this book is for you.

Javascript Design Patterns: Strategy

Fri, 10 Feb 2012 00:00:00 GMT

For a quick assignment I was asked to write the following program:

In the language of your choosing build an application that, given an English language document as input, builds a data structure capturing the count of each word in the document.

Bonus: Create an inverted index as well: a mapping of the words to absolute positions in the document.

As context, this is a foundational algorithm for search systems and information retrieval. Be sure to consider accuracy, complexity, and intent in the design of your program.

The last phrase was the one that got me thinking. This sounded a little vague, so I started thinking what kind of design I can implement that would be flexible enough so I can apply the algorithms later. This kind of program usually runs on the back end using Java/Python/etc, but obviously, the language of my choice was javascript.

I started by defining a master processor:

var Processor = function (doc) {
  this.doc = doc
}
Processor.prototype.parse = function (parser, sorter) {
  var data = parser.parse(this.doc)
  if (sorter && typeof sorter.sort === 'function') {
    return sorter.sort(data)
  } else {
    return data
  }
}

This processor gets a document (in our simple example, a long string) and has parse method, which accepts a “parser” object that has a parse() method and an optional “sorter” object that has a sort() method. As the names suggest, the former will parse the document, and the latter will sort the results. This use of the Strategy Design Pattern will allow the application to be flexible for algorithm changes, in the future.

First, I defined an abstract Parser object. This object is responsible to convert the input to a standard format, and apply an algorithm

var Parser = function () {}
/**
 * The implementation will return an object literal
 * with the format {word: num, word: num ...}
 *
 * @param str {String}
 * @returns {Object}
 */
Parser.prototype.parse = function (str) {
  throw 'please extned abstract object'
}

/**
 * Convert an object literal into a sortable array
 * with the format [[word, num], [word, num], ...]
 *
 * @param data {Object}
 * @returns {Array}
 */
Parser.prototype.convert = function (data) {
  var arr = [],
    data = data || {}
  for (var key in data) {
    if (data.hasOwnProperty(key)) {
      arr.push([key, data[key]])
    }
  }
  return arr
}

My next step was defining the parsers I was requested to write: One for capturing the count of each word in the document:

var CountParser = function (arr) {
  this.arr = arr
}
CountParser.prototype = new Parser() // extend the base parser
CountParser.prototype.parse = function (str) {
  var value,
    i,
    l,
    data = {},
    arr = str.split(/[\s]+/)
  for (i = 0, l = arr.length; i < l; i++) {
    value = arr[i]
    data[value] = data[value] || 0
    data[value]++
  }
  // convert our object literal into a sortable array
  return this.convert(data)
}

And another one for a mapping of the words to absolute positions in the document:

var IndexParser = function (arr) {
  this.arr = arr
}
IndexParser.prototype = new Parser()
IndexParser.prototype.parse = function (str) {
  var value,
    i,
    l,
    data = {},
    arr = str.split(/[\s]+/)
  for (i = 0, l = arr.length; i < l; i++) {
    value = arr[i]
    if (!data[value]) {
      data[value] = i
    }
  }
  return this.convert(data)
}

Next, I defined my Sorter object. It is an object that takes a comparator function as an argument and can later be ran agains arrays using the Array.sort method:

var Sotrer = function (comparator) {
  this.comparator = comparator
}
Sotrer.prototype.sort = function (arr) {
  arr.sort(this.comparator)
  return arr
}

Then, I implemented the two basic comparator algorithms: Ascending and Descending:

var ascCompare = function (a, b) {
  return a[1] - b[1]
}
var descCompare = function (a, b) {
  return b[1] - a[1]
}

The only thing left now is to run an example:

var doc =
  'Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?'
var processor = new Processor(doc)

var indexParser = new IndexParser(),
  ascSorter = new Sotrer(ascCompare),
  countParser = new CountParser(),
  descSorter = new Sotrer(descCompare)

console.log(processor.parse(indexParser, ascSorter))
console.log(processor.parse(countParser, descSorter))

This design, based on strategy pattern, can later on take any parsing algorithm and any sorting algorithm with out the need for refactoring the core application.

Backbone.js URI Sync Adapter

Mon, 06 Feb 2012 00:00:00 GMT

I am working on a backbone based search page, and was trying to figure out what would be a simple way to have both a state model and a URI that represents that state of the page (the search string, search parameters, user preferences, etc.).

Thinking of mixing backbone routes and the application models seemed like an overkill, and would force me to handle everything through a route or an event.

After a short struggle, I realized that the best case would be to have a model that keeps me in model land, but has the representation in the URI, and came out with Backbone URI Storage.

The concept is very simple, and works like charm - use a standard backbone model, enjoy data binding, and simply hook the model in the URI.

var State = Backbone.Model.extend({ sync: uriSync });
var Search = Backbone.Model.extend({ url: '/rest/v1/search/'; });

And now, I can update the application state when my search changes:

var state = new State({ id: 'search-page' })
var search = new Search()
search.on('change', function () {
  state.save(search.toJSON())
})

Its as simple as that!

Backbone.js computed properties

Sat, 04 Feb 2012 00:00:00 GMT

A simple yet powerful way to create backbone model calculated fields or “macros” For one of our applications, we needed a way to store “macros” in backbone models, that will return a calculated value, based on values we have in the model fields.

I came up with a quick solution that seems to be good enough so far. the concept is, the same way you can set anything to a field value, a function in javascript IS a value, so nothing holds you from setting a function in a field:

var myModel = new Backbone.Model()
myModel.set(
  'func',
  function () {
    return 'hello calculated field!'
  },
  { silent: true }
) // bypass the change event

Later on we can get the value of this function with a call such as:

var value = myModel.get('func').call(myModel)

This works, but it is not very convenient. I wanted an automated way to use calculated methods without any side effects, which will include the field results in the model signature. JSON.stringify ignores functions so consider this:

var foo = {
  bar: function () {
    return 'bazz'
  }
}
JSON.stringify(foo) // prints "{}"

Based on that, the original backbone toJSON will just work as is, ignoring our macros. However, if we wanted to have the values our macros returns in our signature, we want to make sure it is being called, returning the resut of the value rather than the function.

I came out with this:

var BaseModel = Backbone.Model.extend({
  get: function (attr) {
    var value = Backbone.Model.prototype.get.call(this, attr)
    return _.isFunction(value) ? value.call(this) : value
  },
  toJSON: function () {
    var data = {}
    var json = Backbone.Model.prototype.toJSON.call(this)
    _.each(
      json,
      function (value, key) {
        data[key] = this.get(key)
      },
      this
    )
    return data
  }
})

As the code tells us, in our new get method we are returning values of calculated fields, and in our new toJSON method we are including computed properties by values.

This could be great, but we have to remember that model.toJSON() is what Backbone sends back to the server when we perform a save operation, so it may be a good idea, depending on the server implementation, to exclude all computed properties from the model signature:

toJSON: function() {
  var json = Backbone.Model.prototype.toJSON.apply(this, arguments);
  _.each(json, function (value, key) {
    if (typeof value == 'function') {
      delete json[key];
    }
  });
  return json;
}

An implementation could look like:

var MyModel = BaseModel.extend({
  defaults: {
    avg: function () {
      return (this.get('min') + this.get('max')) / 2
    }
  }
})
var myModel = new MyModel({ min: 1, max: 17 })
var avg = myModel.get('avg') // 9

One “drawback” we need to be aware of, is due to the nature of the implementation, you can not bind to change events on this field, since the value stays the function and what changes is the computed value it returns.

Simple? Powerful?

EDIT 3/14/2012:

If you do want to observe changes when a computed property value changes, you will need the system to be aware of which attributes are affecting it state. This could be done like that:

var avg = function () {
  return (this.get('min') + this.get('max')) / 2
}
avg.attributes = ['min', 'max']
myModel.set('avg', avg)

Now we have a way to track which fields are impacting our computed property. What’s left to do is observe changes on these fields, and fire a change event on our property when these happen. We could attach the event listener on the “set” method, but that would mean we will need to keep track on when we unset, reset, etc and remove that listener.

A cleaner (yet a little less efficient) approach would be to listen to all change events, and figure out upon it if a related field had changed. This could be done like this:

myModel.on(
  'change',
  function () {
    var i,
      changedAttributes = this.changedAttributes() || []
    _.each(
      this.attributes,
      function (value, key) {
        if (_.isFunction(value) && _.isArray(value.attributes)) {
          for (i in value.attributes) {
            if (_.has(changedAttributes, value.attributes[i])) {
              this.trigger('change:' + key)
              return
            }
          }
        }
      },
      this
    )
  },
  myModel
)

We can add this to out initialize method, and get it automated, so our complete model will look like:

var BaseModel = Backbone.Model.extend({
  initialize: function () {
    this.on(
      'change',
      function () {
        var i,
          changedAttributes = this.changedAttributes() || []
        _.each(
          this.attributes,
          function (value, key) {
            if (_.isFunction(value) && _.isArray(value.attributes)) {
              for (i in value.attributes) {
                if (_.has(changedAttributes, value.attributes[i])) {
                  this.trigger('change:' + key)
                  return
                }
              }
            }
          },
          this
        )
      },
      this
    )
  },
  get: function (attr) {
    var value = Backbone.Model.prototype.get.call(this, attr)
    return _.isFunction(value) ? value.call(this) : value
  },
  toJSON: function () {
    var json = Backbone.Model.prototype.toJSON.apply(this, arguments)
    _.each(json, function (value, key) {
      if (typeof value == 'function') {
        delete json[key]
      }
    })
    return json
  }
})

The question is: since a computed property is a macro/helper and not a “real” part of our data model, and they never do actually change, should we allow then to trigger change event? I personally believe we shouldn’t use this approach, for it abstracts the true nature of the component. However, it can be useful.