Integrating the Compass CSS Framework into Visual Studio

Using Compass with .NET and Visual Studio

Intro to Compass Framework:

So here in my first blog post at thedevstop, I wanted to post about something I very much enjoy. And since I love the design side of development, I decided to go with the Compass Framework.

For any reader who isn’t familiar with the Compass css framework, it is a framework that takes advantage of sass to provide a whole bunch of premade css mixins. For example, take something simple, like adding a border radius. Doing it yourself, you would have to worry about all the different browser prefixes, but with Compass, all you need to do is:

 1: @import "compass/CSS3";

 2:

 3: .test-div

 4: {

 5:     @include border-radius(4px, 4px);

 6: }

Now, once you save the scss file, Compass will give you this:

 1: .test-div

 2: {

 3:     -webkit-border-radius: 4px 4px;

 4:     -moz-border-radius: 4px / 4px;

 5:     -o-border-radius: 4px / 4px;

 6:     -ms-border-radius: 4px / 4px;

 7:     -khtml-border-radius: 4px / 4px;

 8:     border-radius: 4px / 4px;

 9: }

Very nice, and very time saving.

A Quick Aside:

Feel free to skip this and get on with the tutorial.

I feel like a lot of times, .NET developers simply use what Microsoft gives them. I’ve seen this range from a developer giving up on an open source technology like Compass because there’s not a simple .NET or Visual Studio implementation to a .NET developer not knowing what jQuery is because it’s not part of the .NET framework. Don’t let the fact that something doesn’t have a simple .NET implementation stop you from finding a way to utilize it. That’s what this tutorial is all about.

Here are the problems:

1. This is a ruby gem
2. You’re a .NET developer.

Here is the solution:

1. Leverage ruby in .NET development.

Important Note:

This method does require you have ruby installed, along with the compass gem. If you’re working on a project by yourself, this might not pose an issue, but keeps in mind – If you’re working in a team environment, everyone will need to follow this tutorial to get ruby and compass set up (if they want to edit the css).

Step 1: Installing Ruby

The first step is installing Ruby on your machine. This is a very simple process. Go here to get the installer (When I wrote this it was 1.9.3-p0):

http://rubyinstaller.org/downloads/

Get the latest .exe installer. Running through the installer is fairly straightforward.

When you get the Installation Destination and Optional Tasks screen, use the following options (Installing Td/Tk support can go either way, I just chose not to):

Step 2: Installing the Ruby Devkit:

Note:

This step is required for the Ruby Installer for Windows. It may not be required for a different ruby windows installer, and it’s definitely not required for a linux or mac version of ruby.

Go here:

https://github.com/oneclick/rubyinstaller/wiki/development-kit

And follow their set up steps.

Step 3: Installing Compass:

This on is simple. Once you have Ruby and the Devkit installed, fire up a console window and type the following:

gem install compass

That should install the 4 gems required for Compass.

If you’re not familiar with ruby, then note that gems are ruby’s version of nuget package. Actually, the idea for nuget came from ruby gems.

Step 4: Integrating Compass With Visual Studio

So up until now, this has been a pretty easy process. And while this isn’t all that complicated, it’s a bit more involved. So I’ll break it into sub-steps.

Step 4a: Create the ‘Create Compass Project’ command:

The first thing to do when working with compass is create a compass project. A compass project isn’t as complicated as a .sln or .csproj file – it’s three folders and a config.rb file. I’ll go over this in more detail later.

So to integrate this into visual studio, click Tools –> External Tools. Click the add button and use the following configuration:

Note that the Command box is the path to your ruby installation. If you installed it somewhere other than the C:\ folder, then you’ll have to change it accordingly. Also, I strongly recommend checking the ‘Use Output window’ box. When creating a compass project, it outputs the information needed to add it to your html, and by using the output window, it’ll be there for later reference.

Step 4b: Create the ‘Watch Folder’ command:

The way compass knows to compile a .scss file is by watching the compass project’s folder. As soon as you save a file, the new .css files are compiled. So in the External Tools windows, click Add and use the following configuration:

Please note that in both screens, the Argument used is $(TargetName). These have to match so the compass watch command will know the compass project name to watch for.

Step 4c: Adding These Commands to the Toolbar:

This step is optional, but if you’re going to use this often, you don’t want to be clicking the Tools menu all the time. So to do this, click Tools –> Customize.

In the Customize window, in the Toolbars tab, click New. Add a toolbar called Compass.

The checkbox means to show the toolbar. If you get tired of it taking up space, just come back to this screen and uncheck it.

Next, go to the Commands tab. Click the Toolbar radio button, and select Compass from the dropdown. Click Add Command.

Things get a little tricky here. Visual Studio doesn’t handle External Tools in the Customize window very well. It just names them External Command 1, External Command 2, and so on. So you’ll need to look at how many external commands you have, count them, and use the number that ‘Create Compass Project’ and ‘Watch Folder’ are. If you look at my screenshots above, you’ll see ‘Create Compass Project’ is the 5th tool and ‘Watch Folder’ is the 6th. If you don’t have any external tools beyond the default set that comes with Visual Studio, this should be the case for you too.

So in the Add Command windows, click the Tools category, and the appropriate External Tool.

Repeat for the ‘Watch Folder’ command.

Your Customize screen should now look like this:

Step 5: Using Compass in your VS Project:

So now the fun starts. Let’s actually use Compass.

For this demo, I’m using an empty MVC 3 project. For the Compass component, I’m using the Content folder that automatically gets added to an empty MVC 3 project.

So, click the Content folder (or whatever folder you intent to use), and click the ‘Create Compass Project’ button we just added in the toolbar. Your output window should tell you that a compass project has been created, as well as some information about configure it.

However, in order to see it in Visual Studio, you’ll need to include it in the project. So click on the project in the Solution Explorer, and click on the ‘Show All Files’ Button. It’s the highlighted button in the screenshot below.

Notice how there is now a folder called TheDevStop.UI in my Content folder. You can right click it and click ‘Include in Project’.

Additional Step for Mindscape Workbench Users:

If you’re interested in sass development, you probably have the Mindscape Workbench extension installed. If you don’t, I highly recommend it.

Anyways, if you’re using it, there’s an extra step in this process. Mindscape will see the .scss files you’ve just included in the project and try to take over. However, since there’s no physical file called “compass/whatever”, it’ll throw an error when it sees that import. Also, you don’t want it generating the css files, you want compass doing it.

So in the solution explorer, select the .scss files one at a time, go to their properties (F4), and clear out the ‘Custom Tool Namespace’ field.

Compiling your Compass files:

I said earlier I would go over the files Compass adds. It’s fairly simple.

1. .sass-cache folder – I would leave this alone.
2. sass – This is where you’ll actually be working. Compass gives you three files be default, but you can add whatever files you like. Just remember, if you’ve got the Mindscape Workbench installed, you’ll need to repeat the step above.
3. stylesheets – This is where your compiled css goes. To use the css in your html document, this is where you’re href will need to point in your link tag. If you add an additional scss file in the sass folder, you’ll have to remember to include it’s compiled css file to the project.
4. config.rb – This is the configuration of you compass project. You can modify the paths of your sass and stylesheets folders to anything you like, and you’ll also need to set the images_dir value if you’re using images in your scss.

Now that you understand the layout of your Compass project, here’s how you use it.

To start watching for changes, select the folder you put the Compass project in. For me, it was the Content folder. Now click the ‘Watch Folder’ command we created.

The output window won’t display anything unless there’s an error, but it’s handy to have up in case anything errors out when compiling. To stop the watcher, simply select your folder and click the ‘Watch Folder’ button again.

Note: I’ve noticed that the first time you try to save a .scss file, the watching might throw a ‘Permission Denied’ error. I’ve always found that trying to save again fixes this.

Conclusion:

While compass won’t do your design for you, it is a very handy tool to have once you’ve worked your design out. Just keep in mind what I said earlier – if you decide to use this and you’re not the only person on the project, they’ll have to set up their environment like this as well.

Hope this helped, and have fun designing!