Wiseheart Design

Radiant CMS: Add Child Menu

2010-07-19T15:54:44Z

Josh French and I have just committed a series of changes to Radiant that will change the way page children are created (you must be running on edge to see the changes). Instead of creating a child page immediately, the “Add Child” button will now present you with a list of page types. The goal of this change is to move the selection of page type to page creation. This change is essential for a number of other ideas that we are considering.

One benefit of this approach is that it allows a custom page type to change the way a page is initialized. For example, a page type could determine the initial values of fields or page parts.

In the future, this could also allow custom page types to easily make modifications to the page editing interface. So a Blog Post page type could add a dropdown to select the post author, or even list the comments on the post. Or an Event page type could add fields for the location and date.

We are looking for feedback on this change from the Radiant community. Add your thoughts in the comments below.

Compass with Serve and Rack

2010-06-07T18:36:15Z

I talked briefly about racking up your Serve projects in my previous article. But apart from the benefit of being able to deploy Serve on Passenger or Mongrel, why is Rack integration cool?

One benefit is that you get access to all kinds of middleware. Middleware is a software module that extends your server or web application with additional functionality. It’s called middleware because it sits between your application and the web server software. When a request for a file or resource comes into the server it first travels through each layer of middleware before reaching your application. Your application then sends a response back which again travels each layer of middleware before being served up to the user. As the request and response travel through each layer of middleware, the middleware can make changes to or even serve up something totally different. This is useful for adding features like logging, custom error handling, or gzip compression.

I my original article I showed you how to use Rack::ShowStatus and Rack::ShowExceptions to get handy error messages for your project. Today, I’d like to show you how to add Compass integration.

Never heard of Compass? Compass is a fancy new CSS framework built on Sass and it’s awesome. Among other things it provides a number of handy CSS3 modules that allow you to easily use a number of advanced CSS features. Without Compass and Sass this kind of stuff becomes pretty labor intensive to write.

Now Serve comes with built in support for serving Sass files, but it doesn’t know anything about Compass. To use Serve with Compass you will need to add the following lines to your config.ru file:

require 'sass/plugin/rack'
require 'compass'

Compass.add_project_configuration(root + '/compass.config')
Compass.configure_sass_plugin!
use Sass::Plugin::Rack    # Compile Sass on the fly

The first two lines are necessary so that the Sass Rack middleware is installed and the Compass framework is loaded. The next two lines tell Compass where your configuration file is located (in this case I’ve put it in the project root) and configure Sass using the configuration values stored there. The last line loads the Sass plugin as middleware.

Your compass.config should look something like this:

http_path       = "/"
css_dir         = "public/stylesheets"
sass_dir        = "public/stylesheets/sass"
images_dir      = "images"
javascripts_dir = "javascripts"
relative_assets = false

Your actual values will vary depending on how you are using Compass, but the key variables for the purposes of this tutorial are css_dir and sass_dir. In this case I’ve chosen to have the plugin generate my CSS in the public/stylesheets directory and store my Sass (much like Rails does) in the public/stylesheets/sass directory.

If you’ve separated your dynamic and static assets into the views and public directories (like I suggested in my previous article) you will notice that I’ve chosen to put my Sass and CSS in the directory for static assets (public). This is because the Sass plugin is designed to generate your CSS when the first request is made to your Serve application. Generated files are nice in production environments because they can be served directly by the Web server instead of by your application. This is in contrast to the way that Sass files are normally used with a Serve project. Normally, you would put your Sass files in views/stylesheets and they would be processed by the Serve Rack adapter on each request.

Here’s a Gist of the source code for this entire tutorial along with a couple of other goodies. Enjoy!

Hat tip to Chris Eppstein for his help with this.

Racking Up A Serve Project On Phusion Passenger

2010-05-26T18:34:01Z

Serve is a rapid prototyping framework that I have been building for Web applications. It is specifically designed to make it easy to prototype Rails applications, but it can easily be used to prototype applications for any other framework. I’ve talked about the benefits of using Serve before, so I won’t cover that here, but if you are interested in learning more about Serve read, Serve: A Rapid Prototyping Framework for Designers.

Yesterday I released Serve 0.11.2 which adds built-in support for Rack. Rack allows a Ruby application to be deployed in any number of environments (Mongrel, CGI, Passenger, etc.). The good news for Serve users is that you can now deploy Serve projects much like any other Rails application.

Today, I’d like to talk about setting up your Serve project for deployment on Passenger (a.k.a. mod_rails). Passenger is an Apache/Nginx module that allows you easily deploy Rack-based applications in production environments. The benefit for Serve users is that with Rack and Passenger, Serve is much easier to deploy on a modern Web server. This will allow you to put your prototype project on a Web server that is easily accessible by your clients. Or, if you are on a Mac and you prefer to stay away from the command line, you can use Passenger and the Passenger Preference Pane to handle your Serve projects.

I’m not going to cover the setting up Passenger in this tutorial. That is already well documented on the Passenger web site. Instead I’m going to talk about how to convert your Serve project so that it works well with Passenger.

Passenger requires that Rack applications have a certain structure for performance and security reasons.

The Basics

We learn from the Passenger User Guide that Rack applications must have three things:

A tmp directory
A public directory
A config.ru file

The tmp directory is used by Passenger for the restart.txt file. You can notify Passenger that your Rack application should be restarted by updating the Last-Modified timestamp on the restart.txt file. The public directory is needed for static assets like images, javascripts, and stylesheets — in this case anything that is not processed by Serve directly. The config.ru file is a Ruby-based configuration file for Rack.

I’m going to suggest that we add one more directory:

A views directory

In the views directory we’ll put all of the ERB, HAML, and special Serve files that are necessary for the prototype. Anything that does not need to be processed by Serve should go in the public directory. This includes all images, javascripts, etc. CSS files should also go in the public directory, but SASS or SCSS files should go in the views directory.

To create these directories and files, you can execute the following commands from the command line in the root of your project:

$ mkdir tmp
$ touch tmp/restart.txt
$ mkdir public
$ mkdir views
$ touch config.ru

Now move all of your existing Serve files into the views directory (ERB, HAML, SASS, Redirects, etc…). Be sure to preserve the existing directory structure. If you have a view_helpers.rb file that should also go in the root of views directory.

Once that is complete, move images, javascripts, and other static assets into the public directory. Again, be sure to preserve the existing directory structure. (If a file was in images/icons it should now be in public/images/icons.)

Rack Configuration

Now open up config.ru in your favorite text editor and insert the following code:

gem 'activesupport', '2.3.5' # version required by Serve
gem 'serve'

require 'serve'
require 'serve/rack'

# Middleware
use Rack::ShowStatus      # Nice looking 404s and other messages
use Rack::ShowExceptions  # Nice looking errors

# The project root directory
root = File.dirname(__FILE__)

# Rack Application
if ENV['SERVER_SOFTWARE'] =~ /passenger/i
  # Passenger only needs the adapter
  run Serve::RackAdapter.new(root + '/views')
else
  # We use Rack::Cascade and Rack::Directory on other platforms to
  # handle static assets
  run Rack::Cascade.new([
    Serve::RackAdapter.new(root + '/views'),
    Rack::Directory.new(root + '/public')
  ])
end

Advanced users may want to modify this a bit to include other middleware or applications, but this configuration should suffice for the basic Serve project. I’ve included the Rack::ShowStatus and Rack::ShowExceptions middleware to provide pretty 404s, messages, and error handling. To turn off either of these features just comment out the appropriate line. Rack::Cascade and Rack::Directory are used to handle files in the public directory if Passenger is not used. This is useful if you are using Rack from the command line via the rackup command.

So that’s it! Everything you need to know to rackup a Serve project on Passenger.

Full-Stack iPhone Development

2010-05-15T22:16:03Z

Last week I helped my friends at Terralien launch fullstackiphone.com. Full-Stack iPhone is a long-standing service from Terralien under a new name. Terralien has been doing iPhone interfaces for Web applications for some time now so we thought it would be appropriate to begin promoting the service in a more public way.

Terralien can deliver a lot of value to potential clients. Nathaniel Talbott has done a great job assembling a hand-picked team of top-notch developers and designers that are passionate about building successful businesses. If you are looking for a team that can build an iPhone application with an incredible Web-based backend, be sure to check us out.

Radiant CMS Layout Tricks

2010-04-30T18:02:11Z

Page layouts are one of the most powerful features of Radiant. Layouts allow you to encapsulate much of the common HTML of a website into a template of sorts that is filled in with the information unique to each page.

Today, I’d like to share a couple of tips and tricks for making the best use of this powerful feature. These aren’t hard and fast rules, just a couple of the best practices that I’ve picked up over the years as I’ve worked with Radiant.

Use One Layout If Possible

Radiant allows you to create as many layouts as you want for your website. At first glance you may be tempted to create multiple layouts for your site that have a one-to-one relationship with the type of page you are creating. For instance, you may want to have a layout for your home page, one for your portfolio, one for your blog, etc. Resist this urge if you can. Depending on how your HTML and CSS are written, you may be able to get away with just one layout — even if the page that you are working on has a vastly different look and feel. The trick is to use conditional tags to switch parts of the layout on and off depending on the page.

Why is this helpful? It keeps all of the common code in one place and allows you to keep things DRY. It also minimizes user error and ensures that each page has the proper design, because a content editor never has to worry about selecting the proper layout. You set the layout once on the root page, and all the other pages inherit it.

Use Conditional Tags To Build Flexible Layouts

Radiant provides a number of conditional tags that make it easy to build smart layouts. Use them.

The most commonly used is tag is probably if_url (and its sister unless_url). This tag allows you to test the URL of the current page and show or hide content based on the condition. You can do an exact match on the URL by using the equals attribute, but I mostly use the matches attribute because it allows me to use regular expressions to match an array of URLs.

For instance, on WiseheartDesign.com I insert code for comments using the if_url tag with the matches attribute like this:

<r:if_url matches="^/articles/.+">
...code to display comments here...
</r:if_url>

If you are not familiar with regular expressions, this may look a little convoluted, but it is really quite simple. It basically reads, if the URL starts with “/articles/” and is followed by at least one character, then insert the following code. That last part is necessary so that the articles index page (which has the URL of “/articles/”), is not matched by the expression.

As you can see, the if_url tag is quite powerful for adding conditions to your layouts, but it has one significant weakness. Since it relies on the URL of the page, if you change the URL scheme for your website, you will need to remember to come back and update your layout. If your layouts are riddled with calls to if_url this may prove to be a bit of a headache.

Another tag that may be useful here is the if_content tag. You can use the if_content tag to test if a page has certain parts (or the unless_content tag to test that it does not). With clever naming of page parts you can get a lot of mileage out of this simple tag.

For instance, suppose you have two basic page designs for your web site. One is a standard two-column design with content and sidebar. Another is a simple single column design with no sidebar. By testing for the existence of the sidebar, you can actually handle both cases with a single layout:

<r:if_content part="sidebar">
  <div id="content"><r:content /></div>
  <div id="sidebar"><r:content part="sidebar" /></div>
</r:if_content>
<r:unless_content part="sidebar">
  <div id="content" class="no_sidebar"><r:content /></div>
</r:unless_content>

The code above checks for the existence of the “sidebar” part. If it exists it renders two divs, one for the content and one for the sidebar. If the “sidebar” part does not exist, only the content div is rendered – this time with the “no_sidebar” class so that the single column version can be styled differently.

With a little a little imagination, I’m sure that you can see how the same technique can be used to achieve one-column, two-column, and three-column designs – all within the context of a single Radiant layout.

Use Snippets To Simplify Complex Layouts

Radiant snippets are designed to make it easy to share share common code between layouts and/or pages, but they are also useful for other purposes. The more complicated your layouts become the more you will find it makes sense to extract meaningful parts into Radiant snippets.

One purpose is to isolate complex or verbose code. For instance, you may want to put your Google Analytics code in a snippet. You will probably only enter this code once during the lifetime of your site, and there is no reason that it should clutter up your layout code.

Another purpose is to make content more accessible. I often put my navigation code in a snippet because as I update a site it is easier to maintain in isolation.

ToggleJS: Unobtrusively Show and Hide Elements With Effects

2010-04-08T21:03:08Z

Today I would like to announce the release of ToggleJS – a LowPro and Prototype-based solution for unobtrusively toggling elements with effects. ToggleJS makes it easy to create an advanced section on a form that slides out when the “Advanced” link is clicked, or to show more options when a certain check box is checked. And it does all of this with beautiful effects (complements of script.aculo.us).

View the online demo.

The way ToggleJS works is you select an element to be the “Trigger” element that will cause another another element revealed. You can chose a link, a checkbox, a select box, or a group of radio buttons as your trigger. You then add a rel attribute to the element that identifies an ID or group of IDs for the elements that should be revealed.

Using a Link as a Trigger

For example, the following code will create an advanced section that will only be revealed when the “Advanced” link is clicked:

<p><a class="toggle" href="#advanced" rel="toggle[advanced]">Advanced</a></p>
<div id="advanced">
... advanced options here ...
</div>

Note that I’ve set the rel attribute to “toggle[advanced]”. This is a special syntax that identifies the list of IDs that should be toggled when the trigger is clicked. (IDs appear between the brackets. To toggle multiple IDs separate them with commas.) In this case we are telling ToggleJS that the “Advanced” link is a trigger for the “advanced” div. By convention, toggle triggers are also identified with the “toggle” class (this is configurable). Also note that ToggleJS will take care of hiding the “advanced” div when the page loads.

A Checkbox Trigger

To create a checkbox toggle trigger, the syntax is almost identical:

<p>
  <input type="checkbox" class="toggle" name="remind" id="remind" value="1" rel="toggle[remind_on]" />
  <label for="remind">Remind me</label>
  <span id="remind_on">on <input type="text" name="date" /></span>
</p>

In the example above, if the user checks the “Remind me” checkbox a date field will appear where they can enter a date for the reminder. ToggleJS is smart enough to recognize whether the checkbox is checked on page load and will hide or show the related element as needed.

Selects and Options

The code necessary to make this work with a select box is a little different. Instead of setting the rel attribute on the select box, you should set it on each of the options:

<select class="toggle">
  <option>- none -</option>
  <option value="1" rel="toggle[one]">One</option>
  <option value="2" rel="toggle[two]">Two</option>
  <option value="1,2" rel="toggle[one,two]">One and Two</option>
</select>

<div id="one">1</div>
<div id="two">2</div>

In this example, the select box is used to toggle the visibility of divs “one” and “two”, based on selection. Note that the last option, “One and Two”, displays both divs by specifying both IDs in the rel attribute.

Radio Buttons

The fourth and final way that you can use ToggleJS, is with a group of radio buttons. The code is actually strikingly similar to the code used for the select boxes:

<div class="radio_group toggle">
  <p>
    <input type="radio" name="numbers" id="numbers_none"/>
    <label for="numbers_none">None</label>
  </p>
  <p>
    <input type="radio" name="numbers" id="numbers_one" value="1" rel="toggle[one]" />
    <label for="numbers_one">One</label>
  </p>
  <p>
    <input type="radio" name="numbers" id="numbers_two" value="2" rel="toggle[two]" />
    <label for="numbers_two">Two</label>
  </p>
  <p>
    <input type="radio" name="numbers" id="numbers_three" value="1,2" rel="toggle[one,two]" />
    <label for="numbers_three">One and Two</label>
  </p>
</div>

<div id="one">1</div>
<div id="two">2</div>

The Wiring

Apart from the standard script tags for LowPro and Prototype, you will also need to wire in the appropriate LowPro behaviors. If you are building a Rails application, I’d recommend that you put this in “application.js”:

Event.addBehavior({
  'a.toggle': Toggle.LinkBehavior(),
  'input[type=checkbox].toggle': Toggle.CheckboxBehavior(),
  'div.radio_group.toggle': Toggle.RadioGroupBehavior(),
  'select.toggle': Toggle.SelectBehavior()
});

What this code does is associate the LowPro behaviors with the correct elements based on CSS selectors. You can customize the rules above if you want to use different class names or if you would like to tweak the behaviors with custom options.

For example, you can create an inverted toggle checbox by adding the following line to the Event.addBehavior call:

'a.inverted_toggle': Toggle.LinkBehavior({inverted: true}),

An inverted toggle link would hide the associated div the first time it was clicked instead of showing it.

You can also customize the effect used and handle custom before and after toggle events for the Toggle.LinkBehavior. For full details on the different options that you can pass the LowPro behaviors, consult the inline documentation.

There are also two configuration variables that can be used to customize the default settings for all toggle behaviors:

Toggle.DefaultEffect = 'appear';    # a string; the default is 'slide'
Toggle.DefaultEffectDuration = 0.5; # in seconds; the default is 0.25

Conclusion

ToggleJS removes the need to write custom code to toggle the visibility of other elements for many of the common use cases. And it does all of this in a clean unobtrusive way. You can learn more about ToggleJS, over at the GitHub project or view the online demo here.

