adams.co.tt blog - tagged with javascript

Namespacing in JavaScript

2012-05-30

JavaScript’s global variables are evil, and namespacing is a good thing. However, as I regularly move from project to project, I find myself rewriting the code to help manage namespaces again and again. Every time I search for something reusable, I find conventions that require unpleasant boilerplate.

I started a little personal project, and ended up writing this. Hopefully somebody might find it useful.

Grab the source here.

Include it in your document like so:

<script src="/path/to/n.js" type="text/javascript"></script>

n('foo.bar.baz', function(s) {
  s.Person = function () {
    this.greet = function () {
      alert('hello');
    };
  };
});

Reference registered objects and classes like so:

var myPerson = new foo.bar.baz.Person();
myPerson.greet();

That’s all there is to it!

UPDATE: A minified version can now be found here. Thanks Scott Hamper!

Updated jasmine-underscore

2012-03-14

Last year jasmine-underscore was released. Since then, some issues have been fixed, and two new matchers have also been included:

allToSatisfy

expect([2, 4, 6]).allToSatisfy(function (val) { return val%2 == 0; });
expect([1, 4, 6]).not.allToSatisfy(function (val) { return val%2 == 0; });

anyToSatisfy

expect([2, 3, 5]).anyToSatisfy(function (val) { return val%2 == 0; });
expect([1, 3, 5]).not.anyToSatisfy(function (val) { return val%2 == 0; });

These matchers allow any predicate to be applied to element of a collection, with the test only passing if all/any of the elements in collection satisfy the predicate.

Get version 1.1 here. Enjoy!

jasmine-underscore

2011-06-19

I love Jasmine. It’s a fantastic testing framework with a good set of extensions (e.g. jasmine-jquery).

I also love Underscore. It has a number of utility functions that help improve the readability of my code and dramatically reduces the code duplication associated with managing collections in JavaScript.

Recently I’ve been using Jasmine and Underscore together in tests. Underscore provides a number of functions to interrogate the state of an object, and I find I often use these in my Jasmine specs:

it('should return today as a date', function () {
  var cal = new AwesomeCalendar();
  expect(_(cal.today()).isDate()).toBeTruthy();
});

This is a useful test, however it doesn’t read quite as nicely as it could. There is a lot of noise, and the failure reporting won’t be particularly informative. With that in mind I created jasmine-underscore. This extension creates matchers for Jasmine based on the Underscore’s object functions. Any function that Underscore provides that has the ‘is’ prefix can be used as a matcher. For example, the test above becomes:

it('should return today as a date', function () {
  var cal = new AwesomeCalendar();
  expect(cal.today()).toBeDate();
});

This is not only more readable, it also produces better failure messages. The first spec’s error message would be Expected false to be truthy. Now the failure will read Expected null to be date if today unexpectedly returns null.

using

Another situation I found myself using Underscore with Jasmine a great deal is the generation of examples for specs:

_([
    [1, 2, 3], 
    [2, 3, 5]
  ]).each(function (vals) {

  var first = vals[0];
  var second = vals[1];
  var total = vals[2];

  it('should sum ' + first + ' and ' + second, function () {
      expect(sum(first, second)).toEqual(total);
  });
});

Again, this somewhat noisy, and could read somewhat better. The jasmine-underscore extension provides the using function. It is backed by Underscore and helps generate test examples in a meaningful way:

using([1, 2, 3], [2, 3, 5], function (first, second, total) {
  it('should sum ' + first + ' and ' + second, function () {
      expect(sum(first, second)).toEqual(total);
  });
});

Backbone.js - Events and Controllers

2011-05-09

In my last post, we discussed Backbone models and views, and how they can form a basic application. Now we’ll discuss how we can leverage Backbone events to allow rich client interaction, and how controllers can be used to create multiple pages within your application.

View events

Let us take the ArticleView from the previous post’s examples:

