Maintainable front-end code in Ruby on Rails applications

by George Brocklehurst from Reevoo

Presented at RailsConfUa 2010

Ruby is only half the battle

As Ruby developers, most of us spend our time building websites, and whether we like it or not we have to write and maintain a lot of HTML, CSS and JavaScript.

Rails tells us a lot about how to structure our back-end code, but very little about how to structure our front-end code. Beyond providing a few simple helper methods it's more or less silent on the subject.

Just because Rails doesn't make these decisions for us doesn't mean they don't need to be made.

JavaScript & Rails

Hooray for Rails 3!

JavaScript helpers are now unobtrusive and framework agnostic.

Unobtrusive: JavaScript lives in .js files, not in .html files and the application still works if the .js files aren't loaded.
Framework agnostic: We don't have to use Prototype, but can replace it with the best framework for this particular team or project.

Rails 2

link_to_remote 'home', :url => root_path returns <a href="#" onclick="new Ajax.Request('/', {asynchronous:true, evalScripts:true, parameters:'authenticity_token=' + encodeURIComponent('1/GQG8AZN55Dpa…=')}); return false;">home</a>

The link has a fake href, so it won't work without JavaScript.
The JavaScript is inserted directly into the HTML, so to customise it we would have to modify the Rails helper that generates it.
The JavaScript uses the Ajax.Request method, which is specific to the Prototype library.

Rails 3

link_to 'home', root_path, :remote => true returns <a href="/" data-remote="true">home</a>

The link has a real href, so it will work without JavaScript.
The Ruby code we write to generate the link is much closer to the way we would create a non-JavaScript link (helps us think in the right way).
All the JavaScript is contained in rails.js and can be easily tweaked or replaced entirely without monkey patching Rails helpers.
There's no mention of anything specific to Prototype, jQuery or any other JavaScript framework.
Be careful though, you can still create links that make a POST request and only work with JavaScript.

Eventually, the helpers aren't enough

Although the helpers are now very good, they still only provide very basic functionality. As an app grows in size and complexity we are likely to want more JavaScript functionality than the Rails helpers can provide. Usually we would create a new file in public/javascripts and just start hacking, but there are better ways.

So how should we structure our JavaScript?

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 harder than in Ruby).
- There is no block level scoping, so the only way to get a new variable scope is by defining a function.
JavaScript is also awesome, and in places a lot like Ruby:
- Lexical scope and closures make lots of common Ruby idioms easy to implement in JavaScript.
- “JavaScript: The Good Parts” by Douglas Crockford is a good summary of the good parts of the language.
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 to be consistent with Rails 3.

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. This is equivalent to using respond_to? in Ruby.
Note the function passed as the second parameter to replace: This is very similar to passing a block to gsub in Ruby.

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 (e.g. a single Rails partial) 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).

Rails to the rescue

We've talked about adding classes to the body, and setting custom HTTP headers.
Why not roll all of this into some handy Rails 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 %>'>

CSS & Rails

CSS is much simpler than JavaScript, so there isn't as much to say.
There are still some sensible conventions that can help us write maintainable code.

Call things what they are

Good class names: <div class='product with-images'>

Bad class names: <div class='rounded-corners'>

Sharing terminology with designers is useful.
Using class='product' and styling a product to have rounded corners is much better than class='rounded-corners'.
The Rails content_tag_for helper is good at doing this.

Split things up

reset.css
elements.css
layout.css
…

Small, carefully named files are easier to maintain.
Make use of CSS's specificity rules: you can override what went before by being more specific.

Serving front-end code from Rails

Breaking down our front-end code into small, manageable files is a good thing, but making lots of HTTP requests is inefficient.
Rails provides some basic functionality, e.g. javascript_include_tag and stylesheet_link_tag. Both of these can combine files via :cache => true.
What if we want to do more than just combine our CSS and JavaScript files?

The future's bright

public is for designers, those messy kids, app is for the high-level programmer stuff that we care about. That's not really a good way of going about it … and we've been forgetting about stylesheets and JavaScript and ways we can optimise that for a long time. Let's not do that anymore.

David Heinemeier-Hansson speaking about Rails 3.1 at RailsConf 2010

Benefits of putting JavaScript and CSS in the app

We can do additional processing on the assets, e.g. minification.
We can use ERB and helper methods to generate some of the CSS or JavaScript, e.g. for CSS sprites, as mentioned in DHH's RubyConf presentation.
The front end code can easily access server-side configuration, like the routes or the current Rails environment.

ERB in JavaScript

jQuery('<a></a>').text('More'); could be rewritten as jQuery('<a></a>').text(<%= I18n.t('more').to_json %>);

We can pass data from our Rails controllers directly into our JavaScript or CSS.
When adding data to JavaScript we can use Rails' to_json method to handle quoting, escaping and object literals, because JSON is a subset of JavaScript.

The future is now!

Rails 3.1 may not be out yet, but a lot of the tools we need to manage are JavaScript and CSS better already exist.
Controllers, routes, helpers, ERB and to_json are all available now in Rails 2 and 3.0.
There are already some gems and plugins to help make this stuff easier.

Rails CSS views

github.com/rhulse/rails-css-views

Written by Richard Hulse.
Supports ERB in CSS.
Concatenates multiple CSS files.
Any object with a transform method can be used as a transformer, e.g. for minification.

Sprockets

getsprockets.org & github.com/sstephenson/sprockets

Written by Sam Stephenson from 37signals
Concatenates and minifies scripts.
Manages dependancies using specially formatted comments: //= require <jquery>
Supports bundling other assets (images, stylesheets, etc.) with scripts so you can easily share code between apps.
Simple string replacement, but no ERB.

JavaScript features

github.com/georgebrock/javascript-features

Written mostly by me, based on the way we do things at Reevoo.
Helps with client-side structuring.
Provides some Rails helpers.
Concatenates and minifies scripts.
No ERB support… yet.

Any questions?

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

These slides with notes and links:
georgebrock.com/conferences/rubyconfua2010