acts_as_architect

This blog has moved.

2009-09-20T00:26:00.000-07:00

I can't bear to use blogger anymore. I've moved my blog to github. If you're a subscriber, please visit my new blog and subscribe to it. Also, please read my first post there on why abstraction matters in stylesheets.

Compass Screencast

2009-04-26T11:59:00.000-07:00

I've put together a screencast that demonstrates how to get up and running with compass and use it to style a basic webpage. It covers some basic sass syntax in case you're not familiar with it, and then shows how you can create a stylesheet for your semantic markup. If you've been skeptical of the value that compass and sass provide, hopefully seeing it in action will convince you!

The Open Source Project that Social Media Made

2009-04-20T11:05:00.000-07:00

I realized recently that my open source project, Compass, has become popular enough to consider it moderately successful. It has a community, I get bug reports and patches. People write blog posts about it without prompting. I've been asked to give talks about it. All those benefits that you tell your company they will get when you release something into the wild, but that rarely actually happens. It occurred to me that the history of how Compass came to be is actually the story of how social media can make and shape a software project. So I thought I'd share that history with you.

Github

My friend Dustin turned me onto github when it first launched. Suddenly the bar to release open source software had lowered to the point where it was easy enough to share code without putting much effort into project hosting. In those first few months I threw almost a dozen projects up. Finally, I could give back to the community almost as easily as I could take. It was addictive. Every new watcher was a glorious moment. One day, after porting the blueprint css framework to sass, I decided to throw that up there too. It was only about 8 hours of work, maybe less. I wasn't nearly as proud of it as some of the other projects I released. But I thought I might be able to save someone from having to do their own port. This project was called "blueprint-sass" and I still keep it around as "Github SEO Strategy." Within a couple weeks, this project had attracted more watchers than all my others combined. I knew I had struck a nerve but I wasn't really sure how to proceed.

Blueprint

So I took my case to the age-old social media forum that is the Newsgroup. I suggested to the blueprint mailing list, that my new stylesheets built in sass should be the blueprint core stylesheets and that what they generated could be the blueprint distribution. And that those who wanted to use the sass stylesheets directly, certainly could. This seemed (and continues to seem) like the best way to manage that code base, since maintaining a port to a different language is a lot of extra work. I got a green light to begin work on a blueprint proof of concept based on sass which I threw myself into with full gusto. Many of the blueprint tools became obsolete because the sass stylesheets could perform programmatic calculations and sass has several output modes. Before I knew it, except for the generated css that came out, this was a whole new project. The scope of the changes ruffled a few feathers, I guess, and so it was decided that my code wouldn't be merged. As sad I was about this outcome, I was very proud of what I had built and the quality of my code was certainly a reflection of the expectation of becoming part of one of the most watched projects on github. I was not to be deterred in my efforts by this set back. In retrospect, it was probably one of the best things that could have happened.

Heading Off in a New Direction

While coding my port of blueprint, it occurred to me that so much of what I was building had little to nothing "blueprint specific" about it. The tool set was basically generic, change the Sass stylesheets and you could have a new sass-based framework. Now anyone who knows me can tell you that I love meta-ness. And since programming and software archicture is what I do best -- not actually devising clever css frameworks -- I thought I should stick to what I know and provide a tool set to css frameworks and the users of those frameworks everywhere so that they could take advantage of the real star of the show: Sass. Someone needed to point them all in a new direction: A new way of creating and sharing design from the geniuses of the web design world to the mere mortal web developers (like myself) who are much better working on someone else's design than coming up with our own. And so the two-fold vision of providing a compelling library to promote the use of Sass and to bring to web design the concept of sharing code was born. I gave it the name: Compass. Even today my vision for what compass should be is not yet fully realized. But I'm down to my last few unimplemented features before I can declare it version 1.0.

Guerrilla Marketing via Social Media

A wise man once said, "Don't worry about people stealing your ideas. If they are good enough, you'll have to cram it down their throats." (I wish I knew who to attribute that to, I think I heard it in a TED talk). As I was building Compass, I knew from my experience with blueprint, that if my idea was actually a good one, it was one of those requiring cramming. So I kept an eye out for social media opportunities to market it. If an article on CSS or especially CSS frameworks showed up on reddit, digg or ycombinator news, I found a way to link to my project in there. I left comments on relevant blog posts. I eavesdropped on twitter for people talking about blueprint and css, and pointed them toward compass. Week by week, compass grew. Compass-style.org got "stumble-upon"-ed. A small but fervent community of early adopters saw what compass and sass could do for web development, and they latched on to it. They blogged about it, and they tweeted. Oh my did they ever tweet. It's just so damn easy to send out a link to a new and exciting technology and thanks to the large number of ruby developers on twitter who are always eager to try new things, compass spread quickly.

Collecting Feedback via the Twitterverse

Twitter was instrumental in my ability to communicate directly with my users or potential users and learn from them. I learned from their reservations, and I learned from their criticisms. Their positive feedback gave me the energy to keep going. I was able to find out about and fix bugs within hours instead of days. My tech support responses came back to folks asking the twitter-void for compass help. Before twitter, those might have been users who gave up before completing their initial evaluation.

My Commitment to an Open Project

