Structured JavaScript

by George Brocklehurst (@georgebrock)

Presented at BarCampLondon 8, November 2010

Structured JavaScript

MyApp.imageGallery = (function() {

  var imagesURL = 'http://example.org/images/';
  var loadMoreImages = function() { … };

  return {
    showLightbox: function() { … }
  };

}());

JavaScript is far from perfect:
- By default everything is in a global namespace (in the case of the browser, this is the window object).
- The privacy and object models are very different from other languages (not really a problem, but it can make some things feel unfamiliar).
- There is no block level scoping, so the only way to get a new variable scope is by defining a function.
- “JavaScript: The Good Parts” by Douglas Crockford is a good summary of the good parts of the language and what you should avoid.
If we write all our JavaScript as methods on the window object, we'll end up in a mess.
Using objects to group related code and immediately called functions to create a private variable scope helps avoid conflicts.

Initialising the right scripts

Lots of JavaScript files means lots of HTTP requests, which is slow.
Running lots of unneeded JavaScript setup on every page can also be slow, e.g. why initialise inline form validation on a page with no forms?
It is good to serve all of the JavaScript as a single file to reduce HTTP requests and benefit from caching, but be selective about which scripts we run.
This doesn't mean we should write the JavaScript in one big file (more on this later).

Ask the HTML what it needs

<body class='with-js-image-gallery'>

Because the purpose of the JavaScript is to enhance an HTML document, it makes sense to ask the document what it has that needs enhancing.
Class names on the body keeps everything in one place.
You could also use HTML5 data- attributes.

Common JavaScript API

MyApp.imageGallery = (function() {
  …

  return {
    globalInit:   function() { … },
    init:         function() { … }
  };

}());

We've already talked about splitting our JavaScript into objects, so it makes sense to give those objects a consistent interface.
We use init for code that needs to be run on pages that specifically require this feature, and globalInit for code that needs to be run on all pages.

A little bit of glue…

var key, className;

for(key in MyApp) {
  if(MyApp.hasOwnProperty(key)) {

    if(typeof MyApp[key].globalInit === "function") {
      MyApp[key].globalInit();
    }

    if(typeof MyApp[key].init === "function" &&
      jQuery('body').hasClass(classNameFromKey(key))) {
      MyApp[key].init();
    }
  }
}

var classNameFromKey = function(key) {
  return 'with-js-' + key.replace(/[a-z][A-Z]/g, function(str) {
    return str[0] + '-' + str[1].toLowerCase();
  });
};

Iterate over all of the objects in MyApp.
We need to use hasOwnProperty to make sure the property hasn't come from the object's prototype.
We're checking that each object has an init or globalInit function before calling it.

What about AJAX?

All of this happens on DOM ready, so what about content we load after the fact using AJAX?
When we load a fragment of HTML via XHR, there's no convenient container to attach class information to.
Fortunately we have access to other metadata about the request and response via the XMLHTTPRequest object, including the HTTP headers.

Reading HTTP headers in JavaScript

xhr.getResponseHeader("X-With-JavaScript");

We can use custom HTTP headers in the same was as we used the body class, and process them in the AJAX completion callback.
This can be put into a function similar to the DOM ready function mentioned above, and the common parts factored out.

Calling `init` twice?

<div class='gallery'>
  …
  <a href='…'>More</a>
  <a href='…'>More</a>
</div>

Some of our init functions will add elements to the DOM.
If we call them once on DOM ready, and again after an AJAX call has completed we can end up adding duplicate content to the page.

Defensive `init` functions

return {
  init: function() {
    jQuery('.gallery:not(.enhanced)')
      .addClass('enhanced')
      .each(function() {
        var moreLink = jQuery('<a></a>')
                         .text('More')
                         .click(loadMoreImages);

        jQuery(this).append(moreLink);
      });
  }
};

We have to write defensive init functions so we don't enhance the same bit of markup twice and potentially break our pages, e.g. if the JavaScript adds some markup to the page we don't want it to be added twice.
Adding a class to enhanced markup also gives us a convenient way of targeting CSS rules which are only appropriate when the JavaScript enhancements have been applied (it's good to keep style rules out of JavaScript, in the same way that it's good to keep JavaScript and CSS out of HTML).
Note that if you always use the same class name (e.g. enhanced) you can't initialise two features on the same element (thanks to the person who pointed this out in the Q&A at RubyConfUA).

This all sounds like a lot of work

We've talked about adding classes to the body, and setting custom HTTP headers.
Why not roll all of this into some handy server-side helpers?

Requesting JavaScript

def use_javascript_for(feature)
  @js_features ||= []
  @js_features << feature.to_s.downcase
  if request and request.xhr?
    header = @js_features.uniq.join(' ')
    response.headers['X-With-JavaScript'] = header
  end
end

For example:

<div class='gallery'> … </div>
<% use_javascript_for 'image-gallery' %>

Calling use_javascript_for in our views allows bits of HTML to request specific JavaScript enhancment.
Generating the HTTP headers and body classes in one place means we can load render a partial as part of a view or load it via XHR and the JavaScript will just work.

Adding the classes to the body

def javascript_feature_classes
  @js_features ||= []
  @js_features.uniq.map{ |f| "with-js-#{f}" }.join(" ")
end

For example: <body class='<%= javascript_feature_classes %>'>

Any questions?

George Brocklehurst
georgebrocklehurst@reevoo.com
“georgebrock” on Twitter, GitHub, etc.

These slides with notes and links:
georgebrock.github.com/talks/barcamplondon8/

Structured JavaScript

Structured JavaScript

Initialising the right scripts

Ask the HTML what it needs

Common JavaScript API

A little bit of glue…

What about AJAX?

Reading HTTP headers in JavaScript

Calling init twice?

Defensive init functions

This all sounds like a lot of work

Requesting JavaScript

Adding the classes to the body

Any questions?

Calling `init` twice?

Defensive `init` functions