Before closing, I’d like to thank the kind folks at MemberHub who sponsored the initial development of ToggleJS and have allowed me to release it as open source. MemberHub is a group communications platform for churches and other organizations.

Proposal: Generic Conditionals for Radiant CMS

2010-03-11T18:12:32Z

Over the years we have had many requests on the Radiant CMS Mailing List to add better support for conditional tags of some kind. Right now we have an array of tags for making conditional statements that are included in the standard distribution. The following is an incomplete list:

<r:if_children>           <r:unless_children>
<r:if_content>            <r:unless_content>
<r:if_url>                <r:unless_url>
<r:if_ancestor_or_self>   <r:unless_ancestor_or_self>
<r:if_self>               <r:unless_self>
<r:if_parent>             <r:unless_parent>
<r:if_dev>                <r:unless_dev>

When Radiant was first released, we only had if_content and the rest were added as the need arose. We have considered adding generic support for conditionals, but every proposal thus far seems to require additional syntax of some kind. Chris Parish took a stab at adding generic support for conditionals at one point. His extension allows a user to type expressions like:

<r:if cond="breadcrumb matches /your regexp/">

or even,

<r:if cond="parts includes-any ['body', 'other part']">

To date we have avoided adding something like this to the core because of quibbles over the precise syntax. We also value the rigidity that the Radius attribute syntax provides. To be effective with tags in Radiant, a designer only has to understand tags, attributes, and nesting. Adding another strange comparison syntax on top of this seems needlessly complex.

Towards A Generic Syntax for Conditionals

While thinking about some of this today, it occurred to me that there might be a reasonable compromise that preserves HTML-like, attribute-oriented syntax while allowing a high degree of flexibility.

So without further ado, I would like to propose that we add generic support for conditionals to Radiant with the following basic syntax:

<r:if property="name" matches="regexp">

or unless,

<r:unless property="name" matches="regexp">

Above, the property attribute indicates a property on a page that a conditional operates on. (I will talk about properties in detail in a minute.) The matches attribute indicates that the property should match the given regular expression if the tag is going to expand. Additional attributes would include equals, nequals (for not equals), and nmatches (for not matches).

Now what exactly are properties? Properties would be a new first class concept in Radiant. There would be properties for all of the default page attributes (title, slug, url, etc.), but you would also be able to define your own properties with a class method on Page. So subclasses of Page could define their own properties or extensions could add properties to Page to declare properties that are accessible to all pages.

To declare a property you would define it within the class definition of a page like this:

property 'name'

By default, with no additional parameters this would assume that the property ‘name’ is a reference to the ActiveRecord attribute ‘name’. But you could also pass a block to calculate properties on the fly:

# Under the covers, properties are just augmented method
# declarations so you still have access to other methods on
# the page, like "url" below.
property 'full_url' do
  'http://wiseheartdesign.com' + url
end

This would allow you to create constructs like:

property 'author.name' do
  author.name
end

Of course, some additional sugar would make this much easier:

property 'author', :method => 'author', :attributes => [:name, :email, :website]

This would declare three properties, ‘author.name’, ‘author.email’, and ‘author.website’.

Once properties are declared you could access them within tag definitions like this:

# A basic implementation of the if tag
tag 'if' do |tag|
  page = tag.locals.page
  property = tag.attr['property']
  value = page.properties[property]
  equals = tag.attr['equals']
  tag.expand if value == equals
end

The bracket syntax would give tag authors easy access to properties on a page and make properties a first class concept in Radiant that extension authors can take to another level.

A Generic Case Statement

I would also suggest that there is room for a third type of conditional statement. We already have if and unless, why not case?

<r:case property="author.name">
  <r:when equals="John">Lead Designer</r:when>
  <r:when equals="Sean">Lead Developer</r:when>
  <r:else>Core Developer</r:else>
</r:case>

And yes did you see that? case, when, and else allow us to avoid if, then, and else – another one of the commonly suggested features. We can keep it clean with single tags for if and unless, and allow case, when, and else for complex conditionals.

Suggestions, Addendums, Thoughts?

So there you have it. My proposal for adding a generic syntax for Radiant conditionals to the standard tag library. Any thoughts or comments from the Radiant community? Is this a can of worms or a powerful, much needed addition? Put your thoughts in the comments below.

All Designers Are Not Equal: How to Hire the Right Designer

2010-03-02T05:10:45Z

With all the buzz on the Web today about the necessity of good design for success, there has been very little discussion about matching the right designer to the right project. The way the word “designer” is used today is a bit ambiguous. It can refer to any one of a broad range of professions. From usability experts, to illustrators, to HTML and CSS specialists, to typographers, to user experience people.

To make matters worse, this confusion about the word “designer” and what it actually means often leads to hiring decisions that set projects up for failure. Hiring the wrong designer for your project can be akin to asking the wrong type of doctor operate on you. You would never ask a foot doctor to do brain surgery. Or, an eye doctor to remove your appendix. But the same kind of thing happens all the time in the design world and nobody blinks.

The truth is there are many different kinds of designers, and each is good at different things. Yes, some designers are generalists and their value lies in their ability to deliver consistently across multiple disciplines, but generalists rarely deliver the highest quality work.

So how do you find the right designer for your project? Especially if you don’t know a lot about design? Where do you start?

Recognize Different Designers Work Better In Different Mediums

One of the rookie mistakes you want to avoid when choosing a designer for your website is picking a print designer to do a Web designer’s job. There is a huge difference in the skills necessary to pull off a successful website design and the skills necessary to operate well in print. And the opposite is also true!

Since I primarily do Web design for a living I probably wouldn’t be the best person to design an album cover for your new CD or to create a brochure for your business. Could I do it for you? Absolutely! But again, I wouldn’t be the best choice. There are other people who can do this kind of work in less time and with better results than I can currently offer.

Why is this true? Because the medium that you ask an artist to operate in is just as important as the artist you choose. What do I mean by medium? The medium is the method or materials through which a work of art is presented. As this applies to design we generally use terms like print, web, or motion graphics (Flash).

Why is the medium so important? Because the medium that a designer is working in makes a huge difference in the quality of work that he is able to produce. You wouldn’t ask a sculptor to design a skyscraper, or painter to compose a symphony. All of these people can create beautiful things if you put them in their element, but get it wrong and you won’t get good results.

Recognize Designers Have Different Strengths

Along the same lines, the other mistake you want to avoid is selecting a designer that does not have a strong skillset for the types of things that will be necessary to complete your project successfully. Some designers are really good at illustration, use of photos, or color. Some designers are great at branding and logo design. Some at usability or total user experience (UX). Some are amazing at marketing and message.

On the same token, while a designer may be really good at one thing (say illustration), he or she may be terrible at another (say usability).

Why is this? A lot of it is about experience. Some of it, natural gifting. But a huge part of it is related to the designer’s personal passions. Designers tend to do well at the things they enjoy. Or, to enjoy the things that they do well. A good question to ask a potential designer is does your project fall into the category of the things that he or she enjoys? If it does you will probably find them quite knowledgeable about the things that are necessary for your project to be a success.

The last thing you want is to end up paying someone a lot of money to do something that they are not good at. Consider a potential designer’s strengths and weaknesses when matching them up with your project.

Recognize Some Designers Have Different Appeal

Another thing to consider in your search for the right designer for your project is the appeal that their personal style has to your target audience. Some designers are good at tailoring their style to the audience, but others are not. This isn’t necessarily a bad thing. Many designers are very successful at producing a certain look that their clients value. As you are evaluating a designer consider the diversity of his portfolio, or, conversely, the consistency. Is their personal style something that would appeal to your target audience? If the answer is no, move on.

Other Things To Consider

Of course, there are many other things to consider as you look to hire a designer for your own project. How well do they communicate? Do they connect with you personally? How responsible and honest are they? But the points listed above should give you a framework for considering the value that they may be able to deliver in terms of design.

If you can afford it you may want to engage multiple designers. One to work on each of the individual components of the project. For example you could engage one designer to help you develop a good logo and brand for your company (or project), another to work on the marketing and emotional appeal of your website, and another to work on the user experience.

If money is tight, you may want to engage a designer that is more of a generalist rather than a specialist. After all, there are times when it’s just more economical to go to a family doctor instead of a specialist. But know the difference and hire accordingly.

And don’t forget to ask probing questions like the ones mentioned in this article. It is your money, business, and reputation that is on the line.

Brandon Mathis: Fancy Avatars

2010-02-24T20:23:40Z

My good friend and fellow designer Brandon Mathis has put together a wonderful little default avatar package that is available for free on his website.

Brandon and I had the good fortune of being able to work together on MemberHub.com back in 2008. MemberHub’s design needs were growing beyond what I could handle at the time so we needed someone to help us power through many of the features we were working on. An all around great guy and extremely competent designer, Brandon was just the sort of person we were looking for to assist us.

So it was while we were in the midst of things working on MemberHub that Brandon took the time to improve the MemberHub default avatar. The default avatar is the picture that every user gets to represent them if they haven’t uploaded a photo on MemberHub.com. At the time we were using a lame question mark avatar reminiscent of the old Facebook default avatar. We wanted to make the avatar a little more personal. As we looked around for a good free option we discovered to our chagrin that there really weren’t any. We both thought this was a shame, so Brandon spent his own time to create a default avatar set that we could use on MemberHub.com that he could also release for anyone to use.

The result was Fancy Avatars. A default avatar set that can be easily customized to suit your needs. The set includes male and female avatars, and the orignal vector source image (a Fireworks PNG). Fancy Avatars is licensed under a Creative Commons Attribution license so it is free to use on both commercial and personal projects.

Check out the demo page or download the set now.

Open Source Design Help Needed!

2010-02-17T22:51:39Z

I don’t know if this is even possible, but I wanted to put it out there to at least stimulate some discussion and perhaps even jolt some of you to action. I’m issuing a public call for designers interested in contributing to Radiant CMS. Effective immediately.

No, I’m not looking for resumes, portfolios, or recommendations. I’m looking for people who are good at what they do and get it done. Opinionated, kind-hearted folk who communicate well and can handle criticism. If that sounds like you, here’s how you can get involved…

Fork the Radiant Prototype Project on GitHub

We’ve created a prototype project on GitHub for Radiant that makes it easy to jump in and contribute. To get started, fork the project on GitHub, clone it onto your local box and use Serve to get it running so that you can start making changes.

New to Git or GitHub? Check out the GitHub learning site and help system.

New to Serve? Read the introductory article and watch the screencast at the end. The great part about using Serve for the prototype is that it allows us to focus on just the HTML, CSS, and Javascript. Once we get things worked out in the prototype they can easily be ported over into the application.

Pick An Issue

There are a number of issues related to the interface on the GitHub issue tracker, if you are looking for something simple start there. There’s not currently a lot of design related issues, but here’s the low hanging fruit:

There are also a number of unfinished things in the prototype that are just waiting for someone to polish them off.

Or, Work On An Extension

Maybe you aren’t interested in working on one of the core features in Radiant, but you would like to work on a Radiant extension. If so this is great! There are over 190 Radiant extensions in the extension registry that add support for all kinds of things. Things ranging from “version” “control” to “asset” “management”. Most of the extensions have been written for 0.8 and below. We are just getting ready to release 0.9 and the lack of polish on some of the extensions is really starting to show. We need folks who are good at design that can help extension developers bring their extensions up to snuff.

To work on an extension, you can either pull the HTML from the extension into your fork of the Radiant prototype and work on it there, or work on the extension inside of an existing Radiant project. The second option takes a bit of know how, but getting an extension developer to give you a hand with the setup process shouldn’t be too difficult. I’ll talk a little more about getting help at the end of this article.

Or, Make Something New

To date almost all of the work on the Radiant interface has been done by myself and a couple of the of the Radiant developers. I am very interested in hearing other designers ideas about how the interface could be improved and made more user friendly. In particular, I feel like we have a ways to go before we are competitive with products like Wordpress on the UI level. Right now the interface works pretty well for power users, but we need to do a better job reaching out to first time users. More inline help in the interface is important, but we also need to build a real help system. I’m visualizing something that would open in a separate window.

I’m also interested in any thoughts people have on asset management. I’m a big fan of the approach that page attachments takes, but I also see room for the way papperclipped has implemented the Mephisto-style asset bucket approach. Ultimately, I want something that is a bit of a combination of the two. And I want it to work well even if you don’t have support for image thumbnailing installed on your server. This means having alternate views without thumbnails. I would love for someone to take a stab at merging all of these concepts on the UI level. It needs to be slick in every way.

If you are feeling adventurous, you are also welcome to work on something completely new. Redesign an aspect of the interface or even the whole product. Fresh ideas are important if Radiant is going to continue moving forward. Who knows. You might just find yourself at the center of the next major release.

Or, Work On The Marketing Side

I’ve got some ideas for updating the Radiant site itself to be more competitive with with other sites. If you are interested in helping here, contact me directly. The original design for the site is a couple of years old now and it could use an serious update.

Not Ready To Work In The Prototype?

Maybe jumping right into the HTML is not your thing. I hear ya. I often like to work out my ideas in a graphics editor like Fireworks or Photoshop before getting too far. If that is your thing, check out the Radiant mockups project on GitHub. You’ll find the original source images for much of the Radiant interface in there. You heard me right, the original source images! They are in Fireworks PNG format, which means that if you open them in Fireworks you will be able to edit them in all of their vector goodness.

If you are savvy enough, fork the mockups project on GitHub and add your new mockups to the fork. GitHub is a great way to share your work and it will make it easier for people to view and use what you are working on.

If working with Git and GitHub is too complicated for you, you can still download the original source images. On GitHub, browse over to the Radiant mockups project, then open the page for the graphic that you want to use, and click “raw” (in the gray bar underneath the filename) to download the image in its original format.

Getting Your Changes Approved

OK, so we’ve covered a lot of the technical challenges on contributing to the design effort on Radiant, but I’d like to address one of the most important aspects this whole process: getting your changes approved and merged into core.

This is a tricky one to answer.

On the one hand Radiant can desperately use the help of other designers. On the other, there is no question that Radiant has benefited from the opinionated and sometimes heavy handed oversight of one designer (namely me). I don’t plan on relinquishing my role of “Lead Designer” on the project any time soon, but it’s also becoming clear that I can’t do everything that needs to be done.

So here are some tips for working with me to get your changes approved:

E-mail the developer list. Before you get too far on a feature, send an e-mail to the Radiant Developers list and look for feedback from either Sean Cribbs or me. (Sean is the lead developer of Radiant.)
Blog about what you are doing. Help us understand your reasons for wanting to change the Radiant interface. Outline the changes you have made or what you would like to do. And don’t forget to tell us about your article on the developer mailing list.
Post screenshots. I am a very visual person. Posting screenshots will give me a much better idea of what you are working on. Who knows, I may even give you a return volley of screenshots for how I would suggest that a given feature should be implemented.
Work with the existing design. If your design departs from the current look and feel it will be very hard for me to sign off on what you have done, no matter how awesome the feature is. I don’t want to discourage people from seeking to address problems with the current look or feel, but significant departures greatly increase the chances that your changes will not be approved.
Persevere. If I don’t like what you have done on the first or second pass, keep at it. Find a way to work with me. I know I’m an ornery fellow, but find a way to work with me. I’ll do my best to do the same on my end.

Also, don’t forget that even if your changes are not merged into core, someone else within the Radiant community may like what you are doing enough to make an extension out of it. There are plenty of extensions that are extremely valuable that will never be part of the core distribution. This is part of Radiant’s appeal. It is not the CMS that does everything out of the box. It is the simple CMS with a solid core.

A Word On Open Source Design

Open source projects have a reputation for being poorly designed, but I don’t believe it has to be this way. Developers have been working on the problem of “collaboration with anyone” for a long while now and have proven that it can work. As designers I think we are behind the curve a little, but I see no reason why we can’t make it work as well. All it will take is a little commitment, humility from everyone involved, and a lot of hard work.

So what about you? Do you think this can work for Radiant? Are you willing to give it a try?

My Current Toolset

2010-02-20T04:46:38Z

I thought I would give my readers a little information on my current toolset. For the sake of the article, I’d like for you to pretend that we have just started working out of the same office together and you and I are comparing notes about our current tools and processes. Since we can’t actually do this in person I want to encourage you to share some of the tools that you are using in the comments below (or even better, link to your own blog post on the same topic). The tools that we each use are unique and say a lot about the kind of work that we do and what we value.

So without further ado, here is my list:

Index Cards – I’m a big fan of keeping things as simple as possible. I like to have a stack of index cards handy to jot things down on. I like both the 3×5 and 4×6 varieties. Lined on one side, blank on the other, and preferably college rule. I like to use index cards as story cards when planning releases, to write down ideas for new blog posts (one per card), to keep track of to-do items, and to doodle on ideas for projects. Yes, in my opinion, the index card is the single most valuable piece of writing material for the modern man. Infinitely versatile and so compact. Even better than those moleskin notebooks that everyone carries around, but hardly anyone uses.