An open project means much more to me than just being open source. An open project is one that is conducted transparently. Compass is here in the form that it is, because it is what is needed. It's solving real problems for folks today. I know this because they told me through their actions on social media sites like Github and Twitter. But Compass can be much, much more than it is right now. Compass and Sass can change the way we think about the implementation of website design. I have a vision of a future, but I want to work with all of you to make sure it's the right one. I'm listening to your feedback and thoughts and acting on them. I know that a large part of the success of Compass to date has depended on that conversation, and I intend it to continue. Compass is nothing in the long run without its community and I look forward to fostering it more in the coming years.

The Names You Give to Your Data Models Matters More Than You Might Think

2009-04-14T21:10:00.000-07:00

Early in the days of Caring.com we planned to build a personal homepage for our users that would delight them with a customized selection of content that was appropriate for the issues they were dealing with. Many of our early architectural decisions centered around this premise. Unfortunately, the breadth and depth of our content was not sufficient to support that feature and it was shelved rather than disappoint our users. Almost two years later, we have an amazing selection of content for the most common care giving issues, a small army of experts waiting to answer care giving questions from our users, a small but active community of caregivers that are helping each other get through some of the most difficult times of their lives, and a comprehensive guide to care giving resources in your area. We are finally ready to personalize our site and deliver what we hope will be delightful experience for those people who choose to fill out a short questionnaire (not yet launched at the time of this writing).

So I got to take some old code off the shelf and dust it off. It was exciting, and a little frightening. In those early days, I knew I needed a model to represent the person or people that our user is caring for. With my overly analytical, highly trained engineer brain and no formal education in geriatrics or care giving, I called this model the CareTarget. That name stuck, and from time to time, I'd hear myself and others refer to the care target when we needed a term to use in conversation. And while this name clearly and unambiguously describes the purpose of the model, it was the wrong term. These are people, not targets. They are your loved ones and they are my parents. I felt the term CareTarget was dehumanizing. These are the people who receive our care, because we love them and because they deserve it. They are a CareRecipient. Sitting alone in my office, with deadlines to hit, I decided that I could not allow this term to persist. In two weeks the number of uses of these names, would double or more -- there was no better time to rename them than right then, and so it was done right then. Similarly, a model called CareTargetType was changed to CareRelationship (E.g. Mother, Father).

When I came to scrum (our daily standup meeting) the next day and announced I had made no progress on my tasks, not everyone understood why the change was so imperative. But these names are at the very heart of what Caring.com is and does, nothing that central can be allowed to be wrong. Not even their names. In total, I spent a day and a half renaming what were arguably fine names -- they needn't have ever been exposed to our users, but now I never have to worry that they might. And in a few months, when I hear folks in the halls of Caring.com talking about the care relationship one of our users has to their care recipient, I'm going to smile because I understand that the names in our code have a real and lasting effect on the tone and understanding of our domain. Software Architecture and Design is most certainly a technical field, but that doesn't mean it has to be dry and impersonal.

Disadvantages of CSS Frameworks: A Sass-y Response

2009-02-15T00:31:00.000-08:00

A recent post from Smashing Magazine made a very thoughtful and balanced analysis of CSS Frameworks. I recognized the drawbacks of using CSS frameworks long ago and set out to keep the good parts and eliminate the bad parts, as much as is possible, by using Sass for the core technology behind Compass.

Let’s be honest, CSS frameworks, while meeting the technical definition of a “framework”, are not anything more than a collection of css classes that you can use in your HTML. They are not a framework for writing your stylesheets -- they are a framework for building webpages, and this is the fundamental difference when you use Compass & Sass.

So here’s the list of disadvantages of CSS frameworks from Smashing Magazine, and my response to each with respect to Sass and Compass.

You need time to fully understand the framework.

Using external CSS frameworks, you still need a profound understanding of your code. You need to know exactly how your framework is actually built. “By building a site from the ground up, you gain a knowledge of your site’s architecture that can’t be learned through any study or documentation.” [Why I don’t use frameworks]

Yes, you’ll need to know your how your framework works. For example, you’ll need to know that a grid is built using floats and how changes to the element’s box attributes (padding, margins, border) will affect the layout. Your framework should document this, and if it doesn’t you should go read the code and understand it.

You might inherit someone’s bugs or mistakes.

If you use external CSS Frameworks you might get in trouble fixing someone else’s bugs which is far more time-consuming than fixing your own bugs.

Absolutely. This is of course not unique to CSS frameworks, this is a risk you take any time you stand on the shoulders of someone else. Fixing someone else’s bug is slower than fixing your own. But let’s think about this. How many bugs will you make in your attempt to reproduce what the framework gives you? I’m guessing more. But it’s quite likely that you won’t encounter someone else’s bug. But let’s pretend that you do; what is so bad about this? If there’s a community of people sharing a common code-base, once one person finds that bug it’s fixed for everyone. Thanks! You’re a great team player who has been benefiting from the help of others and you’ve just contributed back a small portion of your time savings. As with any build vs. buy decision, you need to consider how widely used the project is, how engaged the maintainer is, etc.

That said, the cost of upgrading a traditional CSS framework is high. The installation is manual and unless you were careful to never make a change to the files provided by your CSS framework, you’ll be stuck trying to manually merge your changes. Worse, some CSS frameworks, in an attempt to make them more customizable, will generate CSS just for you that you can then put into your project. Upgrading will mean regenerating this CSS using the same inputs.