app.views.ArticleView = Backbone.View.extend({
  events : {
    'click span.remove' : 'remove'
  },

  remove : function () {
    var self = this;
    this.model.destroy({
      success : function () {
        $(self.el).remove();
      },
      error : function () {
        throw self.model.id + ' could not be removed';
      }
    });
  },

  render : function () {
    var out = '<h1>' + this.model.get('title') + '</h1>';
    out += '<p>' + this.model.publishDate() + '</p>';
    out += '<p>' + this.model.get('body') + '</p>';
    out += '<span class="remove">REMOVE</span>' 
    $(this.el).html(out);
    return this;
  }
});

There has been some behaviour added to the ArticleView. A span has been added to which we have registered a click event. Clicking on the text “REMOVE” will result in the model it represents being destroyed on the server. This is performed by Backbone.js sending an HTTP DELETE request to the server. Upon success of this operation, the element in the DOM which represents this model will be removed.

As we can see the events hash can be used to great effect in declaring any behaviour that you wish be be a product of direct user interaction. Events are written in the format {“event selector” : “callback”}.

Model events

Let us refer back to the code that we used to initialise the application in the previous post:

var app = {
  models : {},
  views : {},
  init : function () {
    var articleList = new app.models.ArticleList();
    articleList.fetch({success : function () {
      var view = new app.views.ArticleListView({
        collection : articleList
      });
      view.render();
    });
  }
};

$(document).ready(app.init);

As you can see, we load the article list once on page load, and then never again. However, suppose an editor modifies, adds or removes an existing article, and we wish to update the list in the browser to reflect that new state.

By altering the ArticleListView, we can leverage registration to model events:

app.views.ArticleListView = Backbone.View.extend({
  initialize : function () {
    _.bindAll(this, 'render');
    this.collection.bind('refresh', this.render);
  },    

  render : function () {
    var renderedArticles = _.map(this.collection.models, function (article) {
      return new app.views.ArticleView({model : article}).render().el;
    })
    $(this.el).html(renderedArticles);
    $('#container').html(this.el);
    return this;
  }
});

Now we can change the application initialisation:

var app = {
  models : {},
  views : {},
  init : function () {
    var articleList = new app.models.ArticleList();
    new app.views.ArticleListView({collection : articleList});
    setInterval(articleList.fetch, 10000);
  }
};

$(document).ready(app.init);

As a result, any changes to the article list on the server will be displayed shortly thereafter on the browser. Backbone.js models and collections generate a number of events:

“add” (model, collection) — when a model is added to a collection.
“remove” (model, collection) — when a model is removed from a collection.
“refresh” (collection) — when the collection’s entire contents have been replaced.
“change” (model, collection) — when a model’s attributes have changed.
“change:[attribute]” (model, collection) — when a specific attribute has been updated.
“error” (model, collection) — when a model’s validation fails, or a save call fails on the server.
“route:[name]” (controller) — when one of a controller’s routes has matched.
“all” — this special event fires for any triggered event, passing the event name as the first argument.

Controllers

It is debatable as to whether Backbone.js controllers can be considered controllers in the context of the common understanding of MVC. They, in fact, bear closer semblance to the rails routes.rb, declaring handlers for URLs. Consider the following example:

app.controllers.AppController = Backbone.Controller.extend({

  routes : function () {
    'articles' : 'index',
    'articles/:id/edit' : 'editArticle',
    'articles/new' : 'newArticle'
  }

  defaultView : function () {
    window.location.hash = 'articles';
  },

  index : function () {
    var articleList = new app.models.ArticleList();
    new app.views.ArticleListView({collection : articleList});
    articleList.fetch();
  },

  editArticle : function (articleId) {
    var article = new app.models.Article({id : articleId});
    new app.views.ArticleEditView({model : article});
    article.fetch();
  },

  newArticle : function () {
    new app.views.ArticleNewView({
     model : new app.models.Article();
    });
  }
});

Here we have an application that not only renders an article list, but also allows the user to create new articles and edit existing ones. Each function on the controller is invoked when the hash fragment of the url matches the url pattern described in the routes hash. When the user has completed an action on any given page, all the view need do is change the url hash to correspond with whatever the user wants or should do next.

Using events and controllers it is possible to provide a user experience which is rich in behaviour and interaction.

var app = {
  models : {},
  views : {},
  controllers : {},
  init : function () {
    new app.controllers.AppController();
    Backbone.history.start();
  }
};

$(document).ready(app.init);

Backbone.js - Models and Views

2011-05-08

What is backbone?

Backbone.js is a JavaScript framework which brings Model View Controller semantics to your JavaScript application. These semantics allow a rich JavaScript client application to be broken up in meaningful ways. DOM manipulation is separated from business logic by the views and models respectively. Controllers can be used to switch between ‘pages’ within your application.

Models and collections

Backbone provides model and collection classes. For example consider the following:

app.models.Article = Backbone.Model.extend({
  publishedTime : function () {
    return new Date(this.get('publishedDate')).toLocaleTimeString();
  }
});

Here we have a very simple Article class. You’ll notice we have not declared any attributes on this class. This is because backbone models gain their attribute structure from the data used to hydrate them.

Here we have a collection class:

app.models.ArticleList = Backbone.Collection.extend({
  url : '/articles',
  model : app.models.Article
});

As you can see, again the collection class is very anaemic. Both models and collections can be passed to views for rendering, and generate events. In this example the Article list maps to a url which returns JSON in the form:

[ 
  { 
    "id" : 1000,
    "body" : "Bar",
    "publishedDate" : "Mon May 02 2011 16:00:00 GMT+1000 (EST)",
    "title" : "Foo"
  },
  { 
    "id" : 2000,
    "body" : "Bam",
    "publishedDate" : "Fri May 06 2011 15:30:00 GMT+1000 (EST)",
    "title" : "Baz"
  }
]

The object list described here is what provides the models with their structure.

Views

Backbone provides a single view class from which we can extend:

app.views.ArticleListView = Backbone.View.extend({
  render : function () {
    var renderedArticles = _.map(this.collection.models, function (article) {
      return new app.views.ArticleView({model : article}).render().el;
    })
    $(this.el).html(renderedArticles);
    $('#container').html(this.el);
    return this;
  }
});

app.views.ArticleView = Backbone.View.extend({
  render : function () {
    var out = '<h1>' + this.model.get('title') + '</h1>';
    out += '<p>' + this.model.publishedTime() + '</p>';
    out += '<p>' + this.model.get('body') + '</p>';
    $(this.el).html(out);
    return this;
  }
});

Here we see views which can display the article list. The ArticleListView delegates to the ArticleView for rendering of individual elements of the collection. In this example we’re generating the HTML inline, however as your application grows, it’s most likely that you’ll want to extract this to some form of templating system.

The Application

Up until now we’ve only seen models, collections and views on their own. Now we can see how a very basic Backbone.js application hangs together. Here we declare the namespaces, the init function and register it to run on document ready.

var app = {
  models : {},
  views : {},
  init : function () {
    var articleList = new app.models.ArticleList();
    articleList.fetch({success : function () {
      var view = new app.views.ArticleListView({
        collection : articleList
      });
      view.render();
    }});
  }
};

$(document).ready(app.init);

And here we have an extremely basic Backbone.js application. You’ll notice that we have not yet leveraged any events or controllers. In my next post we’ll go over how to use these features to create an application to allow rich user interaction.

RhinoUnit with env.js

2009-05-20

In my previous post, I mentioned the possibility of using John Resig’s env.js as a means to provide a DOM to RhinoUnit. Since then I’ve been playing around with it to some success.

As I described before having a DOM available to RhinoUnit would carry a number of advantages. One of the great things about RhinoUnit is that it runs headless, and thanks to the speed of Rhino, tests can run very quickly. It’s problem is that it doesn’t have a DOM available to it, and so it means that testing view logic is very difficult.

This does have a big advantage that it encourages developers to separate their business logic and view logic, and to have good, loosely coupled testing around their business logic. However it does also mean that the view logic goes basically untested at the unit level. This is less than ideal. It also means that any interactions with frameworks like jQuery and their plugins also cannot be tested by RhinoUnit.

This is where env.js comes in. Env.js is a javascript implementation of the browser, which would allow RhinoUnit to interact with DOM provided they can be made to play nice together. As it turns out, both needed some minor tweaking in order to work with each other.

RhinoUnit uses javascript object self for logging, however env.js overrides this and therefore breaks RhinoUnit’s logging. To fix RhinoUnit, self needs to be assigned to a variable and all references to self need to be updated.

Env.js also needs some minor changes. In order to run RhinoUnit in this example, Rhino is hooked into the Bean Scripting Framework for java. This does not provide all the rhino shell commands that env.js expects, specifically the print function. By simply replacing all calls to print with the self instance variable’s log function, env.js can be made to work.

Finally, RhinoUnit will fail if it thinks you’ve polluted the global namespace. This an extremely useful rule, however env.js does rather break that, with the dozens of ways javascript can interact with a browser. As a result RhinoUnit needs to be configured to ignore a rather long list of global variables, including but not limited to:

rhinounit window closed defaultStatus event frames innerHeight innerWidth clientHeight clientWidth name opener outerHeight outerWidth pageXOffest pageYOffset parent screenLeft screenTop screenX screenY status top open close NodeList Node CharacterData Text DOMText CDATASection Comment DocumentType Attr Element DocumentFragment ProcessingInstruction $domparser DOMParser DOMImplementation Document HTMLDocument HTMLElement HTMLCollection HTMLAnchorElement Anchor HTMLAreaElement HTMLBaseElement HTMLQuoteElement HTMLButtonElement HTMLTableColElement HTMLModElement HTMLFieldSetElement Form HTMLFormElement HTMLFrameElement HTMLFrameSetElement HTMLHeadElement HTMLIFrameElement HTMLImageElement HTMLInputElement HTMLLabelElement HTMLLegendElement Link HTMLLinkElement HTMLMapElement HTMLMetaElement HTMLObjectElement HTMLOptGroupElement HTMLOptionElement HTMLParamElement HTMLScriptElement HTMLSelectElement HTMLStyleElement HTMLTableElement HTMLTableCellElement HTMLTableRowElement Event CSS2Properties CSSRule CSSStyleSheet location $currentHistoryIndex $history history navigator setTimeout setInterval clearTimeout clearInterval addEventListener removeEventListener dispatchEvent onerror XMLHttpRequest getComputedStyle screen moveBy moveTo resizeBy resizeTo scroll scrollBy scrollTo alert confirm prompt $profiler $profile document node iRet nodeList

Once you have RhinoUnit and env.js behaving, you can write tests as follows:

eval(loadFile(‘env-js/dist/env.rhino.js’));
eval(loadFile(‘example/lib/adminUtils.js’));
eval(loadFile(‘example/src/TagPickerInputView.js’));

var templateRenderer;
var view;

testCases(test,
    function setUp() {
        templateRenderer = {};
        view = new rhinounit.example.tagpicker.TagPickerInputView(templateRenderer, ‘first-tag-picker’);
    },

    function shouldShowLoadMessage() {
        document.loadXML(‘<div id="first-tag-picker">’ +
                         ‘<form>’ +
                         ‘<label for="tagPickerInput1">Please select the first tag</label>’ +
                         ‘<input id="tagPickerInput1" type="text" class="tag-picker-input" name="tagPickerInput" autocomplete="off"/>’ + 
                         ‘<div id="loadMessage" class="tag-picker-load-message hidden">Loading…</div>’ +
                         ‘<div class="tag-picker-matched-tags"></div>’ +
                         ‘</form>’ +
                         ‘</div>’);
        document.getElementById(‘loadMessage’).style.display = ‘none’;
        
        view.showLoadMessage();
        assert.that(document.getElementById(‘loadMessage’).style.display, eq(‘block’));
    });

Although env.js also apparently supports jQuery, my attempts to integrate the two with RhinoUnit have so far been fruitless. This may be due to the fact that although env.js does offer a high proportion of the features available in your average browser, the holes in functionality are still too great at the time of writing to satisfy the recent versions of jQuery.

Footnote: There are a couple of branches of env.js. This is the one that I used: link.