*Note: this article was written using OS X Leopard, if you are using something similar, you may have to pre-install Rake in order to follow along. Check on google for instructions in your operating system.

The Tools

Protodoc is a small ruby class that was created for the Prototype Javascript Framework project. Its main purpose is to combine multiple files into one. The source code for Protodoc is incredibly simple. Grab a copy of protodoc and put it in the lib folder of your website.

Rake, or Ruby Make, is a simple build program that allows you to write build scripts in straight ruby. We're going to write a Rakefile that contains a task that combines all of your debug stylesheets together. You may need to install this!

Expression Engine is a great little CMS/Blogging engine from Ellislab. We use it for our website, and our clients websites. It's incredibly flexible and we've always been able accomplish interesting things with it relatively easily.

Now that we've had a run down of the components involved we are going to talk about how we've organized our files in order to make it easier to combine.

Moving from the top to the bottom, we've got /lib/protodoc.rb which can be downloaded above. Next we've got /stylesheets/production.css. This file will be the file outputted from our Rake task. Inside /stylesheets we've got src this folder will contain two things. First is a set of files that we want combined. Second is another production.css, only this one has pointers to the other files in src. We'll learn more about soon.

Creating our Production Stylesheet Source

This is the /stylesheets/src/production.css file. Here is a copy of the one from bigbangtechnology.com:

<%= include 'reset.css', 'core.css', 'sIFR-screen.css' %>

Pretty simple right? See how it references the other files in /stylesheets/src?

This is the only special file other than protodoc that is required really. The only thing left to in order to have our files combine into a single one is write the rake task.

Writing the Rakefile Task

The Rakefile file is created in the root of your website. This keeps things simple.

Here is a copy of the bigbangtechnology.com rake file, with only the :combine_stylesheets task showing. It might look a little confusing at first, but it's really simple. I'll break it down for you.

 1     require 'rake'
 2     require 'rake/packagetask'

Just the basics, tells the script that this is a rake file and it allows you to use the task method

 3     ROOT     = File.expand_path(File.dirname(__FILE__))
 4     STYLESHEET_DIR = File.join(ROOT, 'stylesheets')
 5     STYLESHEET_SRC_DIR  = File.join(STYLESHEET_DIR, 'src')

Tells the Rakefile where your assets are. STYLESHEET_DIR points to /stylesheets. STYLESHEET_SRC_DIR points to /stylesheets/src.

 8     namespace :production do
 8       desc "Builds the css files into production.css"

It is good practice to namespace your rake tasks. We've started a new namespace here so all tasks created inside will be called via terminal using the style rake production:combine_stylesheets

 9       task :combine_stylesheets do
10        $:.unshift File.join(ROOT, 'lib')
11        require 'protodoc'

Defines the rake task and adds the protodoc file from /lib/ and loads the protodoc module.

13        Dir.chdir(STYLESHEET_SRC_DIR) do
14          File.open(File.join(STYLESHEET_DIR, 'production.css'), 'w+') do |dist|
15            dist << Protodoc::Preprocessor.new('production.css')
16          end
17        end
18      end

The real meat of the task. This changes to the STYLESHEET_SRC_DIR (/stylesheets/src) opens up our production.css and starts writing each file it encounters in the include block into /stylesheets/production.css

20      desc "Combines all files required for deployment"
21      task :deploy => [:combine_stylesheets]
22     end

A helper task that runs any other tasks involved in deployment together. In the future we will add more tasks to this.

All Done!

You can now run the Rakefile from the command line by typing:

rake production:deploy

You should do this right before you are ready to move yours website from development/staging into production.

Setting up your environment to automatically load production.css

Since Expression Engine is built on PHP, we can easily just have it check to see if we're in production and load /stylesheets/production.css, and if not, it will load all of the other stylesheets from /stylesheets/src.

Check out this short video showing how you can enable PHP in EE in order to embed the production.css or the development css files.

So now we've got a single production.css loading instead of our multiple stylesheets. Why is this important? Read up on it at yahoo.com

Stay tuned for more articles on moving files into production. Next up we will use rake to compress all of our javascripts into a single file.