Compass was designed to be upgraded trivially addresses this problem in two ways. It relies on the ruby installation framework called rubygems so upgrading is a simple matter of issuing:

$ sudo gem update chriseppstein-compass

Now, because you’re code is written in Sass instead of CSS, you simply need to recompile your stylesheets and you’re up and running with the latest bug fixes:

$ compass --update myproject

You develop sites upon a framework, not upon the solid knowledge of CSS.

“A big problem with frameworks is when up and coming developers attach themselves to a framework as opposed to the underlying code itself. The knowledge gained in this case surrounds a specific framework, which severely limits the developer.” [Please Do Not Use CSS Frameworks, by Jonathan Christopher]

This argument has been made every time a technology evolves a new layer of abstraction. There’s a certain amount of truth to this argument if you’re speaking about complex code frameworks like rails, MFC, etc. But in the case of CSS frameworks and Compass, I just don’t agree. As we said above you’re going to need to take the time to fully understand the framework. The output and construction of the framework is not hidden from you and you’re fundamentally working with abstractions that you have in CSS anyway.

You get a bloated source code.

“Whether it be in a server side language framework or JavaScript library, there is often a large percentage of code that will never be executed. While not a major issue server side, this can greatly degrade the performance of a client side framework such as a JavaScript library.” [Please Do Not Use CSS Frameworks, by Jonathan Christopher]

This is true. You can degrade the performance of a browser. But did you? I’ve seen this argument before, but I’ve never seen anyone back it up with numbers. But let’s make an aesthetic argument instead: Having a bunch of CSS that is superfluous to your project is ugly. I agree. Compass currently has 4 CSS frameworks that you can use. This ridiculous bloat just doesn’t matter though because you control what ends up in your stylesheets. You can select the non-semantic versions of these frameworks with simple commands like:

@import compass/reset.sass, @import compass/reset.sass, blueprint.sass

+blueprint

Or you can be more selective. For example, if you just want blueprint’s grid system:

@import compass/reset.sass, blueprint.sass

+blueprint-grid

CSS can not be framed semantically.

“CSS and (X)HTML go hand in hand. (X)HTML is a language semantic in nature, which is impossible to wrap up in the style of a framework. Each and every project is unique in and of itself, right down to the document structure, classes, and ids. A CSS framework passively removes a great majority of semantic value from the markup of a document and, in my opinion, should be avoided.” [Please Do Not Use CSS Frameworks, by Jonathan Christopher]

Bingo. This is, hands down, my #1 problem with CSS Frameworks. CSS based frameworks have to work within the limitations of the technology. As such, you have to make sure your markup conforms to the framework and violate the best practice of keeping your content and presentation separate. And this is the #1 reason Compass exists. I didn’t want to choose between using a framework and following best practices. I wanted to eat my cake too! Compass, together with the awesome concept in Sass called a “Mixin”, allows you to build semantic stylesheets!

@import blueprint.sass
#page
+container
#sidebar
+column(8)
#content
+column(16, true)

This generates the following CSS:

#page { width: 950px; margin: 0 auto; overflow: auto;
   overflow: -moz-scrollbars-none; display: inline-block; }
#page { display: block; }
#page #sidebar { float: left; width: 310px; margin-right: 10px; }
#page #content { float: left; width: 630px; margin-right: 0; }

As you can see, your #page element is a container that has been clear-fixed and set to the appropriate width. The #sidebar is an 8 unit grid column and your #content is a 16 unit grid column with no right margin because the “true” means it is the last column in a row. This is a simple example, but I hope it demonstrates how you can start to think about your stylesheets in a new way and why I say Compass is a real stylesheet framework, not just a collection of classes.

Ignoring the uniqueness of your projects.

Designs should be based upon the content, not upon a standard template you use over and over again.

I don’t know. I’ve never had a framework dictate my design. Our designer would never stand for that. Sometimes the framework informs some basic guidelines surrounding widths, etc. If your framework is dictating a design you don’t want, pick a different one. Compass comes with three (blueprint, yui, and compass-core) and you can install a plugin to get support for 960.gs. Even if you don’t want grids, these frameworks can help you set up your typography and vertical rhythm and perform common styling tasks like making lists lay out horizontally or building a tag cloud. Here’s a demo of some of the compass utilities.

In conclusion

Using Sass instead of CSS let's you insulate yourself from the nitty gritty mechanics of CSS while keeping you close to the syntax and semantics of CSS. It provides the power to keep your stylesheets both DRY and semantic and let's you stand on the shoulders of others or even your yourself (reuse across projects, websites). Compass is the pointing they way to cleaner, more maintainable stylesheets. If you want to use it, I hope you get value out of it. But even if you don't, just sticking with Sass and building up your own framework will give you many of the benefits I've discussed here.

I'm on the Sass core team

2009-01-15T10:51:00.000-08:00

While it actually happened back in late September, Nathan recently announced that I've joined the Sass Core Team. Sass is such an amazing technology! It has dramatically improved our productivity at Caring.com. and I'm happy to be part of the team and helping drive its development. I do all my work on my fork of haml so if you want to keep tabs on upcoming changes to sass, you should watch it on github.

Creating a Reusable Three-column Layout using Compass

2008-11-18T14:36:00.000-08:00

