When we built the new Magento responsive theme, we decided to use Sass as the CSS pre-processor and Compass as the compiler (technically known as a transpiler). Sass is the base syntax that supports mixins, variables, and nesting and Compass is a compiler that extends Sass’s capabilities by adding CSS3 mixins that we used to make the responsive theme compatible with older browsers. Here is the TL;DR infographic:
You can read all about the basics of working with the new responsive theme over at the Magento knowledge base. In this article, we’re going to take a more in-depth look at how to compile with Compass on the command line and via PhpStorm.
This article assumes that you’ve gone through the Magento RWD documentation and you have a custom Magento theme setup at skin/frontend/custompackage/customtheme.
Compass on the command line
Before you can compile with Compass, you need to install the command-line utility. After you’ve installed Compass, you can compile by running this command:
compass compile <MAGENTO_DIRECTORY>/skin/frontend/custompackage/customtheme
This command will compile your .scss files into .css files, but you have to run this command every time you make a change to your .scss files. To automatically re-compile your .scss files every time there is a change, you can run this command:
compass watch <MAGENTO_DIRECTORY>/skin/frontend/custompackage/customtheme
While it is valuable to know how Compass works on the command-line, many developers use their IDE or a standalone GUI app (like Scout or CodeKit) to compile with Compass. If you are going to do a lot of frontend development with Sass/Compass, I could encourage you to experiment with your different options and choose the approach that best integrates with your workflow. I use PhpStorm, so that is what I use to compile with Compass.
Compiling Compass in PhpStorm
PhpStorm seems to have become the de facto IDE for Magento backend developers, due to its excellent support for features like syntax highlighting, auto-completion and debugging. However, I was skeptical about using a Php-oriented IDE for front end development, as my previous experiences with robust IDEs like Eclipse/PDT provided to be clunky. Prior to PhpStorm, I used apps like CSSEdit/Espresso/TextMate for front end development. However, I found PhpStorm to be a joy to for front end development, as it offers features like CSS/HTML validation, Sass variable auto-completion, and rapid HTML markup creation via it Live Templates. It is now my IDE for frontend and backend development.
PhpStorm has a feature called “File Watcher” that allows you to automatically run Compass any time you change a .scss file. The way this feature works is that any time you make changes to .scss files in PhpStorm, PhpStorm will run a command line call to “compass compile”. Here are the steps for setting up this feature:
- Go to “PhpStorm > Preferences” (Cmd + ,)
- Type “File Watchers” in the filter input, click the “+” icon, and then click “compass scss”
- Configure the File Watcher with these settings:
Notable settings:- Immediate File Synchronization: Uncheck this option so that PhpStorm doesn’t compile until you actually save a file. It can get really annoying if PhpStorm is trying to recompile as you’re typing.
- Trigger watcher regardless of syntax errors: PhpStorm is smart. It knows when you have errors in your code, and you can configure the File Watcher to only compile when your code is error-free. However I find that feature to be confusing — when I had it enabled, I would commonly make a change, save the file, flip over to the front end to wait for my CSS to refresh (via LiveReload), only to realize a minute later that the .scss file wasn’t compiling due to an error. With this option disabled, PhpStorm will try to compile your .scss file and will throw an obvious error, which I find to be more helpful:
- Program: This tells PhpStorm which command line utility to run. Since PhpStorm is just running the command line “compass” utility, enter “compass” into this field.
- Arguments: This field includes the arguments that get passed to the “compass” command above. This field needs to include the location of your custom theme, relative to the root of your PhpStorm directory.
- Working directory: PhpStorm will take the value from this input and use it as the working directory when running the compass command. NOTE: You must insert this variable using the “Insert Macro…” button. If you just type the “$ProjectFileDir$” text, PhpStorm won’t recognize it.
So based on the configuration screenshot above, PhpStorm will essentially run these commands any time a .scss file is changed:
cd /Volumes/Server/www/magento/magento_1.14_compass compass compile skin/frontend/custompackage/customtheme/scss
If you have multiple themes for which you need to compile .scss files, you simply need to setup File Watchers for each theme. For example:
If you follow these steps, your .scss files should be compiled any time you make a change in PhpStorm!