Paper – I don’t often use paper other than index cards (do those qualify?), but when I do, I use plain 8½×11 printer paper. For paper prototyping I like to print out sheets of paper with a box in the center that is useful for keeping illustrations of the web app I’m working on constrained. I use the margins to jot down implementation details. Here’s the document that I use.

Pencils and Sharpies – I am a longtime user of #2 BIC mechanical pencils. They are super cheap, write extremely well, and never need sharpening. I like them better than pens because they aren’t permanent (so they are better for sketching). If only the clip didn’t break off so easily. (Though I will admit to a certain amount of satisfaction every time I break a clip off.) I’m also a fan of the Sharpie. It is a great tool to leverage when you want to avoid getting too detailed in your sketches. 37signals has talked about this before and I agree. Sharpies are awesome.

A Whiteboard – I don’t always have a whiteboard handy, but when I am working with a client this is an awesome way to capture ideas, map out complex flow diagrams, and discuss interface changes.

My Computer – Of course, no description of the physical things would be complete without talking about my computer. As you may have guessed, I have a MacBook Pro. I recently exchanged my 15″ for a fully loaded 17″. I decided to max out the memory and the hard drive this time and I am loving it. I can finally run a graphics program and VMware without the system coming to a crawl. I also have room for all my movies, TV shows, and music. It’s the perfect work/personal machine. During the day (if I’m not out galavanting about), I like to plug into my 22″ Apple display (it’s not one of the newer ones, but it is still pretty classy). I am also currently using a Microsoft Natural Keyboard and the Apple Magic Mouse (which may be the first mouse Apple has ever created that is worthwhile). I also have a pair of JBL speakers (no subwoofer to kick), which are compact and perfect for easy listening during the day.

Fireworks – My graphics editor of choice is Adobe Fireworks (formerly Macromedia Fireworks). Fireworks is quite simply the best website graphics tool on the market today (in my opinion). I know that there are people who prefer Photoshop, but I’m of the opinion that most of them aren’t UX people. They either do a lot of extremely high end design with lots of textures and polish, or more likely they also do print design and are using the tool that they are comfortable with. For my needs Fireworks is more than sufficient. It successfully combines vector and pixel-based editing into one program allowing you to create pixel perfect designs with far less effort than it takes in Photoshop. Oh, and did I mention that it’s fast? It makes Photoshop look like a 4-ton behemoth. The one caveat is that Adobe and Macromedia have always been a little hit and miss on the releases. I’m currently using CS3 as it seems to render fonts better.

Illustrator – I don’t do a lot in Adobe Illustrator, but whenever I’m working on a logo or a complicated piece of vector art I like to do it in Illustrator. I’m still not very efficient with it as I’m mostly a Fireworks man, but Illustrator offers a fantastic array of tools for doing complex stuff with vector art. On Windows, I was an Xara man. Xara is an amazing tool. It beats Illustrator hands down in terms of usability and can create photo realistic vector art. Unfortunately, they have yet to get it going on the Mac. Somebody please help them port it to the Mac. It’s simply awesome.

Photoshop – I rarely use Adobe Photoshop, but when I do it’s usually for what it is good at: photo editing. The layer-based approach is simply awesome for this. Most of the time the built-in bitmap editing tools in Fireworks are sufficient for me, but when they are not I drop back and punt. Photoshop rocks for photo editing, but please! Don’t use it for anything else!!

Textmate – Textmate is my comfortable everyday editor. I like it because it provides pretty good support for whatever language I am working in. And did I mention that it is simply gorgeous? I love its project-based approach and typically launch it in a directory with the `mate` command.

Vim – I’m a Vim guy on the console or server. I’d probably use it instead of Textmate as my everyday editor except for the fact that I can’t get away from Textmate’s beautiful project drawer. Vim is great because it’s installed practically everywhere. This means that whenever I SSH into a server I can edit files in the comfort of a familiar editor. I don’t know a lot of Vim commands, but I know enough to get around.

Tweetie – Yup. I love Tweetie. When it comes to Twitter, there isn’t a better client on the Mac. And it is simply beautiful. The interface is unique, but very functional. I love the fact that it allows me to easily manage multiple Twitter accounts. This lets me keep @johnwlong, @rcreative, and @radiantcms in sync. Oh, and they also have a similarly awesome product for the iPhone.

Gmail – I’m currently using Gmail as my main e-mail client. It’s taken me a while to warm up to it, but without faster support for IMAP this seems to be the best way to view my mail. I use it with Google Notifier for the Mac to keep me informed about unread messages. I also use Gmail for chat these days and like the fact that I can close it all down if I need to get work done.

Skype – Skype seems to be the best way to screenshare at the moment. It is much more stable than iChat, making it the ideal screensharing tool when I’m trying to demo things for clients. The only thing it’s not good for is yielding control of your screen to another user (which is extremely handy when pairing remotely). For that, I do resort to iChat, though it seems to crash every once in a while.

Serve – I’ve built a couple of tools that help streamline my workflow, but none is more useful than Serve. Serve is a rapid prototyping framework for Rails applications. It makes it easy for me to throw a bunch of HAML, SASS, and images in a directory and render the content. Serve allows me to use concepts similar to Rails partials and layouts to dry up my HTML mockups of the application, which allows me to quickly build a prototype of any web application. Think of it as Rails without the backend – just the views directory. Serve is simply awesome. I use it almost every day.

Shell Scripts – I’ve written a couple of custom shell scripts that help me fly around the command prompt. I’m not sure that my scripts are generally useful to anyone outside of myself, because you would have to structure your projects exactly like I do to get the same benefit, but I highly recommend that you take the time to write a couple of commands to make it easy to do your common tasks on the command line. Shell scripting is a bit convoluted, but with a little effort you can save yourself hundreds of hours of typing over the course of your career.

So there you have it. My list of tools and the reasons I use them. There are a lot of other tools I could list like Xscope, Billings, or TextExpander, but these are the ones I can’t live without. What about you? What are the major tools that you are using on a regular basis? Are there any tools that you would recommend to improve my workflow? What about those of you who do more development than design? What tools are you using?

How to Create Stateful Navigation in Radiant CMS

2010-02-20T04:56:00Z

In the past, I haven’t blogged very much about Radiant CMS – the content management system I created. Part of that is due to the fact that a lot of my early documentation efforts were focused on writing information that would appear on RadiantCMS.org itself, either in blog posts or on the project wiki. Part of it is due to feeling self-conscious (for whatever reason) about blogging about my own project. Another part of it, perhaps the largest part, is due to the fact that I haven’t done a very good job of blogging consistently about anything.

But no more. This year I am working hard to turn over a new leaf, and blogging consistently is my #1 priority. For content I’m going to be pulling from a number of projects I’ve worked on in the past, and Radiant will be featured prominently.

For starters I’d like to kick off this series with a discussion of how to create stateful navigation in Radiant CMS. When I say stateful navigation I mean navigation that indicates where you are on a web site. For instance, in the header of my web site you can see the following links:

“Portfolio” is a lighter color and is set in bold type instead of normal type like the other two links. This indicates to the user where they are on my site. If they were viewing my weblog, “Weblog” would appear bold and the other two links as normal text, and so forth.

Approach #1 – If and Unless

To achieve this effect, I have resorted to a couple of Radius tags. Radiant comes packaged with a powerful macro-like language called Radius that is used to transform snippets of HTML into a working web page. The format is relatively simple. It looks a lot like XML or HTML, except that all of the tags begin with the r: prefix.

On my site, I have three links and I’m using a bit of a brute force technique to get it to work for me. This is taken straight from the main layout of my site:

<div id="navigation">
  <ul>
    <r:if_url matches="^/portfolio"><li class="here"><a href="/portfolio/">Portfolio</a></li></r:if_url>
    <r:unless_url matches="^/portfolio"><li><a href="/portfolio/">Portfolio</a></li></r: unless_url>
    <r:if_url matches="^/(weblog|articles)"><li class="here"><a href="/weblog/">Weblog</a></li></r:if_url>
    <r:unless_url matches="^/(weblog|articles)"><li><a href="/weblog/">Weblog</a></li></r:unless_url>
    <r:if_url matches="^/about"><li class="here"><a href="/about/">About</a></li></r:if_url>
    <r:unless_url matches="^/about"><li><a href="/about/">About</a></li></r:unless_url>
  </ul>
</div>

As you can see, I’m making heavy use of the <r:if_url /> and <r:unless_url /> tags. These tags both use the matches attribute, which matches the URL against a regular expression. (There is a great introduction to regular expressions in the free version of Programming Ruby, here). The <r:if_url /> tag will only output its contents if the URL matches the given regular expression (and the reverse is true for <r:unless_url />).

The downside of this technique is that it is extremely verbose. For each link I have to create a set of <r:if_url /> and <r:unless_url /> tags that contain the state of the link when it is selected and when it is not. The advantage of this technique is that it allows me to use regular expressions to match a huge variety of URLs. This works out well, especially for the “Weblog” link, which should show itself as selected when the URL starts with either “/weblog” or “/articles”.

Approach #2 – The Navigation Tag

If I hadn’t needed to use fancy regular expressions to build my navigation correctly I could have used another set of tags that would construct the navigation more efficiently. The <r:navigation /> tag is designed specifically for rendering this kind of navigation:

<div id="navigation">
  <ul>
    <r:navigation urls="Portfolio: /portfolio/ | Weblog: /weblog/ | About: /about/">
      <r:here><li class="here"><a href="<r:url />"><r:title /></a></li></r:here>
      <r:selected><li class="here"><a href="<r:url />"><r:title /></a></li></r:selected>
      <r:normal><li><a href="<r:url />"><r:title /></a></li></r:normal>
    </r:navigation>
  </ul>
</div>

The <r:navigation /> tag has one attribute, urls. This attribute contains multiple key/value pairs of the title/URL of each link in the navigation. Inside of the <r:navigation /> tags are three additional tag sets containing the HTML for the three different link states. here is the state of a link when the URL matches exactly. selected is the state of a link when the user is on a child page of the given URL. And normal is the state of a link under normal circumstances.

Approach #3 – Clever Use of the Page Slug

There is one final approach that is sometimes useful when dealing with stateful navigation. Ryan Heneise first talked about this approach in an article on ArtOfMission.com. Unfortunately, that article is no longer available so I’ll outline the general technique here.

For starters, this approach makes clever use of CSS and the page slug. The page slug is the last part of the URL. It generally follows the page title, but it is lowercase and it replaces all spaces and punctuation with dashes. So for the root level page “About Us” the slug is generally “about-us”. I say “generally” because the end user can customize the page slug to be whatever they want.

What Ryan realized was that he could use the current page’s slug to set the body class in his main layout:

<body class="<r:slug />">

He could then use a couple of CSS rules to achieve the same effect:

body.portfolio li#portfolio,
body.weblog li#weblog,
body.about li#about {
  color: white;
  font-weight: bold;
}

Conclusion

So there you have it: three fantastic ways to achieve stateful navigation with Radiant CMS. Hopefully I’ve primed the pump a little and your head is already spinning with ways to do cool things with Radiant.

What are you doing with Radiant CMS?

How to Structure a Sass Project

2010-02-20T04:58:36Z

When you start out with Sass it is very easy to use it much like you do CSS without leveraging some of the more useful features. For myself I used it for a long time without realizing much of its true power. In this brief article I’d like to show you how I structure my Sass projects and give you some practical pointers to a couple of open source projects where you can learn more.

I typically store my Sass source in stylesheets/sass. The Haml/Sass plugin for Rails encourages this arrangement. Sass source is stored there and compiled to the stylesheets directory. You don’t have to set it up this way (particularly if you are not using Rails), but this setup works pretty well for me.

In the root of my stylesheets/sass directory are the main Sass files that will be converted directly into CSS files. Files like screen.sass, print.sass, and blog.sass.

Partials

I also have a directory for partials. In my partials directory I store snippets of CSS that are incorporated into other stylesheets through the Sass @import directive. The @import directive works somewhat differently in Sass than it does in CSS. Instead of telling the Web browser to download another CSS file, it inserts the source code from the specified file directly into the generated CSS. Sass partials begin with an underscore (_). This tells Sass that it doesn’t need to generate a corresponding CSS file in the output directory, but that the code in the Sass source file is used in other Sass files. I typically have partials for each of the major sections of my CSS: header, navigation, main, footer. I also tend to have one called layout where I store layout-oriented rules. The exact names of the partials I choose depend on the project, the main idea is to break your stylesheets down into manageable chunks.

Modules

The second directory that I have is reserved for modules. My modules directory is filled with Sass partials containing mixins. I reserve modules for highly reusable Sass code and have a great variety that I typically use when getting started on a new project. Some of the modules are customized greatly for each project (like typography and forms), while some of the modules are the same on every project. I’m doing a lot with CSS3 these days, so I like to have an assortment of CSS3 modules for doing things like gradients and rounded corners. I also have a modified version of a reset module that I stole from Compass which helps me start on the right foot with all browsers.

Example Projects

The image above is showing the stylesheet directory structure from the Sass for the Radiant Extension Registry. One of my more recent projects, this is a great example of how to structure your Sass projects. You might also check out the prototype project for Radiant as it uses a similar structure but doesn’t have as many goodies. And there is also Octopress, which has a slightly different philosophy but is also an excellent example of a well organized project. I’d also recommend that you browse around in the Compass repository as there are a buch of great ideas there.

Are there other examples of Sass projects out there that you have found to be particularly helpful? Are you finding that Sass is easy to pick up? Are there things from my experience that you would like to learn more about?

Line Comments Make Debugging Sass a Breeze

2010-02-20T05:03:21Z

In response to my recent article about Sass, a couple of folks have asked about how easy it is to debug. The question is a good one.

If Sass is generating your CSS this adds another layer of complexity that you must deal with when something goes wrong. If you use tools like FireBug, you can easily inspect an element and see the line number where a particular style was defined. But if you are using Sass, how can you tell the line number of the rule in your source file if the generated CSS file bears little resemblance to your Sass file?

As it turns out, Sass actually has a solution for this. If you set the :line_comments option to true the generated output will contain the line number and source file where each rule was defined.

The output looks something like this for each rule:

/* line 20, sass/_reset.sass */
body {
  line-height: 1;
  color: black;
  background: white;
}

Here’s my Sass initialization file that I use with Rails to ensure that this only happens in development mode. Drop this in config/initializers/sass.rb:

require 'sass'

if /production|staging/.match(RAILS_ENV)
  # Compress CSS (a small file is preferable in production)
  Sass::Plugin.options[:style] = :compressed
else  
  # Expand CSS
  Sass::Plugin.options[:style] = :expanded
  
  # Generate CSS from SASS every time a controller is accessed
  Sass::Plugin.options[:always_update] = true
  
  # Insert comments in the CSS about the line numbers of the Sass source
  Sass::Plugin.options[:line_comments] = true
end

Note that the Sass Reference currently claims that the key to enable this behavior is :line_numbers, but this is wrong. The correct key name is :line_comments. I suspect that they are updating the docs as we speak.

The Demise of Plain CSS: Why Sass and Languages Like It Will Triumph

2010-02-20T05:03:39Z

It is my opinion that these [tools like Sass] are only really of benefit to people who haven’t yet mastered writing CSS properly from the outset…

Harry Roberts (CSSwizardry.com)

Huh?

Sass only really benefits people who haven’t mastered writing CSS properly? Excuse me? I am a very experienced CSS developer and I find Sass quite valuable, having written CSS for a living for many years now. While I won’t claim the level of mastery that an artist like Michelangelo achieved in painting, I can say that I wasn’t born yesterday either. I write all my CSS and HTML by hand. I haven’t used tools like Dreamweaver in nearly a decade.

I can only assume that Mr. Roberts has not done enough Sass to see the utility of the language. Perhaps he’s had to deal with someone else’s Sass or only muddled around with it for a short period of time. At first glance Sass may seem like too much software, but in the hands of a competent designer it is truly wonderful. Having written Sass professionally for almost two years now I can say with confidence that Mr. Roberts is clearly missing something.

Sass – A Programming Language for Designers

Sass is essentially a programming language for designers. It is extremely limited when compared with other languages, but it does a magnificent job of translating the core concepts of a programming language in a way that makes sense for styling a document.

Right now folks that use Sass primarily use it as a Rails plugin, but the Ruby gem also makes it possible to use it from the command line. This makes it easy to use Sass with any language (PHP, Python, even plain-jane HTML).

To use, you need to install the Haml gem. On a Mac you can do this from the command line like this:

sudo gem install haml

This will the give you access to the sass command, which you can use to generate CSS from Sass source files.

Nesting

So let’s talk about what I love about Sass.

At first blush, Sass looks like a better CSS. Instead of requiring you to repetitively list selectors, Sass allows you to nest selectors and rules:

form
  p label
    display: block
    font-weight: bold
  input.textbox
    background: white
    color: #666
  button
    color: white
    background: red
    padding: 10px 20px

The example above would generate:

form p label {
  display: block;
  font-weight: bold;
}
form input.textbox {
  background: white;
  color: #666;
}
form button {
  color: white;
  background: red;
  padding: 10px 20px;
}

Note the absence of brackets and semi-colons in the input. If this seems strange or ugly to you, consider how many times a misplaced bracket or semicolon has caused a rule to render incorrectly. In practice, this bracket-less form of CSS keeps code clean and makes it much easier to write. Believe me. It may look strange at first, but it leads to cleaner and less error-prone code. Of course, the code will be a lot easier to read if you use an editor with good syntax highlighting. (I recommend Textmate with the Sass bundle installed.)

But have no fear, if you prefer brackets, a future version of Sass will allow for a bracketed syntax as well (check out the scss branch).

The ability to nest rules is extremely powerful. Especially when you use it to combine selectors:

#content, #sidebar
  p
    margin: 1em 0

This would generate:

#content p, #sidebar p {
  margin: 1em 0;
}

The amount of typing that this can save is marvelous. Of course, all of this added power comes with a price. If you aren’t careful about your use of nesting and the comma operator, you can generate a huge CSS file.

I’d recommend that you avoid nesting your rules more than three levels deep and that you use the comma operator sparingly. This will minimize the number of lines in the output.

One day if Sass is supported by the browser this won’t be an issue, but as long as Sass is converted to CSS you will need to be conscientious about the output.

Variables

Another powerful feature that Sass borrows from programming languages is the concept of variables. Sass variables always begin with an exclamation point. Variable assignment looks like this:

!text_color = #666
!background = #f5f5f5

You can then use variables in your rules like this:

table
  color= !text_color
  tr.even td
    background= !background

Note the use of the = operator on the color and background rules. This is necessary so that Sass knows that you are using a calculated value for a rule (in this case, a variable).

The above would generate the following CSS:

table {
  color: #666;
}
table tr.even td {
  background: #f5f5f5;
}

Sass even allows you to do math on variables. Need a darker gray for odd rows? No problem:

table tr.odd td
  background= !background - #333

Output:

table tr.odd td {
  background: #c2c2c2;
}

Variables can store font names, numbers, colors, you name it. If you can write it in CSS you can store it in a variable.

Mixins

This brings me to my favorite thing about Sass: mixins. Sass mixins are the stylesheet equivalent of functions. They allow you define a series of rules that can be mixed in to another ruleset with ease.

Here is an example of a simple clear fix mixin:

=clearfix
  overflow: hidden
  display: inline-block

This mixin can then be applied to a ruleset like this:

#content
  +clearfix

Which would generate:

#content {
  overflow: hidden;
  display: inline-block;
}

Mixins can also accept arguments. Here is one of my favorite CSS3 mixins:

=round-corners(!amount)
  border-radius= !amount
  -moz-border-radius= !amount
  -webkit-border-radius= !amount

This would allow you to write:

.box
  +round-corners(5px)

Which would output:

.box {
  border-radius: 5px;
  -moz-border-radius: 5px;
  -webkit-border-radius: 5px;
}

But mixins aren’t just about limiting the amount of typing that you have to do to create a certain effect. I have mixins for default form styles, base typography, resetting a stylesheet, etc… Mixins give you the ability to build a reusable library of styles that you can incorporate into your projects as needed.

It is important to note that mixin definitions do not impact the CSS output unless they are used in a ruleset. This means you can have potentially hundreds of mixins defined and only use a couple of them on a given project. For the first time it is now possible to build a viable CSS framework. (Compass is a powerful example of this.)

Other Features

There are a number of other features that Sass offers that make it a formidable tool in the designer’s arsenal, but these are features that I love. If you want familiarize yourself with all of Sass’s loveliness, I recommend reading the Sass Reference.

A Little Programing History

Now, it is my opinion that one reason designers have been slow to embrace languages like Sass is that these languages appeal to people that think more like programmers than designers. Programmers have almost made code simplicity an art form, while designers are known for spending vast amounts of time doing very tedious and repetitive work to get the effect that they want. Thankfully, this is not always the case with web developers, but in this case we are still a bit behind the curve.

Programmers haven’t always been this way. There was a time when programmers stuck to assembler like newborn babes cling to their mommies. They objected to the output of compilers and preferred writing assembler by hand. (Sound familiar?) They could write better assembler themselves, they said. They didn’t need the productivity boost that higher level languages offered. They were just fine, thank you.

And then something marvelous happened. Compilers got to the point that they were able (as a general rule) to produce more efficient assembler than most coders could by hand. With compiled languages, people found that they were able to tackle more complicated programming work because they could think less about the machine and more about the problem they were trying to tackle.

Surprisingly, it was assembler that got the boot as higher-level languages began to dominate.

And this trend in programming has continued. Interpreted languages like Ruby, Python, Perl, and yes, even PHP, are now replacing compiled languages. I am not saying that the need for compiled languages will be completely eliminated by interpreted languages, but it is clear that as computers have gotten faster the need for compiled code (for many applications) is diminishing. (Yes I am aware Ruby, Python, Perl, and PHP can now be compiled, but they will always retain their dynamic, uncompiled heritage.)

Programmers are used to this kind of progress. Every couple of years the dominant programming language is replaced by another. Code is getting leaner, meaner, and easier to understand.

The Moral of the Story

Does anyone else spot the trend here? Just like higher-level programming languages compile to assembler, so Sass compiles to CSS. And just as higher-level programming languages eventually replaced the regular usage of assembler, so Sass (or a language like it) will eventually replace CSS.

Now, don’t get me wrong. I am sure CSS has many more years ahead of it, but Sass and languages like it are the future. Yes, you can complain about the syntax. You can complain about the generated code. But ultimately, the productivity and simplicity that languages like Sass offer will win over the masses. Of that you can be sure.

One day, Sass (or a language like it) will be more common than CSS.

Update! Based on feedback I’ve tweaked the title of this post a little. The original title began, The Demise of CSS: Why Sass… Apparently, some people thought I was saying that Sass would replace CSS. While that may happen, it is probably more likely that features of Sass will be incorporated into CSS. Either way CSS will certainly remain in one form or another. Sass doesn’t replace CSS. It adds a cleaner syntax and additional functionality.

Out With the Old, On With the New

2010-06-12T18:48:51Z

Today, I’m officially retiring the old design above in favor of a new design. For the benefit of my RSS readers, here’s a screenshot of the new design:

The new design uses a number of CSS3 techniques, including gradients, drop shadows, rounded corners, and rotation. In order to get the best results, you will need to use a Webkit-based browser (Safari or Google Chrome). The site degrades gracefully though, so you shouldn’t have any problem reading the site if your browser doesn’t support theses features of CSS3. You just won’t be able to view the site in all of its glory.

I am very pleased with how the whole site has turned out. I have spent a significant amount of time tuning the message of the different pages. I’m quite fond of my about me page, and the new hire me page is a worthy addition. Cream turns out to be a wonderful background color. It adds extra pop to each of my images.

Radiant Extension Registry Updated!

2010-02-20T05:15:14Z

My holiday project for the last couple of weeks was to rework the Radiant Extension Registry. Sean Cribbs did a wonderful job a couple of years ago banging out the initial code, but we never had the opportunity to polish it off really well.

The extension registry was originally a huge step forward for us. Before Sean’s work we had a wiki page and that was it. But as more and more extensions were added to the registry it was becoming increasingly clear that we needed to rework it a little. The extension listing wasn’t alphabetical or paginated. It was just one long list of extensions listed in the order that they happened to have been added to the registry. If you wanted to find something, Ctrl+F was your only friend.

The dire need of the extension registry became especially apparent to me when I sat down with Sarah Allen and a couple of her friends in San Francisco in November. Sarah had contacted me about Radiant a couple of weeks before asking about the best way that she and a couple of like-minded developers could contribute to the Radiant community. When I mentioned that I was going to be out in San Francisco for Ruby Conf we decided to meet to talk about things in person.

As we talked I kept mentioning this extension or that extension. Some of the extensions they had heard of, but some of the extensions they didn’t even know existed. As we talked further I discovered that they did not even know that the Radiant Extension Registry existed. To my great shame I realized that a link to it had never been added to the navigation of the Radiant web site! A huge oversight on my part. What this meant was that Sarah and other newcomers to the Radiant community had assumed that the only way to find extensions was to search for them on GitHub or Google!

We were able to remedy the navigation problem pretty quickly, but the apparent flaws of the existing extension registry were beginning to weigh on me.

I had the good fortune this year of being able to be at home with my parents in Pennsylvania for a couple of weeks over Christmas. The holidays are always an important family time for us. I have two brothers and a sister. Three of us are still unmarried, so we typically try and spend as much time together during Christmas as we can. I decided to choose the extension registry as my holiday project – between all of the games and activities, it would provide something to pour my mind into.

After a day or two I had a couple mockups done. Soliciting some help from the Radiant community I continued the project shortly after Christmas, and we made great progress. Joel Oliveira helped me turn my mockups into HTML and got paperclip going so that extension authors could upload screenshots. I spent some time reworking the extension listing and authors listing, adding pagination and a couple of additional fields. I also made a simple search page and reworked the home page.

One of the features that we added that I’m particularly excited about is the “Available for Hire” checkbox. When selected, a big “Available for Hire” badge will be displayed on your profile and next to your name in the authors listing, like this. I’m hoping that this concept will help turn the author’s listing into a bit of a professional directory for people who do Radiant projects. Hopefully if you need work on custom Radiant extensions for your web site will you will be able to find the right folks here.

Believe it or not, one of the highlights of the project was reworking the “New Extension” screen. Form design is one of the hardest aspects of modern web application design. Your forms need to communicate clearly to the user what needs to be done. It is a great challenge to put the right elements on the form and to organize it in a way that makes sense to the user. It easy to be too brief or, on the other hand, to be too wordy. Striking the right balance so that what you have written will be read and clearly understood is tricky. I think I came pretty close to striking that balance, but judge for yourself. You can see the old form here and the updated form here.

We’ve got a number of things that we would like to see added to the extension registry in the near future. If you are interested in helping out, fork the project on GitHub, write some code and tests, and submit a pull request. (You can also submit feature requests or bug reports on the issue tracker.) I would love to see someone take on the challenge of adding reviews and ratings to the system. I’m also playing around with the idea of making extension pages more like wiki pages with versioning and multi-author editing.

You can visit the new extension registry here.

DateInputJS: The Fantastic Date Control

2010-02-20T05:16:25Z

One of the nice things I put together while I was working on
MemberHub.com was a LowPro
and Prototype-based date input control. Today, Five Points Solutions (aka
MemberHub) has released it as open source:

http://github.com/fivepointssolutions/dateinputjs

It’s fairly easy to use. Just wire it on to text field that you would like to
turn into a date input control and the DateInputBehavior does the rest. A
simple line like this:

Event.addBehavior({'input.date': DateInputBehavior()});

…will unobtrusively
wire it onto all input controls with a class of “date”. It’s pretty slick. I’m
sure you will like it.

Dan Webb (of LowPro fame) actually wrote a good portion of the code. We
discovered
date_selector.js
in the LowPro repository, found that it was about half of what we wanted, and
were able to modify it to suit our needs. Dan’s original version didn’t allow
the calendar portion to drop down or provide easy access for jumping forward
to another year or month. We added these features, styled it up rather nicely,
and have packaged the whole thing up in a nice little project on GitHub.

I, for one, am very grateful that Five Points has released their version as open
source. I have plans to see that it gets integrated into a little
CMS that I’m working on.

StatusJS: Work Well With Messages

2010-02-16T01:10:56Z

I talked briefly about my javascript library StatusJS in the article Tech Notes: Radiant 0.9.0 RC1 but thought that it would be good to take the time to introduce it in more detail as it is such a useful library.

We live in a time where Rails-style flash messages have become so common and annoying in web applications that they litter the webscape like confetti in the annual Thanksgiving day parade. Enough already! I know I just deleted that object! I know I just created a message!

Now a couple of folks have come up with creative ways to automatically hide flash messages after a certain period of time or allow the user to manually close the message, but both solutions have the annoying effect of causing the content underneath to “slide up” once the message disappears. This can be jarring for users that are working with content below.

Perhaps we need to rethink this whole concept. Maybe it is less important to tell the user what they have just done and more important to tell them about the work that is being done.

This is where StatusJS comes in. StatusJS provides a robust solution for displaying progress messages to users while the work is being done. So instead of displaying “Changes saved.” in a flash message after the form is submitted, you display “Saving changes…” while the form is submitting.

A bit of a paradigm shift mind you but something that Web applications should have borrowed from desktop applications a long time ago.

So how does it work?

StatusJS defines a couple of global functions that make it easy to control the status overlay, as the following code sample demonstrates:

showStatus("Initializing...");
setStatus("Loading graphics...");
setStatus("Finished!");
hideStatus();

The showStatus() function displays and centers a new status overlay, setStatus() changes the status message and re-centers the overlay, and hideStatus() hides the status overlay completely.

StatusJS also includes a LowPro behavior for forms that makes it easy to add onsubmit status messages when a user clicks a submit button.

To automatically connect the behavior with your forms, add the following line to your application.js file (assuming you are doing Rails development):

Event.addBehavior({’form’: Status.FormBehavior()});

This allows you to add a custom attribute to each of your forms that contains the onsubmit status message:

<form action="/controller/action" onsubmit_status="Saving Changes...">
  ... contents of form ...
</form>

The form above would display a “Saving Changes…” progress message after the user clicked the submit button.

There are a couple of additional configuration variables that are worth noting. Normally you should set these variables in your application.js file (assuming you are doing Rails development). It is essential that application.js be loaded after status.js so that the variables are not overridden by the defaults. Here is how it works:

// The size of the corner images. A value of 12 means square
// 12x12 pixel corners.
Status.CornerThickness = 12;

// The path, width, and height of the spinner image
Status.SpinnerImage       = "/images/status_spinner.gif";
Status.SpinnerImageWidth  = 32;
Status.SpinnerImageHeight = 33;

// The background and corner image paths
Status.BackgroundImage  = "/images/status_background.png";
Status.TopLeftImage     = "/images/status_top_left.png";
Status.TopRightImage    = "/images/status_top_right.png";
Status.BottomLeftImage  = "/images/status_bottom_left.png";
Status.BottomRightImage = "/images/status_bottom_right.png";

// Dim the background when a status message is displayed. Also
// prevents stray mouse clicks from having any effect.
Status.Modal = true;

At the moment, StatusJS requires prototype.js, effect.js, and lowpro.js (all included in the GitHub project), but Sean Cribbs is working on a JQuery port. It will be added to the main project once it is ready for general use.

You can download StatusJS from GitHub here. The project includes a small demo in the test directory that requires Serve.

If E-mail Had a Baby: Notification Messages

2010-02-20T05:22:20Z

I’ve been noticing recently that a lot of my e-mail of late is notification
related. I get a lot of e-mail from applications like Twitter and Facebook
that falls into this category. “Someone added you as their friend”, “X is now
following you”, “There is a new message in your Facebook inbox”, “A photo was
uploaded with you in it”, etc… These messages can normally be expressed in a
single line.

I often sort messages from different web services into their own folders.
Here’s an example of how my Twitter “inbox” looked earlier today:

As you can see, each of these notification messages can be displayed on a
single line. In fact, an entire summary of each e-mail message is expressed in
the subject line.

The Big Idea

So here is my big idea: What if a notification e-mail message like this was
formatted so that it would allow e-mail clients to handle them as a special
case?

This would allow an e-mail client to have a special pane that would show
recent notifications. You could also build rules that would do certain things
when a site sent you a notification. Like download the photo you were last
seen in to a special folder or display a small notification window (like a
Growl notification) or forward the notification to you as an SMS message on
your cell phone.

If the body of the e-mail contained a special part tailored for display, you
could even get a feed view that would look much like Facebook’s news feed
or perhaps your Twitter stream.

Probably the biggest win here in treating notification messages differently is
that normal messages begin to take center stage again. Your inbox would no
longer be filled with notifications from Twitter and Facebook. It would
contain the real stuff you need to deal with for your work or personal life.

The possibilities here are mind boggling. This could change the way we
communicate with each other.

All it would take would be for a major e-mail client like G-mail or Yahoo to
start handling messages this way and promoting the concept.

The Technical Jargon

I’m not familiar enough with the e-mail spec to completely outline how this
should be done, but I do have a couple of suggestions for how this could work
in practice.

First of all, I’d suggest that web services begin marking notification
messages with a special “X-Notification” e-mail header. The header could
include information about whether the message required some action from the
user or not. Other things that could possibly be included here would be flags
that would be read by mail servers as the message is passed along that would
determine the priority that it should be delivered. Lower-priority
notifications would not need to be delivered immediately.

Secondly, I’d suggest that the subject of the message be treated as a one-line
summary of the notification. Web services seem to be doing this already.

Thirdly, I’d also suggest that we add a new alternative part to a MIME encoded
message that would contain the compact rich notification summary suitable for
display in a feed of some kind (I’m thinking HTML here). The new part type is
essential because it would allow messages to be displayed in the new format
only if the e-mail client supported it, whereas older clients could continue
to display them as normal e-mail messages.