Let's pretend we want to build a three column layout like so: Using blueprint, the page is divided into 24 columns. In just a few minutes we whip out our three column layout for our webpage: And here's our stylesheet that implements this layout: Again, this is as easy to use as blueprint, but we've avoided making the mistake of putting presentation in our content. Now let's say you have several different templates and you've been good about making nice semantic names for the different pages and none of the IDs are the same. But we want all of these pages to use the same layout. This is where your power to create abstraction comes in. Using Sass you can define your own mixins that you can reuse! So you start by defining a three column mixin: Now you can now simplify your layout declaration even further:

A Compass Primer

2008-11-18T11:46:00.000-08:00

The goal of this post will be to help you install Compass and Sass and then learn the basics. When you are done, if you follow along, you will have a working stand-alone compass project. If you're looking to better understand what Compass can do for you, please read the compass introduction and then come back. If you plan to use Compass with Rails, Merb, or StaticMatic, there's specific installation instructions for each available on the wiki but for now, you can follow along without them.

Some Basic Prerequisites

Both Compass and Sass require you to have Ruby installed. If you don't have ruby installed, please do so now.
Please make sure you have rubygems version 1.3 or greater by running gem -v.
Using compass will require you to do some basic command line work. If you're not comfortable using the command line, you should probably pass on Compass for a while until we get more users and some IDE support, etc.

Installing Compass

$ gem sources --add http://gems.github.com/
$ sudo gem install chriseppstein-compass

You have successfully installed compass if you can perform this command:

$ compass -v
Compass 0.8.15
Copyright (c) 2008 Chris Eppstein
Released under the MIT License.

Sass, which is part of the Haml project, was also installed for you. Sass comes with two command line tools that you should be aware of:

sass - A sass compiler for single files and directories that emits css.
sass-convert - A sass translator for your existing css, less, sass, and scss files.

Both of these tools also operate on "stdin" for easy integration with other command line tools and GUIs.

Setting up your First Compass Project

We will now create a new project named "my_compass_project" based on blueprint. The contents of the project will be placed into the my_compass_project subdirectory of your current directory -- which will be created for you.

$ compass create my_compass_project --using blueprint --syntax sass
  directory my_compass_project/
  directory my_compass_project/images/
  directory my_compass_project/src/
  directory my_compass_project/src/partials/
  directory my_compass_project/stylesheets/
     create my_compass_project/config.rb
     create my_compass_project/src/screen.sass
     create my_compass_project/src/partials/_base.sass
     create my_compass_project/src/print.sass
     create my_compass_project/src/ie.sass
     create my_compass_project/images/grid.png
     exists my_compass_project/stylesheets
    compile my_compass_project/src/ie.sass
     create my_compass_project/stylesheets/ie.css
    compile my_compass_project/src/print.sass
     create my_compass_project/stylesheets/print.css
    compile my_compass_project/src/screen.sass
     create my_compass_project/stylesheets/screen.css

  *********************************************************************
  Congratulations! Your compass project has been created.

  You may now add and edit sass stylesheets in the src subdirectory of your project.

  Sass files beginning with an underscore are called partials and won't be
  compiled to CSS, but they can be imported into other sass stylesheets.

  You can configure your project by editing the config.rb configuration file.

  You must compile your sass stylesheets into CSS when they change.
  This can be done in one of the following ways:
    1. To compile on demand:
       compass compile [path/to/project]
    2. To monitor your project for changes and automatically recompile:
       compass watch [path/to/project]

  More Resources:
    * Wiki: http://wiki.github.com/chriseppstein/compass
    * Sass: http://sass-lang.com
    * Community: http://groups.google.com/group/compass-users/


  Please see the blueprint website for documentation on how blueprint works:

      http://blueprintcss.org/

  Docs on the compass port of blueprint can be found on the wiki:

      http://wiki.github.com/chriseppstein/compass/blueprint-documentation

  To get started, edit the screen.sass file and read the comments and code there.

  To import your new stylesheets add the following lines of HTML (or equivalent) to your webpage:
  <head>
    <link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/print.css" media="print" rel="stylesheet" type="text/css" />
    <!--[if lt IE 8]>
        <link href="/stylesheets/ie.css" media="screen, projection" rel="stylesheet" type="text/css" />
    <![endif]-->
  </head>

As you can see from the output several new directories have been created, some sass files have been added already and they've even been compiled to css for you. Before we change anything let's verify that our project is working out of the box.

Create an HTML file

Let's create the following html file named index.html in the my_compass_project directory:

Now open index.html in your browser and you should see a nice looking H1 that is left justified within the centered 950px blueprint grid container.

A Quick Intro to Sass

As mentioned already, Compass is built on top of the Sass stylesheet language. Before we can style our webpage, we should review some Sass basics. Sass provides a much cleaner syntax than CSS for styling your webpages. But before we style our ours, let's review some of the basics of the Sass language. First and foremost, Sass allows you to use indentation to indicate a descendent selector, yielding style

Which generates two css rules that look like: This ability to scope selectors allows you to easily avoid the dreaded "CSS Spaghetti" where your styles and class names end up bleeding into areas where you'd rather they didn't. Have you ever wanted to name your colors so that you wouldn't have to remember the hex values or so that you could change them easily? Sass provides variables to which you can assign values and reuse them over and over again: Do you find recurring patterns for styles and copy and pasting them into different selectors? Sass provides a concept called a mixin that addresses this problem. You can define a mixin like so: And once you'd defined your mixin, you can "mix it" into any selector like so: Mixins can also take arguments, define rules for descendants, and even include other mixins: +clearfix is a mixin provided by the compass utilities module that makes sure the bottom of an element containing floated elements falls below the contained elements. These mixins can be used like so:

This ability to create abstractions using mixins is what makes Compass possible and what makes your life easier. Sass has many features that I cannot cover here, I highly encourage you to go read the Sass documentation to learn more.

Introduction to Blueprint

If you are familiar with the Blueprint CSS Framework, you can now use it just as you would have without compass. All of the Blueprint classes are defined and available to you. If you're not familiar with blueprint, I'll give a quick overview here:

Blueprint creates a 950px wide container that is divided into 24 units across. Each unit is composed of 30px of content space and 10px of gutter space. Using the +column mixin you can define an element as a column that is some number of units wide. Columns are floated left and new rows are created by this floating whenever an element would extend past the container bounds. For this reason, we have to tell the last element on a row that it is the last one so that it knows to remove the 10px gutter on the right side and fit into the current row. When a columns is 24 units wide it is implied that it is the last column for the row and so it is safe to omit the last argument from those column declarations. Columns can be nested in which case the nested columns must add up the the width of the containing column and each row of nested columns must end with an additional last option. Please see the wiki for a complete reference of the blueprint grid library.

Getting Semantic

However, the very reason that compass was created was to make it possible for us to avoid using presentational class names in our markup. So let's rip out a few things that we're not going to use to avoid enlarging our stylesheet unnecessarily.

Open up src/screen.sass in your text editor and change it to this:

This change removes the blueprint grid classes from our generated CSS, we don't need them because we're going to use the blueprint library's grid mixins with our semantic markup instead.

Let's briefly go over the changes we've made here:

First, we're only applying these styles to pages that have a body class of "blueprint". This is entirely optional, but as a best practice, I encourage you to always scope your styles by a body class or id so they don't appear where you intend them to.
We've taken out the generic +blueprint mixin that adds the entire blueprint framework and replaced it with +blueprint-typography which only styles our typography.
We've told the class .container that it is a blueprint container on body.bluprint pages.

The parts that didn't change:

@import directives make different sass libraries available to us. If those libraries have styles in them, those styles are added to our pages as is the case for the compass/reset.sass which will do a global reset to all pages that include this stylesheet. For more information on css resets, please read Eric Meyer's Post. It is also possible to selectively reset only certain pages, but that is outside the scope of this post.
the scaffolding import and the +bluprint-scaffolding call makes our page look nicer as we're first getting started, but soon enough we'll want to pull these out because the styles it provides usually get in the way of a fully styled website.

Now we update our CSS files by running the compass command line while in the my_compass_project directory.


$ compass compile
compile src/ie.sass
overwrite stylesheets/ie.css
compile src/print.sass
overwrite stylesheets/print.css
compile src/screen.sass
overwrite stylesheets/screen.css

Reload index.html and things should look exactly the same.

Setting up auto-updates

We'll be making a number of stylesheet changes going forward and having to run the compass command-line after each edit gets tedious. So compass provides a "watch" mode that will monitor your project for changes and recompile your stylesheets automatically. In your project directory run the following command:


$ compass watch

If you encounter an error, the details will appear at the top of your webpage.

Styling your First Page

Now it's time to add some content to our page and style it. Let's update the container element in our index.html to the following: We will now style this page to have a header, footer, sidebar and primary content area using blueprint grid mixins. Open src/screen.sass in your text editor change it to the following: These sass mixins assign blueprint styles to our page that causes it to be laid out nicely. After saving, the css should have been automatically compiled for you. Go ahead and reload your index.html. It looks pretty good, but I think the header needs a little cleanup so we'll apply some basic styling as well as some compass utilities to it: First, let's pull in the compass utility library by adding an import: @import compass/utilities And then amend the #header style rules like so: You'll notice we've floated the h1 left and the site actions right. I've also told the site-actions list to be a horizontal-list, which is a very handy utility mixin provided by compass. Reload the page, and I hope you'll agree that looks pretty decent. Let's take a look at the css we've generated just for giggles:

Conclusion

Well, you've seen how to style a page using Sass and Compass. We've only just scratched the surface here. I hope this was enough to get you started. From here you should go read the wiki, and ask questions on the mailing list if you get stuck.

Introducing Compass.

2008-11-01T13:34:00.000-07:00

Pointing the way to cleaner, more maintainable stylesheets.

Are you stuck in a web of CSS Spaghetti? Are you tired of starting from scratch with every website that you build? Don't designers deserve tools to create abstractions just like their programmer buddies? With compass you start with a vocabulary of common styling patterns and best practices all wrapped up and ready to go. With Compass, you don't write CSS! CSS was designed to make browsers efficient, not designers. Instead you write your stylesheets in a language called Sass and it gets converted to CSS for you. But don't let this frighten you. Sass was designed to make CSS easier. So let's start with a really simple example. Ever wanted a list that was displayed horizontally instead of vertically? I thought so. In fact, you probably have a css class tucked away somewhere called "horizontal" that you can apply to lists to achieve this effect. If you do, you've created an abstraction that you can apply to your html to achieve a desired presentation. This is practical and I understand why you've done this but that doesn't change the fact that you're doing it WRONG! You've heard the CSS Experts talk about writing "Semantic" HTML and how you should keep your content and styles separate. But the power of abstraction to simplify your immediate task at hand always trumps the theoretical benefit of "doing it right." Using Compass and Sass, you no longer have to make this trade-off -- Doing the right thing now is just as easy as doing the wrong thing was. So instead of doing this: You can omit the non-semantic "horizontal" class and just add this to your stylesheet instead: +horizontal-list is called a "Mixin". It adds a behavior to the "ol#menu" selector. A mixin can add styles and nested rules. So the above code generates the following CSS: Aren't you glad you didn't have to write all that by hand?

