This is the first part in my Asset Strategy series. Read the second part here..

Introduction

I’ve always hated how the css/ and js/ directories of any app generally become a junk drawer of hundreds of files which need minifying, compiling, managing etc

They can be the first point of a project that has the broken window effect and really go downhill.

In Ruby on Rails 3.x they introduced something called the Assets Pipeline which changed how assets are managed, files are stored in an Assets/ path in the app directory outside the webroot. These asset files are then compiled into a single JS and CSS file (depending on configurations) in the web root. Various filters are run on the files allowing them to be compiled from Pre Processor languages like CoffeeScript and Scss, and to be minified.

While still controversial in some parts of the RoR community, generally it’s been accepted and I feel it is a much better way of managing the styles and scripts for a project.

In my next few posts I’m going to outline how I’ve managed to build an Asset Strategy for CakePHP that is very similar to the Rails solution and improves my project organisation.

Getting Started

I’ll be basing this series on a clean setup of CakePHP 2.3.5. No actual code, other than whats required for the Asset Strategy is in the app. I’m also going to assume that your app is under source control using Git, initialised in the top level directory (the one with app/ libs/ vendors/ in it)

Asset Compress

The lynchpin of my strategy is the brilliant plugin Asset Compress from Mark Story (one of the core contributors of CakePHP) Install this into your app as a git submodule, or just download and unzip it, but basically you need to end up with AssetCompress directory in your app/Plugin directory

Some 3rd party help

We’ll also need a couple of tools to help compile and compress our assets.

• ScssPHP from http://leafo.net/scssphp/
• CssMin from https://code.google.com/p/cssmin/
• UglifyJS - install via NodeJS & NPM (uglify-js@1)

• CoffeeScript - install via NodeJS & NPM (coffee-script)

  Install CssMin and ScssPHP into your app/Vendor directory.
  Install Uglify and CoffeeScript via

  sudo npm install <tool> -g
  

  The -g on the end install globally so you can use this with multiple apps in the future

Creating the core files/paths

Now we need some specific paths and files created. The first is the Asset Compress asset_compress.ini file which goes in the app/Config directory. I’m not going to repeat here all the great documentation from the Github repository so you can check out all the options there, but for ease I have reproduced the simple settings I’ll be using in this guide.

[General]
cacheConfig = false

; javascript build instructions
[js]
paths[] = APP/Assets/scripts/*
cachePath = WEBROOT/js/
timestamp = false
filters[] = CoffeeScript
filters[] = Uglifyjs

; css build instructions
[css]
paths[] = APP/Assets/styles/*
cachePath = WEBROOT/css/
timestamp = false
filters[] = ScssPHP
filters[] = CssMinFilter

[application.js]
files[] = global.coffee

[application.css]
files[] = layout.scss

We will also need a new directory in your app/ path called Assets with 2 child folders styles and scripts

With the asset_compress.ini and the new Assets/styles and Assets/scripts we are pretty much ready to get started building our assets

Building our first Assets

For ease I’ve not included any popular libraries, just a couple of generic files in each path

Assets/styles/layout.scss

body {
a {
text-decoration: none;
}
}

Assets/scripts/global.coffee

alert 'Hello World!'

They’re pretty basic files I know, but its just something to use as an example in the guide.

Having created these files, we can now run Asset Compress’ shell command to build the compiled files and make sure everything is hooked up correctly.

Later on we’ll be adding a script to our Git hooks to automatically compile our assets when ever we do a commit with our Assets path in the commit.

The first build

Run the following command on the CLI in your CakePHP app/ directory

./Console/cake AssetCompress.asset_compress build -f

If everything is hooked up correctly you should see a couple of build outputs and then application.js and application.css should appear in your webroot/js and webroot/css respectively.

These can now be added to your .gitignore file so they aren’t in the repository. We don’t want them in there as later on we’ll be adding the build step to our deployment which will build fresh assets on the target server each time we deploy.

Thats all for this time. Hopefully everything up to now has worked and you have some compiled assets.

In the next piece, I’ll be covering automating the compile on git commits and how to get the assets into your layouts depending on debug state.