So this is my big idea. What do you think?

Tech Notes: Radiant 0.9.0 RC1

2009-10-14T04:36:55Z

On Friday of last week we did a release candidate
for the next version of Radiant. Radiant 0.9 is the most significant overhaul
of the adimin interface since Radiant was first released back in 2006.

Apart from the obvious interface improvements, there have been a number of
technology changes on the frontend that are worth talking about.

We’ve Climbed Aboard The SASS Bandwagon

SASS is a new framework to build the cascading stylesheets.
It’s the sister of HAML (the indentation cousin of ERB), but in many ways it is
much more revolutionary than HAML. SASS gives a designer many of the same tools to
keep stylesheets clean, that programmers have used for decades for their own code.
It has support for variables, functions (called modules), and basic conditionals.

For Radiant we are just begining to tap in to the power that SASS provides, but I can show
you a couple of code snippets that show exactly how it can make stylesheet development easier.

For example, here is a SASS module that makes declaring opacity for an element easier:

=opacity(!opacity)
  opacity= !opacity
  -moz-opacity= !opacity
  -khtml-opacity= !opacity
  -webkit-opacity= !opacity
  filter= "alpha(opacity=" + round(!opacity*100) + ")"
  -ms-filter= "progid:DXImageTransform.Microsoft.Alpha(Opacity=" + round(!opacity*100) + ")"

Then, in the actual stylesheet I can reference the module like this:

#transparent
  +opacity(0.5)

Which will output the following when it is compiled to CSS:

#transparent {
  opacity: 0.5;
  -moz-opacity: 0.5;
  -khtml-opacity: 0.5;
  -webkit-opacity: 0.5;
  filter:alpha(opacity=50);
  -ms-filter:progid:DXImageTransform.Microsoft.Alpha(Opacity=50)
}

Effecively making a div with an ID of “transparent” 50% transparent in a browser
compatible way.

The great thing about this is I can use the opacity mixin as many times as I want
across my stylesheets. If I then need to update the technique that I used for creating
opacity (say, to use transparent PNGs instead) I can redefine the opacity module
and all of the code that uses it will get updated with the new rules.

Apart from the opacity module, I have also written or found modules for rounding
corners, and adding drop shadows. We still have a long way to go in leveraging the
power of SASS for Radiant, but I am excited about the possibilities that it
opens up, particularly for extensions.

I am finding that SASS, when used appropriately, makes CSS much easier to maintain
and refactor.

If you are interested in learning more about SASS, the
Compass project on GitHub is a great
one to explore.

The New Javascript Sauce: LowPro + Prototype

Another major change in this release is the introduction of LowPro
behaviors. Most of the core Javascript has been repurposed to leverage this technology.
LowPro make it easy to attach objects (called behaviors) to the DOM that respond to
events. LowPro does all of this unobtrusively
which also encourages code reuse.

One example of this is the Popup.TriggerBehavior. The Popup.TriggerBehavior makes it
possible for extension developers to pop up Facebook-like windows without writing a
single line of Javascript. LowPro automatically attaches the Popup.TriggerBehavior to
links with the “popup” class, like this:

<a class="popup" href="#reference_window">Reference</a>
<div id="reference_window" style="display: none">
  ... contents of window ...
</div>

The href in the code above specifies the ID of the div that should be wrapped
in a popup window. When the behavior is attached, it removes the div from the DOM and wraps
it in the chrome of a popup window. Then when the link is clicked the window is centered
within the view port and shown. All of this without writing a single line of javascript.

Another very cool example of LowPro behaviors in action is the Status.FormBehavior. This behavior
is attached to every form and works using a custom attribute.

<form action="..." onsubmit_status="Saving Changes...">
  ... contents of form ...
</form>

In the code above the status message “Saving Changes…” will be displayed whenever the
form is submitted. This serves to let the user know that they clicked the right button
and also gives them a small progress pinwheel so that they know work is being done.

Both of the behaviors metioned in this article ship with Radiant and are also separate
projects on GitHub. The first is called PopupJS and the second StatusJS.

Serve: A Rapid Prototyping Framework for Designers

2010-02-20T05:22:44Z

Since Adam McCrea has introduced his solution for simplifying HTML mockups over on the EdgeCase blog, I thought I would take the time to reintroduce my own: Serve.

I’ve been using Serve for almost a year now to prototype MemberHub and before that I used various forms of a simple Ruby script to power my HTML mockups.

Serve has become an indispensable part of my development methodology because it allows me to prototype the application using HTML in a DRY format independently of the work that is being done by developers. This independence is essential as we explore various facets of an application and prioritize the parts that should be developed first.

To give you an idea of how it has worked on MemberHub. I sit down with the client beforehand and discuss a feature and the initial user stories that make up that feature. On a large feature I may spend some time during this phase drawing up a couple of paper prototypes so that we can get a general idea of the shape of the feature and how it will affect the application. We can then use the paper prototypes to give a client a fairly reliable estimate of how long it will take to do the initial development.

Once the feature has been outlined in this way I can then begin work with the HTML prototype. I tend to start with the HTML prototype and not in a graphics program as it allows me to focus on the functionality without getting too caught up with how it looks initially. (I may drop back to a graphics program and “punt”, so to speak, if I’m having trouble getting the layout just right for a particular screen.)

Often while I’m working on a screen for a particular section, I will call the client over (yes, I love working onsite with my clients) and ask for their input on how it flows and feels. One of the chief advantages of developing an HTML prototype for your application is that it gives you the opportunity to explore the flow of your application before the backend development has begun. Hopefully, during the prototyping phase you will be able to iron out any problems in flow, with minimal expense because there is no backend to rework.

The “Design First” approach is huge for us, because most, if not all, of the business decisions are ironed out in the design phase. Also at the point that a feature has passed completely through the design phase we can then estimate that feature with extreme accuracy. The client also knows exactly what they are going to get when the development is done.

Once the client has signed off on a feature in the prototype, it can then be thrown over the wall to the development team. Because we use Serve, the views can be copied over from the HTML prototype to the application almost as is. This does take some effort on my part to construct the views in a way that is friendly to a Rails application, but in general this is not hard if you understand the RESTful approach that Rails encourages. This process is also eased because Serve has full support for partials and layouts with either ERB or HAML.

Does the developer find it annoying to have to copy the views over from the prototype into the application instead of having the designer work with him in the application? In general, yes and no. Yes more work is involved in copying views over into the application (particularly when views change because a feature is revisited). But no, because he doesn’t have to worry about a designer breaking tests or causing the application to fail in some way. It’s also hugely beneficial to the developer because the guesswork is taken out of a feature when it is completely developed (and signed off on) in the prototype before the development begins.

Also, I can’t emphasize enough the freedom that the two project approach gives the designer. No longer is he caught up with views that are hooked into controllers, etc… He can explore new features and focus almost completely on the HTML, CSS, and creative part of his job. With designers often juggling the roles of business analyst, creative expert, HTML/CSS/Javascript guru, asking for the two project approach small price to pay for the increased productivity.

I’ve put together a brief overview of Serve in screencast form below. Let me know what you think.

Mentioned in the screencast:

MemberHub.com in Six Minutes

2009-09-23T21:31:50Z

Since January of last year, I have been working with a small startup here in Raleigh building a web service called MemberHub. MemberHub has been a bit of a dream come true for me. It is the first time I’ve had the opportunity to build a subscription-based web service that has massive online appeal. If it takes off, I believe that MemberHub could be the next Facebook or LinkedIn.

Now don’t write me off just yet… Hear me out.

People use Facebook for their personal lives to help manage the relationships they have with friends. LinkedIn is useful for keeping track of your business connections. MemberHub is designed to help organizations, such as churches and nonprofits connect with their members and manage the various groups that make up the organization.

Using MemberHub, you can create online “hubs” for each of the groups that make up your organization. A hub is a simple online home for a group. It contains a home page, a calendar, a place for announcements, a discussion board/mailing list, and a place to upload files. A church, for example, could create hubs for each of its bible study groups, a hub for the homeless ministry, a hub for the singles ministry, a hub for the worship team… You get the idea.

Now the concept of a hub is nothing new. There are plenty of services online today that offer similar features. Many organizations are using services like Yahoo Groups or Google Calendar with great success. MemberHub’s chief strength—and differentiator—is that it provides these features in a way that is friendly to organizations and members.

For the organization, MemberHub makes it easy to setup and organize secure online homes for each of your groups. For the member, MemberHub makes it easy for you to keep up with multiple groups and even multiple organizations in one convenient location! One of the most incredible features of MemberHub is that it can take all of the events across all of the hubs you are affiliated with and display them on one convenient calendar. Imagine never having to enter events in for your organizational activities again!

We’ve really worked hard to make MemberHub simple and intuitive. Below is a brief, 6-minute video that will give you a bit of the bigger picture of what MemberHub can do for you:

If you’d like to learn more about MemberHub, visit http://memberhub.com. And do let me know if you have questions or comments.

HTML Canvas Test

2009-09-23T21:31:50Z

Meet Dataset: The Fixture-Killing, Data-Loading Framework

2009-09-23T22:13:52Z

My good friend and partner Adam Williams has just finished bolting the doors on his new YAML-fixture-killing Rails plugin: Dataset. Dataset is the next generation of a plugin that Adam and I wrote last year called Scenarios.

Why the need for a new plugin? The Scenarios plugin was originally built inside of a Rails application that we were working on. At the time we threw it together rather haphazardly. There were few tests (if any). The main thing was to prove that the idea was good. Scenarios worked so well for us that we soon extracted it and used it in our next application. A friend added support for Test::Unit. Pretty soon the implementation our “simple” fixture replacement plugin had grown quite complex. It was becoming hard to maintain.

This year Adam and I have been working on a rather large Rails application. The run time for tests in our application had almost become unbearable. In an effort to speed up those tests and fix some of the outstanding issues in the Scenarios plugin, Adam decided to start from scratch and rewrite the plugin from the ground up using the test first approach.

We have christened the rewrite “Dataset”. It is virtually a drop-in replacement for the Scenarios plugin. Our initial tests suggest that it is significantly faster than its predecessor.

Folks our experience with it over the last year leads me to believe that Dataset is the solution to the Rails fixture debacle. If you haven’t tried it out yet give it a try!

Installation

Like most other Rails plugins you can use the script/plugin install command to download the plugin into your current project:

./script/plugin install git://github.com/aiwilliams/dataset.git

Once the plugin is installed, you will need to add the following lines to test/test_helper.rb:

require 'dataset'
class Test::Unit::TestCase
  include Dataset
  datasets_directory "#{RAILS_ROOT}/test/datasets"
end

General Usage

The basic idea behind Dataset is that creating and using fixture-like data for your application shouldn’t be a chore. To this end Dataset encourages the use of Ruby code for generating your models. A set of Ruby models can be wrapped up for easy usage in a “dataset”.

For example, suppose I’m writing tests for the my application’s authentication system. I could create a dataset with two users in it with the following code (assuming the User model is defined):

# in test/datasets/users_dataset.rb
class UsersDataset < Dataset::Base
  def load
    create_record :user, :john, :name => 'John', :password => 'doodaht'
    create_record :user, :cindy, :name => 'Cindy', :password => 'whoot!'
  end
end

Above, I’m using the create_record method to insert records for two people into the Users table. The create_record method takes three parameters. The first is the singular name of the table to insert the record into, the second is the symbolic name of the record (for referencing the record in a test), and the third is a hash of the attributes of the record.

Jumping over to my test case, I can now write:

# in test/unit/user_test.rb
class UserTest < Test::Unit::TestCase
  dataset :users
  
  def test_do_something
    user = users(:john)
    assert_equal "doodaht", user.password
  end
end

In order to use a specific dataset in a given test, you must declare that the test depends on it with the dataset class method. In the example above I’m declaring that UserTest depends on just UserDataset, but I could easily declare dependancies on multiple datasets by passing multiple parameters to the dataset class method (similar to the way that the Rails fixture method works). Once the dataset is declared you can reference specific models using the appropriate reader method (almost exactly the same as with Rails fixtures). In the example above, I loaded “John” with the reader method users and the symbolic name :john. Remember that in UsersDataset I declared that “John” should be accessible through the symbolic name :john. The users reader method can also retrieve an array of models if you pass it multiple symbols: users(:john, :cindy).

Create A Variety of Datasets for Each Model

When you load a dataset with the dataset class method, only the data declared in the dataset will be available to tests that use it. This is by design. Part of the dataset philosophy is that datasets should be small containing only a fraction of the data needed for your entire test suite. Instead of creating one massive file with all of the data needed for a testing a certain model in different states (like you would with Rails fixtures), create multiple smaller datasets and load only the data you need for each test.

Composition

As the complexity of your application grows there are times when it is useful to declare that a one dataset depends on another. The Dataset plugin allows you to do this through composition. You can declare that dataset C depends on dataset B. Then, when a test declares that it needs dataset C, dataset B will be loaded first and then C. If B depends on A, dataset A will be loaded first, then B, then C, and so forth.

Here’s a simple example using posts and comments:

# in test/datasets/posts_dataset.rb
class PostsDataset < Dataset::Base
  def load
    create_record :post, :first, :title => "First Post"
    create_record :post, :second, :title => "Second Post"
  end
end

# in test/datasets/comments_dataset.rb
class CommentsDataset < Dataset::Base
  uses :posts
  
  def load
    create_record :comment, :first, :body => "Nice post!", :post_id => post_id(:first)
    create_record :comment, :second, :body => "I like it.", :post_id => post_id(:first)
    create_record :comment, :third, :body => "I thoroughly disagree.", :post_id => post_id(:second)
  end
end

In the example above, CommentsDataset declares that it depends on PostsDataset with the uses class method. This means that if a test declares that it needs CommentsDataset, PostsDataset will be loaded first and then CommentsDataset.

(Note that inside the load method I’m using another form of reader method which simply yields the ID for a symbolic name. In this case: post_id. This is useful for making associations without needing to load the model, as done here with comments and posts.)

Helper Methods

Another way of simplifying your datasets and tests is through helper methods. Helper methods are declared inside the helpers block of a dataset:

# in test/datasets/users_dataset.rb
class UsersDataset < Dataset::Base
  def load
    create_user "John", :email => "john@example.com"
  end
  
  helpers do
    def create_user(name, attributes={})
      defaults = { :email => name.gsub(/[,. ]+/, '.') + "@example.com" }
      create_record :user, name.downcase.intern, defaults.merge(attributes)
    end
    def login_as(user)
      @request.session[:user_id] = user.id
    end
  end
end

Any of the methods declared inside a dataset’s helper block are available to the dataset in addition to being mixed into datasets and tests that use it.

In the helper block above I’ve defined two methods. The first, create_user, gives me an easy way to create new users with sensible defaults. (I would highly encourage using factory methods like this to remove duplication from your test data.) The second method, login_as, is a helper method for integration tests. You can see it in action below:

# in test/integration/projects_test.rb
class ProjectsTest < ActionController::IntegrationTest
  dataset :users, :projects, :todos
  
  def test_should_show_active_projects
    login_as users(:john)
    get :projects
    assert_tag '#active_projects'
  end
end

What About Machinist, Factory Girl, and the Other Fixture Replacement Plugins?

If you’ve taken the time to read everything above I hope you can see that Dataset is more than just a new way to construct models for testing. Dataset gives you an easy, declarative method for constructing sets of data to be used in testing. It is a data loading framework. This is in contrast to Machinist and Factory Girl which focus only on making it easy to create new models for testing, but have no solution for loading sets of data. For the record you can use Dataset with Machinist or Factory Girl, though my personal preference is to create my own factory methods for each model.

As to the other fixture replacement plugins? Frankly, I haven’t seen anything that comes close to providing the power and flexibility of Dataset. But don’t take my word for it! Try it for yourself and experience the difference.

Radiant Sprint on December 13

2009-09-23T21:31:50Z

Just in case you missed the news we are planning another Radiant Sprint on Saturday, December 13. Several prestigious members of the Raleigh Ruby Brigade plan to attend along with some of the more questionable characters (like me!).

The plan is to continue working to implement the next version of the Radiant UI and bring some of the internals up to snuff. Radiant has recently been upgraded to use the more modern RESTful approach, but there are still plenty of tests to write and other improvements to be made.

This is the perfect opportunity to gain a little insight into the Radiant development process and get up to speed on some of the tools we have been working with (RSpec, HAML, Serve, Spec Integration, and Dataset, to name a few).

It will be hosted at Red Hat here in Raleigh. We’ll get started around 9 am and continue until about 6 pm that evening. RSVP if you want to come along for the fun. Everyone is welcome to attend, even if all you want to do is heckle.

Create Facebook-like Windows with Popup.js

2009-09-23T21:31:48Z