Why does semantic markup matter?

I'll direct you to a page on my website and point out that there's three menus on this page. There's a top menu for general navigation, a context menu on the left side, and a footer menu. Each of them looks completely different and yet the same code was used to generate the html for each one. The only difference is how they are styled. Certainly doable without Compass, but because our abstractions live in the stylesheets, it was no harder than styling custom generated html for each with the corresponding utility class names in the html markup.

We've only scratched the surface.

There are about twenty utility mixins (and growing) found in compass to make the things you do every day as a designer easier. But compass is much more than a collection of utilities. Compass contains a complete port of the Blueprint CSS Framework. And if that's not enough, Compass is designed to work with other CSS frameworks as well and it will even let you mix and match them. For instance, at Caring.com we use YUI's font system and base styles but Blueprint's grid system.

Are you ready to get started?

It's time to read the Compass Primer. You can also head over to the wiki and read the Getting Started page.

Don't forget

Please follow the Compass project on github to stay up to date on developments and join the Mailing list for major announcements and support. For now, please report any bugs you find to the mailing list.

Back after a Hiatus

2008-11-01T12:29:00.000-07:00

It's been a year and a half since I joined Caring.com. I've learned a whole hell of a lot during that time and instead of sharing my trials and tribulations of learning rails and building out a pretty darn complex website, I'm going to shift the focus of this blog to share how we're doing things that are different and unique.

Caring.com engineers have produced no fewer than ten unique open source projects as part of our work on the site and have contributed features and bug fixes to numerous open source projects like haml, rails, beanstalk, and git. I'm pretty darn proud of us and I intend to start sharing more about the great things we do.

We've just launched a complete redesign of the site. From a technical perspective, this launch was a resounding success. We have a very solid feature set that exceeded expectations, and we did this with just four engineers. As the architect, I did some up-front coding and planning and got our application infrastructure in place so that the rest of the team could hit the ground running. I spent about two months preparing while the others were building other features. In that time, I overhauled our core data model, implemented dramatic changes to the Cells project, created an entire stylesheet framework built on the awesomeness that is Sass, and eventually ended up joining the HAML project as a core contributor. Needless to say, I've been busy and my family is glad that things are cooling off a bit.

Seven weeks before launch we still didn't have a single template built but I had all the infrastructure in place when the full team finished their other work. Truth be told, I was freaking out and didn't imagine that we would hit our date. But 5 weeks later we were feature complete and two weeks after that we had all the bugs fixed and the site was looking better in all our target browsers than it had ever looked before. The engineers kept complaining that things were too easy and straight-forward and they didn't have to think enough when building out the features. In other words: music to my ears.

In the coming weeks and months, I will be sharing with you as much as I can about how four engineers in five weeks rebuilt what amounted to a complete rewrite of the "core" of caring.com: Our content system. I will also be describing the open source projects Caring.com is contributing back to the open source community that has given so much to us. I hope you find it interesting and at least somewhat helpful.

Rails partial collection counter behavior changed

2008-04-17T10:23:00.000-07:00

In migrating from rails 1.2 to 2.1 (edge), we found that the automatic counter is no longer a zero-based index, it starts with 1 now. I can see how that's a more useful default but it took a while to figure out why all our partial_counter == 0 conditions were failing.

Creating a Unique URL

2007-07-23T14:32:00.000-07:00

SEO optimization these days requires that you have nicely-dashed-urls instead of ids. While there's a few examples of how to generate these on the web, I found all of them lacking in flexibility and reuse. So here's my solution to the problem. The approach decomposes the problem into three subproblems:

Eliminate unsafe characters from a string.
Identify the uniqueness of a string.
Generation of endings to construct uniqueness candidates.

You can then put them all together according to your needs. For example:

#Generate a unique name by adding integers to the end
uniquify(url_safe(name.downcase)) do |candidate| 
  Article.find_by_url_name(candidate).blank?
end

The code is formatted as a Ruby module that can be mixed in to your classes as needed. I hope you find it useful!

