Static site development with Middleman

It’s great to use innovations such as CoffeeScript, Sass/Less and templating engines like Haml and Slim but they all need to be compiled in order to be understood by browsers. Command-line tools are provided but it can get tedious when working with multiple of these tools at a time. Building a huge rakefile might be a solution but it would be nice to have a flexible and ready to use solution, right? Luckily there is!

Enter Middleman: static site development at its finest. Middleman is static site generator based on Sinatra. It consists of a single command-line tool that watches a directory for changes and runs a server serving the compiled files.

Installing Middleman

To install Middleman and initialize a project:

$ cd my_project
$ gem install middleman
$ middleman init my_project --bundler --template=html5

I used two flags: --bundler creates a Gemfile containing a fixed version of middleman itself. --template=html5 adds HTML5 Boilerplate as a starting point. You can use the added index.html and style.css if you are OK with using plain HTML and CSS. I prefer HAML and SASS. You can drop in these HAML/SASSified versions of HTML5 Boilerplate I created. Or download the latest versions from this actively maintained Compass version of HTML5 Boilerplate at GitHub.

Start the server from the command-line:

$ cd my_project
$ middleman server

.. and open http://localhost:4567 in your browser.

Now just start developing your site! Any file you drop in your projects source folder will be automatically compiled by Middleman. The terminal will also notify you of any errors in your files.

Exporting your site

When you are done developing your site you will need to build it. Building means compiling all the source files for a production environment. This can be achieved by running the middleman build command:

$ cd my_project
$ middleman build

You will find the compiled site in the build folder.

Compressing assets

Middleman will optionally minify CSS & Javascript and compress images. You can enable these optimizations by editing the config.rb file to include the following lines:

configure :build do
  activate :minify_css
  activate :minify_javascript
  activate :smusher
end

Smusher image compression requires for the middleman-smusher gem to be installed:

$ gem install middleman-smusher

If you’re using Bundler, just add gem "middleman-smusher" to your Gemfile and run bundle.

Automatic browser reloads with LiveReload

LiveReload is a Ruby gem and browser extension which automatically reloads your browser when you make changes to source files.

This is how to install it on OSX:

Add rb-fsevent and guard-livereload to your Gemfile
Run bundle
Install a browser extension (Safari, Google Chrome, Firefox)
Run middleman server --livereload
If you’re using Safari, right-click the page and click ‘Enable LiveReload’

Your browser will now automatically reload upon file changes!

Follow the installation instructions on the LiveReload Github page for instructions on how to install on Linux and Windows.

Conclusion

Working with Middleman is a really pleasant experience. It definitely changed the way how I work on static sites. Its flexible system allows you to swap any templating or markup language and there are a whole lot of other features to discover like YAML data, templates & layouts and a ‘blog mode’. I tried a whole lot of other solutions like Nanoc and writing my own rakefiles, but in the end I definitely recommend Middleman. For more information, check out the excellent documentation over at middlemanapp.com.

Automated Jasmine Javascript testing

Last week I went on a bootcamp with my team to build a prototype for an upcoming web app. We decided on a test-driven approach to the project. I feel like this is one of the best decisions we’ve ever made. It might be slow to get into, but once you are you never want to go back to regular ‘ol programming style. Never I’ve had so much faith in the code I’ve written. It also really is a huge step forward in productivity.

I’m working quite a lot with Javascript as I’m the front-end developer on the team. In this tutorial I will now explain how I handle with tests in Javascript and I hope I can convince you of the awesomeness that is test-driven development!

The ingredients

There are a couple of ingredients to the automated testing workflow I’ve come to love:

Jasmine - A testing framework for Javascript
Jasmine-jquery - Some sweet Jasmin selectors and fixture support
CoffeeScript - Programmer happiness++
Jasmine Headless Webkit - Outputs feedback into the terminal
Guard - Makes it possible to run tests directly when you save them

Prerequisite

Jasmine Headless Webkit uses a QTWebKit Widget to run the tests in. Therefor we’ll need QT on our system. If you’re on OSX, the easiest way to install it is via Homebrew:

$ brew install qt

If you’re on another OS check the Jasmine Headless Webkit website and look in the Qt 4.7.X section for instructions.

Setting up the Ruby environment

If you haven’t already done so, install RVM by reading the installation documentation. Now create a new RVM configuration by running the following commands in a terminal in your project directory:

$ rvm use 1.9.2@myproject --create
$ echo 'rvm use 1.9.2@myproject' > .rvmrc

This will create and use an enclosed Ruby 1.9.2 environment within your project and will make sure it will use the correct Ruby version every time you enter your project via the command line. Try this by cd .. and cd myproject. The first time, you’ll be asked to confirm you want to use the .rvmrc file we just created.

We will now create a Gemset using Bundler. With Bundler we will create a “Gemfile” which will list the gems needed for our project. Installing it is as easy as running:

$ gem install bundler

Now create a file called Gemfile (yes, without an extension) in your project directory root and add the following lines to it:

source 'http://rubygems.org'

gem 'jasmine'
gem 'jasmine-headless-webkit'
gem 'guard-jasmine-headless-webkit'

Save the file and run the following command:

$ bundle

This will download and install the gems and their dependencies to a contained gemset within the RVM environment. It will also create a new file called “Gemfile.lock” which is kind of a binary file containing the gems.

We’re now ready to configure our environment. Let’s get started!

Setting up Jasmine

Jasmine comes with an init function which will set up a directory structure for you. Run the following command from your project root directory:

$ bundle exec jasmine init

With bundle exec, the jasmine executable will be called from the gemset.

Download the latest release of jQuery and drop it into public/javascripts/vendor (you’d have to create the ‘vendor’ folder). Next download jasmin-jquery to spec/javascripts/helpers.

We’re now going to edit the Jasmine configuration file. Open up spec/javascripts/support/yasmine.yml and replace the contents with the following:

src_files:
  - 'public/javascripts/vendor/jquery-1.6.2.min.js'
  - 'public/javascripts/*.{coffee,js}'

spec_files:
  - '**/*[sS]pec.{coffee,js}'

This ensures that jQuery is picked up at the start so we can use it in our tests. We’ll also tell Jasmine to look for .coffee files since Jasmine Headless Webkit supports CoffeeScript!

You could actually start testing right now but there’s one more thing..

Configuring Guard to automate testing

Guard lets us start a process when filesystem events occur. In our case, Jasmine will run the tests when we edit them. To enable Guard for our project, run the following command:

$ guard init jasmine-headless-webkit

This creates a “Guardfile” with all configuration we need. To start watching your project, simply run guard from your project root. This will automatically run all tests when you save a spec file.

Bonus (Growl notifications): Add the gems rb-fsevent and growl_notify to your Gemfile and run bundle to enable Growl notifications for Guard!

Let’s test our testing setup

Finally we’ve got our testing environment all set up so it’s time to test if our setup works.. The actual writing of tests is beyond the scope of this tutorial but for now I’ve provided a spec and an implementation file. I might do an in-depth testing tutorial soon.

spec/javascripts/pwd_spec.coffee

public/javascripts/Password.coffee

If you’ve run guard already, you should see that the 5 tests that came with Yasmine passed. Once you’ve created above files there should be 8 passing tests.

Richard Venneman

Scalable and Modular Architecture for CSS