Over the past couple of months I’ve been working on a little library for a client that allows us to create Facebook-like popup windows with ease. It’s called popup.js. The library depends on Dan Webb’s excellent Low Pro and comes complete with it’s own behavior for easy unobtrusive use.

So how does it work? Well, once you have the proper plumbing in place you can declare a simple popup window like this:

<div class="popup" id="test" style="display: none">
  <h3 class="title">Popup Window</h3>
  <div class="popup_content">
    <p>Hello world!</p>
    <p><a href="javascript: Element.closePopup('test')">Close</a>
  </div>
</div>

This markup assumes that you are using the included facebook.css stylesheet, but the only thing that is necessary to have a functioning popup window is a div with an ID attribute. You should also set style=“display: none” to ensure that the div is not visible when the page loads.

Popping up the window is as simple as linking to it:

<a href="#test" class="popup">Popup</a></code>

Links with the class of “popup” get the Popup.TriggerBehavior which will trigger the popup when clicked. Note that the href should be set to the ID of the element to popup. If you prefer you can set the href to a URL that returns the HTML for the popup and an AJAX call will be made to that URL.

For more information about this little lib, see the README in the GitHub project:

http://github.com/jlong/popupjs/tree/master/README

And investigate the test project:

http://github.com/jlong/popupjs/tree/master/test

Special thanks to Five Points Solutions for their help debugging this library. They have contributed several Internet Explorer bug fixes in addition to funding much of the initial development.

Pragmatic Programmer Site Live!

2009-09-23T21:31:49Z

This may be old news for some of you, but the Pragmatic Web Site got a face lift a couple of weeks ago. I was thrilled to have the opportunity to work on the site with Mike, Dave, and Andy. Most of the design work was done this summer, while the finishing touches on programming and the data import pushed the launch date back to the beginning of October. (Site credits here.)

If you haven’t seen it yet, I’d encourage you to head on over to the site and buy a book or something!

Introducing Serve: Now With Gemmi Goodness!

2009-09-23T21:31:48Z

Based on my HAML Server for Web Designers article, I’ve created a small gem “serve” which makes it extremely easy for a Web Designer to get up and running with Haml and Sass:

$ sudo gem install haml redcloth bluecloth serve
$ cd ~/Workspaces/prototype
$ ls . * 
.:
index.haml

images:
logo.gif

javascripts:
prototype.js        dialogs.js         tabset.js

stylesheets:
application.sass        dialogs.sass
$ serve
[2007-09-25 02:11:42] INFO  WEBrick 1.3.1
[2007-09-25 02:11:42] INFO  ruby 1.8.5 (2006-12-25)
[2007-09-25 02:11:42] INFO  Serve::Server#start: pid=1626 port=3000
...

And voila! I can now access the files in ~/Workspaces/prototype at:

http://localhost:3000

Serve isn’t just a HAML or SASS server. With the proper gems it can also handle Textile and Markdown (not to mention plain Jane HTML!).

Serve also plays nicely with Rails. If you have a file named “script/server” in the current directory, Serve will execute that script instead of launching the normal WEBrick server.

Complete usage information is available with:

$ serve --help

Learn more about the project over at Ruby Forge…

A HAML Server for Web Designers

2009-09-30T03:53:16Z

I have a script named serve in my bin directory that let’s me quickly startup a Webrick server in any directory. This is handy for serving HTML mockups or other files. Today, I updated it to work with HAML:

#!/usr/bin/env ruby
require 'webrick'
require 'rubygems'
require 'haml'

class HamlHandler < WEBrick::HTTPServlet::AbstractServlet

  def initialize(server, name)
    super
    @script_filename = name
  end

  def do_GET(req, res)
    begin
      data = open(@script_filename){|io| io.read }
      res.body = parse_haml(data)
      res['content-type'] = 'text/html'
    rescue StandardError => ex
      raise
    rescue Exception => ex
      @logger.error(ex)
      raise HTTPStatus::InternalServerError, ex.message
    end
  end

  alias do_POST do_GET

  private
    def parse_haml(string)
      engine = Haml::Engine.new(string,
        :attr_wrapper => '"',
        :filename => @script_filename
      )
      engine.render
    end

end

WEBrick::HTTPServlet::FileHandler.add_handler("haml", HamlHandler)