module UrlUtils
  # Makes a string safe for urls
  # Options:
  #   :replacements - a Hash of a replacement string to a regex that should match for replacement
  #   :char - when :replacements is not provided, this is the string that will be used to replace unsafe characters. defaults to '-'
  #   :collapse - set to false if multiple, consecutive unsafe characters should not be replaced with only a single instance of :char. defaults to true.
  def url_safe(s, options = {})
    default_regex = options.fetch(:collapse, true) ? /[^a-zA-Z0-9-]+/ : /[^a-zA-Z0-9-]/
    replacements = options.fetch(:replacements, { options.fetch(:char,"-") => default_regex })
    replacements.each do |replacement, regex|
      s = s.gsub(regex,replacement)
    end
    return s
  end
  
  # Generate integers
  # Options:
  #   :start => 1, The integer to start with
  #   :end => nil, the last integer to generate, when nil this becomes an infinite sequence
  #   :increment => 1, the amount to add for each iteration
  def int_generator(options = {})
    start = options.fetch(:start,1)
    last = options[:end]
    increment = options.fetch(:increment, 1)
    raise ArgumentError if increment == 0
    raise ArgumentError if last && (increment > 0 && start > last) || (increment < 0 && start < last)
    Generator.new do |g|
      i = start
      loop do
        g.yield i
        return if !last.nil? && (increment > 0 && i >= last) || (increment < 0 && i <= last)
        i = i + increment
      end
    end
  end
  
  # accepts a block that will be passed a candidate string and should return true if it is unique.
  # Options:
  # => :separator => "-", a string that will be injected between the base string and the uniqifier
  # => :endings => generator, a Generator that provides endings to be placed at the end of the base.
  #                           defaults to the set of positive integers.
  def uniquify(base, options = {})
    sep = options.fetch(:separator, "-")
    endings = options[:endings] || int_generator
    return base if yield base
    while endings.next? do
      candidate = base+sep+endings.next.to_s
      return candidate if yield candidate
    end
    raise ArgumentError.new("No unique construction found for \"#{base}\"")
  end
end

If you prefer you can get the code as a pastie.

DRYing up Unit Test Preconditions and Postconditions

2007-06-17T19:47:00.000-07:00

It's good practice in unit testing to assert any preconditions (aka assumptions) relevant to the test and the expected postconditions (aka side-effects). I had a unit test that went something like this:

class TaggableTest < Test::Unit::TestCase
  fixtures :tags, :items
  def test_tagging
    one = items(:one)
    one.tag_list = "tag1, tag2, tag3, tag4"
    assert_equal 0, one.tags.size
    assert_equal 3, Tag.count
    assert_equal 0, Tagging.count
    one.save
    assert_not_nil one.id
    assert_equal 4, Tagging.count
    assert_equal 4, Tag.count
    assert_equal 4, one.tags.size
  end

I didn't care for this code because of the redundancy of the assert equals. So I added some new asserts to TestCase in test_helper.rb and was able to convert it into the following:

  def test_tagging
    one = items(:one)
    one.tag_list = "tag1, tag2, tag3, test4"
    assert_changed(lambda {one.tags.size},
                   lambda {Tag.count},
                   lambda {Tagging.count},
                   :from => [2, 3, 2],
                   :to => [4,4,4]) { one.save } 
  end

assert_changed will execute the code blocks passed in prior to the execution of the primary block and again afterwards. It will then compare those values to the from and to values (optionally) passed in. If you don't pass in both :from and :to, assert_changed merely validates that the values changed.

  private
  def singleton_maybe(s)
    return s[0] if s.is_a?(Array) and s.size == 1
    return s
  end
  
  public
  def assert_array_or_svo_equal(expected, actual)
    expected = singleton_maybe(expected)
    actual = singleton_maybe(actual)
    assert_equal expected, actual
  end

  def assert_changed(*expressions)
    options = {}
    options.update(expressions.pop) if expressions.last.is_a?(Hash)
    initial = expressions.map {|e| e.call}
    assert_array_or_svo_equal options[:from], initial if options.has_key?(:from)
    yield
    subsequent = expressions.map {|e| e.call}
    initial.each_with_index { |i, n| assert_not_equal i, subsequent[n] } if not (options.has_key?(:to) and options.has_key?(:from))
    assert_array_or_svo_equal options[:to], subsequent if options.has_key?(:to)
  end
  def assert_unchanged(*expressions)
    initial = expressions.map {|e| e.call}
    yield
    subsequent = expressions.map {|e| e.call}
    initial.each_with_index { |i, n| assert_equal subsequent[n] }
  end

Continuous Build Integration

2007-05-22T16:37:00.000-07:00

If you don't know what Continuous Build Integration is, then you should because it makes the development process work very well.

Here at UnnamedStartup® we're using Mercurial (a.k.a. Hg) as our revision control system and we wanted to use buildbot to manage our continuous integration according to the following diagram:

I've just got the closed loop from developer to Hg to Buildbot to email. It could have gone smoother. Here's a few of the challenges I faced, and how I solved them.

Sending Check-in Notifications from Mercurial to Buildbot - There is a user contribution to buildbot for doing this. You can download hg_buildbot.py and make sure it is executable to the user(s) commiting to your Mercurial repository. Follow the instructions in the comments of that file to have mercurial call this script. Please note that if you are submitting changes via https, I hit a bug and ended up changing to committing via ssh to work around it (for what it's worth, ssh is faster than https).
Configure Buildbot Sources - The hg_buildbot.py script is expecting buildbot to be accepting changes from a PBChangeSource. Configure buidbot like so:
from buildbot.changes.pb import PBChangeSource c['sources'].append(PBChangeSource())

Unified email recipients list - I've configured Mercurial to send email notifications like so:


.hg/hgrc

...
[hooks]
#callback to the notifier extension when changegroups are constructed
changegroup.notify = python:hgext.notify.hook

[notify]
#only send out emails if a changegroup is pushed to the master repository
sources = serve
# set this to True when you need to do testing
test = False
config = /usr/local/share/hg/my_email_notifications
template = Subject: Changes in repository: {desc|firstline|strip}\nFrom: {author}\n\ndetails:   {baseurl}/rev/{node|short}\nchangeset: {rev}:{node|short}\nuser:      {author}\ndate:      {date|date}\ndescription:\n{desc}\n
...


/usr/local/share/hg/my_email_notifications

[reposubs]
* = "Developer 1"<dev1@unamedstartup.com>, "Developer 2"<dev2@unamedstartup.com>

So we now want to use the same list when telling our developers that the build failed. Since buildbot configuration file is just python we can embed this parsing code directly in our configuration file:


emailcfg = open("/usr/local/share/hg/my_email_notifications")
emailcfg.readline()
import re
emailparser = re.compile("<(.+@.+)>")
emails = map(lambda s: emailparser.search(s).group(1),
             emailcfg.readline().split("=")[1].split(","))
emailcfg.close()

Granted, this isn't going to handle changes to the my_email_notications file very well, but you should get the idea. The important thing is that we aren't maintaining two lists of emails.

Sending email to an authenticating smtp server - Out of the box buildbot can only send email to an open SMTP server... I'm not sure who's dumb enough to leave their email server open like that, but we don't. So a little reading through the twisted libraries and I found that twisted kind-of supports ESMTP. I had to wrap this up in a buildbot notifier. Here's the code for that:


from buildbot.status.mail import MailNotifier
class ESMTPMailNotifier(MailNotifier):
  def __init__(self, username=None, password=None, port=25, *args, **kwargs):
    MailNotifier.__init__(self,*args,**kwargs)
    self._username = username
    self._password = password
    self._port = port
  def sendMessage(self, m, recipients):
        from twisted.internet.ssl import ClientContextFactory 
        from twisted.internet import reactor
        from twisted.mail.smtp import ESMTPSenderFactory
        from StringIO import StringIO
        from twisted.internet import defer
        s = m.as_string() 
        ds = []
        for recip in recipients:
           if not hasattr(m,'read'):
                # It's not a file
                m = StringIO(str(m))
           d = defer.Deferred()
           factory = ESMTPSenderFactory(self._username, self._password,
                                        self.fromaddr, recip, m, d,
                                        contextFactory=ClientContextFactory())
           reactor.connectTCP(self.relayhost, self._port, factory)
           ds.append(d)
        return defer.DeferredList(ds)
 
from buildbot.status import mail 
c['status'].append(ESMTPMailNotifier(username="yourusername",
                                     password="yourpassword",
                                     fromaddr="you@yourcompany.net",
                                     relayhost="smtp.gmail.com",
                                     mode="all",
                                     extraRecipients=emails,
                                     sendToInterestedUsers=False))

Granted, this isn't a complete guide to how to set up Mercurial and Buildbot, but I hope this will help you get over some of the minor hurdles I had to jump over.

Paranoid Versions

2007-05-21T16:09:00.000-07:00

As I mentioned in my previous post, we have an Item object that is both versioned and remains in the database after it's deleted. Fortunately, there's two ruby plugins that do just that: acts_as_versioned and acts_as_paranoid. Unfortunately, these plugins don't work together perfectly. Even more unfortunately, this fix doesn't work as it should because acts_as_versioned tries to version the deleted_at column as well, so here's the module we're using to combine them:

module ActiveRecord
 module Acts
  module Versioned
    module ClassMethods
      def acts_as_paranoid_versioned
        acts_as_paranoid
        acts_as_versioned    
        self.non_versioned_columns << 'deleted_at'
        # protect the versioned model
        self.versioned_class.class_eval do
          def self.delete_all(conditions = nil); return; end
        end
      end
    end
  end
 end
end

All Aboard!

2007-05-16T23:49:00.000-07:00

Today at 1pm I started writing our first ruby model object. It is the Item base class and of course it's non trivial as far as model objects go because we have lots of non-standard behavior for it. But I don't like to start with the easy stuff, especially when I'm just learning a new framework and all... At 11pm I had the following working:

Item model and schema complete with data migrations so that anyone can start with an empty database
CRUD support for Item
output as html and xml
Items are versioned. The complete edit history is stored in the database (each version is a complete record)
Items are "paranoid". This means that when they are deleted, they are not really deleted -- instead the deleted_at timestamp is set.
Concurrent editing detection, first submitter wins (error handling needed)
textile formatting support
listing of items using the xoxo microformat

What we don't have that we should:

Version viewing/comparing/reverting from the interface

I took a few breaks for dinner at whatnot. I'd say I spent a sum total of 7 hours "programming" but in actuality, it was about 1 hour of programming and 6 hours of looking up things on websites and doing research on how to use these rails plugins. This included fixing an incompatibility between two of the rails plugins I wanted to use (acts_as_versioned and acts_as_paranoid). it's hard to to much more with items until we make more models. My goal was to get enough underway that we could check in our initial project and set up continuous build, testing, and demo environments. And that, my friends, is why rails is neat. An experienced rails developer would have finished all this before leaving the office and then do something more productive with his/her evening ;-)

Getting Rolling

2007-05-15T16:00:00.000-07:00

As chief architect of a angel-funded web startup that shall remain nameless for now, I've decided to use Ruby on Rails as our site platform. My early experiences with rails have been extremely positive and have so far, made me very productive -- in most part due to the great work that has been done by the rails community. I'll post my experiences and any useful information I learn here, in an attempt to give back to the community.