args = ARGV.join(' ')
args.gsub!(%r{^http://}, '')
args = args.split(/[ :]/).compact

server = WEBrick::HTTPServer.new(
  :Port => args.pop || 3000,
  :BindAddress => args.pop || '0.0.0.0',
  :DocumentRoot => Dir.pwd
)

trap("INT") { server.shutdown }

server.start

Update! A more powerful version of this script has been packaged up in a gem called serve.

Just an Experiment

2009-09-23T21:31:48Z

OK, this has nothing to do with what I’m working on in Adam’s basement, but here’s a starfield simulation I’ve been working on for a small game in Javascript. It’s an interesting example of what is possible in Javascript on a modern Web browser (tested on Safari 3 and Firefox 2). Be sure to check out the source. Prototype makes this type of thing extremely easy.

Constraints, Frameworks, and Adam’s Basement

2009-09-23T21:31:50Z

It’s official. Adam Williams and I are now working feverishly in his basement on our little idea for a web app. We’re both pushing off other obligations for the next 3 months so that we can concentrate on building a quality product.

One of the fun things about building your own application is that you can truly make it whatever you want it to be. If you’ve been in an environment (like me) where you are constantly building things for other people, working on your own project can be liberating. As a creative person I love this! The sky is the limit. No idea is a bad one. Every idea is worth considering.

But wait a minute! Even though we are now working on our own project we still have constraints. We don’t have an unlimited amount of time or money that we can devote to this. We eventually need to ship a working product even if it isn’t everything we initially visualized it would be. In fact, we have to be brutal about what we allow into the app and what we throw out. If we aren’t brutal we’ll end up with something sub-par. Either the app will lack the really useful features when it ships or it will never ship.

This week we’ve worn our creative hat a lot. One of the mistakes I think that we have made is that we have focused a lot on system architecture issues and not enough on application features. I’m beginning to realize that on the front end of this process it is extremely important to focus on application features. We can always refactor the application in the future when we know more about what the system architecture issues are. The features will help clarify that.

Extract a framework from your application. Resist the urge to invent a framework before working on features.

Better Modularization for Rails 2.0 (or What Rails Can Learn from Django)

2009-09-23T21:31:49Z

In my previous post about Rails and Engines, I talked about some of the issues I’d like to see resolved in Rails 2.0. Specifically, it seems that we need to rethink modularization in Rails and make it easier for people to share complete slices of applications.

One of the primary hinderances of the present Rails architecture to modularization is the directory structure.

Consider the typical rails app directory:

app/
  controllers/
    application.rb
    account_controller.rb
    blog_controller.rb
    comments_controller.rb
  helpers/
    application_helper.rb
    account_helper.rb
    blog_helper.rb
  models/
    user.rb
    blog.rb
    post.rb
    comment.rb
  views/
    account/
      signup.rhtml
      login.rhtml
      edit.rhtml
    blog/
      index.rhtml
      archive.rhtml
      post.rhtml
    comments/
      view.rhtml
      remove.rhtml
    layouts/
      application.rhtml

Now at first glance, the Rails directory structure seems quite helpful. There is a place for everything and everything is in its place. Models go here, views here, controllers here… The entire MVC in 3 different directories. Wait a minute! Compare this to the Django directory structure for the same application:

account/
  __init__.py
  urls.py
  models.py
  views.py
  templates/
    account/
      account_login.html
      account_signup.html
      account_edit.html
blog/
  __init__.py
  urls.py
  models.py
  views.py
  templates/
    blog/
      blog_list.html
      blog_archive.html
      blog_detail.html
    comment/
      comment_view.html
      comment_remove.html

Wow! See the difference? Django divides the application up not according to file type, but according to logical structure. Related files are together. This makes it easy to share entire chunks of an application. All you have to do is create an svn:external to the appropriate directory of another app and instantly you have access to an entire slice of the other application.

Imagine if Rails took the same approach. The new app directory could look something like this:

app/
  application/
    application_controller.rb
    application_layout.rhtml
  account/
    _config.rb
    _routes.rb
    account_controller.rb
    account_helper.rb
    account_edit.rhtml
    account_login.rhtml
    account_signup.rhtml
    user.rb
    user_migrations.rb
  blog/
    _config.rb
    _routes.rb
    blog_controller.rb
    blog_helper.rb
    blog_index.rhtml
    blog_archive.rhtml
    blog_post.rhtml
    comment.rb
    comment_migrations.rb
    comments_controller.rb
    comments_helper.rb
    comments_view.rhtml
    post.rb
    post_migrations.rb

Now I’ve changed things around just a bit to accommodate the new directory structure and support better modularization. Views are now prefixed with the name of the controller that they are associated with (this allows us to avoid having to put them in a separate directory). I’ve also changed migrations around so that all the migrations for a particular model are in the same file (we would probably need a new domain language for this). Also note that the config.rb and routes.rb files give us a convenient place to store configuration for a particular slice of our application (the underscore prefix would sort them to the top of a directory listing).

So that’s my big idea for Rails 2.0. It would be a radical departure from the present directory structure. So radical that it would effectively make Rails 2.0 applications incompatible with Rails 1.0 apps. But we are already dropping support for deprecated features in Rails 2.0, so perhaps it’s time to rethink the directory structure.

Update: There is some interesting discussion going on about this on the Rails-Core mailing list.

Setting Up Ubuntu for Rails

2009-09-23T21:31:49Z

I just found a wonderful little screencast by Geoffrey Grosenbach of Peep Code Screencasts on setting up the full Rails stack on Ubuntu. He’s uploaded it so that anyone can watch it over on the ShowMeDo website.

From the description:

This 10 minute demo shows how easy it is to install Ruby, Rails, Apache, Mongrel, Subversion, and MySQL on an Ubuntu server. Capistrano and the deprec gem (deployment recipes) are used to automate the installation process with only a few commands. It finishes with a deployment of a Rails app to the newly built server!

The demo is done with Parallels on a Mac, but would work with any machine that can boot from the Ubuntu 6.06 Live CD.

Props to Geoffrey for his great work with helping Rails newbies (and even “old timers” like me) get their feet wet.

Two Rails Testing Plugins

2009-09-23T21:31:48Z

I just released two Rails plugins that should make testing a little easier for some of you.

The test_helpers plugin makes it easy to DRY up your test cases by moving shared code into modules. It includes the handy dandy “test_helper” class method to make requiring and including a snap.
The abstract_testcases plugin makes it easy to create abstract test cases that don’t complain about tests not being defined. If you’d rather not go the module route, this is the plugin for you.

Installation is just like any other Rails plugin:

$ script/plugin source http://wiseheartdesign.com/svn/plugins/
$ script/plugin install test_helpers
$ script/plugin install abstract_testcases

Comments and feedback are welcome.

So You Want to Write a Book?

2009-09-23T21:31:49Z

Over on Dave Thomas’ Blog he’s writing a unique series of articles entitled So You Want To Write a Book. If you’ve ever thought about writing a technical book, or even a non-technical book you will definitely enjoy the series. Here’s an excerpt from his second article, The Hero’s Journey:

Every Hero’s Journey follows the same basic plan. We start by meeting the protagonist, an average person living a standard life. Suddenly, something bad happens to them, normally something unimaginable and outside their control. At this point, our character must make a decision. Do they cave, or do they commit to face the challenge—do the take a risk an embark on the journey?

Once they join the path, they face a series of challenges, often getting harder or more complex as the story progresses. By overcoming each, the hero gradually masters the initial problem.

But the story never ends there. Once the hero conquers all the problems, they face one last challenge. They must return to the real world, which often feels different to them. However, once back home, they get to apply what they learned on their journey. They are stronger.

What does this have to do with technical books?

Everything.

Because a good technical book is also a hero’s journey. The reader joins the book already faced with a major challenge—they need to learn some new technique or technology. Thy need to make a commitment to follow the path. Along the way, they need to learn stuff, try things, conquering increasingly difficult concepts and challenges. Eventually they graduate; they’ve learned what they came to learn. But they journey doesn’t end there. Like the hero, they then have to come home, bringing back what they learned.

Dave really has a talent for connecting with his readers. Read More…

John’s Essential Guide to CSS

2009-09-23T21:31:48Z

I once taught a workshop on CSS and in the process compiled a list of essential reading for people interested learning CSS. I’ve revamped the list below, adding a few additional articles, and reorganizing it a bit. Most of the articles are from A List Apart, but the volume of articles at A List Apart can can be overwhelming to people just to getting started. Consider this a pocket guide to the best of A List Apart with a few additional links thrown in to spice it up a bit.

The Basics

The Power of Floats and Backgrounds

Faux Columns
Creating Liquid Layouts with Negative Margins
Two Column Tableless Layout
CSS Design: Creating Custom Corners & Borders
Mountain Top Corners
CSS Drop Shadows (1, 2, and 3)

Print Stylesheets & Cross-Browser Compatibility

CSS Design: Going to Print
Print It Your Way
Alternative Style: Working With Alternate Style Sheets
Flash of Unstyled Content
The IE Doubled Float-Margin Bug
The Trouble With EM ’n EN
The Box Model Hack
Position Is Everything has fixes to bugs in IE, Opera, and Firefox

Lists, Rollovers, & Image Replacement Techniques

Secrets of Absolute Positioning

Additional Resources

The Terralien Crew

2009-09-23T21:31:48Z

Nathaniel Talbott (of Test::Unit fame) has put together an unbelievable crew that may be just what you need for your next Ruby on Rails project. Crew members include such notables as:

Myself
Bruce Williams (a popular blogger, programmer, and designer)
Matt McCray (the author of Comatose CMS and the Rails Theme Support Plugin)
Duff O’Melia (the creator of Soapadoo)
And others…

Terralien is a network of designers and programmers who specialize in developing Web applications with Ruby on Rails. We have a reputation for being able to deliver quality code on a deadline through rapid prototyping and incremental release cycles. Read more about the crew on the Terralien Web site.

Introducing FeedChamp: A Camping RSS Feed Aggregator

2009-09-23T21:31:49Z

I went camping last night and decided to see how easy it would be to create an RSS feed aggregator. After just a short time I had a working app and with some additional tweaking it became FeedChamp:

http://github.com/jlong/feedchamp

Have a look if you can. And if you want to help with its development I’ll gladly give you commit rights.

It’s not much right now, but perhaps with a little love from a few others it will turn into a nice app. For more info see the README.

Rails Needs Something Better Than Engines

2009-09-23T21:31:48Z

I need to apologize for exploiting a title like the above to introduce an article like this. The Rails Engine guys have taken a lot of flack for the work that they have done to make it easy to share code between applications and I don’t want to add to their misery. Instead, I’d like to use the issue to put the focus on something else.

The traditional argument against Rails Engines (as I understand it) is that prepackaged components are a pipe-dream. Components, particularly the way Rails Engines implements them are just too big. Every application will require something custom, and Rails Engines are too generic. Sure, they work well for getting you up and running, but what about down the road when you need to tweak something that the engine author hasn’t thought about yet? And after all, Rails is so easy to use why not take the agile approach and only develop what you need when you need it?

I’m interested in the Rails Engine argument because I think it exposes something about the philosophy that is driving Rails which may not be extremely obvious to those of us on the sidelines who are just trying to use Rails to build better Web sites and applications. That is that Rails is primarily designed for building completely custom green-field Web applications and it shows. When it comes to sharing code between applications the best thing Rails has to offer is generators. So instead of offering a login engine Rails offers a login generator.

Now don’t get me wrong here, generators are great for getting people up and running quickly. At first glance they offer exactly what Rails engines offer in that they allow you to get up and running quickly with prepackaged code and the added bonus that you can completely customize the generated code. But where they fall down is that they encourage rampant code duplication.

Take the login generator for example. How many of us use the generated login code nearly unmodified in application after application? Even if we customize the generated code is it not true that we often perform the same modifications again and again as we move from one application to another?

Folks we need something better. In a nutshell we need standard way to share views, models, controllers, and URLs between applications.

Of Snakes and Rubies

On December 3rd of last year I helped organize a debate between David Heinemeier Hansson and Adrian Holovaty (the creator of Django). We dubbed the event Snakes and Rubies and the video and audio from it are available here.

Even though I am an avid Rails user I was favorably impressed by Adrian’s presentation on Django and I must say that I am sad to see that more of the ideas in Django have not gained greater traction in the Rails community.

One of the things that Django does better than Rails at the moment is that it encourages you to subdivide your application according to components. In Django terms you don’t just create an “application” you create a Django “project” which contains multiple “apps”. An app is a full slice of the application and contains models, views, and controllers (actually in Django terms it contains “models”, “templates”, and “views”, but it is essentially the same thing).

Django’s model is perfect for Web sites because you can have mini apps for the admin, blog, and forum, and maybe one for that extremely custom event registration system that you have. Of course the great thing about this is that you can share these little mini apps across applications.

As I was working on this article I wrote Adrian Holovaty to ask him about this very point. He wrote back:

This was a big design goal when we were first putting together Django, because at our Web operation, we managed several sites—all of which used bits and pieces of the same functionality, but always a different mix. Indeed, as you point out, Django has a “batteries included” philosophy and ships with some apps that you can choose to use in your own projects.

And how easy is it to use another Django mini app in your own project? All you need to do is include it in the INSTALLED_APPS configuration variable. Here’s a small configuration snippet from the Django tutorial:

INSTALLED_APPS = (
  'django.contrib.auth',
  'django.contrib.contenttypes',
  'django.contrib.sessions',
  'django.contrib.sites',
  'mysite.polls'
)

There are four little mini apps there that are installed by default for the standard Django project: auth, contenttypes, sessions, and sites (I’ll bet you can guess what they do). Django also provides a rather powerful admin mini app that automatically creates an admin interface for your models. This is extremely helpful in that it allows you to concentrate on the Web site part of your application while leaving the admin part to Django. To see all of this in action check out the Django Screencast at throwingbeans.org.

Can Rails Take a Page from the Django Playbook?

I’m interested in all of this because of my work on Radiant (the content management system I developed for the Ruby Web site). Over the past several months I have been working on an extension system for Radiant that will allow others to develop mini rails apps that plug straight into a Radiant application. A Radiant extension is like a Rails plugin except that it supports additional models, views, and controllers (much like Rails Engines do, but with added benefits). The directory structure for a Radiant extension looks like this:

vendor/extensions/
  my_extension/
    app/
      controllers/
      helpers/
      models/
      views/
    lib/
    test/
    my_extension.rb
    Rakefile

The benefit that Radiant Extensions offer over something like Rails Engines is that they integrate into the Radiant administration system. Right now that integration is a little rough, but we hope to make it easier in the future. Even so, the progress that we have made is encouraging. Here’s a snippet which demonstrates adding a custom tab to the Radiant administration system:

class AssetManagerExtension < Radiant::Extension
  version "1.0"
  description "Provides asset management support for Radiant."
  
  define_routes do |map|
    map.connect 'admin/assets/:action', :controller => 'admin/asset'
  end
  
  def activate
    admin.tabs.add "Assets", "/admin/assets", :after => "Layouts"
  end
  
  def deactivate
    admin.tabs.remove "Assets"
  end 
end

Now the work on the Radiant extension system has been difficult. Rails doesn’t make it easy to allow views to reside in multiple places (there is only one template_root). Nor does it provide support for defining routes in multiple locations. Model reloading through the dependencies mechanism is also a difficult issue. Time and again I find myself twisting Rails’ arm to let me do what I want to do. I’ve had to hook into the Rails internals on multiple occasions (just like the Rails Engines people did).

I can’t help looking beyond Radiant though to wonder if built in support for this kind of thing would not be a benefit to the Rails community at large? I know Rick Olson is working on something like the Radiant extension system for Mephisto and I can see that other apps could be benefited by something similar. We’ve already seen Rails Engines and now there is also Appable Plugins. How many other approaches are necessary before the Rails community is able to settle on a standard?

As the Rails-Core team is looking towards Rails 2.0, perhaps it’s time to start thinking about restructuring Rails applications to take a more modular approach? Maybe there really is something to be learned from Django after all.

The Official Ruby Logo

2009-09-23T21:31:49Z

It’s official! Matz now owns the copyright on the Ruby logo the identity team did for the Ruby Web site. You can now download the logo and use it on your own projects (T-shirts, Web sites, etc…)—free of charge. It’s available under the Creative Commons Attribution-ShareAlike 2.5 License. Get the complete logo kit at rubyidentity.org.

Ruby Conf Facebook 2006

2009-09-23T21:31:50Z

Looking to meet up with an old friend at Ruby Conf? Interested in getting together with someone you’ve never met in the flesh, but know through electronic means? James Edward Gray has put together just the thing. If you are planning on attending Ruby Conf, head on over to the Facebook page on the Ruby wiki and add your photo.

Pop me an e-mail if you plan to be at the conference and want to get together. I’d love to talk about Radiant, Ruby, Rails, business, or any other topic that might interest you.

BTW, if you missed it before, the schedule for Ruby Conf is now up. Looks like I’m up to talk about Radiant on Friday afternoon.

Class-Level Instance Variables

2009-09-23T21:31:49Z

I’ve been doing a lot of metaprograming of late with Radiant and have gained a deep appreciation for class-level instance variables. If you haven’t done a lot with class variables, you probably won’t see much value class-level instance variables.

Maybe you’ve been playing around with those neat little class methods on your Rails model objects:

class Person < ActiveRecord::Base
  validates_presence_of :name
  validates_numerically_of :age
end

Or perhaps you’ve been experimenting with Dwemthy’s Array:

class Dragon < Creature
  life 1340     # tough scales
  strength 451  # bristling veins
  charisma 1020 # toothy smile
  weapon 939    # fire breath
end

Ruby makes creating this kind of Domain Specific Language a snap, but it’s not without it’s
pitfalls if you’ve never done it before.

At first glance you might think that you could store this kind of meta information in a class variable. Let’s take a simple example. You want to create the Creature class that Dragon inherits from. You might define your first attribute like this:

class Creature
  def self.life(life = nil)
    @@life = life || @@life
  end
end

Class variables are a convenient method of storing information in the class object itself. Since class variables look much like instance variables (in that they are preceded with two @ signs) you might be tempted to think that they are just instance variables for classes, but don’t be fooled! Class variables are shared variables. Every subclass of a superclass has access to the superclass’s class variables between superclasses and subclasses. That is, instead of getting a new version of the class variable every time you inherit from the superclass, you get the same version of the variable (not a copy).

In practice this means that class variables are a poor choice for storing meta data. In the example above if we inherit from Creature more than once we quickly see the problem:

class Dragon < Creature
  life 1340
end
class Gwythaint < Creature
  life 250
end
p Dragon.life  #=> 250 !!!!

Instead of getting 1340 for the dragon’s life, we get 250!! Again this is because class variables are shared between the superclass and every one of its subclasses. It has been suggested that an easy way to work around this problem is to use a hash and store class/value pairs for each of the subclasses:

class Creature
  @@lives = Hash.new
  def self.life(life = nil)
    @@lives[self] = life || @@lives[self]
  end
end

This works, but is somewhat verbose. Instead of using a class variable, you can use a class-level instance variable. What?! You thought instance variables were only for instances of the class? Look again:

class Creature
  def self.life(life = nil)
    @life = life || @life
  end
end

The above works because within the context of the class method the instance variable refers to a class-level instance variable—not a normal instance variable. In fact, any time you reference an instance variable outside a method definition you are working with a class-level instance variable:

class MyObject
  @class_level = "a class-level instance variable"
  
  def initialize
    @normal = "a normal instance variable"
  end
end
p MyObject.instance_variables #=> ["@class_level"]
p MyObject.new.instance_variables #=> ["@normal"]

Don’t be confused. Classes in Ruby are also objects. Just like other objects they have their own instance variables. The trick with class-level instance variables is that they are defined after the class is created. With a normal object this would look like this:

o = MyObject.new
p o.instance_variables #=> ["@normal"]
o.instance_eval do
  @new_var = "test"
end
p o.instance_variables #=> ["@normal", "@new_var"]

Most of the time you probably setup instance variables for an object when you initialize it. However, with classes, since instance variables are created after the class is initialized (which happens as soon as you open the class to define methods), instance variables will always be nil when you create a subclass:

class LargeGwythaint < Gwythaint
end
p LargeGwythaint.life #=> nil !!!!

Ruby gives us a nice way of working around this problem with a the inherited class method:

class Creature
  def self.inherited(subclass)
    subclass.instance_variable_set("@life", @life)
  end
end

Which works as expected:

class LargeDragon < Dragon
end
p LargeDragon.life #=> 1340

Of course, you can package all this logic up in its own module:

module InheritableTraits

  def self.included(base)
    base.extend ClassMethods
  end

  module ClassMethods
    def traits(*attrs)
      @traits ||= []
      @traits += attrs
      attrs.each do |attr|
        class_eval %{
          def self.#{attr}(string = nil)
            @#{attr} = string || @#{attr}
          end
          def self.#{attr}=(string = nil)
            #{attr}(string)
          end
        }
      end
      @traits
    end

    def inherited(subclass)
      (["traits"] + traits).each do |t|
        ivar = "@#{t}"
        subclass.instance_variable_set(
          ivar,
          instance_variable_get(ivar)
        )
      end
    end
  end

end

And make your life much easier:

class Creature
  include InheritableTraits
  traits :life, :strength, :charisma, :weapon
end

class Dragon < Creature
  life 1340     # tough scales
  strength 451  # bristling veins
  charisma 1020 # toothy smile
  weapon 939    # fire breath
end

class LargeDragon < Creature
  life 2000     # even tougher
  strength 821  # bulging veins
  charisma 715  # much more vile
  weapon 1213   # scorching flames
end

class Gwythaint < Creature
  life 250      # a large bird
  strength 340  # eats meat
  charisma 191  # ugly
  weapon 524    # beak & talons
end

class LargeGwythaint < Creature
  life 612      # gigantic!
  strength 429  # massive wings
  charisma 95   # extremely ugly
  weapon 842    # razor sharp talons
end

Now go read Why the Lucky Stiff’s article Seeing Metaclasses Clearly for more metaprogramming madness.

Ruby Web Site Goes Live!

2009-09-23T21:31:49Z

At long last, the Ruby site is live! The site is the collective work of the Ruby Visual Identity Team and is powered by Radiant. Kudos to everyone involved! Full write up here.

Rails and Vim

2009-09-23T21:31:48Z

This week I’ve been doing some work for a client where the most of the development needs to take place on Linux. It’s possible that I could have taken the time to stub out most of the code that depends on Linux, but instead I decided to do what I needed to do with with Vim over SSH. Vim is perfect for this kind of work. It’s not quite as friendly for Rails development as something like Textmate, but once you get used to it it can be quite useful. The fact that it works well remotely is a huge plus.

One of the problems I have with Vim is that it’s hard to open a bunch of related files. Vim doesn’t know much about Rails so opening a model and an associated test case is difficult. I often have to type something like this:

$ vi -o app/models/user.rb test/unit/user_test.rb

It’s even more verbose when I want to open all of the files associated with a controller. Imagine what I have to type when I want to open several controllers!

Today, I got tired of doing all that typing and created a small command to make this easier for me. I put it in a file which I named edit and placed it in my home directory’s bin (which is in my environment’s path). Here’s the source:

#!/usr/bin/env ruby

if ARGV.empty?
  puts "usage: #{File.basename($0)} string"
  puts "  Scans related Rails directories for " + 
         "files begining with string "
  puts "  and opens them in vi."
  exit
end

files = []
ignore = [/CVS$/]

# Find models or controllers that match args
ARGV.each do |arg|
  models = Dir["app/models/#{arg}*"]
  controllers = Dir["app/controllers/#{arg}*"]
  files += models + controllers
end

# Remove duplicates
files.sort!.uniq!

# Add unit tests for models
files.grep(%r{app/models/(.*?).rb}) do
  tests = Dir["test/unit/#{$1}_test.rb"]
  files += tests
end

# Add views and functional tests for controllers
files.grep(%r{app/controllers/(.*?)_controller.rb}) do
  views = Dir["app/views/#{$1}/*"]
  tests = Dir["test/functional/#{$1}_controller_test.rb"]
  files += views + tests
end

# Add views and fixtures for mailers
files.grep(%r{app/models/(.*?_mailer).rb}) do
  views = Dir["app/views/#{$1}/*"]
  fixtures = Dir["test/fixtures/#{$1}/*"]
  files += views + fixtures
end

# Again remove duplicates
files.sort!.uniq!

# Remove files that match ignore list
files.delete_if do |filename|
  result = false
  ignore.each do |i|
    if filename =~ i
      result = true
      break
    end
  end
  result
end

system "vi -o #{files.join(' ')}"

Now I can type:

$ edit account_c

And it will open account_controller.rb, account_controller_test.rb, and all of its views. I can also type:

$ edit account_m

And it will open account_mailer.rb, account_mailer_test.rb, all of its views, and all of its fixtures.

Much, much better.

Speaking at Ruby Conf in October!

2009-09-23T21:31:49Z

My Ruby Conf talk proposal was accepted! This will give me a chance to show of Radiant to the rest of the Ruby community in October. From the talk description:

Say the words “content management” in the ears of nearly any Web developer and they will likely frown and complain that most content management systems are too complicated, difficult to setup, or not very flexible. They have good reason to complain. Content management systems are notorious for containing every feature, except for the kitchen sink!

Enter Radiant—a light-weight content management system designed from the ground up to be simple to use, while remaining flexible and powerful. It’s a content management system that has borrowed much from Textpattern and MovableType while seeking to be more than a simple a blogging engine.

Radiant features:

The ability to arrange pages in a hierarchy

Layouts that can be used to apply a common look to a Web site

Snippets that are similar to partials or includes

Pages which are defined in multiple parts (body, extended, sidebar, etc…)

A custom tagging language (radius)

Special page-oriented plugins called behaviors

A simple user management/permissions system

Several domain specific languages which make it easy to write plugins

In his talk John will talk about the design and discovery process he went through while building Radiant and cover the guiding philosophies behind it. He will also demonstrate installation and setup from a Gem and talk about how Radiant can be extended. You will discover the joys of Radiant’s robust domain languages and revel in the ease with which you can create new content. He will also discuss how Radiant is being used on the new version of the main Ruby web site (http://ruby-lang.org) and explain how others are using it.

Reflections on Rails Conf 2006

2009-09-23T21:31:48Z

It’s been over two weeks since Rails Conf and I am only now finding time to write about it. Rails Conf is really the first technical conference I’ve attended and I must say that I found the whole experience invigorating. Watching the Rails community grow over the past two years has been quite an education for me. Getting a chance to meet in Chicago with so many of the people involved in the community will be something I long remember.

Probably the thing I valued most about the conference was the chance to hear more about the undergirding philosophies of Rails. This is what fascinates me about the Rails community. From the top to the bottom, the community is filled with people who are downright philosophical in their approach to software development. To people involved in the Rails community, software development shouldn’t be the complicated mess that characterizes so many projects. Code should be beautiful—-both in its utility and in its aesthetic. Rails developers’ guiding philosophy is a healthy mix of utilitarianism and idealism. In the Rails community it is called pragmatism.

Scott Raymond touched on this a bit in his talk on his work with Firewheel Design. He spoke about the principles of a man named Vitruvius who was an architect in the century before Christ. Vitruvius believed that there were three primary principles that governed good architecture (or design).

The first was firmitas. Firmitas is the latin word for firmness, stability; strength of mind, constancy. Vitruvius believed that the first principle of good design is that it must be structurally sound. What does it matter if the structure was beautiful if it collapsed because of poor construction? No, in order to be good the building must be structurally sound.

The second principle of Vitruvius was what he called utilitas. Utilitas is the latin for usefulness or utility. Today we might use the word usable and talk about the importance of usability. According to Vitruvius, a designer should strive to not only make the building structurally sound, but also useful. For if the building lasted a millennium, but was impractical for the purpose for which it was designed, what was the use?

The final princple of Vitruvius was venustas. The word venustas is from the same latin root that thename Venus comes from (Venus was the Roman goddess of love and beauty). Venustas means loveliness , charm, or attractiveness. According to Vitruvius a building failed to achieve the ideal if it was not also beautiful.

These three principles together (firmitas, utilitas, and venustas) form what I would call the Rails world view. The Rails community has a great focus on the utility of what they are doing. They are very conscious that code, particularly code that is introduced into the core, must have a clear purpose. They don’t spend a lot of time on features that people visualize as being merely “nice”. Every feature must help solve the practical problem at hand. At the same time the Rails community has spent a great deal of time developing a sense for the aesthetics of good design. So while focusing on the utility of what they are doing they don’t lose site of the ideal.

David spoke some about this a talk he gave at Snakes and Rubies back in December called Pursuing Beauty with Ruby on Rails. I heard echos of this throughout the conference. His keynote about incorporating a RESTful approach to Web services into Rails is a great example of this. On the one hand you have the ideal of the REST architecture and on the other you have the utilitarian question: Does it really make my life any easier? In his talk David discussed how he struggled with these two perspectives only to have it somewhat resolved as he realized that RESTful architecture often did lead to better, more robust design (which he went on to demonstrate).

I think that the great test for the Rails community in the coming months (and years) will be over whether we are able to maintain a healthy balance between beauty and utility. It was certainly fun to see this played out in the conference. I hope to be able to join in again next year.

Preparations for Rails Conf 2006

2009-09-23T21:31:48Z

I had fun today working on something I figure I’ll need at Rails Conf: business cards! Pictured right is the design I came up with. I especially like the tag-line: Beautiful Code. Smart Design.

I decided to go with a pure black and white design because I wanted to print them on my parent’s laser printer. (We have a bubble jet, but the results are hard to predict as it’s a Lexmark.)

The nice thing about the constraint of having to design the business cards in black and white is that it forced me to concentrate on the shapes and balance of the design vs. the color.

One thing I’ve been thinking about lately is how constraints can often push you to higher levels of achievement. I thought about this as I worked on a default design for a Radiant blog last week. The challenge there was to create a design that didn’t rely on images. Since Radiant doesn’t support storing images in the database yet, I didn’t want to add extra clutter to the public directory for an example template that a user may or may not choose to use. Working to keep the style of the template limited to what I could do with borders and backgrounds certainly expanded my mind to some different techniques. Constraints can do that—if you let them.

Something else arrived this week that I’m going to need at Rails Conf (pictured right). Just look at that beautiful ruby from the Ruby-Lang.org design! It makes me proud to be able to wear such a nice T-shirt.

What are you bringing to Rails Conf?

Poor Man’s Site Stats

2009-09-23T21:31:50Z

One of the strange things about the normal TextDrive plan is that they don’t provide any site statistics. Fooling around on the command line recently I came up with this:

$ cat logs/access_log | awk '{print $1}' | sort | uniq | wc -l
     538

Which tells me the number of unique IP addresses that have hit my site in the last day. Without getting too complicated I can also get the total number of unique visitors ever (or at least as far back as my logs go).

Here’s the code:

$ (cat logs/access_log && gzip -dc logs/access_log*.gz) | awk '{ print $1 }' | sort | uniq | wc -l
    3887

And this shows me the total number of unique visitors to RadiantCMS.org.

What are you doing on TextDrive?

RadiantCMS.org is Live!

2009-09-23T21:31:50Z

After many months of hard work it’s wonderful to have something to show you. Today, I released Radiant into the wild with its own Web site. It’s actually been around since last week, but only a small group of people have known of its existence.

The site sports a couple of sections that might be of interest to you:

Oh, and did I mention that the main site is actually powered by Radiant? I’ve taken a few screen shots of Radiant and the Web site and have posted them on Flickr.

Rails Documentation in CHM Format

2009-09-23T21:31:48Z

Delynn Berry just released another version of the Rails Documentation in CHM format:

http://delynnberry.com/pages/rails-chm-documentation

CHM format is Microsoft’s proprietary help format for Windows. It allows them to package up an entire Web site of information in a searchable package.

Unfortunately—er—fortunately, I’m on a Mac now. This makes viewing files in CHM format a little tricky. After a quick google search I was able to locate a couple of programs:

xCHM is nice, but doesn’t display documents using their original stylesheets.
Chmox allows documents to be displayed with their original stylesheets, yet allows only the viewing of CHM documents, not searching.
Chamonix happens to handle both search and display admirably, though the UI isn’t as spiffy as Chmox’s.

Are there other options?

Ruby Blue Textmate Theme

2009-10-22T12:38:18Z

When did the initial design for the Ruby-Lang Web site a year ago I created a Vim theme that mirrored the colors used in the little code window of the design. Times have changed and I am now an avid Mac user. With the change in operating system I’ve also picked up another text editor called Textmate. Today I decided to spend a little time on a theme for Textmate that mirrored the Ruby Lang design in the same way that my Vim theme did.

To install:

Download the Ruby Blue theme
Copy it into: /Applications/TextMate.app/Contents/SharedSupport/Themes/

Enjoy!

Update! The RubyBlue theme for various editors (including the RubyBlue Vim theme) is now hosted on GitHub.

Jim Weirich on Continuations

2009-09-23T21:31:50Z

I attended a Chicago Area Ruby Group meetup this evening. Joe O’brien was able to lure Jim Weirich up for the meeting to teach some deep Ruby magic. His topic was Demystifying Continuations. I throughly enjoyed his presentation style. He had a great mix of entertaining illustrations coupled with hands-on coding exercises.

He started off with a demonstration of the Amb library (Amb is an abbreviation of “ambiguous”), followed by a couple of other examples, and then gave us a half hour to pair up and write our own version of catch and throw using continuations (which was really invigorating—none of us finished, but a few people got pretty close). After that he had a lucid explanation of continuations based on one of the Zelda games where the game was completed by going back and forth in time (continuations are a sort of programming “time-machine”). He then finished the talk with a nice example of a console application and a similar web application (which used continuations to mimic the feel that you got in the console).

All in all a very good talk. I have a much better understanding of what continuations are (though I’m still not sure that I’m smart enough to know when to use one).

I had to ask Jim at the end of the talk if he’d implemented the one_step_back function using continuations or not! He just laughed.

Xara Open Sourced!

2009-09-23T21:31:50Z

Wow. This is good news! Xara, my favorite vector graphics program, has been open sourced. This means that there will one day be a Mac version of Xara!

My major regret about moving to Mac last fall was having to leave Xara behind. I figured I would have to get used to Adobe Illustrator or another such program. Now it looks like I won’t have to. Xara, Ltd. has announced plans to open source the product. I’m not sure what this will mean for Xara (the company), but it sounds like Linux will finally have a decent vector graphics program. They have already started work on the Mac version of the product as well.

Simply put, Xara is the best graphics program on the market today (in my opinion). It’s speed and ease of use is unrivaled by any other graphics program (including Illustrator). I haven’t been able to figure it out, but for some reason Xara has not been able to gain much market share among users in relation to Adobe Illustrator and Freehand. Perhaps it has something to do with the fact that Xara, Ltd.‘s only major program is a vector graphics program. They don’t have the ability to offer a suite of applications as Adobe and Macromedia have had.

Hopefully, the move to open source will be good for the program. It will certainly be good for the users.

Radius 0.0.2 Released

2009-09-23T21:31:48Z

I just released the next version of Radius. This is a minor update (mainly a little refactoring). From the change log:

Refactored Parser to use Context#render_tag instead of #send when rendering tags defined on a context.
UndefinedTagError is now thrown when Parser tries to render a tag which doesn’t exist on a context.
Added Context#tag_missing which works like #method_method missing on Object, but is tag specific.

Update: If you would like to help with the development of Radius, you can contribute to the project on GitHub: http://github.com/jlong/radius.

Radiant CMS Behaviors

2009-09-23T21:31:50Z

One of the features I’m really excited about in the CMS I’m building for ruby-lang.org is support for what I am calling “behaviors”. A behavior is a Ruby mixin of sorts that alters the way a page behaves on the site. It can do everything from changing the way content is rendered to setting headers on the response. Think of a behavior as a special plugin for pages.

This morning I finished coding a behavior for the Ruby site that will redirect you to a sub-folder of the site based on your prefered language (a browser configurable setting).

Above you can see that I’ve already started testing it. The CMS seems to be handling Japanese rather well.

Test Helpers for Rails

2009-09-23T21:31:49Z

In Rails, I occasionally find myself needing to share some specific functionality between tests. I usually take advantage of Ruby’s remarkable modules and make a module which defines the functionality that I need. I then use the include class method to import the functionality into the test case where I need it. When I create a module like this I call it a test helper.

For example, in my current project I have a Page model object for which I created the following test helper (abbreviated):

module PageTestHelper
  VALID_PAGE_PARAMS = {
    :title => 'New Page',
    :slug => 'page',
    :breadcrumb => 'New Page',
    :status_id => '1',
    :parent_id => nil
  }
  
  def page_params(options = {})
    params = VALID_PAGE_PARAMS.dup
    params.merge!(:title => @page_title) if @page_title
    params.merge!(:status_id => '5')
    params.merge!(options)
  end
end

In a test case, when I need access to the methods on the PageTestHelper module I just include it:

require 'test/helpers/page_test_helper'

class PageTest < Test::Unit::TestCase
  include PageTestHelper

  def setup
    @page = Page.new page_params
  end

  # etc...
end

My naming convention for test helpers is that they always include TestHelper in their module name. Sometimes I forget to include Test in the name when I include it in a test case which causes an error. Sometimes I forget to require the file which the test helper is stored in which also causes an error. This happens quite frequently.

Recently, I decided to make things easier on myself. In test_helper.rb (found in the test directory of every rails project) I inserted the following code:

require 'pathname'
TEST_ROOT = Pathname.new(
  File.expand_path(File.dirname(__FILE__))
).cleanpath(true).to_s

# Auto require test helpers
Dir[TEST_ROOT + '/helpers/**/*_helper.rb'].each do |helper|
  require helper
end

Also, amongst the other code that modifies Test::Unit::TestCase in test_helper.rb I added a test_helper class method:

# Class method for test helpers
def self.test_helper(name)
  name = name.to_s
  name = $1 if name =~ /^(.*?)_test_helper$/i
  constant = Inflector.constantize(Inflector.camelize(
    Inflector.singularize(name.to_s) + '_test_helper'))
  self.class_eval { include constant }
end

This was my first chance to use the marvelous Inflector class that Rails provides. It certainly makes it much easier to write class methods that work with symbols.

Now, when I need to use a test helper in a test case I do something like this:

class PageTest < Test::Unit::TestCase
  test_helper :pages

  def setup
    @page = Page.new page_params
  end

  # etc...
end

Meta-programming is marvelous. I no longer need to remember to require my test helpers and the test_helper class method removes the verbosity from the include. Much, much better.

How are you making testing easier for yourself in Rails?

Introducing Radius

2009-09-23T21:31:48Z

I’m pleased to announce the first release of Radius—a small, but powerful template language for Ruby similar to the ones used in MovableType and TextPattern. It uses tags similar to HTML, but can be used to generate any form of plain text (XML, e-mail, etc…).

Check out the documentation at:

http://radius.rubyforge.org

Or get started with the gem right away:

$ gem install radius

Radius was conceived and coded by the 3 founding members of the Chicago Area Ruby Group (myself, Brian Young, and Ryan Platte).

Update: Radius has moved to Github: http://github.com/jlong/radius.

Testing Rails Validations

2009-09-23T21:31:48Z

Today, I extracted some code from an older IBLP project and polished it up a bit for use on the Ruby Web site. It makes it quite easy to test validations on model objects in Rails. I present:

validation_helper.rb

When you include ValidationTestHelper into your test case you can access to two additional assertions: assert_valid and assert_invalid. Use them to assert that a model object is valid or invalid when a field is set to a certain value.

For example, suppose you have a model object that looks like this:

class Page < ActiveRecord::Base
  validates_presence_of :title, :slug, :breadcrumb, :status_id, :message => 'required'
  validates_format_of :title, :slug, :breadcrumb, :with => /^.*?\S.*?$/, :message => 'required'
  validates_format_of :slug, :with => /^[-_.A-Za-z]*$/, :message => 'invalid format'
end

To test it, first set the @model instance variable to an object that will validate without errors:

@model = Page.new(
  :title => 'New Page',
  :slug => 'new-page',
  :breadcrumb => 'New Page',
  :status_id => '1'
)

Were you to call @model.valid? at this point, it would return true. But hold steady, you are ready to write your first assertion:

assert_invalid :title, 'required', '', ' ', nil

This will assert that when the title field on your @model object is set to "", " ", or nil that a validation error occurs and that the error message is set to “required”. Note that the first two parameters are for the field name and message, while the parameters at the end are all values to test.

The next assertion, assert_valid, is useful for testing that an object should be valid when when a field is set to a value or series of values. For example, to test the regular expression that is being used to validate the slug field we can do:

assert_valid :slug, 'abc', 'abcd-efg', 'abcd_efg', 'abc.html'

This will set the slug attribute on the @model object to ‘abc’, ‘abcd-efg’, ‘abcd-efg’, and ‘abc.html’. Each time it will check to see if the model is valid with the new value. If it is not for any one of the values, the assertion will fail.

Pretty nifty, eh?

Here’s an entire test method for all of the validations shown in the model above:

def test_validations
  @model = Page.new(
    :title => 'New Page',
    :slug => 'new-page',
    :breadcrumb => 'New Page',
    :status_id => '1'
  )
  
  [:title, :breadcrumb, :slug].each do |field|
    assert_invalid field, 'required', '', ' ', nil
  end 
    
  assert_valid :slug, 'abc', 'abcd-efg', 'abcd_efg', 'abc.html'
  assert_invalid :slug, 'invalid format', 'abcd efg', 'abcd/efg'
    
  assert_invalid :status_id, 'required', '', nil
end

Special thanks to Ryan Platte for his part in conceiving and coding ValidationTestHelper.

Javascript Bliss—Well, Not Exactly!

2009-09-23T21:31:49Z

After a couple of days hard work I’ve finally got a tab control built that I like. It has been interesting, but mostly frustrating.

I haven’t worked enough with Javascript to be really comfortable with it yet. Each time I do something with it I find it frustrating. My brief brushes with it have been too short for me to attain a good level of proficiency with it.

The first couple of days with a new language can be very frustrating as you are learning the ins and outs. Much of the frustration comes because of the cryptic error messages that are being thrown your way every time you do something creative. Your frustration lessons substantially as you actually learn what the error messages mean, but alas, that doesn’t help the beginner.

One of the blessings for me this time has been delving into Sam Stephenson’s amazing Prototype library. With a little sytatic sugar He almost makes Javascript feel like Ruby. He makes clever use of hashes to give you the impression that you are doing Object-Oriented programming and even turns anonymous functions into Ruby-like blocks. Javascript with Prototype is still very verbose compared to Ruby, but it is much, much nicer.

One of the hard things about Prototype is that it doesn’t come with any documentation. A couple of people have taken it upon themselves to document the library and there are even some nifty unit tests, but the best knowledge still comes from reading the source. If you are anxious for more this site may be able to help, or, you can stay on the cutting edge by following the feed on del.icio.us.

Rails Badges

2009-09-23T21:31:49Z

Someone asked for “I wish this site were powered by Rails” badges on Ruby-Talk today so I thought I’d oblige them:

Enjoy! :-)

Creating a New Page in Radiant CMS

2009-09-23T21:31:49Z

Here’s another comp for the Ruby Web site administration system.

One of the aspects of a page that I hope to really leverage is this concept of sections. Each page will have multiple sections which contain appropriate content. You can see this on the tabs: “Body”, “Expanded”, “Summary”, and “Sidebar”. You will be able to add custom sections or use one of the predefined sections.

When a page is rendered using a Template, the Template can render the sections however it chooses. Or, when a page’s content is included in another page, the page will be able to choose to render specific sections and exclude others. For example a blog index could choose to render only the “Summary” section for each article.

First Look at Radiant CMS

2009-09-23T21:31:49Z

I’ve decided to follow 37signals’ advice and draw out “screens” for the admin system of the Ruby site before I do any major coding.

I spent the afternoon drawing a few screens out on paper. This evening I took one of the screens and fleshed it out in Fireworks. Pictured left is the final result. It’s a comp of the first page you will see after you login. It reveals the main contours of the way I picture the CMS working.

The first three tabs across the top are for the three main model objects: Pages, Templates, and Snippets.

Pages are the meat of the system. Each page will store the Textile formated data for a physical page on the Web site. Pages will be able to contain other pages using a simple template language. It will be easy to use the template language to create a blog index which lists the most recent articles.

Each page will also be able to specify a Template with which it should be rendered. This should make it easy to repeat a look across several pages.

Pages will also have the ability to include the content from Snippets—little bits of content that will be repeated accross several pages.

I also spent some time today thinking about a name for my new CMS. I’d like to use a term from the gemstone world. Scanning through the terms in a jewelry glossary I ran accross a couple of words that would make really good names.

The first one that I liked was “brilliant”. Brilliant cut is the superman shaped gemstone. Brillaint CMS has a nice ring to it, but it does sound a little vain.

The other option that I liked was “radiant”. Radiant cut is a squarish shape. I don’t like the shape as much a brilliant cut, but the name is rather nice. Unless someone has other suggestions I think I am going to call it Radiant CMS.

Snakes and Rubies Audio and Video

2009-09-23T21:31:50Z

Jacob Kaplan-Moss just anounced that he has posted the audio and video from the Snakes and Rubies event!

If you didn’t hear about it the first time, Snakes and Rubies was a mini-conference of sorts that I helped coordinate for peole interested in Django and Rails.

We invited Adrian Holovaty (lead developer of the Django project) and David Heinemeier Hansson (creator of Rails) to come and share with us about their work and the future of Web application development.

The event was a blast and much was learned about the differences and similarities of Django and Rails. If you haven’t already, I’d encourage you to head on over to the Snakes and Rubies Web site and download the audio or video from the event.

Update: The Snakes and Rubies website is no longer online. You can download the audio and the video from the event on the Django project’s website here.

Testing 1-2-3… Is This Thing On?

2009-09-23T21:31:50Z

Testing 1-2-3… Is This Thing On?

Pardon the dust! I’m in the midst of revamping this very Web site. If you see something out of place this is probably why. (Don’t let that stop you from letting me know though.)

You may have noticed that I’ve added a Typo powered blog and some additional information. The old portfolio is still pretty much intact. I’d like expand it with more information, but that will have to wait.

The main reason for this update is the blog. Over the next month or two I’m going to be working on the backend for the new Ruby Web site. I wanted a place to chronicle my progress.

Stay tuned for more.