Sass 3.2 is going to ship with an awesome new feature: blocks. Just like Ruby. Instead of yield, you use @content. The rest is exactly the same. You can place anything inside your blocks: selectors (like table.products) and rules (like border: 1px solid gold).

The Sass documentation mentions that you can use it to specify it for IE6 compatibility, but I like it most for making my design responsive. Just create a mixin that places the @content inside the @media directive.

The following scss code defines mixins for small screens and big screens. You could even go further and define 3 categories, really small screens for mobile phones, medium sized screens like tablets and small desktop windows, and your normal big layout.

$site-width: 1000px;

@mixin small-screen {
  @media only screen and (max-width: $site-width + 99px) {
    @content;
  }
}

@mixin big-screen {
  @media only screen and (min-width: $site-width + 100px) {
    @content;
  }
}

I add around 100px, which makes the switch between big and small screen styling happen a bit earlier. This makes it always have a bit of margin, which I like.

For smaller screens, it is common to make the site fill the width of the window and place columns underneath each other. The following code does that.

$grid-count: 12;

.container {
  @include big-screen {
    width: $site-width;
    margin: 0 auto;
  }
  @include small-screen {
    width: auto
  }
}
.column {
  @include big-screen {
    width: $site-width / $grid-count;
    float: left;
  }
  @include small-screen {
    width: auto;
    float: none;
  }
}

I have found that it with this approach, it is easiest to split the CSS into layout and styling. The styling, like colors and font-size, is probably the same on every screen, but the size, padding and floating of elements will change depending on the screen size.

In this case, I'd like place the @media directive around the tags, creating a clear distinction between layout for big and small screens:

$grid-count: 12;

@include big-screen {
  .container {
    width: $site-width;
    margin: 0 auto;
  }
  .column {
    width: $site-width / $grid-count;
    float: left;
  }
}

@include small-screen {
  .container {
    width: auto;
  }
  .column {
    width: auto;
    float: none;
  }
}

It depends on your site, which approach works best for you. It will result in the same CSS. The @media directive is not allowed nested. Sass will automatically correct it if for you anyway. You got to love Sass for things like this!

I've seen some projects with really complicated mixins, taking in really complicated arguments. This will definitely clean this up.

Another reason might be that you're using ActiveRecord without Rails. This might be in another framework like Sinatra, or in a gem. Without Rails you might be lost a little on how to set up ActiveRecord.

Preparation

First, install the gems you'll need. This should be enough:

gem install activerecord rspec sqlite3

I'm using a really simple spec to get up and running. I'm even defining the model inside the spec itself, just because it's easier to get started:

# spec/widget_spec.rb

class Widget < ActiveRecord::Base
  validates_presence_of :name
end

describe Widget do

  it "requires a name" do
    subject.name = ""
    subject.should have(1).error_on(:name)
    subject.name = "Foo"
    subject.should have(:no).errors_on(:name)
  end

end

Loading ActiveRecord

Run this spec on its own, simply by running:

rspec spec/widget_spec.rb

You'll see that it doesn't even know ActiveRecord yet.

Let's create a support file for specs that need ActiveRecord. I put this in spec/support/active_record.rb.

For now, this file will just require ActiveRecord for us:

# Create the file spec/support/active_record.rb:

require 'active_record'

We need ActiveRecord before we define our model, so require the support file at the very top of your spec:

# Prepend to spec/widget_spec.rb:

require 'support/active_record'

RSpec automatically adds the lib and spec directory to the load paths, so these files can be required easily.

Connecting with the database

When we run the spec now, it should tell us that ActiveRecord has no connection with the database. I'm going for a SQLite database in memory, so let's define the connection in the support file.

# Append to spec/support/active_record.rb:

ActiveRecord::Base.establish_connection adapter: "sqlite3", database: ":memory:"

When we run it now, it will tell us that we don't have a table yet.

Run migrations

If you have migrations, you can run them with just one simple line:

# Append to spec/support/active_record.rb:

ActiveRecord::Migrator.up "db/migrate"

You can also just create the migration inline, which is probably even simpler:

# Append to spec/support/active_record.rb:

ActiveRecord::Migration.create_table :widgets do |t|
  t.string :name
  t.timestamps
end

If you have a schema.rb file, you can simply load it:

# Append to spec/support/active_record.rb:

load "path/to/db/schema.rb"

Getting some RSpec helpers

When we run it now, we'll see the familiar output of the migrations. The next error we get is an undefined method error_on.

If your project already depends on rspec-rails, you can simply require the file:

# Append to spec/support/active_record.rb:
require 'rspec/rails/extensions/active_record/base'

If you're not in a Rails project (but in a Gem or Engine), you might not want to have rspec-rails as a dependency, because it adds a lot of extra dependencies. You can just define the error_on method yourself, by copy-pasting it:

# Append to spec/support/active_record.rb:

module ActiveModel::Validations
  # Extension to enhance `should have` on AR Model instances.  Calls
  # model.valid? in order to prepare the object's errors object.
  #
  # You can also use this to specify the content of the error messages.
  #
  # @example
  #
  #     model.should have(:no).errors_on(:attribute)
  #     model.should have(1).error_on(:attribute)
  #     model.should have(n).errors_on(:attribute)
  #
  #     model.errors_on(:attribute).should include("can't be blank")
  def errors_on(attribute)
    self.valid?
    [self.errors[attribute]].flatten.compact
  end
  alias :error_on :errors_on
end

This should be enough to get your spec running! And look how fast it is! Clearly, loading ActiveRecord isn't what makes Rails startup time slow.

Transactions

The last part you'll want is to run your specs in transactions, so that one spec doesn't influence the others. To do this, we'll make a simple around filter:

# Append to spec/support/active_record.rb:

RSpec.configure do |config|
  config.around do |example|
    ActiveRecord::Base.transaction do
      example.run
      raise ActiveRecord::Rollback
    end
  end
end

The ActiveRecord::Rollback exception will be caught by the transaction block and roll back all the database changes after each spec.

Profit!!!

Now, you might want to clean it up a little more, but this should be enough to getting you started testing your ActiveRecord classes in (relative) isolation. And the cool thing is, running these specs hardly takes any time!

If you have any tips, please share them in the comment-section below.

If you want to know more about how ActiveRecord works, I can recommended this good series of posts by Robin Roestenburg. In the course of several blog posts he dives into the inner workings of ActiveRecord, even refactoring parts of it.

Next up: Testing controllers in isolation. Stay tuned!

Why groups?

Speed: Requiring gems can get slow, even more so when you have a lot of them. Groups help you require the gems only when they are needed.

This is especially true if you use Ruby 1.9.2. In this version of Ruby, the require statement can get very slow. The number of gems inside a project can get rather large, so loading only the gems that are needed can improve Rails' boot time immensely.

Safety: Some gems provide functionality that you don't want to enable in certain cases. Take webmock, for instance. This handy gem blocks all outgoing network traffic inside your application. Very handy for testing purposes, but not in production!

Clarity: The group name can act as documentation. If you ever wonder what a gem does and where it is used inside your application, a group can tell you a lot.

The Basics

You probably already know the basics of groups in Bundler. Rails already uses groups out of the box. If you have a group named after the Rails environment, it will get loaded.

If you have gems that are used in the application itself, your best bet is to put them outside of any group. I'm talking about gems like Rails itself, devise, will_paginate, and so on.

Gems without a specified group are placed in the :default group and will be loaded in every Rails environment.

This is your safest choice. When in doubt in which group to place a gem, don't use a group at all.

Adding custom groups

You can easily add other groups. For example, Rails 3.1 and up have gems in the :assets group. This line from config/application.rb instructs Bundler to only require the assets in development and test environments.

Bundler.require(*Rails.groups(:assets => %w(development test)))

You can add your own groups and let Bundler require them automatically.

Here is an example:

group :security do
  gem 'devise'
  gem 'cancan'
end

group :monitoring do
  gem 'newrelic_rpm'
  gem 'airbrake'
end

So, we want security to always be there, but monitoring only in production. Then your configuration inside config/application.rb should read:

groups = {
  assets:     %w(development test),
  monitoring: %w(production)
}
Bundler.require(:security, *Rails.groups(groups))

You can group together gems per type of gem, like :assets, or per part of the application, like :security, or :backend. See what makes the most sense for your application.

Grouping related gems

When you use Cucumber, Spinach, or Turnip, you'll end up with a set of related gems. When you cram all of these into the test group, they'll end up loaded in your RSpec tests too.

You could create a group for this:

group :cucumber do
  gem 'cucumber-rails'
  gem 'capybara'
  gem 'launchy'
  gem 'database_cleaner'
end

This group won't be loaded. If you want to require these gems inside your Cucumber tests, add this line to features/support/env.rb:

Bundler.require(:cucumber)

You could do this for other groups of related gems too. For instance, you might have a couple of scripts or rake tasks running periodically that use gems that you don't use in the rest of your application. With groups you can require them at the right moment.

Other gems

There are also some gems that are only used from the command line. An example might be thin, or capistrano. Here are some more examples:

group :capistrano do
  gem 'capistrano'
  gem 'capistrano-ext'
  gem 'capistrano_colors'
  gem 'capistrano_chef_solo'
end

group :test_tools do
  gem 'autotest'
  gem 'spork'
  gem 'spec_coverage', :platforms => :ruby_19
  gem 'fuubar'
  gem 'fuubar-cucumber'
end

There is no need to add :require => false to every gem, because it won't get loaded anyway. These gems either provide a command line tool like cap or autotest, or they will be required manually at a specific moment, only when they are needed.

Console Extensions

There are a number of gems that will spice up your IRB session, like awesome_print, hirb and wirb. You can load them inside your ~/.irbrc file, but if they are not present inside your Gemfile, they won't be available inside projects using Bundler.

A group can play a part in solving this problem.

group :console do
  gem 'wirb'
  gem 'hirb-unicode'
  gem 'awesome_print', :require => 'ap'
end

Now, to automatically load them in Rails, but only when opening the console, open up config/application.rb. At the top you'll find an if-statement checking for Bundler. Inside this block, you can add this piece of code:

Class.new Rails::Railtie do
  console do |app|
    Bundler.require(:console)
    Wirb.start
    Hirb.enable
  end
end

This creates an anonymous Railtie in which you can specify what happens when the console is started. Here you can require all your console extensions and perform additional configuration.

Railties need to be loaded before you define your Rails application, or else you're too late and the console block won't be executed.

You can also build your own backend. Building your own gives you maximum freedom. It requires a bit more work, but it might be preferrable, especially if your customer also needs to work with it.

There are some awesome tools out there to help you build your own backend. I'll show you how I would go about making such a backend. I'm using Rails 3.1 (the rc5 at this moment) on Ruby 1.9.2. I might gloss over some details here and there, so use your own expertise to fill in some gaps.

The entire backend is available on Github. I have also published the end result on Heroku You can log in with username "frodo" and the password "thering".

A new application controller

A backend can be seen as a different application inside your regular application. That's why I start out with a fresh application controller, just for the backend, from which every other controller can inherit.

rails generate controller backend/application

Because I don't want to be bothered by anything from the normal application controller, I choose to inherit straight from ActionController::Base:

class Backend::ApplicationController < ActionController::Base
  protect_from_forgery
end

All routes should be in the backend too. This is extremely simple. Just wrap your normal routes inside a namespace block:

SimpleBackendExample::Application.routes.draw do

  root to: "home#index"
  # other routes go here

  namespace :backend do
    root to: "products#index"
    resources :products
    resources :widgets
  end

end

Now it's time to implement these resources.

Resources

Usually, you'll need a lot of CRUD resources inside your backend. I prefer to use the inherited_resources gem.

First, make sure you install it, by adding it to your Gemfile and running the bundle command:

gem 'inherited_resources'

Next, I prefer to make a base class for all resource controllers too. This is the ideal place for configuring Inherited Resources. Every CRUD controller can inherit from this one, while other controllers can inherit from Backend::ApplicationController.

rails generate controller backend/resource

Normally inherited_resources advices you to inherit from InheritedResources::Base. In turn, InheritedResources::Base inherits from your own ApplicationController. But here we want to inherit from Backend::ApplicationController. Luckily, we can do that:

class Backend::ResourceController < Backend::ApplicationController
  inherit_resources
  respond_to :html
end

Now, if we want to create a CRUD controller, we can do that by inheriting from Backend::ResourceController.

rails generate controller backend/products

The controller code is now really simple:

class Backend::ProductsController < Backend::ResourceController
end

View inheritence

You're now free to make the views for every controller. This can be really boring, so it's a good thing that Rails 3.1 ships with a feature called 'view inheritence'. This means that if a view does not exist, it will go up the inheritence tree to find a view to render.

This means that we can create some simple views for our Backend::ResourceController and every resource controller can render those. Only if we want something different, we need to make a specific view. This means though that our views need to be agnostic about the model they're handling.

Inherited Resources provides a lot of helpers to make views agnostic of the model they are rendering. In the index action you have access to collection, in the other actions you can reference resource. There are also URL helpers like resource_path and collection_path.

But if we're agnostic of the model, we need to use inflection to see which fields we can render. We can ask the resource_class to see what attributes are defined. This will include automatic fields like id, updated_at and created_at too. But even without these fields, the list can become a bit too long for index pages.

In fact, I've found that the list of columns to display on the index page is something you want to customize just about every time. So let's build a simple view to be overriden in every controller. In app/views/backend/resource/index.html.haml, I put the following:

= render "index", attributes: attributes

And add to the Backend::ResourceHelper:

module Backend::ResourceHelper

  def attributes
    resource_class.attribute_names - %w(id created_at updated_at)
  end

end

This will render the index-partial with the first three attributes of the model. The index-partial then looks like this:

%table
  %thead
    %tr
      - attributes.each do |attr|
        %th= resource_class.human_attribute_name(attr)
      %th  
  %tbody
    - collection.each do |resource|
      %tr[resource]
        - attributes.each do |attr|
          %td= resource.public_send(attr).to_s.truncate(20)
        %td
          = link_to 'show', resource_path(resource)
          |
          = link_to 'edit', edit_resource_path(resource)
          |
          = link_to 'destroy', resource_path(resource), method: :delete, confirm: "Are you sure?"

I can now easily override this per controller. If, for example, I wanted to only show the name column for products, I could create app/views/backend/products/index.html.haml with only this line:

= render "index", attributes: %w(name)

The show action probably wants to list everything, so it'll be something like this:

%dl
  - resource_class.attribute_names.each do |attr|
    %dt= resource_class.human_attribute_name(attr)
    %dd= resource.public_send(attr)

Simple Form

My favorite gem for creating forms is simple_form. It is really flexible. Install it, by adding it to your Gemfile and following the instructions in simple_form's README.

Our form partial in app/view/backend/resource/_form.html.haml will look something like:

= simple_form_for [ :backend, resource ] do |f|
  - attributes.each do |attr|
    = f.input attr
  = f.submit

And the new and edit pages will simply render this partial, and look similar to the index template:

%h2 Edit #{resource_class.model_name.human}

= render "form", attributes: attributes

Scopes & Pagination

For the index page, you'll need pagination too. My favorite choice is Kaminari in combination with has_scope:

gem 'kaminari'
gem 'has_scope', git: 'git://github.com/plataformatec/has_scope.git'

I'm using the version of has_scope directly, because it has a fixed a deprecation error.

Next, implement it by adding this line to Backend::ResourceController:

has_scope :page, default: 1

And put it in your view as well:

= paginate collection

Super easy! Don't forget to run the generators provided by kaminari to configure it further, if you want.

Responders

To get flash messages, we'll need to create a responder. The responders gem has a generator for this, which you should use. We'll need a small tweak to get it to work:

# app/controllers/backend/responder.rb
class Backend::Responder < ActionController::Responder

  include Responders::FlashResponder
  include Responders::HttpCacheResponder

  def initialize(*)
    super
    @flash_now = :on_failure
  end

end

I've renamed it to make it clearer that this is the responder for the backend only. For the reason of the initializer, see this pull request.

To get flash messages for validation errors, you need to customize the locale file that was generated, to include alert messages for create and update:

en:
  flash:
    actions:
      create:
        notice: '%{resource_name} was successfully created.'
        alert: '%{resource_name} could not be created.'
      update:
        notice: '%{resource_name} was successfully updated.'
        alert: '%{resource_name} could not be updated.'
      destroy:
        notice: '%{resource_name} was successfully destroyed.'
        alert: '%{resource_name} could not be destroyed.'

Next, you'll need to add it to Backend::ResourceController, because Inherited Resources will otherwise override it with its own responders.

# app/controllers/backend/resource_controller.rb
self.responder = Backend::Responder

By adding the HttpCacheResponder, the website speeds up quite a bit. It will set the appropriate headers, like ETags, based on the resource you're viewing. This means that if you're viewing a page for the second time, you don't have to render the view anymore and your Rails app only sends a 304 Not Modified to your browser. If you're viewing my example on Heroku, you can see Varnish adding another layer of caching on top of it, using those ETags. It makes your backend really snappy!

Authentication

Our backend needs to be private, so we'll need some form of authentication. In most cases (more than you'd think even) basic authentication will work. This can be easily done inside the Backend::ApplicationController, by adding one simple line:

http_basic_authenticate_with name: "frodo", password: "thering"

If you're opting for a more complex system, with users and so on, I would go for Devise. The powerful thing about Devise is that you can really easily create a multiple types of users who have nothing with each other in common. They each have their own tables and sign in pages.

You can configure Devise to use your own controllers instead of its own, so you can really separate the admins from the rest of the system.

To generate administrators:

rails generate devise admin

Then I prefer to place the views inside the backend namespace as well. This means that I need to recreate the controllers that Devise provides. This sounds like a lot of work, but it also means that I can really easily customize it. Rather than depending on the customization hooks that Devise provides (they are really good), I can override certain methods inside the controller. Devise's code is so nice, I can easily override just the functionality I like to make it work.

To do this, place the devise_for route inside your namespace:

namespace :backend do
  devise_for :admins, skip: :registrations
end

And create controllers like this:

class Backend::SessionsController < Devise::SessionsController
  layout "backend/sign_in"
end

As you can see, I can now easily define the backend layout inside the controller, without having to revert to a more complex hook method. Remember that, due to view inheritance, you don't need to install the views. The original views that Devise provides are in the inheritence tree, so they will be rendered if you don't provide your own.

And don't forget to activate the authentication to every controller in the backend, by adding to your Backend::ApplicationController:

before_filter :authenticate_admin!

Personally, I would try to avoid going with Devise and stick to basic authentication as long as possible. That's also one of the main reasons I don't tend to go with the of the shelf admin solutions. They require Devise. It adds a lot of overhead that I don't usually need. You might also want to check out the Railscast on creating your own authentication system.

Styling

Update I've switched to using the Twitter Bootstrap styling. It's a lot prettier and cleaner than wep-app-theme. Have a look at this commit to see what I've had to do. You can skip this chapter if you like now.

So, we now have a nice backend system in place. But it still looks ugly. Time to add some style! Let's get something of-the-shelf to get going. I like web-app-theme. This will make our backend look just like RailsAdmin.

The easiest way to get a theme, I found, is to just clone web-app-theme somewhere and copy over the files you need. Rails 3.1 has the asset pipeline, so this means we can have a nice spot to put them: in the vendor/assets directory.

mkdir -p vendor/assets/stylesheets/web-app-theme
cp ../web-app-theme/stylesheets/base.css vendor/assets/stylesheets/web-app-theme/
cp ../web-app-theme/stylesheets/themes/default/style.css vendor/assets/stylesheets/web-app-theme
cp -r ../web-app-theme/stylesheets/themes/default/images vendor/assets
cp -r ../web-app-theme/stylesheets/themes/default/fonts public

You need to change styles.css a bit to change the paths to images and any custom fonts. In Rails 3.1, assets aren't located in an images directory, but in /assets. Fonts are not served through Rails, so those should go inside the public directory. A quick find and replace should do the trick just fine.

Next up is the layout. You can install web-app-theme as a gem in your project and let it generate the layout for you. This is not necessary. You can find a layout inside lib/generators/web_app_theme/theme/templates/layout_admin.html.erb. Copy it to app/views/layouts/backend/application.html.erb. Remember, view inheritance will automatically pick it up for every controller in the backend. I'm a Haml user, so I converted it using html2haml:

gem install hpricot ruby_parser
mkdir -p app/views/layouts/backend
html2haml ../web-app-theme/lib/web_app_theme/theme/layout_admin.html.erb > app/views/layouts/backend/application.html.haml

You have some cleaning up to do. Or just grab the one I've already made! Afterwards, look at the classes web-app-theme uses and apply it to your views as well.

To include the stylesheets, I just include one inside the layout:

= stylesheet_link_tag "backend"

In app/assets/stylesheets/backend.css, I use the awesome power of Sprockets to include the rest:

/*
 *= require web-app-theme/base
 *= require web-app-theme/style
 *= require_tree ./backend
 */

It also includes every css file I have inside the app/assets/stylesheets/backend directory, which is where future customizations will go.

I also use the same structure for javascripts, creating the following app/assets/javascripts/backend.js:

//= require jquery
//= require jquery_ujs
//= require_tree ./backend

This styling would give you enough to start your backend. There are a ton of customizations you can do, but I'll leave that up to you.

More namespacing

Because of the way namespacing works, you can customize your models for use in the backend. This allows you to add methods for use in the backend only, without cluttering your classes in the rest of the application.

# app/models/product.rb
class Product < ActiveRecord::Base
  has_many :widgets
end

# app/models/backend/product.rb
class Backend::Product < ::Product

  def deactivate_all_widgets
    widgets.each(&:deactivate)
  end

end

Because Inherited Resources is in the Backend namespace, it will use this class instead of the normal one.

You can also make use of lexical scoping to implicitly reference the namespaced classes. This is quite subtle, so it's a bit error-prone.

In the following example, @product will be an instance of Backend::Product:

module Backend
  class ProductsController
    def new
      @product = Product.new
    end
  end
end

In the next example, @product will be an instance of ::Product, because only the class and module keywords will create the scope for you. You are scoped inside Backend::ProductsController, but not really inside Backend.

class Backend::ProductsController
  def new
    @product = Product.new
  end
end

Also, you don't need to explicitly tell the form that its resource needs to be scoped to the backend. There are a lot of tiny nuances that change when you go this route. So beware. Ruby's namespacing is powerful, but combined with Rails' naming conventions it can also be a bit confusing at times.

Conclusion

Making your own backend is really easy. Sure, there are out of the box gems that do all this for you and more. But if you want more control, yet still get some of the productivity, Rails 3.1 has all the tools to make it work. All the gems I've used fit nicely together. Sure, most of them are made by José Valim, or by his company Plataforma, but it shows how extensible the Rails platform really is.

Whether to choose for a custom solution or something more automatic is something you should decide on a per-project basis. If you're building it for non-technical customers, doing it yourself might be the better solution. But products like RailsAdmin give so much nice features, you'd better make sure.

As much as I agree with this, I think there is a way of using Cucumber that makes it a valid option to use it in more cases than you think. It's for doing Behavior Driven Development with a high focus on the problem you're trying to solve. Let me explain what I mean by this.

Using steak for integration tests

Most examples of Cucumber use the web steps that the generator of cucumber-rails provides. These are fairly low level: click a link, fill in some fields, submit and check the outcome. Writing features like this is easy. All the parts are present by default, so you can get some work done quickly. But if you do it like this, there is no reason why you should use Cucumber. You're adding complexity (features and step definitions) which don't add anything compared to Steak.

In fact, Ruby is a very clean language, and the Capybara API is very clean too. Even if you have a customer that wants to read your features, they can read and write for Steak as well, with very little extra effort. So, if you're only in it for the integration testing, Cucumber will only make your life more complex. And we don't want this extra complexity, unless there is a good reason for it.

On behavior and implementation

But there is more to writing acceptance tests, or doing BDD and TDD. One of the more interesting parts is to discover the design of your code (or the structure of your application). To do this in unit tests, you need to focus on behavior, rather than implementation.

For example: this means that you don't want to test if the results are an empty array, but you should just test that it is empty. The fact that you happened to have implemented this with an array is not important.

it { should == []    } # bad: testing implementation
it { should be_empty } # good: testing the behavior

The same is true for Cucumber. But here we mostly care about the behavior for the feature. Not the fact that you happened to have implemented it as a website with links and buttons. Take a look at the very first example the RSpec book gives of Cucumber:

Feature: pay bill on-line
  In order to reduce the time I spend paying bills
  As a bank customer with a checking account
  I want to pay my bills on-line

  Scenario: pay a bill
    Given checking account with $50
    And a payee named Acme
    And an Acme bill for $37
    When I pay the Acme bill
    Then I should have $13 remaining in my checking account
    And the payment of $37 to Acme should be listed in Recent Payments

There are no implementation details here. No following links, no filling in fields, no pressing buttons. This is in my opinion the biggest reason to use Cucumber. It focusses you to towards what you are actually trying to achieve. The step definitions are here to fill in the details.

When you use Cucumber this way, it opens the way for real BDD. You're describing what you want to achieve, not how you want to achieve it. This is in my opinion the unique selling point of Cucumber. It's a very nice framework to separate the implementation from your intention. Focussing on your intentions (in a way that can be automated) is the essence of BDD.

But why do this in a natural language?

You could also do this with Steak of course. It's just Ruby, so you could add some code to hide some of the details to helper methods. And because it is Ruby, you're probably tempted to do it earlier than with Cucumber. You are now programming, so your programming instincts will come in to play, making the features clean and simple. We do this all the time. So why should you write in a natural language?

You're doing it human language, so write it down in the same way you are talking about it. Think about how you would explain using the website to the stakeholder of the feature. It doesn't matter that the stakeholder doesn't care about your nifty cucumber features. How would (s)he explain it to you?

Also, the natural language is closer to your understanding of the problem you're trying to solve. When I write in code, my programmer side becomes active. My programmer side is focussed on solutions. But I want to delay the solution as long as I can, until we have a decent understanding of the problem. So by not writing in code, you can focus more on the problem, rather than on the solution.

Cucumber provides a hard boundary. Your intent is in the feature files, your implementation is in step definitions. And it is helpful in doing this too; it provides you with the right step definition when it encounters something that it doesn't know yet. It's really easy to keep the feature files clean and simple. I will grant you that organizing your step definitions requires a fair bit of OCD.

Make no mistakes about it: it isn't easy. It's very hard to figure out the right way of describing your problem, using the right language and in such a way that Cucumber can make sense of it too. But that is what is to be expected. If your problem is hard, than trying to figure out what your problem entails and describing it in a way that isn't ambiguous, should to be hard too. But you should make the effort to really get the language right, because the implementation that follows will reflect the way you've described it earlier. And besides, if it wasn't hard, than it wouldn't be interesting, now would it?

Closing thoughts

I'm not saying that you shouldn't use Steak. You should test your application from start to finish, from top to bottom. I don't care what tools you use, as long as you test all the fucking time. If one of these tools is keeping you from doing that, than you shouldn't use it. If you find writing Cucumber features depressing, then obviously you shouldn't use it. These tools are here to help us, not the other way around.

That being said, I think Cucumber can help me in coming up with the right solution to the problem, documenting what my application is all about and testing it, all at the same time. I like that and that's why I'll continue to use Cucumber, even for my own projects where I am the only one reading the features.

And remember, when doing BDD with Cucumber: "When you’re writing a new scenario, I recommend you start with the formulation of the desired outcome. Write the Then steps first. Then write the When step to discover the action/operation and finally write the Given steps that need to be in place in order for the When/Then to make sense." (from the Cucumber wiki)

More information

Looking around to see other people writing Cucumber stories is very educational. Have a look at RSpec's features on Relish. On writing good steps, you should read up on cuking it wrong and cuking it right. Also, Hashrocket has an interesting discussion online about how they use Cucumber. Jeff Kreeftmeijer wrote a great introduction on Steak. And finally, the RSpec book is really gives a good insight into how to use Cucumber the right way.

Also, Dan North wrote a lengthy article on how to write stories, making a similar point.

MetricFu is awesome. It helps me keep my code clean by identifying problem spots in my code. Unfortunately, it's difficult to get running. MetricFu requires to be run with Rake. But by doing that, it becomes part of your project's dependencies. Especially if you're using Bundler.

Enter Metrical

Metrical is a wrapper around MetricFu, that allows it to be run as an executable on any project. Just install it, and run it. No setup or adjustments to your project should be required. It's that easy!

cd /path/to/project/
gem install metrical
metrical

If you want to configure MetricFu, you can add a file called .metrics, in which you can add your regular configuration. For all configuration options, you can visit the MetricFu homepage. All I've done is add a small tweak to the rcov options, so it'll run RSpec without problems.

So, give it a spin and tell me what you think of it!

describe "array matching" do

  it "should pass" do
    [ 1, 2, 3 ].should =~ [ 2, 3, 1 ]
  end

  it "should fail" do
    [ 1, 2, 3 ].should =~ [ 4, 2, 3 ]
  end

end

Note: There is no inverse (should_not) version of this matcher.

To me this sounds like a professional carpenter saying that a chainsaw is less useful for making big things because you can hurt yourself with it or make a big mistake more easily. While it might be true that these things can and do happen, it's not a definitive reason not to use it. And while other tools might be better at a certain task, it can still do the job just fine.

With great power comes great responsibility. I cannot lecture you on the precautions you need to take when using power tools, but when it comes to software development the things you need to do is testing and refactoring. I believe this to be true for every programming language, just as you always need to be careful you don't hurt yourself or others when you saw something, no matter which kind of saw you use.

I don't consider Java to be a screwdriver, Ruby to be a saw and Python to be a hammer. Choosing the right tool for the right job is correct, but when it comes to programming languages, the tools aren't that different from each other. They're more like different kind of saws. They can all be used for cutting things in half. It's the skill of the person wielding the tools that makes the difference.

Analogies will take you only so far. They all break down at a certain point. I've already taken this one too far for its own good. The bottom line: I like reading about interesting stuff people do in software development, no matter which language. It's all cool! Stop trying to put them into an ordered list of greatness and use your knowledge to educate and inspire us!

This is how it looks with the ir_black colorscheme:

source :rubygems
gem 'rails'
gem 'hoptoad_notifier'
gem 'newrelic_rpm', :require => false
gem 'mysql2'
gem 'devise'

# ... etc ...

platforms :ruby_18 do
  gem 'system_timer'
  gem 'fastercsv'
end

group :development, :test do
  gem 'rspec-rails', '2.0.0.beta.20'
end

Enjoy!

In Theory

Services are best defined by what they're not. They're not entities or value objects. To recap: entities are identifiable objects, that have real meaning in your domain. This might be a user or a post (if you're making a blog). Value objects are objects that are not defined by their identity, but by their value. An address of a person is usually a good example. It doesn't matter which address object it really is, as long as it contains the data it is supposed to have. Services are none of these. Services do something with the entities in your domain.

A good example of services are classes. By their very nature, classes are services for initializing objects. In Ruby this is idea is emphasized by the fact that classes are objects too. They have state and behavior, just as any other Ruby object. But their behavior is always aimed at something else, not themselves. Services tend to have no state, or very little at the most.

What's the advantage of thinking of classes as being services? Well, in my opinion it leads you to organize your code better. Class methods are only allowed to do something with creating instances of that class. If they are not doing that, they shouldn't be class methods.

It also answers the question: where should this behavior go? If it's not obvious, it's probably a service. The 'fat model, skinny controller'-principle has gotten some news lately. This principle was invented because developers (me included) were putting too much logic into the controllers. It made the controllers skinny and readable; but it had the side affect that everybody jammed the behavior into their models (entities), making them big and unwieldy. Services will help you create small and manageable classes.

In Practice

Time for an example. Suppose you have an admin interface which allows the user to find their entities in many different ways, filtering on attributes and ordering them around until he finds the entities he wants. It might be part of a advanced search box. This filtering business is an excellent candidate for a service.

There are many ways of making a filter service. I've made something similar to this recently. I'll start by making a basic filter, with nothing specific.

module Filter
  class Base

    class_inheritable_array :filters
    self.filters = []

    # Call filter to define which filters are available.
    # These will all be run in the order you specified
    def self.filter(*filters)
      self.filters.unshift(*filters)
    end

    # The params are the parameters you might have entered in your form.
    attr_reader :params
    def initialize(params)
      @params = params
    end

    # Get all filtered results. This is the public facing method that
    # you'd want to call when getting the results of the filter.
    def all
      apply_filters
      scope
    end

    private

    # As part of the contract, set the default scope by overriding this method.
    def scope
      raise NotImplementedError
    end

    # Run all the filters, specified in subclasses.
    def apply_filters
      filters.each { |filter| send(filter) }
    end

    # Probably every filter should be able to paginate the results.
    # remember to call pagination last, because will_paginate won't return
    # a real ActiveRecord::Relation object.
    def pagination
      @scope = scope.paginate(:page => page, :per_page => per_page)
    end

    def page
      params[:page] || 1
    end

    def per_page
      params[:per_page] || 20
    end

    # Similar to pagination, sorting is something common to all filters,
    # The default order is :id, because that will be available on every
    # model. You can override it easily however.
    def sort(default = :id)
      @scope = scope.order(params[:order] || default)
      @scope = scope.reverse_order if params[:direction] == 'desc'
    end

  end
end

Now, you can make filters for every model. This means creating a class that inherits from this base class and implementing the simple contract we put in place. I'll use the (t)rusty Post model as an example implementation.

module Filter
  class Posts < Base

    # Here I define the filter methods that will be used for posts.
    filter :published, :by_name, :sort, :pagination

    # The default scope for posts is a plain Post class without any scope added.
    # You can apply some permissions here, for instance.
    def scope
      @scope ||= ::Post
    end

    # Only show published posts, when the 'only_published' checkbox has been
    # checked in the form.
    def published
      @scope = scope.published if params[:only_published] == '1'
    end

    # Provide a simple name field to filter on the name of the post
    def by_name
      if params[:name].present?
        @scope = scope.where('name LIKE ?', "%#{params[:name]}%")
      end
    end

    # I want to sort by the published_at column by default
    def sort(default = :published_at)
      super(default)
    end

  end
end

To use this filter, call it from the controller:

class Backend::PostsController < ApplicationController

  respond_to :html, :json, :xml

  def index
    @posts = Filter::Posts.new(params[:filter]).all
    respond_with @posts
  end

end

As you can see, this places the logic of filtering in its proper place. It's not part of the model, since it's not part of initializing objects, or behavior of individual post objects. It's a separate service, doing something with something else.

These services are incredibly easy to make. Just think about the objects it's trying to handle. These are probably the arguments of your initializer. Store those methods with an instance variable. All methods you create do something with either these objects or call methods that do so.

Don't forget to run reek on your code to see if you have any Low Cohesion or Feature Envy warnings. If you get any, than that method probably doesn't belong here, or you've got you're initial parameters wrong.

module Filter
  class Base

    def self.all(*args)
      new(*args).all
    end

    # ... rest of the base class ...

  end
end

Autotest.add_hook :initialize do |at|
  at.add_mapping(%r%^spec/(.*)_spec\.rb$%) { |filename, _| filename }
  at.add_mapping(%r%^app/(.*)\.rb$%) { |_, m| ["spec/#{m[1]}_spec.rb"] }
end

It was a long talk, so I couldn't cover all the topics I wanted to cover. I talked about ubiquitous language, bounded contexts, core and support domains, and showed some ways to do this in Ruby, using modules. Basically, I concentrated on techniques to organize essential complexity, while keeping an eye on practical usage with Ruby and Rails.

When you talk about Domain Driven Design, you hardly cannot do that without mentioning the three types of objects that Eric Evans discusses in his book. It's Entity objects, Value objects and Service objects. Still I managed to do just that. Time to fix it; here is what I failed to mention.

Entities

Entity objects are objects that represent something in the real world and can be referenced as such. Translated into Rails terms these would be instances of (most of) your models. You can reference a post instance by getting it via its id from the database.

These objects are prime candidates for using plugins like friendly_id, making the fact that these objects have a real identity in real life clearer. This is because you can now reference them by name, instead of some database id. To use friendly_id with Rails 3, point your gemfile to the 'edge' branch on github.

Value Objects

Objects that don't have any real identity are called "Value objects". Any object that is a value object has no real identity, nor is it important to know its identity.

Addresses are a good example. The value of the address (e.g. street, house number, city, country) is important. But it's less obvious to store this in a database and reference it by an id. This id would be purely superficial and have no meaning in the domain you are designing.

A pure Ruby way to do this with Structs, which I have mentioned before on this blog. If you're using a document based database, like MongoDB, these would obviously be embedded documents. With ActiveRecord you can use the composed_of-method. Allow me to demonstrate that:

# Attributes of Person include:
#
# * first_name  string
# * name_infix  string
# * last_name   string
# * male        boolean
#
class Person < ActiveRecord::Base
  composed_of :name,   :mapping => Name.members
  composed_of :gender, :mapping => Gender.members
end

class Name < Struct.new(:first_name, :name_infix, :last_name, :gender)

  def to_s
    [ first_name, name_infix, last_name ].select(&:present?).join(' ')
  end

  def first_name
    super.presence || title
  end

  def title
    I18n.t(gender.key, :scope => :titles)
  end

end

class Gender < Struct.new(:male)

  def to_s
    I18n.t(key, :scope => :genders)
  end

  def key
    male ? :male : :female
  end

end

By defining to_s on these structs you can output their gender or name in views without doing anything special:

%dl[@person]
  %dt= Person.human_attribute_name(:name)
  %dd= @person.name

  %dt= Person.human_attribute_name(:gender)
  %dd= @person.gender

In this example, Person is actually an aggregate of the entity Person and two value objects, called Name and Gender. Although all attributes are flattened out in your persistence layer (in this case, your database table); they do have a deeper structure in your code. And it's easier to test too!

Services

Things that aren't really a 'thing' in the domain you're designing are usually services. They are not really part of any entity or value object, but do something with them.

In Rails, these would be observers or plain Ruby objects lying around. Maybe it's time to call them what they are and place them in app/services.

Every Rails developer knows the pattern "Fat Model, Skinny Controller". This is a pattern to remember that you shouldn't put model logic in your controller but in your model. But this pattern is often taken too far. There are people that give the params-object, or worse, the entire controller-instance, to the model and do their shit there. This is not right. Use a service for that.

Pagination and searching are good candidates for a service. But this blog post is on the long side, so I'll save an example implementation of that for another time. No post is complete without a promise to a follow-up that never comes, right?

Customizing my work environment is a nerdish hobby of mine. I spend far to much time tweaking my terminal. While I'll save my terminal customizations for another time, I'll show you my IRB tweaks in this post.

There are several tools to improve your IRB, and some of them have been around for ages. But the arrival of Bundler makes it difficult to use them. Bundler creates a bubble in which you have to specify your dependencies explicitly. Furthermore, with project specific gemsets, provided by the ever so awesome RVM, we need to install these IRB extensions for every project.

This means that you cannot be sure that extensions like Wirble are available in your new and shiny Rails console. There is only one way around that: add them to your Gemfile. This is what I usually add:

group :development do
  gem "wirble"
  gem "hirb"
  gem "awesome_print", :require => "ap"
  gem "interactive_editor"
end

Extension Loading

To load the IRB extensions without blowing up in your face when they're not available, I gently try to load them, and configure them only when that is successful. You can download my .irbrc on github. Here is what it looks like:

When you start IRB, it shows a line with the extensions loaded. If it's gray, it's not appropriate (like rails2 in this example), loaded extensions are green and extensions that are not available are in red.

Showing Queries in ActiveRecord 3

As you can see, the queries done by ActiveRecord are displayed in the same way as they are displayed in your log files. In Rails 2, you would've done this by redirecting the log output to STDOUT. In Rails 3 you need to subscribe to the 'sql.active_record'-notifications.

This could in theory also be done for other Rails 3 compatible ORMs like Mongoid, but I haven't looked into that yet.

Hirb

Hirb formats objects into pretty tables, as you can see in the picture above. It also provides some scrolling possibilities like the command line tools less and more. Very handy!

Wirble

The first IRB extension anyone uses. Wirble provides you with history and syntax highlighting.

Awesome Print

While Wirble colorizes the output to improve readability, it can get cluttered really fast, especially when you're dealing with nested hashes and arrays. AwesomePrint helps to untangle your object mess:

Print Methods

The 'pm'-extension I found on the intertubes some time ago, lists the methods and what arguments they take on any given object. You can filter it, by providing a regex. This is what it looks like:

It's not a gem, but a snippet pasted directly into my irbrc, so it's always available.

Interactive Editor

Open vim (or any other editor) from IRB, edit your code, save it, close your editor and the code gets executed. Open vim again and your code is visible and editable again. Very awesome! Check it out!

More

Yeah, there more. There's bond, which makes autocompletion better, and utility belt, and more. I can't remember to use them all, so I haven't included them into my irbrc. They certainly are cool enough for you to check out! Also, a lot of great tips are here on Stack Overflow.

If you have any good tips, please share them! Oh, and the other OSX tweaks I use are on github.

PS. For those that don't know how to load this: put the .irbrc file in your home directory and it will load automatically.

The jQuery UI framework contains some nice styles and some nice javascript to accompany it. But the class names you're ought to be using are awkward. Nobody wants to add "ui-widget-header" to their classes. We have standards; we want semantical html and css, even if we don't want to be doing much styling ourselves.

Editing the css file that jQuery UI gives you is not an option; that would be a hideous mess even before we get started. Luckily, Sass can help us. Sass introduced the "@extend" method since version 3, which we can (ab)use.

We need to convert the css file jQuery gave us to Sass. I'm a big fan of sass, not scss, so I'll be using that:

sass-convert --from css --to sass path/to/jquery-ui-1.8.2.custom.css > app/stylesheets/_jquery_ui.sass

I've included an underscore so it won't be compiled to a real css file when I run my application. I've also configured Sass to load my sass files from app/stylesheets.

Next, create your own sass/scss file and use @extend:

In sass:

@import jquery_ui

.project-header
  @extend .ui-widget
  @extend .ui-widget-header
  @extend .ui-corner-all

In scss:

@import "jquery_ui";

.project-header {
  @extend .ui-widget;
  @extend .ui-widget-header;
  @extend .ui-corner-all;
}

Now you just need to add the class "project-header" to the appropriate HTML element, include the compiled "screen.css" tag in your layout and you're done!

Be sure to use the javascript too, for nice interactions. The javascript will add classes dynamically to certain elements. They will still work.

So what really happens? Well, @extend appends your own selector to the jQuery selector you specified. So the compiled jQuery css would've looked like this before:

.ui-widget-header {
  border: 1px solid #aaaaaa;
  /* more... */
}

But after doing our @extend-trick, it will now compile to:

.ui-widget-header, .project-title {
  border: 1px solid #aaaaaa;
  /* more... */
}

Sass parsing is incredibly smart. Really smart. The original jQuery css will be changed automatically. Awesome! And without hardly any effort from my side!

For more awesomeness in styling: Have a look at compass. It will be worth your time!

class FooBar
  attr_initializer :foo, :bar
  def to_s
    "your #{foo} is #{bar}"
  end
end

FooBar.new('foo', 'bar')

But there is a way of doing it without a monkey patch. Use the Struct.

FooBar = Struct.new(:foo, :bar) do
  def to_s
    "your #{foo} is #{bar}"
  end
end

FooBar.new('foo', 'bar')

Pretty cool.

Update

As was pointed out in my comments by Radoslav Stankov (which you can't see anymore, because I switched to Disqus), you can also do this:

class FooBar < Struct.new(:foo, :bar)
  def to_s
    "your #{foo} is #{bar}"
  end
end

FooBar.new('foo', 'bar')

I use this one more often, actually.

One final note: the parameters here aren't stored as instance variables, they can only be accessed through their accessor methods.

Imagine you add a class to the menu item that is active, like this:

<nav id="menu">
  <ul>
    <li><a href="foo.html">Foo</a></li>
    <li class="active"><a href="bar.html">Bar</a></li>
    <li><a href="baz.html">Baz</a></li>
  </ul>
</nav>

Then all you would need to do is something like this with jQuery:

$(function() {
  $('nav#menu a').click(function(){
    $('nav#menu li').removeClass('active');
    $(this).blur().parents('li').addClass('active');
  });
});

I've added a blur()-command in between, so the dotted lines disappear earlier.

Try it out, you can really notice the difference. It works best when the menu items don't move, but only change appearance.

Update

Because I switched to Disqus, some nice comments have gone. Stefan Borsje, of Pressdoc fame, replied with this concern:

To be honest, I don’t like it very much. It really changes a basic way the web works; you click on something, the page loads (and optionally shows an activity indicator) and you get to see the result. With this method you already get see part of the result even before the actual loading fase, which could easily confuse users by letting them think the page is already done but nothing has changed.

I agree that you should be careful applying this technique. But the clicking of the link is done instantly, so the user would see the page loading immediately, thus he/she wouldn't think the page is done. This technique works best if your pages are speedy enough, but can use just a bit more oomph.

Rails gives you a helper module for every controller. The problem with modules is that they don't contain state and are usually used to just put a lot of methods in. But this can grow quickly out of hand when the stuff that you're building is a little more complex.

Never forget to run tools like Reek on your helpers as well. What do they say? Are your methods too long? Do your methods require too many arguments? Is the complexity too high? Do your methods have feature envy?

I've seen quite a lot of Rails projects and helpers are almost always the forgotten parts of the application. Every Rails developer knows about the "Skinny Controller, Fat Model"-principle. Better teams also make skinny models, by using modules and creating macro's. But helpers are usually ugly. And they shouldn't!

Helpers are code too! They want your love and dedication!

There are a couple of ways to keep it clean. Sometimes they are called "Presenter Objects" or something similar. It doesn't matter how you call them, and you don't have to use any complicated gems or libraries. Regular classes suffice.

Here's an example of a typical helper:

module PostsHelper

  def post_title(post)
    header_class = post.published? ? "published" : "normal"
    header = content_tag(:h2, post.title, :class => header_class)
    content_tag(:div, :class => "post header") do
      if post.user == current_user
        [ header, edit_post(post), destroy_post(post) ].compact.join(' ')
      else
        header
      end
    end
  end

  def edit_post(post)
    link_to('edit', edit_post_path(post))
  end

  def destroy_post(post)
    link_to('delete', post, :method => :delete, :confirm => "are you sure?")
  end

end

You might choose a different route, like putting the if-statement in the view. But that's beside the point. The point is that this is what usually happens when you don't use objects as they are supposed to be used. Look at the post argument for example. It's on every frickin' method! That's not DRY!

And what if you need to extend it? What if you need approve and reject links as well? What if the destroy link needs to only show when the post has been approved? It's becoming more and more messy. Time to refactor!

This is an example of how I would do it:

module PostsHelper

  def post_title(post)
    PostTitle.new(self, post).to_html
  end

  class PostTitle

    attr_initializer :template, :post
    delegate :content_tag, :link_to, :current_user, :to => :template

    def to_html
      content_tag(:div, elements, :class => "post header")
    end

    def elements
      [ header, edit, delete, approve, reject ].compact.join(' ')
    end

    def header
      content_tag(:h2, post.title, :class => header_class)
    end

    def header_class
      post.published? ? "published" : "normal"
    end

    def edit
      link_to('edit', edit_post_path(post)) if my_post?
    end

    def my_post?
      post.user == current_user
    end

    # etc... (you get the drift)

  end

end

Nice! Small testable methods! Readable code! Less repetition. Run Reek on that!

If you're wondering what the attr_initializer is, it's a monkey patch, that I've described here. The delegate-method is something ActiveSupport offers you. Use it, it's super effective!

Wait a minute. Did I say "testable"? Yes, I most certainly did! As with any code, this needs to be tested. But it's not that hard anymore! If you're using Rspec, you can use the helper specs it provides. But you don't need to!

The PostTitle-class is a regular Ruby class, and so every test framework can test with it without much effort. You might want to use stubs and mocks for the other helper methods you call. Or subclass PostTitle, define the used helper methods and use this to subclass in your tests. The delegate specifies which other helper methods are used.

Remember that what you program is entirely up to you. You, and only you, have to decide when a simple method is enough, or whether you need to add a class, or something similar. You can also consider using Builder for some parts, if the HTML generation becomes too hard.

The main point is that any part of your application needs to receive the same attention to detail. Don't hide your dead bodies (of code) in helpers, or anywhere! Be critical everywhere and all the time! Run Reek regularly. It's a depressing tool and you don't need to fix every message every time. Use it wisely and pay attention. There is no excuse for ugly code!

In this example, I would use a partial, but when the view logic increases, you should be thinking about extracting it.

Programmers humor dictates me that from time to time I say things like "In Ruby, that's only one line!" or "In Ruby, that would cost me just one minute!". Putting money where my mouth is, I wrote the entire application in just one line of Ruby.

So here it is. It looks more like Perl than Ruby. But it works!

String.class_eval{define_method(:to_grid){(self =~ /\A(\d+)x(\d+)\z/ ?
(0...split('x').last.to_i).map{|_| (0...split('x').first.to_i).map{|_| rand > 0.5 } } :
split("\n").map{|row| row.split(//).map{|cell_string| cell_string == "o" } }
).tap{|grid| grid.class.class_eval{define_method(:next){each{|row|
row.each{|cell| cell.class.class_eval{define_method(:next?){|neighbours|
(self && (2..3).include?(neighbours.select{|me| me }.size)) ||
(!self && neighbours.select{|me| me }.size == 3)}}}} &&
enum_for(:each_with_index).map{|row, row_num| row.enum_for(:each_with_index).map{|cell, col_num|
cell.next?([ at(row_num - 1).at(col_num - 1), at(row_num - 1).at(col_num),
at(row_num - 1).at((col_num + 1) % row.size), row.at((col_num + 1) % row.size),
row.at(col_num - 1), at((row_num + 1) % size).at(col_num - 1),
at((row_num + 1) % size).at(col_num), at((row_num + 1) % size).at((col_num + 1) % row.size) ])
} }} && define_method(:to_s){map{|row| row.map{|cell| cell ? "o" : "." }.join }.join("\n")}}}}}

I didn't cheat! No semicolons where harmed during the making of the spaghetti code. I did enter some newlines in the code shown above to prevent wild scrollbars from appearing.

You can use it like this:

# generate a random grid
grid = "100x30".to_grid
# show the grid:
puts grid.to_s
# get the next generation of the grid
new_grid = grid.next
# convert a drawn out grid to a grid
new_grid.to_s.to_grid == new_grid # returns true

If you want to know how it works, or make an animation of it, it's all here.

This is what it looks like:

It was a fun exercise, but I don't think I'll be writing all my code like this in the future :)

In views you can automatically scope translations to the view you're working in.

So this HAML code (in the users#index view):

= t('.foo')

It's the same as:

= t(:foo, :scope => [:users, :index])

I use this technique a lot.

Anyway, we could clean up it even more, by making a dynamic dispatcher. It would look something like this:

module ViewTranslatorHelper

  def vt
    @view_translator ||= ViewTranslator.new(self)
  end

  class ViewTranslator < ActiveSupport::BasicObject

    def initialize(template)
      @template = template
    end

    def method_missing(method, options = {})
      ViewTranslator.class_eval <<-RUBY
        def #{method}(options = {})
          @template.t(".#{method}", options)
        end
      RUBY
      __send__(method, options)
    end

  end

end

And now you can write:

= vt.foo

How does this work?

The vt method returns ViewTranslator instance. It is cached inside an instance variable. The ViewTranslator object inherits from BasicObject (ActiveSupport's BasicObject uses Ruby 1.9 if it is on Ruby 1.9, and constructs it's own when on a lower Ruby version). BasicObject is an object that knows no methods, except methods like __id__ and __send__. This makes it ideal for using dynamic dispatchers.

When we define method_missing every single method we call on it will be passed to there. We could call @template.t directly from here, but we don't. To know why, we must know how method_missing works. When you call a method on an object, it looks to see if the object knows the method. When it doesn't know it, it looks to it's superclass and tries again. This happens all the way until it reaches the top of the chain. In Ruby 1.8 that is Object, because every object inherits from Object. Ruby 1.9 goes one step further and goes to BasicObject. If a method is not found anywhere, it will go to the original object you called the method on and it calls method_missing. Since that usually isn't there, it goes up the superclass chain until it comes to (Basic)Object. There it exists. It will raise the exception we all know and hate: NoMethodError. You can do this yourself too:

> "any object".method_missing(:to_s)
NoMethodError: undefined method `to_s' for "any object":String

You see, even though the method to_s does exist on the string, we stepped halfway in the process of a method call. The error message is a bit confusing, but the we just called a method on the superclass of String. Anyway, by defining method_missing on our own object, it cuts this chain short. To cut it even shorter, I define the method itself, so it doesn't need to go through this process at all. After it's defined I call the freshly created method.

Now, to be honest. This is not at all that expensive to use method_missing in this case. The chain is only classes long, so it's hardly putting a dent in your performance. There are cases were this is very important though. One such case is ActiveRecord. When you call a method on a new ActiveRecord-object for the first time, you reach method_missing. It needs to look at the database to find out if it is an attribute. Looking inside the database is very expensive, so method_missing creates methods for all attributes. If the attribute exists, it will be called, and it'll be a normal method call from then on.

Thanks for reading. If you found it informative: I love feedback ;)

I recently gave a presentation at my company Finalist IT Group about the philosophy behind Ruby. Code written with this philosophy in mind is called 'Rubyesque'. It's not hard science, so we had plenty ingredients for a discussion.

The reason behind the presentation was because we're in need of more Ruby developers and looked inside our own company for Java developers that want to learn Ruby. Because Java and the philosophy behind it are so radically different from Ruby, we organized a discussion to explore those differences.

About programming and the 'flow'

The Rubyesque mindset is all about opinions. Opinions tend to vary from person to person. By reading a lot of blogs and code I do see some sort of consensus. This opinion is not always explicitly mentioned, so I don't pretend to speak in absolute truths or be complete.

Programming is usually compared with other professions to give an idea what it's like to do it. Ruby programmers tend to compare programming with craftsmanship. I even go one step further. I think programming Ruby is a form of art of playing an instrument. Programming is a creative process. You're programming to express meaning and intent. The only way to achieve this, is if you know your instrument so intensely that it's not compromising you're ability to express yourself.

Every programming language has its own style. You can call it its 'flow'. It's wise to go with the flow. It's easier to use the language as it's intended to be used than to go against it. For example, don't try to force inheritance in a language that is intended to be prototype based. Program according to the flow and other programmers can understand and maintain your code better.

About Ruby

Everything in Ruby is aimed towards making the programmer happy. A happy programmer is better motivated to deliver great code and will feel responsible to do so. And better code makes everyone happy.

It's the machine that is supposed to do the heavy lifting, not the programmer. This means that Ruby isn't particularly fast, but since machine power is cheaper than man power, it's not that big of a deal.

Ruby has a couple of traits that make it a joy to work with:

• Dynamic and open to bend it to your liking
• Few rules, so easy to learn
• There are 'shortcuts' for common tasks
• Many ways to reuse code, such as mixins
• Optional punctuation to improve readability
• Methods like attr_accessor to become more DRY

Dynamic

In a dynamic language it's not important to know which type of object you're dealing with, but it's more important to know what it can do for you. This is called duck typing. This isn't only handy in making mock object, but also means that you don't have to abuse inheritance to comply to some method you'd like to call.

A nice example is the Rack specification. The header object you're supposed to return needs to have the method each. It doesn't say that it needs to be a hash. You could use a hash, but if it makes more in your sense to have some other object, it's fine. You don't have to inherit from hash, just to implement the each method.

The flow in Ruby is not to perform any check of the objects. If you're explicitly want an integer, just call to_i inside the method. Any code that checks the type is usually considered to be distracting from the real meaning of the code. It's the programmer that uses the gem/library responsibility to use the right objects, and not the responsibility of the gem-maker. The naming of methods and variables need to be obvious enough, so that it shouldn't be a guessing game.

Open

In Ruby, nothing is final. This allows for the ability to add and change anything in any object, including core classes. This is called Monkey Patching or duck punching. This results in even nicer and more readable code, like:

15.minutes.ago

Nobody needs to explain this. Nobody needs to look up any documents to understand what is going on here. Monkey patching can improve the readability of the code immensely.

I understand that this technique may be considered extreme by some people. It doesn't comply to the strict rules that govern most other languages. Still, these kinds of techniques are very handy and addicting.

Monkey patching is dangerous. It's your own responsibility to use it responsible. Use tests to ensure that you don't break anything unintentionally.

Punctuation

Some of Ruby's punctuation is optional. Ruby programmers love to leave them out. It's mostly a matter of taste. Readability is key here.

Rubyists rather write this:

class Post
  belongs_to :author, :dependent => :destroy
end

Than the same code with all punctuation visible:

class Post
  belongs_to(:author, {:dependent => :destroy})
end

It's not important that {:dependent => :destroy} is a hash. Nor is it important that belong_to is a method, and that it takes two arguments. It's much more important that the post belongs to an author and that the post will be destroyed when the author is being destroyed.

By not using all the possible punctuation, it becomes easier for our brains to focus on what is actually written, rather that which objects might be used to express it.

Few rules, many shortcuts

There are only a few genuine language constructs. There are just three elements in the language that have any real meaning. Those are objects, methods and blocks/closures. The only way in which classes and modules are special is by their implementation, but they are still regular objects. There are just a few other constructs, most notably if, while and the logic operators like && and ||.

The rest of the keywords you see are just shortcuts, you can type to perform common tasks. Like defining a class:

class Car < Vehicle
  # ...
end

The Ruby interpreter reads this as:

Car = Class.new(Vehicle) do
  # ...
end

Defining a class is actually just a method called on an object. The first argument is another object (the class to inherit from) and the second argument is a block. You can write it like this if you want to and play with it too, like dynamically making many different classes.

Some other examples:

counter += 1           # this is a shortcut
counter = counter + 1  # without the shortcut, but also without punctuation
counter = counter.+(1) # without the shortcut and with all punctuation (yes, + is just a method)

@user ||= User.new        # this is called a 'teapot'-operator or 'or-or-equals'
@user = @user || User.new # assign @user to @user if it exists, otherwise create a new user

exit unless busy or cancelled  # 'unless' is a shortcut for 'if !()'
exit if !(busy or cancelled)   # 'if' at the end of a sentence is also a shortcut
if !(busy or cancelled)        # for a regular if
  exit
end

There are many more shortcuts. But why? Why are there so many ways to do the same thing? It's not just readability, but also the ease in which you can translate the ideas in your head to code.

The smaller the difference between your thoughts and your code, the easier it is to program. Ruby gives you full freedom to express yourself how you feel fit. That doesn't mean it always works out. If you have an unclear image of the problem you're trying to solve, the code you write will be unclear too. Nothing stops you to write bad code. Ruby doesn't force you in any way. These things cut both ways.

Exposing intention

Code needs to expose its intent. Ruby code is Rubyesque if it uses the above mentioned techniques to expose its intent. Because Ruby has such clean syntax, most DSLs (Domain Specific Languages) will be written in Ruby. These kinds of DSLs are called internal.

The naming of variables and methods is extremely important. The meaning of the code must be clear the first time you read it.

A fantastic example is Rspec, my favorite test framework.

describe Post do

  context "when it's not approved" do
    subject { Post.new(:approved => false) }
    it { should_not be_publishable }
  end

  context "when it's approved" do
    subject { Post.new(:approved => true) }
    it { should be_publishable }
  end

end

The entire Ruby bag of tricks is being used to make it as natural as possible to write down your specifications. This example doesn't like like regular Ruby code, but it still is. It's nothing more than objects, methods and blocks.

This is very Rubyesque. There is almost no distraction from the meaning of the code. I can plainly read if my code still does what my customer wants and I can run the specs to see if my code does what I specified it to do. And even nicer: it's incredibly easy! Rspec makes Test Driven Development very easy.

If you're interested in the code to implement this example, take a look at this gist.

Succinct and Concise

Rubyesque code is succinct. That doesn't just mean short lines (I try to limit myself to about 80 or 100 characters per line), but also about short methods. The code smell detector Reek will raise a warning if your method is longer than 6 lines. Does this means you are not allowed to write longer methods? Of course not. Is it a good idea? No.

People are better at understanding short sentences. And it's the people that need to understand the code and maintain. And we're back to the philosophy behind Ruby. It's meant to be understandable for people. It's less important if the computer needs to do some extra work.

Conclusion

Ruby is a free language. You can bend the rules. The goal is to make you happy. Ruby was made to make you happy, to close the gap between human and computer language. Try to do that in the code you write too, it works!

I found that most people coming from languages like Java or PHP find Ruby a weird or magical language. That is only the appearance. Ruby is very easy to learn. It has few rules. Ruby programmers don't code using rigid rules and dogmas, but experiment solving the same problem in different ways.

I hope you got some idea of what it means to program Rubyesque. I advise everybody to look at the different languages and their philosophies. See what philosophy suits you. If the Ruby philosophy suits you and you have the discipline needed to write Ruby, give it a try! Ruby transformed the way I feel about my job and never regretted learning it one bit.

I often find myself writing code like this:

class Foo
  attr_reader :bar, :baz
  def initialize(bar, baz)
    @bar, @baz = bar, baz
  end
end

This can be very annoying to maintain. The variable names are repeated four times, within three lines of code!

Ideally, I'd want to write something like this:

class Foo
  attr_initializer :bar, :baz
end

Much better, if you ask me. Here is one example of how to do this.

class Class
  def attr_initializer(*attributes)
    attr_reader *attributes
    class_eval <<-RUBY
      def initialize(#{attributes.join(', ')})
        #{attributes.map{ |attribute| "@#{attribute}" }.join(', ')} = #{attributes.join(', ')}
      end
    RUBY
  end
end

No piece of code is complete without tests, so this is it:

class AttrInitializerTests < Test::Unit::TestCase

  def test_attr_initializer
    klass = Class.new do
      attr_initializer :foo, :bar
    end
    object = klass.new(1, 'b')
    assert_equal 1, object.foo
    assert_equal 'b', object.bar
  end

end

~

The tilde method (~) is used by Sequel and you can use it like this:

class Post
  def ~
    11
  end
end

post = Post.new
~post # => 11

That's right: you call this method by placing the tilde before the object.

In Sequel it is used to perform NOT queries, by defining the tilde on Symbol:

Post.where(~:deleted_at => nil)
# => SELECT * FROM posts WHERE deleted_at IS NOT NULL

-@

The minus-at (-@) method works just about the same as the tilde method. It is the method called when a minus-sign is placed before the object. In effect, this means that Fixnum is implemented somewhere along the lines of this:

class Fixnum
  def -@
    self * -1
  end
end

num = 10
negative = -num # => -10

I found this one browsing through the source of the ActiveSupport::Duration class (you know, the one you get when you do 1.day). I guess it makes sense.

Be careful with chaining methods though:

ruby-1.9.1-p378 > num = 5
 => 5
ruby-1.9.1-p378 > -num.to_s
NoMethodError: undefined method `-@' for "5":String
  from (irb):5
  from /Users/iain/.rvm/rubies/ruby-1.9.1-p378/bin/irb:17:in `
'

This also applies to the tilde method.

So?

I don't know. Enrich your DSLs and APIs, if it makes any sense to do it.

I got a few of them lying around, so I am going to post one every month. I also welcome your favorite monkey patch, which you can email me.

So, the first one: group_by. This method groups arrays of objects by the result of the block provided and puts the result into a hash.

class Array
  # Turns an array into a hash, using the results of the block as keys for the
  # hash.
  #
  #   [1, 2, 3, 4].group_by(&:odd?)
  #   # => {true=>[1, 3], false=>[2, 4]}
  #
  #   ["One", "Two", "three"].group_by {|i| i[0,1].upcase }
  #   # => {"T"=>["Two", "three"], "O"=>["One"]}
  def group_by
    hash = Hash.new { |hash, key| hash[key] = [] }
    each { |item| hash[yield(item)] << item }
    hash
  end
end

No piece of code is complete without tests, so this is it:

class ArrayExtGroupingTests < Test::Unit::TestCase

  def test_group_by
    assert_equal {true=>[1, 3], false=>[2, 4]}, [1, 2, 3, 4].group_by(&:odd?)
    assert_equal {"T"=>["Two", "three"], "O"=>["One"]}, ["One", "Two", "three"].group_by {|i| i[0,1].upcase }
  end

end

Update

Silly me, this one is already in Ruby itself. Anyway, this is how it works under the cover...

# Without Symbol#to_proc
[1, 2, 3].map { |it| it.to_s }
[3, 4, 5].inject { |memo, it| memo * it }

# With Symbol#to_proc
[1, 2, 3].map(&:to_s)
[3, 4, 5].inject(&:*)

It has been in Rails as long as I can remember, and is in Ruby 1.8.7 and 1.9.x. I love it to death and I use it everywhere I can.

It is actually quite simple, and you can implement it yourself:

class Symbol
  def to_proc
    Proc.new { |obj, *args| obj.send(self, *args) }
  end
end

It works because when you prepend an ampersand (&) to any Ruby object, it calls #to_proc to get a proc to use as block for the method.

What I always regretted though was not being to pass any arguments, so I hacked and monkeypatched a bit, and got:

class Symbol

  def with(*args, &block)
    @proc_arguments = { :args => args, :block => block }
    self
  end

  def to_proc
    @proc_arguments ||= {}
    args = @proc_arguments[:args] || []
    block = @proc_arguments[:block]
    @proc_arguments = nil
    Proc.new { |obj, *other| obj.send(self, *(other + args), &block) }
  end

end

So you can now write:

some_dates.map(&:strftime.with("%d-%M-%Y"))

Not that this is any shorter than just creating the darn block in the first place. But hey, it's a good exercise in metaprogramming and show of more of Ruby's awesome flexibility.

After this I remembered something similar that annoyed me before. It's that Rails helper methods are just a bag of methods available to, because they are mixed in your template. So if you have an array of numbers that you want to format as currency, you'd have to do:

<%= @prices.map { |price| number_to_currency(price) }.to_sentence %>

What if I could apply some to_proc-love to that too? All these helper methods cannot be added to strings, fixnums, and the likes; that would clutter way to much. Rather, it might by a nice idea to use procs that understands helper methods. Here is what I created:

module ProcProxyHelper

  def it(position = 1)
    ProcProxy.new(self, position)
  end

  class ProcProxy

    instance_methods.each { |m| undef_method(m) unless m.to_s =~ /^__|respond_to\?|method_missing/ }

    def initialize(object, position = 1)
      @object, @position = object, position
    end

    def to_proc
      raise "Please specify a method to be called on the object" unless @delegation
      Proc.new { |*values| @object.__send__(*@delegation[:args].dup.insert(@position, *values), &@delegation[:block]) }
    end

    def method_missing(*args, &block)
      @delegation = { :args => args, :block => block }
      self
    end

  end

end

I used a clean blank class (in Ruby 1.9, you'd want to inherit it from BasicObject), in which I will provide the proper proc-object. I play around with the argument list a bit, handling multiple arguments and blocks too. You can now use this syntax:

<%= @prices.map(&it.number_to_currency).to_sentence %>

That is a lot sexier if you as me. And you can use it in any object, not just inside views. And lets add some extra arguments and some Enumerator-love too:

class SomeClass
  include ProcProxyHelper

  def initialize(name, list)
    @name, @list = name, list
  end

  def apply(value, index, seperator)
    "#{@name}, #{index} #{separator} #{value}"
  end

  def applied_list
    @list.map.with_index(&it.apply(":"))
  end

end

In case you are wondering, the position you can specify is to tell where the arguments need to go. Position 0 is the method name, so you shouldn't use that, but any other value is okay. An example might be that you cant to wrap an array of texts into span-tags:

<%= some_texts.map(&it(2).content_tag(:span, :class => "foo")).to_sentence %>

So there you have it. I'm probably solving a problem that doesn't exist. It is however a nice example of the awesome power of Ruby. I hope you've enjoyed this little demonstration of the possible uses of to_proc.

presence

First up is Object#presence which is a shortcut for Object#present? && Object. It is a bit of a sanitizer. Empty strings and other blank values will return nil and any other value will return itself. Use this one and your code might be a tad cleaner.

"".presence # => nil
"foo".presence #=> "foo"

# without presence:
if params[:foo].present? && (foo = params[:foo])
  # ..
end

# with presence:
if foo = params[:foo].presence
  # ...
end

# The example Rails gives:
state   = params[:state]   if params[:state].present?
country = params[:country] if params[:country].present?
region  = state || country || 'US'
# ...becomes:
region = params[:state].presence || params[:country].presence || 'US'

I like this way of cleaning up you're code. I guess it's Rubyesque to feel the need to tidy and shorten your code like this.

uniq_by

Another funny one is Array.uniq_by (and it sister-with-a-bang-method). It works as select, but returns only the first element from the array that complies with the block you gave it. Here are some examples to illustrate that:

[ 1, 2, 3, 4 ].uniq_by(&:odd?) # => [ 1, 2 ]

posts = %W"foo bar foo".map.with_index do |title, i|
  Post.create(:title => title, :index => i)
end
posts.uniq_by(&:title)
# => [ Post("foo", 0), Post("bar", 1) ] ( and not Post("foo", 2) )

some_array.uniq_by(&:object_id) # same as some_array.uniq

exclude?

And the final one for today is exclude? which is the opposite of include?. Nobody likes the exclamation mark before predicate methods.

# yuck:
!some_array.include?(some_value)
# better:
some_array.exclude?(some_value)

And it also works on strings:

# even more yuck:
!"The quick fox".include?("quick") # => false
# better:
"The quick fox".exclude?("quick") # => false

The full release notes of Rails 3 can be read here.

This time it's an old one: http_accept_language

• Splits the http-header into languages specified by the user
• Returns empty array if header is illformed.
• Corrects case to xx-XX
• Sorted by priority given, as much as possible.
• Gives you the most important language
• Gives compatible languages

For more information, read the README on GitHub.

Basic Usage

I was fed up with writing:

Post.all(:conditions => { :published => true }, :select => :title, :include => :author)

So with BasicNamedScopes, you can now write:

Post.conditions(:published => true).select(:title).with(:author)

All named scopes are called the same, except for include, which is now called with, because include is a reserved method.

Reuse them by making class methods:

class Post < ActiveRecord::Base
  def self.published
    conditions(:published => true)
  end

  def self.visible
    conditions(:visible => true)
  end

  def self.index
    published.visible
  end
end

Also, the all-method is a named scope now, so you can chain after callling all, for greater flexibility.

Post.all.published

Arrays can be used as multple parameters too, sparing you some brackets.

Post.with(:author, :comments).conditions("name LIKE ?", query)

The read_only and lock scopes default to true, but can be adjusted.

Post.readonly         # => same as Post.all(:readonly => true)
Post.readonly(false)  # => same as Post.all(:readonly => false)

Why?

NamedScopes are really handy and they should play a more central theme in ActiveRecord. While I heard that Rails 3 will support similar syntax, there is no reason to wait any longer.

I find defining named scopes very ugly, especially when dealing with parameters. Just compare the amount of curly braces!

# Using normal named scope:
named_scope :name_like, lambda { |query| { :conditions => ["name LIKE ?", query] } }

# Using BasicNamedScopes
def self.name_like(query)
  conditions("name LIKE ?", query)
end

Also, regular named scopes don't support using other named scopes at all!

I found myself implementing these named scopes (mostly conditions, but others too) so often, that a little gem like this would be the obvious choice. Use it if a gem like searchlogic is overkill for your needs.

Installing

The gem is called "basic_named_scopes". You know how to install it.

gem install basic_named_scopes

Use it in Rails:

config.gem "basic_named_scopes"

I had figured that the supplied dutch keywords in languages.yml were not very practical. It supplied "Gegeven" as a naive translation of "Given". Although this is correctly translated, it is very unpractical to form Dutch sentences with it. The only to really start a sentence with "Gegeven" is to write "Gegeven het feit dat..." ("Given the fact that..."). It's very strange to say "Gegeven dat ik een profiel heb" ("Given I have a profile") in Dutch.

I decided to use the synonym "Stel" like in "Stel ik heb een profiel". Not entirely correct either because it misses a comma after "Stel", but much better, in my honest opinion. So I forked cucumber, changed languages.yml and used this as custom git repository in my Gemfile.

Apparently I was in the middle of a Release Candidate, so what I had committed on github. The Rails integration was extracted out in that version (like RSpec does) to the "cucumber-rails" gem. This gave about an evening of confusion, but I got it to work eventually.

Two days later, we had visitors at our company, from another Ruby company, talking about cooperation on future projects. I introduced myself and he was trying to remember if he'd seen anything on the interwebs by me. That seems to be common. When meeting people on conferences it's always the same question: "Do I know any of your gems?".

Anyway, he had actually read my name recently, namely in the commit log of cucumber. Without asking or sending a pull request, they had added my commit to the 0.5 release of cucumber. A pleasant surprise! Aslak Hellesøy, you're a very observant GitHub user!

By the way, you can still use "Gegeven", as it is just an alias.

I am constantly wrestling with the best way write cucumber features down. Does anyone have Dutch features? Do you write them down with your customers or are they for developers only? Can you share some of them? Here are some of mine:

Scenario: Inloggen
  Stel ik ben uitgelogd
  En ik heb een account voor "gebruiker@test.com" met het wachtwoord "geheim"
  En ik ben op de inlogpagina
  Als ik de volgende velden invul:
    | E-mailadres | gebruiker@test.com  |
    | Wachtwoord  | geheim              |
  En ik op "Inloggen" druk
  Dan zie ik de melding "Je bent ingelogd"

Scenario: Verkeerd wachtwoord
  Stel ik ben uitgelogd
  En ik heb een account voor "gebruiker@test.com" met het wachtwoord "geheim"
  En ik ben op de inlogpagina
  Als ik de volgende velden invul:
    | E-mailadres | gebruiker@test.com  |
    | Wachtwoord  | verkeerd            |
  En ik op "Inloggen" druk
  Dan zie ik de foutmelding "Ongeldig e-mailadres of wachtwoord"

By the way, don't forget to order the RSpec and Friends book. It'll be released this februari and is a really good read if you want to learn BDD, RSpec or Cucumber.

This has been mentioned somewhere on some mailinglists, but to make it a bit more findable, I'd thought I'd post it here.

The solution workaround is to set the server protocol, like this:

it "should show the pdf" do
  request.env["SERVER_PROTOCOL"] = "http"
  get :show, :id => "report", "format" => "pdf"
  response.should render_template(:show)
end

I also do TDD, which means that I write a failing test first, and then program until it passes. But Autotest's flow is that, once you've fixed a failing test or spec, it reruns the entire the suite to see if you're solution doesn't have any side effects. Normally this is fine, but with this kind of test suite, I cannot afford to wait for it to complete.

So, after going through Autotest's code, I've decided to stub out this behavior. You can still trigger a complete rerun of the entire suite by pressing Ctrl+C, but it doesn't do that every time you go green. It's a bit of a monkey patch, but it works just right.

The autotest-growl gem clears the terminal. I don't like that, because I like to see a bit of history. That's why I changed that behavior too.

Here's my ~/.autotest file:

# Use file system hooks on OS X
require 'autotest/fsevent'

# Don't run entire test suite when going from red to green
class Autotest
  def tainted
    false
  end
end

# Use Growl support
require 'autotest/growl'

# Don't clear the terminal, when using Growl
module Autotest::Growl
  @@clear_terminal = false
end

While browsing through the code of Autotest I also found that it also looks for a .autotest file in the current working directory. So if you want to apply these changes to one project only, you can define this file locally for the project. I didn't know that!

What I have so far is:

• Automatic validations and relations
• Completely configurable, with sensible defaults
• A management interface
• Works with acts_as_list and supports drag and drop sorting
• I18n support

Let's take a tour of it's usage.

Install acts_as_list, if you want to:

./script/plugin install git://github.com/rails/acts_as_list.git

Install root_table:

./script/plugin install git://github.com/iain/root_table.git

Make a model that needs a list to choose from, like a product that has a category:

./script/genetate model Product name:string category_id:integer

Make a model for the root table, category:

./script/generate model Category name:string position:integer

Make category a root table for product:

class Category < ActiveRecord::Base
  root_table_for :product
end

And let the product model know as well what is happening:

class Product < ActiveRecord::Base
  has_root_table :category
end

Let's add a configured root table for good measure. Let's convert the User-model to a root table. User is not a list, and doesn't have a name-field to recognize it, nor does it have a position field. It requires some options to make it work.

class User < ActiveRecord::Base
  root_table_for :product, :to => :last_edited_by,
      :validate => false, :field => :login
end

And update the product model again:

class Product < ActiveRecord::Base
  has_root_table :category
  has_root_table :user
end

The relation is called last_edited_by, it doesn't add any validations and the displayed (and thus sorted) field is login instead of name. It doesn't have position field, nor do I provide it, so it'll sort on login and won't be manually sortable, as we'll se in a bit.

Using the User model might not be the best example, but you'll get the point.

Management in a Rails Engine

Visit the management interface at http://localhost:3000/root_tables and see something like this:

Since User has no position field, you'll end up with a simple scaffold-like management screen for it:

However, the Category model does have a position, so the interface has drag and drop functionality:

It has a very simple new and edit screen, just as you would with scaffold:

This is all done with a layout that Rails scaffold generates. If you have your own layout it might look completely different. The management pages are a Rails engine. This means that you can override any file by creating a file with the same name in your app-directory. Have a look at the code to see which files you can override.

Also, to enable the drag and drop interface, you'll need to have prototype included. If you don't want prototype be loaded everywhere, I've made it so that only drag and drop pages load the javascript. Please add <%= yield(:head) %> to your html header.

You can also override views on a table basis. That means that you might want a view that is different just in case of one table. The form for new users might want to have more fields than just the login field, but also include password fields. Create a view for that in app/views/root_table_contents/new_user.html.erb. Available for override per model are index, new and edit.

Using it elsewhere

But we're not there yet. Now we've built a root table and filled it, we need to use it somewhere. The plugin provides a root_table_select helper, that renders a drop down. The first parameter is the root_tables (real) name, it figures the rest out automatically. You can pass any options as the options you would pass the other select helpers. Here's an example:

<% form_for @product do |f| %>
  <p>
    <%= f.label :category_id %><br />
    <%= f.root_table_select :category, :include_blank => true %>
  </p>
<% end %>

Also for showing a delegate method is provided. This is how you can show the category name:

@product.category_name

That about wraps it up for root_table. Please provide me with feedback and report any bugs and improvements. You can use the comments on my blog, or the issues page on github.

Update!

I've made some tiny updates, most importantly reducing the amount of magic. Rails does a very nice job of lazy loading your models which can lead to some strange errors with the previous version of my plugin. These should be fixed now.

Lessons learned:

• A model does not know another model exist in development environment. Mentioning a model is enough to trigger Rails autoload and even constantizing a string works. Sweet!
• Don't require a model again during a request. Some models will break. I found this to be the case with the session class needed by AuthLogic. Again, to know for sure that a model has been loaded, simply mention it in your code, usually that is enough.
• Tests are run in an environment very similar to production. I already knew that, but it's worth mentioning that a stable development environment is also essential and you might not catch that with unit tests alone.

Rails.backtrace_cleaner.add_silencer { |line| line =~ /^\s*passenger/ }

Saves you scrolling through the endless backtraces passenger gives you for free :)

PS. A colleague tweeted this lovely backtrace of a spring with grails error. I say: backtrace cleaner FTW!

I like the method of using a named_scope and delegating to specified filters. This way, you can structure your filters properly and get clean URLs. Also, you can chain other named scopes to the filter.

If you find yourself making an administrative web application, with many tables and filters, here's an example to make it a little more DRY.

Making a partial

First, make the filters a partial, in something like app/views/shared/_filters.html.haml.

%h3= t(model_name, :scope => :filter_titles)
%ul
  - model_class.available_filters.each do |filter|
    %li= link_to t(filter, :scope => [:filter_names, model_name]), url_for(params.merge(:filter => filter))

I've changed the translate-calls a bit, so they work with different models.

A helper method

Then, create a helper method:

def show_filters_for(model_name)
  render :partial => "shared/filters",
         :locals => { :model_name => model_name, :model_class => model_name.to_s.camilze.constantize }
end

Now you can render the filters like this:

= show_filters_for :person

And a module

On the model side, you can make a module, probably in lib/chainable_filters.rb.

module ChainableFilters

  def self.extended(model)
    model.named_scope :filter, lambda { |f|
      model.available_filters.include?(f) ? model.send("filter_#{f}") : {}
    }
  end

  def available_filters
    self.methods.select { |m| m =~ /^filter_/ }.map { |m| m[7..-1].to_sym }
  end

end

Use it in a specific model, by extending with the module you just made:

class Person < ActiveRecord::Base
  extend ChainableFilters
end

Or just every ActiveRecord class, by creating an initializer file (i.e. config/initializers/chainable_filters.rb):

ActiveRecord::Base.extend ChainableFilters

Now, that is some nice meta-programming, if you ask me! ;)

I like the method of using a named_scope and delegating to specified filters. This way, you can structure your filters properly and get clean URLs. Also, you can chain other named scopes to the filter.

This is an example of how I would do that.

The view

In your index view, add a list of all filters:

%h3= t(:people, :scope => :filter_titles)
%ul
  - Person.available_filters.each do |filter|
    %li= link_to t(filter, :scope => [:filter_names, :people]), people_path(:filter => filter)

This will generate links that go to your index page (e.g. /people?filter=adults). You can even make a route that will clean up your views even more.

map.connect "/people/filter/:filter", :controller => "people", :action => "index"

I use i18n to get the displayed link text for each link, so my locale file might look something like:

en:
  filter_titles:
    people: Select a subset
  filter_names:
    people:
      deceased: Select deceased people
      alive: Select people that are (still) alive
      adults: Select people over 18

The controller

Add the named_scope to your query:

def index
  @people = Person.filter(params[:filter]).paginate(:page => params[:page])
end

The model

Here's the interesting stuff. Define the available filters as a class method:

def self.available_filters
  [ :deceased, :alive, :adults ]
end

Then, define class methods for each those filters, specifying what they need to do. I like to prepend them with "filter_", so it shows more intent. You can go crazy with these filter methods if you'd like. Just return valid ActiveRecord find-options.

def self.filter_deceased
  { :conditions => "deceased_on IS NOT NULL" }
end

def self.filter_alive
  { :conditions => "deceased_on IS NULL" }
end

def self.filter_adults
  { :conditions => ["birthday <= ?", 18.years.ago.to_date] }
end

And finally, add the named scope that uses these filters:

named_scope :filter, lambda { |f| available_filters.include?(f) ? send("filter_#{f}") : {} }

We check to see if the filter is available, excluding any invalid filter. Also, by default no filter is given from the controller. Then params[:filter] will be nil and so it won't try to call Person.filter_. You can replace the empty hash with a default filter if you like.

Conclusion

These predefined filters can really help the usability of your new fancy web application. And I like the code too, because it looks very clear and it's easy to test.

Named scopes can get quite messy, certainly if you use a lambda and some logic. Delegating the body of the lambda to a class method is a good idea. Just be sure that the method returns a hash of some sort.

named_scope :foo, lambda { |*args| foo_parameters(*args) }

You can make this into a named_scope generator even, but I'll save that for another time and post. Also, stay tuned for the encore: DRYing up the code for re-use!

Well, to get the prettiest results, I do something like this:

def write(filename, hash)
  File.open(filename, "w") do |f|
    f.write(yaml(hash))
  end
end

def yaml(hash)
  method = hash.respond_to?(:ya2yaml) ? :ya2yaml : :to_yaml
  string = hash.deep_stringify_keys.send(method)
  string.gsub("!ruby/symbol ", ":").sub("---","").split("\n").map(&:rstrip).join("\n").strip
end

I use the gem ya2yaml to create YAML, because the default Hash#to_yaml doesn't work well with UTF-8. If you have it installed and loaded, it uses that.

Then I turn all keys into strings with the method deep_stringify_keys, so the keys don't get formatted like the symbols they are. I remove some random junk and strip whitespace.

To add the deep_stringify_keys, open the Hash class:

class Hash
  def deep_stringify_keys
    new_hash = {}
    self.each do |key, value|
      new_hash.merge!(key.to_s => (value.is_a?(Hash) ? value.deep_stringify_keys : value)))
    end
  end
end

Here are the specs for this:

class Hash
  def deep_stringify_keys
    new_hash = {}
    self.each do |key, value|
      new_hash.merge!(key.to_s => (value.is_a?(Hash) ? value.deep_stringify_keys : value)))
    end
  end
end

First of, build the models. I have a project with many stages:

class Project < ActiveRecord::Base
  validates_presence_of :name
  has_many :stages
  accepts_nested_attributes_for :stages, :allow_destroy => true
end

class Stage < ActiveRecord::Base
  validates_presence_of :title
  belongs_to :project
end

Here is what the form partial for the project looks like:

- form_for @project do |form|
  %p
    = form.label :name
    = form.text_field :name
  #stages
    - form.fields_for :stages do |fields|
      = render :partial => "stage", :locals => { :form => fields }
  %p= partial_button(f, :stage, "Add stage")

And the stage partial:

.stage[form.object]
  %p
    = form.label :title
    = form.text_field :title
  %p= remove_partial(form, "Remove stage")

Ok, so nothing to scary there. Nice clean views. Those two helper methods might be scary though. But apart from that, it's actually quite normal.

Notice that the square brackets used at the first line of the stage partial either adds a class "new_stage" or "stage_X" (where X is the id of an existing stage object).

Let's see what's inside the partial_button method!

def partial_button(form, attribute, link_name)
  returning "" do |out|
    base      = form.object.class.to_s.underscore
    singular  = attribute.to_s.underscore
    plural    = singular.pluralize
    id        = "add_nested_partial_#{base}_#{singular}"
    form.fields_for attribute.to_s.classify.constantize.new do |field|
      html = render(:partial => singular, :locals => { :form => field})
      js   = %|new NestedFormPartial("#{escape_javascript(html)}", { parent:"#{base}", singular:"#{singular}", plural:"#{plural}"}).insertHtml();|
      out << hidden_field_tag(nil, js, :id => "js_#{id}") + "\n"
      out << content_tag(:input, nil, :type => "button", :value => link_name, :class => "add_nested_partial", :id => id)
    end
  end
end

Ok, this looks scary. But it isn't that scary. This method returns a string called out. First of I build some variables, which will be needed as options for the javascript, since javascript doesn't have those cool inflections ActiveSupport has.

Second, I am going to make a fields_for block, which you'll already know what it does. I render the partial and assign it to the html variable. Then I generate some javascript which initiates a new NestedFormPartial object. Finally, I build a hidden field, which contains this javascript as value and a button.

Here's the javascript, you'll need to add:

var NestedFormPartial = Class.create();
NestedFormPartial.prototype = {
  initialize : function(html, options){
    this.newId          = "new_" + new Date().getTime();
    this.html           = html;
    this.parentName     = options["parent"];
    this.singularName   = options["singular"];
    this.pluralName     = options["plural"];
    if (!this.pluralName) this.pluralName = this.singularName + "s";
    this.replaceHtml();
  },
  oldPartialId : function(){
    return this.singularName + "_new";
  },
  oldElementId : function(){
    return this.parentName + "_" + this.singularName + "_";
  },
  oldElementName : function(){
    return this.parentName + "\\[" + this.singularName + "\\]";
  },
  newPartialId : function(){
    return this.singularName + "_" + this.newId;
  },
  newElementId : function(){
    return this.parentName + "_" + this.newPartialId() + "_";
  },
  newElementName : function(){
    return this.parentName + "[" + this.pluralName + "_attributes][" + this.newId + "]";
  },
  replaceFunction : function(pattern, replacement) {
    this.html = this.html.replace(new RegExp(pattern, "g"), replacement);
  },
  replaceHtml : function(){
    this.replaceFunction(this.oldPartialId(),   this.newPartialId());
    this.replaceFunction(this.oldElementId(),   this.newElementId());
    this.replaceFunction(this.oldElementName(), this.newElementName());
  },
  insertHtml : function(){
    $(this.pluralName).insert({ bottom :  this.html });
  },
}

function initPartialButtons() {
  $$(".add_nested_partial").each(function(button, index) {
    Event.observe(button, "click", function(evt) {
      eval($("js_" + button.id).value);
    })
  });
}

Event.observe(window, 'load', initPartialButtons, false);

Ehm, what did I just do there? Well, the most important thing is that some parts of the partial get replaced. There are three problems which need to be addressed:

• A new object always has the same generated id for input fields. Adding two stages would mean that their ids would be the same and that would mean that the labels wouldn't be clickable (and it wouldn't be valid html).
• Rails wants "stages_attributes" to be included, when providing a new object, it would be named simple "stage".
• Rails expects a hash as stages_attributes. We'll need to add some arbitrary key, so it'll turn into a hash.

I generate a new id by using the timestamp and replace the values in my html. When the window loads I find any add_nested_partial class button and eval the value of the hidden field I added earlier, so the scripts gets executed.

As you can see, I did my best to make this as unobtrusive as possible, but going any further made my head hurt.

Finally, the remove_partial method, which I haven't cleaned up yet:

def remove_partial(form, link_name)
  attribute = form.object.class.name.underscore
  if form.object.new_record?
    button_to_function(link_name, "$(this).up('.#{attribute}').remove()")
  else
    form.hidden_field(:_delete) +
    button_to_function(link_name, "$(this).up('.#{attribute}').hide(); $(this).previous().value = '1'")
  end
end

I hope this helps. I found a lot of my initial optimism after hearing about accepts_nested_attributes_for have gone now. It cleans up a lot of code in the model though. I'll keep this post updated when I have some improvements.

Sources:

• Ryan's Scraps
• Eloy Duran's complex form examples

sudo gem cleanup

It removes old versions of your installed gems. You can of course specify the gems you'd like to cleanup.

For instance, a controller can be easily tested like this:

describe ArticlesController do

  integrate_views

  describe "the index action" do

    before :each do
      stub(@article = Article.new).id { 1337 }
      mock(Article).all { [@article] }
      get :index
    end

    it { should route(:get, articles_path).to(:action => :index) }
    it { should respond_with(:success) }
    it { should render_template(:index) }
    it { should_not set_the_flash }
    it { should assign_to(:articles).with([@article]) }

  end
end

As you see I'm a fan of rr as well. I love the sleek and concise syntax it offers, just as the Shoulda matchers.

So, now what?

Well, I don't like to spec views separately. It's too much of a drag to set up all the required instance variables, because there tend to be a lot of them. That's why I use the integrate_views command. I do want to spec some essential elements rendered in the view. Just knowing that no exceptions were thrown is not always good enough.

The solution is the have_tag matcher. This is actually a wrapper around assert_select, allowing you to use CSS selectors to check your view. I ended up testing links to certain actions, to ensure all the actions are reachable for the user. For example:

it { should have_tag("a[href=#{article_path(@article)}]") }

Yuck! That is a lot of noise! The whole use of RSpec is to create human readable tests. Also, there is a lot that can go wrong here. I will easily forget one or more of those differently shaped brackets. I want to write something like:

it { should have_link_to(article_path(@article)) }

Much cleaner! Making a matcher for this isn't that difficult:

module CustomLinkMatcher

  include Spec::Rails::Matchers

  def have_link_to(url)
    AssertSelect.new(:assert_select, self, "a[href=#{url}]")
  end

end

Don't forget to activate it, though:

Spec::Runner.configure do |config|
  config.include CustomLinkMatcher
end

So, why go through all this trouble? Why should I even care? I mean, the have_tag selector isn't that unreadable, just a bit cluttered. Well, I found that the ease of which you can type specs is directly related to how extensive you test. If a test is difficult to type, hard to read, or feels repetitive, most people (with possible exception of Bryan Liles ;) ) will get annoyed with it and don't do it anymore.

To give myself as an example. I never cared much about heckle. Heckle could mutate so much code, I soon stopped caring. Now, with the matchers Shoulda gives me, I like running Heckle! I know keeping Heckle happy shouldn't be a goal, and I accept certain things Heckle will heckle me about even now, but writing specs like this really made my tests much more robust!

So, in conclusion: if you find yourself hating to write certain specs, try to refactor your specs so it becomes easy and fun! Try to write tests as you would like your tests to be written. Testing should be fun! Keep it that way! Use every gem, tool and technique you have to do so!

I too will present you a Ruby x-mas present. It's a nice, but useless present, not totally out of line with the usual x-mas presents.

It is a gem called not. With not you can get rid of exclamation marks and the not keyword, and putting it later on in the sentence, thus making it better English.

An example:

# for core Ruby methods:
@foo.not.nil?
# or any custom method:
@user.not.active?
@user.not.save!

If you want it, you can install it as a gem:

sudo gem install not

or as a Rails plugin:

./script/plugin install git://github.com/iain/not.git

I hope you'll like it! Happy holidays!

Update

I moved the gem to gemcutter. If you haven't tumbled yet, please do so, before installing my gem:

gem install gemcutter
gem tumble

It changes:

<%= @user.name.blank? ? 'no value' : h(@user.name) %>

Into:

<%= show(@user.name, :h) %>

But wait! There is more! This method can accept blocks too and rescue you from those pesky nils! Keep on reading!

The problem I wanted to solve

This Ruby on Rails plugin tries to solve a common pattern when showing values from the database. If you want to show a nice message like 'no value' when an optional attribute has been left empty, you usually need to do the same thing over and over again:

<%= @user.name.blank? ? 'no value' : @user.name %>

It gets even worse when it's about an optional relation, with some extra methods:

<%= @user.daddy ? link_to(@user.daddy.name, @user.daddy) : 'no daddy' %>

The solution: no_value_helper

So this plugin tries to shorten this:

<%= show(@user.name) %>

Or the second example:

<%= show(:link_to, @user.daddy) { @user.daddy.name } %>

Don't worry, NoMethodErrors will be caught for you. That is why we use a block in this case.

For the exact usage, read the specs.

Configuration

To translate the message, you can simply add the "no_value" key (no scope) to your translation files.

nl-NL:
  no_value: geen waarde

By default the message is encapsulated by an em-tag with the class 'no_value'. To change this, set the class variable @@no_value_text with a lambda. This is done so I18n.translate will work. Make an initializer (in config/initializers/no_value_helper.rb), containing this:

module NoValueHelper
  @@no_value_text = lambda { "something more to your liking" }
end

You can also change how this plugin checks for empty values. By default this is done with the method blank? This means that empty strings are also treated as 'no value'. To change this, set the class variable @@no_value_check_method to a lambda that does what you want. Your initializer will look something like this:

module NoValueHelper
  @@no_value_check_method = lambda { |value| value.nil? }
end

Some more examples

Here are some more examples to inspire you:

<%= show(:l, :format => :long){@user.birthday} %>
<%= show(@user.savings, :number_to_currency) %>
<%= show(:simple_format){@user.contract.company.billing_address} %>

Luckily, there is a new plugin/gem that does this better. It's called AuthLogic. It used to be called AuthGasm, but now we can actually install it without blushing every time we do ls vendor/plugins. It gives you a familiar acts_as_authentic for your user model (nothing more, mind you!) and a UserSession model, which isn't inheriting from ActiveRecord, but from AuthLogic::Session::Base class, which AuthLogic provides.

The big plus is that now you can use form_for for user sessions just as you would for any ActiveRecord model. Your UserSessionsController can even be like rails scaffold provides. Just save to the @user_session object and a session is set.

You're free to make multiple sessions per user to be able to log in on multiple locations. Just read the README to see what is possible!

There are no specs provided with AuthLogic, so here are some helpers to spec controllers. Add them to spec_helper.rb or in another file which gets loaded by RSpec.

def current_user(stubs = {})
  @current_user ||= mock_model(User, stubs)
end

def user_session(stubs = {}, user_stubs = {})
  @current_user ||= mock_model(UserSession, {:user => current_user(user_stubs)}.merge(stubs))
end

def login(session_stubs = {}, user_stubs = {})
  UserSession.stub!(:find).and_return(user_session(session_stubs, user_stubs))
end

def logout
  @user_session = nil
end

So you can write specs like this:

describe SecretsController do
  before { login }
  it "should be very very secret!"
end

And as a litte bonus, it works nice with my plugin: acts_as_translatable_model. Making your login forms is easier than ever! So please take a look at it! I'm betting you'll love it!

<img src="rails.png?20849923" alt="Rails" />

If I wonder if a website was made in Rails, I always look at the HTML. This is a good indicator.

Sometimes you don't want this behavior. It can get in the way of wget, which saves the file including everything after the question mark. But it's not that straightforward to turn this off. At least, I couldn't find it. There is not much information available on this subject and I had to dive into the Rails source code to solve it.

The easiest way I found was to override a helper method:

module ApplicationHelper
  def rewrite_asset_path(source)
    source
  end
end

Please correct me if there is a simpler way!

I18n.t(:people, :count => @people.size)

With these translation-files:

en:
  people:
    one: "one person"
    other: "%{count} people"

nl:
  people:
    one: "een persoon"
    other: "%{count} personen"

First a small recap in how to load locales. Add this to a new initializer:

I18n.load_path += Dir.glob("#{RAILS_ROOT}/app/locales/**/*.yml")

This has been changed at a very late moment. I18n.store_translations and I18n.load_translations have been removed.

After that, you need to create a place to store your locales. Make the directory app/locales/nl-NL/ and place your yaml files in there. Here is the English version of the locale-file:

en-US:
  date:
    formats:
      # Use the strftime parameters for formats.
      # When no format has been given, it uses default.
      # You can provide other formats here if you like!
      default: "%Y-%m-%d"
      short: "%b %d"
      long: "%B %d, %Y"

    day_names: [Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday]
    abbr_day_names: [Sun, Mon, Tue, Wed, Thu, Fri, Sat]

    # Don't forget the nil at the beginning; there's no such thing as a 0th month
    month_names: [~, January, February, March, April, May, June, July, August, September, October, November, December]
    abbr_month_names: [~, Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec]
    # Used in date_select and datime_select.
    order: [ :year, :month, :day ]

  time:
    formats:
      default: "%a, %d %b %Y %H:%M:%S %z"
      short: "%d %b %H:%M"
      long: "%B %d, %Y %H:%M"
    am: "am"
    pm: "pm"

All you need to do is replace the English terms with the translated versions. Remember that all these keys are necessary to have. If you leave out, say month_names, it won't work at all.

After this is done, translate dates and times like this:

I18n.localize(Date.today)

If you want to use any of the other formats, specify this in the options hash:

I18n.localize(Date.today, :format => :short)

One more tip: you can add as many formats as you like, but remember that formats like :db are reserved for obvious reasons. Here is an overview of the strftime syntax in Ruby.

PS. Rails 2.2 RC1 is really really close now!

- if current_user.admin?
  %p= link_to(@project, :method => :delete)
-# or this:
%p= link_to(@project, :method => :delete) if current_user.admin?

It's no problem when you're doing this only once or twice, but as the project moves on, your views get swamped, and your controllers too! My suggestion is splitting it into multiple controllers, one for each role, like this:

ActionController::Routing::Routes.draw do |map|
  map.resources :projects
  map.resource :admin do |a|
    a.resources :projects, :controller => 'admin_projects'
  end
end

This will generate these paths (amongst all usual others):

      project GET /projects/:id       { :action=>"show", :controller=>"projects"}
admin_project GET /admin/projects/:id { :action=>"show", :controller=>"admin_projects"}

This way controllers and views stay clean and uncluttered. It has a cluttered rake routes as trade off though, but that's just a minor problem if you ask me. The admin controller can be used as administrator dashboard. If you have another solution, I'd love to hear it!

./script/plugin install git://github.com/iain/acts_as_translatable_model

class User
  acts_as_translatable_model

  attr_accessor :name, :password
end

Now you can do familiar things with the class, just as you would do with normal ActiveRecord models. Supply a translation:

nl-NL:
  activerecord:
    models:
      user: gebruiker
    attributes:
      user:
        name: naam
        password: wachtwoord

User.human_name
# => "gebruiker"
User.human_attribute_name("name")
# => "naam"

Of course, you can use inheritance, just as you would use Single Table Inheritance (STI).

It also works nicely together with i18n_label. A simple example:

%h1= translate :please_login
- form_for(User.new) do |f|
  = f.label :name
  = f.text_field :name
  = f.label :password
  = f.password_field :password
  = submit_tag( translate(:login) )

Hopefully, this will make your life a little bit easier.

Since form labels don’t use I18n in Rails 2.2 (I was too late in submitting the patch), we’d have to make due with a plugin.

Installation and configuration consists of 1 easy steps:

• Run: ./script/plugin install git://github.com/iain/i18n_label.git

Example

In your translation file:

en-US:
  activerecord:
    attributes:
      topic:
        name: 'A nice name'

In your view:

<% form_for Topic.new do |f| %>
  <%= f.label :name %>
<% end %>

The result is:

<label for="topic_name">A nice name</label>

For more information about where to put your translations, read my post about translating ActiveRecord.

Installing

First make sure you're running Rails 2.2 or edge:

rake rails:freeze:edge

Install the plugin:

./script/plugin install git://github.com/iain/translatable_columns.git

Create or modify a model to have multiple columns for one attribute:

./script/generate model Topic title_en:string title_nl:string title_de:string title_fr:string

Usage

Identify the columns you want to translate:

class Topic < ActiveRecord::Base
  translatable_columns :title
end

And you're done!

Create a form like this:

<% form_for(@topic) do |f| %>
  <%= f.text_field :title %>
<% end %>

And it will save to whatever locale is set in I18n. No hard feelings, nothing to worry about.

Validating

Validation is of course built in. If you want to validate the presence of at least one of the translations, just call validates_translation_of:

class Topic < ActiveRecord::Base
  translatable_columns :title
  validates_translation_of :title
end

This will make your record invalid when none of the translated columns exist. It works exactly as validates_presence_of, including all its options!

Customizing

You can change the settings of translatable_columns on both a global level and at individual attribute level. There are two configuration options at the moment, called full_locale and use_default.

Set the global configuration in your environment file:

# These are the defaults of translatable_columns:
ActiveRecord::Base.translatable_columns_config.full_locale = false
ActiveRecord::Base.translatable_columns_config.use_default = true

full_locale

With this option you can change which part of the locale is used in the columns. Default is false, so only the first part of the locale is expected in the column. So a title for en-US is called title_en and a title for en-GB is also called title_en. When you set full_locale to true, it uses the entire locale, substituting the hyphen with an underscore. This way a title for en-US is called title_en_us and a title for en-GB is called title_en_gb.

full_locale cannot be set per attribute just now.

use_default

With this option you can specify which value will be returned automatically if no proper value has been found. Default is true, so it will try harder to find a value. It might even be a value in another language.

You can set this option per attribute if you'd like, to override the global config.

class Topic < ActiveRecord::Base
  translatable_columns :title, :use_default => false
end

Some extras

What if the user has selected a locale which you don't have in the database? In this case it'll get the column belonging to the I18n.default_locale. Make sure you have a column for this locale, because you'll be serving a nasty error if even this one isn't present!

You might want to provide multiple languages for a user to fill in at once. This is one way to do it:

<% form_for(@topic) do |f| %>
  <% Topic.available_translatable_columns_of(:title).each do |attribute| %>
    <%= f.text_field attribute %>
  <% end %>
<% end %>

Happy devving!

Nice to see that Sven also thanked himself :)

Dmitry asked in the comments of my last post about translating ActiveRecord:

Can you write about how to use translated columns of database in rails? For example we have table named ‘blog’, and I want to translate it on several languages: fr, en, ru. How to do that?

And although I don't think this is the way to go, I can of course demonstrate an easy way to do this, using I18n.

Here's the table definition:

create_table :posts do |t|
  t.string :title_en, :title_nl, :title_fr, :title_de
  t.string :text_en, :text_nl, :text_fr, :text_de
end

So what you'd want to do is read the currently selected locale and choose to write to the proper attribute depending on that.

class Post < ActiveRecord::Base
  def title
    self[column('title')]
  end
  def title=(str)
    self[column('title')] = str
  end
private
  def column(name)
    column_name = "#{name}_#{I18n.locale.split('-').first}"
    self.class.column_names.include?(column_name) ? column_name.to_sym : "#{name}_#{I18n.default_locale.split('-').first.to_sym}"
  end
end

Now, you can treat Post as if it had a normal title attribute, but it would save to the proper column. If you don't have a column named for this attribute, it'll save or get the value of the default_locale.

So for instance you can do this in your edit view:

<% form_for(@post) do |f| %>
  <%= f.text_field :title %>
<% end %>

But when you have multiple columns that needs to be translated, even scattered through multiple models, it tends to be a boring and repeating business to add all those virtual attributes. So let's do some meta-programming, and clean up models!

First, make a file in the RAILS_ROOT/lib directory, called load_translations.rb and put in this Ruby meta-programming goodness/madness:

module TranslatableColumns

  def translatable_columns(*columns)
    columns.each do |column|

      define_method column do
        self[self.class.column_translated(column)]
      end

      define_method "#{column}=" do |value|
        self[self.class.column_translated(column)] = value
      end

    end
  end

  def column_translated(name)
    column_name = "#{name}_#{I18n.locale.split('-').first}"
    self.column_names.include?(column_name) ? column_name.to_sym : "#{name}_#{I18n.default_locale.split('-').first.to_sym}"
  end

end

Now all you have to to in the model is extend it with this module and specify which columns can be translated:

class Post < ActiveRecord::Base
  extend TranslatableColumns
  translatable_columns :title, :text
end

Still I'm not really fond of this. I can't find a good, sensible scenario where this would be the best option. I would rather go with an attribute called 'locale'. So let's look at that too.

./script/generate migration add_locale_to_post locale:string
rake db:migrate

And add a named_scope to the models you want to be localized, like Post in this case, to get the proper locales and save it to whatever locale was selected at the moment, if it hasn't already been set any other way (you might want to make the user able to choose it when entering the post).

class Post < ActiveRecord::Base
  named_scope :localized, { :conditions => { :locale => I18n.locale } } }
  before_save :store_locale
private
  def store_locale
    self[:locale] ||= I18n.locale
  end
end

Let's meta-program this one as well!

Get the proper posts, just call Post.localized or Post.localized.find(params[:id]). Note that I'm not using any translatable columns now. Just use normal columns and create multiple posts if you want more than one language for a post (e.g. create a Dutch one and a French one).

As you can see, I'm not using the translating functionality of I18n here. I just use I18n to know which locale to choose.

With Rails 2.2 releasing any day now, I want to show you how to translate ActiveRecord related stuff. It is quite easy, once you know where to keep your translations. Here is a complete guide to using all built in translation methods!

Scenario

Suppose we're building a forum. A forum has several types (e.g. admin) of users and suppose we want to make the most important users into separate models using Single Table Inheritance (sti). This gives us the most complete scenario in showing off all translations:

class User < ActiveRecord::Base
  validates_presence_of :name, :email, :encrypted_password, :salt
  validates_uniqueness_of :email, :message => :already_registered
end

class Admin < User
  validate :only_men_can_be_admin
private
  def only_men_can_be_admin
    errors.add(:gender, :chauvinistic, :default => "This is a chauvinistic error message") unless gender == 'm'
  end
end

Setting up

Make sure you're running Rails 2.2 or Rails edge (rake rails:freeze:edge)

Now let's translate all this into LOLCAT, just for fun. We need a directory to place the locale files:

mkdir app/locales

And we need to load all files as soon as the application starts. So we make an initializer:

# config/initializers/load_translations.rb
%w{yml rb}.each do |type|
  I18n.load_path += Dir.glob("#{RAILS_ROOT}/app/locales/**/*.#{type}")
end
I18n.default_locale = 'LOL'

This approach is recommended, because loading files is not something you want to do during the request, when it should already be available. Setting you're locale like this is probably not recommended, but it's easy, if you're just using one language.

Translating models

Next, we're going to make some simple translation files. All ActiveRecord translations need to be in the activerecord scope. So when starting your locale file, it starts with the locale name, followed by the scope.

LOL:
  activerecord:
    models:
      user: kitteh
      admin: Ceiling cat

Let's try this out in script/console

User.human_name
# => "kitteh"
Admin.human_name
# => "Ceiling cat"

It's nice to know that the method human_name is used by error messages in validations too. But we'll come to that in just a second.

If you didn't specify the translation of admin, it would have used the translation of user, because it inherited it.

Translating attributes

We could append to the same file, but I choose to make a new file, because it keeps this post clean and it's a bit easier to see how the scoping works.

LOL:
  activerecord:
    attributes:
      user:
        name: naem
        email: emale

And let's try this again:

User.human_attribute_name("name")
# => "naem"
Admin.human_attribute_name("email")
# => "emale"

Once again, you can see that single table inheritance helps us with this.

Both human_name and human_attribute cannot really fail, because if no translation has been specified, it would return the normal humanized version. So if you're making an English site, you don't really need to translate models and attributes.

Translating default validations

Let's translate a few default messages:

LOL:
  activerecord:
    errors:
      messages:
        blank: "can not has nottin"

u = User.new
# => #<User id: nil, etc>
u.valid?
# => false
u.errors.on(:name)
# => "can not has nottin"

Interpolation in validations

You have more freedom in your validation messages now. With every message you can interpolate the translated name of the model, the attribute and the value. The variable 'count' is also available where applicable (e.g. validates_length_of)

LOL:
  activerecord:
    errors:
      messages:
        already_registered: "u already is {{model}}"

u.errors.on(:email)
# => "u already is kitteh"

Remember to put quotes around the translation key in yaml, because it'll fail without it, when using the interpolation brackets.

Model specific messages

A message specified in the activerecord.errors.models scope overrides the translation of this kind of message for the entire model.

LOL:
  activerecord:
    errors:
      messages:
        blank: "can not has nottin"
      models:
        admin:
          blank: "want!"

u.errors.on(:name)
# => "can has nottin"
a = Admin.new
# => #<Admin id: nil, etc>
a.valid?
# => false
a.errors.on(:salt)
# => "want!"

Attribute specific messages

Any translation in the activerecord.errors.models.model_name.attributes scope overrides model specific attribute- and default messages.

LOL:
  activerecord:
    errors:
      models:
        admin:
          blank: "want!"
          attributes:
            salt:
              blank: "is needed for cheezburger"

a.errors.on(:name)
# => "want!"
a.errors.on(:salt)
# => "is needed for cheezburger"

Defaults

When you specify a symbol as the default option, it will be translated like a normal error message, just like you've seen with :already_registered. When default hasn't been found, it'll try looking up the normal key you have given. With :already_registered, that key has already been set by Rails, because we're using validates_uniqueness_of.

When you specify a string as default value, it'll use this when no translations have otherwise been found.

a.gender = 'f'
# => "f"
a.valid?
# => false
a.errors.on(:gender)
# => "This is a chauvinistic error message"

Using error_messages_for

When you want to display the error messages in a model in a view, most people will user error_messages_for. These messages are also translated. The message has a header and a single line, saying how many errors there are. Here are the default English translations of these messages. I will leave it up to you to translate it to LOLCAT. Win a lifetime supply of cheezburgerz* with this mini-competition ;)

en-US:
  activerecord:
    errors:
      template:
        header:
          one: "1 error prohibited this {{model}} from being saved"
          other: "{{count}} errors prohibited this {{model}} from being saved"
        body: "There were problems with the following fields:"

There is one slight problem with the messages it displays. error_messages_for uses the errors.full_messages in it's list. This means that the attribute names will be put before it. Of course these will be translated with human_attribute_name, but it might not always be desirable. In other languages than English it's sometimes hard to formulate a nice error message with the attribute name at the beginning. This will have to be fixed in later Rails versions.

Conclusion

I hope you'll agree with me that these translation options for ActiveRecord are really nice! This is what we have been waiting for. Too bad I was a bit too late with my adjustments, so form labels don't translate by default. I did build it, but Rails was already feature frozen by then. I will probably post a plugin that adds this functionality. Same goes for a i18n version of scaffold.

Please keep coming back to my site, or add the RSS feed to your favorite reader.

Of course, stay in touch with the i18n mailinglist. A lot of people are putting a lot of effort into the project. New plugins and gems solving problems problems rapidly. I18n is one of the more difficult things to do, so if you have a special insight in a language, please contribute!

Happy devving!

PS. Damn! I wish I was in Berlin right now!

* invisible cheezburgerz only

Update

This post is old. Still, after 2 years, it still accounts for 10% of my daily traffic. How cool is that? Seriously though, read the official Rails guide on this subject, for up to date information!

Ruby on Rails (r9r ;) ) v2.2 ships with builtin internationalization (i18n). It tries to solve the problem dividing the world: language and localization (l10n). This topic is the most annoying of most topics in programming. Anyone who has ever worked with dates, timezones and number formatting has probably been swearing at it, loosing sleep over it and cursing the fact that difference exist between cultures. The idiot that made this decision "I know that they use a comma as delimiter in country X, but in my country we're going to use a dot!" certainly deserves to be shot, if he (or she) hasn't already died. And whoever thought of the ridiculous way in how we measure time? Dates and times really suck!

There are two kinds of problems here. If you live in a country other than the US, preferably one where they don't speak English, and want to make a website, you're immediately fucked. If you are from any English speaking country, or just don't care yet, the problem will arise a bit later when you're expanding beyond the borders.

Making your site in just 1 language is relatively easy. Before Rails 2.2 we had to rely on a lot of monkeypatching, overriding some key parts of the framework. But not anymore. In Rails 2.2, only two lines will fix the problem.

I18n.locale = 'nl-NL'
I18n.load_path << "#{RAILS_ROOT}/config/translations.yml"

Put them somewhere they'll get loaded, an initializer will do. All you need to do now is to make you're basic Rails translations for you language. Does your language use a dot or a comma, what does "invalid" mean in your language, etc.

Having multiple translations at once, were the user can choose the language they prefer, is a bit more difficult. You have to find out which language they have chosen and load the proper translation file every time a new request comes in. The best way to do this is make a before_filter in your application controller. In here you find out what the language is, and load the appropriate file.

class ApplicationController < ActionController::Base
  before_filter :set_locale
  private
  def set_locale
    I18n.locale = params[:locale] or session[:locale] or I18n.default_locale
  end
end

How to make translation files is the topic of my next post, so stay tuned! Stay updated through the mailinglist too! For now, things are still changing rapidly, so please take care. When Rails 2.2 ships (hopefully somewhere next month), it'll be safe!

But time hasn't stopped. Ruby on Rails is busy advancing to version 2.2. One new feature in the upcoming Rails version has caught my eye and my undivided love and attention. It's the I18n-module built into Rails! It is already available if you're running edge.

Rails 2.2 ships with it's language elements already indexed and a simple backend (called SimpleBackend) for handling translations. The whole idea is to keep it as simple as possible so any developer can implement their own way of doing the i18n-dance. The SimpleBackend keeps it translations in memory. Soon a new version of Globalize will arrive for storing translation in a database and no doubt a gettext based backend will appear soon too.

Using the SimpleBackend, translating your database is dead easy. Amongst it's features are (in no particular order):

• Scoping, for sorting your keys and thus avoiding name clashes
• Bulk look up of multiple translations
• Default translations for when the translation hasn't been found
• Interpolation, inserting values in the middle of translations
• Pluralization, handling multiple translations depending on a value being plural or singular
• Having multiple default translation, for using another keys as default
• Localization of dates and times

I can't go into each features into one post, so I'll be posting more in a while. First, let us take a look at the basics:

I18n.store_translations( 'en-US', { :hello => 'hello' } )
I18n.store_translations( 'nl-NL', { :hello => 'hallo' } )
I18n.translate( :hello ) # => "hello" (en-US is the default locale)
I18n.locale = 'nl-NL'
I18n.translate( :hello ) # => "hallo"

The big advantage is that I18n is now baked into Rails, so all you're favorite "railties" will automagically be translated (en-US translations are of course default and provided for, so you don't have to use I18n if you don't want to). Amongst others, cool stuff like date-formats, number and currency formatting and default ActiveRecord error messages are indexed. Here is an example:

I18n.store_translations( 'nl-NL', { :support => { :array => { :sentence_connector => 'en' } } } )
%w{a b c}.to_sentence # => "a, b, en c" (look mama, no I18n.translate call!)

In date(and -time) objects you need to call the method localize to translate. You can define your own preferred formats too, so no more need for those ugly strftime method calls in your code.

I18n.localize( Time.now, :format => :long ) # "vrijdag, 8 augustus 2008, 20:51:15"

ActiveRecord column names and error messages are easily translated too! You just have to know the proper scope. What you need to do is store translations in these scopes and Rails will automatically use it for you. In my opinion it is a bit of mess. Hopefully it'll be changed to something less scattered soon.

In this example, I have a model called Post and it has an attribute named 'title'.

Update 1

The proper way to translate ActiveRecord is described here!

I18n.store_translations( 'en-US', {
  :active_record => {
    :error => {
      :header_message => "default message for error_messages_for",
      :post => "When the model name is not what you like"
    },
    :error_messages => {
      :blank => "your default 'cannot be blank' message",
      :custom => {
        :post => {
          :title => {
            :blank => "error message for @post.title only"
          }
        }
      }
    },
    :human_attribute_names => {
      :post => {
        :title => "Translation of the column name"
      }
    }
  }
} )
I18n.translate :'active_record.human_attribute_names.post.title'
# => "Translation of the column name"

Unfortunately there isn't a good list of which translations are available. I will try to make one soon.

There are some limitations to the default I18n implementation. How you want to incorporate it in your site is completely up to you. Also, how and where you keep your translations has not been implemented. So you have to load a bunch of files yourself in which you keep translations.

But it gets easier. I made a plugin, called i18n_yaml, which handles all of this for you. It is not a different backend, but rather an extension to SimpleBackend. It stores its translation files in yaml-files found in app/locales. It also provides a before_filter to find the appropriate locale. In other words: everything you need to make SimpleBackend useful! Like Rails 2.2, it is not finished yet, but you can have a go at it of course.

Would you like to contribute to i18n? Join the mailinglist. Rails i18n also launched it's own website: rails-i18n.org. There are a number of tutorials and articles already available, listed here.

This concludes the first part of the Rails i18n introduction. I'll be posting some more insights into i18n soon, so stay tuned!

Update 2

Locate the locale.yml files in Rails to find all possible translations. Here is a pastie with everything translated to Dutch.

create_table "users" do |t|
  t.column :name, :string, :limit => 40
  t.column :email, :string
  # etc
end

I almost didn't recognize it at first. I didn't know Ruby back then, I just did what was necessary to make it work without looking at what it does. But take a good look at what it really does. It creates a table and gives you an object for you to play with. Within the block you can edit the properties of the thing you're creating in small readable lines. Ruby itself is full of these functions. Iterators are probably the best examples. What would any Ruby programmer do without each, select and sort? These blocks are arguably one of the nicest features in Ruby.

It's good to know that Rails incorporates this feature. Although I find it lacking in the view part. Sure you'll use methods like each, but think of all the helper-methods out there. Usually they are single methods doing some stuff and returning some HTML. Nice, but a bit cumbersome. Not that you'd need anything more complicated for creating a link or an image, but there is hardly anything 'sweet' going on in the views.

Then there are forms. Forms form the center of any web application, certainly Rails-made applications. In the views at least. Rails gives us the form_for and form_tag methods. These work in rather the same way as the migrations, giving you an form-object to play with. With this form object you can create all kinds of fields. Consider this simple form:

<% form_for(@user) do |form| %>
  <p>
    <%= form.label(:name, 'your name:') %>
    <%= form.text_field(:name) %>
  </p>
  <p>
    <%= form.label(:password, 'your password:') %>
    <%= form.password_field(:password) %>
  </p>
<% end %>

You might think: "That's rather neat!" and it is! But it is still lacking a lot. For once it's not DRY. You can correct that by making your own form builder, moving stuff to partials and a lot of other great examples float around the web waiting to be implemented. But something strikes me here. If the form is an object, why aren't fields? Why don't we apply the same principle here? Fields can have a lot of properties that would make the block-with-object method a nice solution. A field may have label, but also a description, some javascript validation, it can be a required field. A field my have multiple fields in it, like multiple checkboxes or radiobuttons. A block-with-object method for your fields might look like this:

<%= form.create_field(:name) do |field|
  field.type = :text_field
  field.label = 'Name'
  field.required!
  field.description = 'Please enter your name here. It may only contain alphanumeric characters and underscores'
end %>

<%= form.create_field(:category_ids) do |field|
  field.label = 'Select some categories'
  field.type = :checkboxes
  field.add_options do |opt|
    opt.add 1, 'foo'
    opt.add 2, 'bar'
  end
end %>

I hope you agree with me that this is much more readable and editable. It trades of long lines for more shorter lines which is a good trade-off. If you're using Haml for your views it's even more important to have short lines than in ERB. In Haml you can't easily break up lines so short lines of code is vital to the readability of your views. Views naturally have the tendency to become hard to follow and ugly, so it is recommended that important and complex parts of it (mainly views) stay easy and readable. Readability helps your maintainability. I am currently making this kind of form builder, so if you have any suggestions, please do!

But why stop here? Forms are not the only part which involves a lot of HTML and repetitive coding. Website often include blocks in a sidebar which are totally suited for this kind of solution. These are the days of glossy website designs, in the world of Web 2.0 every angle is softened or rounded. Sometimes this asks for a lot of HTML, building divs into divs. I'm a fan of Haml for making this easy, but you need a way to shorten lines, and in some way 'metaprogram' your HTML. At the risk of sounding 'Java-ish', I'd say it would be better to build an extra layer of abstraction into the so trusty MVC. In your view you decide what goes where, what your lines are and which fields are available. Above it lies an HTML layer which translates it to whatever your website is designed to look like. A view gets split in two: a structural layer and a design layer. If thought out well you can even change one layer without the need to change the other.

This might not be your solution. Your website might be too small to make such a difference. But it's worth thinking about it when you're building something. If you're making a helper-method, and you find yourself in need of a lot (say, more than 2) arguments, consider making a small object with some accessors to making this easy. Here is something to help you on your way:

# in your view, traditional way (which can get very long, depending on the number of arguments):
<%= small_menu(:title => 'Monkey', :foo => 'bar') %>

# with a small helper class and a block structure it may become:
<%= small_menu do |sm|
  sm.title = 'Monkey'
  sm.foo = 'bar'
end %>

# you'll need this in your helper for that:
module SomeHelper

  def small_menu
    sm = SmallMenu.new
    yield sm
    # construct your html here, using parameters from the sm-object
  end

end

# in the same helper (only if it's short) or in another file (helper or lib)
class SmallMenu
  attr_accessor :title, :link, :partial, :foo
end

By the way, if you haven't seen it yet, you should watch Railscast episode 101 for another nice way to incorporate classes into your helpers.

#feedback
  = remote_form_for(@feedback ||= Feedback.new, :url => @feedback, :update => 'feedback') do |f|
    = f.input_field :message
    = submit_tag

will result after the button is pressed:

<div id="feedback">
  <div id="feedback">
    <form>etc
  </div>
</div>

One solution is to create the div outside of the partial, but that would make the partial less self sufficient. Since I am a big fan of self sufficient partials, I'd want to just render the partial, and never to care about any div's around it.

An ugly solution, especially when using Haml, is to dynamically create the open and close tags:

= '<div id="feedback">' unless request.xhr?
- remote_form_for(etc)
= '</div>' unless request.xhr?

My solution is a small helper, resulting in this view-code:

= content_for_ajax_request(:id => 'feedback') do
  = remote_form_for(etc)

Which requires this helper:

def content_for_ajax_request(options = {}, &block)
  c = capture_haml { yield }
  request.xhr? ? c : content_tag(:div, c, options)
end

The only minor problem is, that it screws up the indentation, but I'm not being picky this time.

When you're not using Haml, but ERB, just use this:

def content_for_ajax_request(options = {}, &block)
  c = capture { yield }
  request.xhr? ? c : content_tag(:div, c, options)
end

Naturally, you can change the condition, if you'd like.

def div_if(condition, options = {}, &block)
  c = capture { yield }
  condition ? c : content_tag(:div, c, options)
end

This is exactly why I like Ruby so much. Using blocks can make your code so much sweeter...

Haml actually is a blessing. Doing minor adjustments is very easy, your code remains looking nice, the output keeps looking nice. Just be sure to know how to shift blocks of code to the left or right in your favorite editor.

OK, there are some downsides. You have very little control over how you HTML turns out. It is usually spot on, but sometimes you do have to use ERB. Making your own autocomplete boxes for instance. Here I needed to use ERB, because the indentation would end up in the textfield, which would break the functionality in IE6. You still have to use ERB in emails too, since you cannot afford to go to a new line with every variable.

One thing that especially enjoys me is that you cannot go to the next line unpunished. Sometimes you're tempted to enter a long line of Ruby code within your template. In ERB you could just go to the next line and continue there. With Haml that's not the case. So rather than making long and ugly lines of code, you should be triggered to use helpers more often. I need that nudge in the back.

But those are just tiny problems. After a while of using Haml, I can't imagine going back to ERB for an entire website. It is too tiresome using ERB, compared to Haml. And a good programmer is a lazy programmer, although admittedly not the other way round. ;)

One more tip: use helpers to render partials or partial-layouts to output HTML. That way you can have this kind of code:

In your view:

= in_special_block do
  %li.username=  h(@user.name)
  %li.edit_link= link_to( 'edit', edit_user_url(@user) )

And in your helper:

def in_special_block
  # do stuff
  render(:layout => 'shared/block_layout') { yield }
  # other stuff
end

• It's so definitely faster and easier to write than ERB.
• Your HTML output is nicer.
• Partials rendering with the right indentation automatically.
• It forces you to take a good look of what you're actually making.
• Because it's so strict on it's syntax, you will be using more helpers and custom model methods, which is a good thing.
• No more forgetting to close a div and spending hours to find out which one.
• Faster refactoring because of less code and easier to read.

There are some downsides however. I'd rather not talk about the hours I tried to fix some idiot problem with partials and the locals option. Just use locals as less as possible, preferably not at all. Some cons:

• Yet another syntax to be learned.
• Errors with Haml syntax are a bit harder to locate, but you'll make less after you encountered a few.
• A gem needs to be installed on the server, which can be difficult if you don't have root rights on the server
• The syntax highlighter on VIm is not quite up to it.
• Rails helpers screw up the nice HTML Haml creates for you. The form_tag helpers for example.

So if you are starting a new project, or redoing the entire HTML of you're application: try Haml! Chances are you'll like it!

My current project (not being the same as the one from my previous post about the knights templater) in which I totally wrote **123 **views, of which **48 **partials. Since this project was so Agile, it would have made fucking of the ugly fat girl from some party look like it had been planned and completely documented months in advance, it has become a jungle of views rendering partials rendering partials rendering partials. The HTML had come from the templaters, the functionality is all finished. All we (Arie and me) need to do now is completely reimplement all the views. Yuck!

Haml has been popping op often lately in my feed reader. It certainly gets the community talking, but no-one really implements it just yet. I heard Obie Fernandez's new company HashRocket is using it. And since I'm still an intern studying Ruby on Rails, this seemed the best moment to try it out for real.

But why Haml? Isn't there a faster way? A way to use the HTML done by the templaters? Well, no not really. Because all templates are more ruby code than HTML anyway. It has more "If I have one object of this, render that, or else, render that. If you have none of that, replace this with that and show this message". So much for separating Ruby code from HTML. In this project there is much more display logic than application logic and although I have about a dozen fully packed helpers, it can only go so far.

So we had to redo the site anyhow. It would be two weeks of sifting HTML from our old templates and replacing it with our new templates, putting in the ruby code again. Almost the same as retyping it all. So if I am going to be retyping it all, I want it to be fast. Let's put Haml to the test!

So I turned to Gettext. Gettext uses .po- and .mo files, like a proper GNU application, which attracted me. But when it came to substitution, small parts, like link texts, were scattered through the language file. I had to come up with a little scheme.

So I wrote a simple plugin for Ruby on Rails. This plugin inspects a single string to get pluralization with substitution. The single string keeps the translation in one place.

Although I created this plugin for gettext, it can be used whenever you like. If you're not using gettext, _("string").pluralize_for becomes "string".pluralize_for... Simple enough...

I've opened a google-code spot, so you can have a peak there, although I haven't gotten round to filling out every page there.

Learn how to install gettext in this excellent guide. Use this tip to get it working with Rails 2.0.

Installation

./script/plugin install http://pluralize-for-gettext.googlecode.com/svn/trunk/

And then rename vendor/plugins/svn to vendor/plugins/pluralize_for_gettext

Examples

<%=_('No posts ~~ Only one post ~~ You have {$N} posts!').pluralize_for(Post.count) %>

The example speaks for itself.

You can change the conditions for each part in the string:

<%=_('~~$N==0: No posts ~~$N==1: Only one post ~~else: You have {$N} posts').pluralize_for(Post.count)%>

Note: The translator can change the logic for this, for languages with weird pluralization rules. ;)

Caution: It's being eval'ed, so always check language files (or ruby code) for any Ruby injections.

Substituting more variables

Why not use the default sprintf-like function from rails? You'd get this:

<%_('You have %d posts, view %s') % [ Post.count, link_to(_('more'), view_more_url)%>

You'd get multiple entries in you .po file, and just 'more' can't be translated differently according to the context. The point of this whole exercise was to keep text that appears in one place together in the .po-file.

More advanced, for entering links and stuff, simply use {1:your text} and pass a block to the function to manipulate the texts in anyway you like. The number becomes the id for the array, so be careful in how you use them.

<%=_('No posts, create one by clicking {1:here} ~~ Only one post ~~ You have {$N} posts ~~$N&gt;6: You have {$N} posts, view {2:more}').pluralize_for(Post.count) do |i|
    i[1] = link_to(i[1], create_post_url) if i[1]
    i[2] = link_to(i[2], view_more_url) if i[2]
  %>

Which would result in the .po file:

#: app/controllers/some_controller.rb:102
  msgid "No posts, create one by clicking {1:here} ~~ Only one post ~~ You have {$N} posts ~$N>6~ You have {$N} posts, view {2:more}"
  msgstr "Geen artikelen, {1:plaats een artikel} ~~ Slechts een artikel ~~ Je hebt {$N} artikelen ~$N>6~ Je hebt {$N} artikelen ({2:bekijk meer...})"

Simple pluralizations

Perhaps you just want to specify a singular and plural for one word in the entire sentence:

<%=_('You have {$N} {post|posts}').pluralize_for(Post.count)%>

English is simpler than many other languages, so the translator could change it into the more elaborate version:

#: app/controllers/some_controller.rb:102
  msgid "You have {$N} {post|posts}"
  msgstr "~~$N==0: Helemaal geen artikelen ~~$N==1: U heeft een artikel ~~$N>1: U heeft {$N} artikelen"</pre>

"$N==0:No posts. {1:create one}.~~else:You have {1:{$N} new {post|posts}}...".pluralize_for(Post.count) do |i|
  i[1] =  link_to(i[1], url) if i[1]
  i[2] = link_to(i[2], other_url) if i[2]
end

More news about my adventures with Selenium. It's hot and juicy, so lot's of exciting new things to do. I made a syntax highlighter for plain text stories in vim. Here's how it looks:

To make it look like this, I adjusted the slate colorscheme and added my own story syntax file.

Here is what you need to do:

Put the black-slate colorscheme file in /usr/share/vim/vim71/colors directory

Put the story syntax file in /usr/share/vim/vim71/syntax directory

Append these lines to the end of /usr/share/vim/vim71/scripts.vim:

if did_filetype()
  finish
endif
if getline(1) =~ "^Story:\s.*"
  setf story
endif

Add these lines to your personal vimrc (~/.vimrc) or the systemwide vimrc file (/etc/vim/vimrc):

set background=dark
set tabstop=2   "please default all tabs to 2 spaces
set shiftwidth=2
set expandtab
set number
set smartindent
set smarttab
filetype plugin on
filetype indent on
colorscheme black-slate

Type your plain text stories, make sure every story file starts with 'Story:' It won't recognize it's a plain text story right away, so first type 'Story:', save it and reopen it to get nice colours.

By the way, Arie has made a syntax highlighter for the google javascript syntax highlighter. Keep a look out on his blog too!

Story: Selenium clicking a label

As a developer
I wanted to make acceptence tests
So I installed Cucumber and Selenium

  Scenario: Writing clean tests
    When I wanted to make the stories as clean as possible
    And I wanted to click a rails generated radiobutton
    Then the story became ugly
    And it had lines like 'the user clicks a customer_gender_m button'

  Scenario: I made a step for labels, getting the text
    When I wanted to get rid of it
    And I couldn't find an easy answer
    And I spent the better part of my evening googling it
    Then I made a post on the Selenium forum
    And asked for advice

  Scenario: I found a solution myself
    When I was sitting in the train
    And I was trying all kinds of solutions
    Then I stumbled upon the solution
    And I was overjoyed
    And it was: $selenium.click("//label[text()='#{label}']")

So here is the entire step:

When "the user clicks on a $element labelled $label" do |element, label|
  $selenium.click "//label[text()='#{label}']"
end

Luckily we were assured by the project manager: "This is an easy website. People enter the website, choose which prize they want to win, enter some data and that's it. Nothing big, because there are no users having to log in." After drawing up a rudimentary class diagram I found out that a website without users is in fact quite hard! You can invite more than one person to the company (a big Dutch insurance company), you have to insure that all it's invites becomes linked to the same person for letting him have more chance of winning the prize. We had to fake logged in users and all relations that user had, put it all into a session, but still use the database on every form to utilize the validation ActiveRecord gives us.

Speaking of testing, we're quite fans of Behavior Driven Development, using Rspec and user stories and such, but we had no time for it. We are going to write some specs and acceptance tests next week, after the website goes live, hopefully finding no big bugs after that. With a few managers looking down on our shoulders every few hours, the pressure was on to come up with as much functionality in a short amount of time. Thus making the Dilbert way of Agile development a reality.

Still there was a black hole of productivity lurking. What would cost us the most time, was implementing the HTML. For years, any decent IT company has it's own designing team with HTML template makers and all. These people know a lot about all the quirks of this horribly abused markup language, and spit out giant blobs of static pages representing each page of the application. And although it looks pretty, for a developer in Rails, it's a nightmare of converting that into Rails views, templates and partials. Every image tag, label, form element and so on needed to be looked at, replaced or altered. With no consideration of how difficult javascript can be, dropdowns magically interacting with the page are added. A button, described with "doing the obvious thing", would have to do all kinds of fancy Ajax stuff, being as nice as your everyday Google-application. Designers never think about error messages, where they should go and how your application should deal with unexpected behaviour. By far the worst thing is that you'll be given the entire CSS every time, so you had to dig through it to find changes, convert it again and implement it.

But, despite of it all, I like the outcome. Everyone did their best, everyone with a bit of HTML knowledge stepped in to help, to make the deadline. It was definitely worth it!

Update: Leven is now live on http://www.levenals.nl/

Here are some stats:

+----------------------+-------+-------+---------+---------+-----+-------+
| Name                 | Lines |   LOC | Classes | Methods | M/C | LOC/M |
+----------------------+-------+-------+---------+---------+-----+-------+
| Controllers          |   244 |   204 |       4 |      20 |   5 |     8 |
| Helpers              |    19 |    16 |       0 |       1 |   0 |    14 |
| Models               |   215 |   167 |       7 |      20 |   2 |     6 |
| Libraries            |     0 |     0 |       0 |       0 |   0 |     0 |
| Integration tests    |     0 |     0 |       0 |       0 |   0 |     0 |
| Functional tests     |    24 |    18 |       3 |       3 |   1 |     4 |
| Unit tests           |    61 |    46 |       7 |       7 |   1 |     4 |
+----------------------+-------+-------+---------+---------+-----+-------+
| Total                |   563 |   451 |      21 |      51 |   2 |     6 |
+----------------------+-------+-------+---------+---------+-----+-------+
  Code LOC: 387     Test LOC: 64     Code to Test Ratio: 1:0.2

namespace :test do
  desc "Run all tests at once through rcov."
  task :rcov do
    test_files = FileList['test/**/*_test.rb']
    output_dir = File.expand_path("./coverage/all/")
    command = "rcov -o \"#{output_dir}\" --rails --sort=coverage -T -x \"gems/*,rcov*,lib/*\" \"#{test_files.join('" "')}\""
    puts command
    puts `#{command}`
    puts "View all results at <file://#{output_dir}/index.html>"
  end
end

Now, it doesn't take any argument yet, but it works quite all right.

class User < ActiveRecord::Base
  has_many :subscriptions
  has_many :newsletters, :through => :subscriptions
end

class Subscription < ActiveRecord::Base
  belongs_to :user, :dependent => :destroy
  belongs_to :newsletter, :dependent => :destroy
end

class Newsletter < ActiveRecord::Base
  has_many :subscriptions
  has_many :users, :through => :subscriptions
  has_many :old_users, :through => :subscription, :conditions => 'age > 60'
end

Now you'll see that having a nice name for the join model is important for keeping it readable. From personal experience I really need to repeat that: It is important to give a good name to your join model. You might be tempted to use the default way of calling has_and_belongs_to_many. That would be newsletter_users. It would be incredibly annoying to have to refer to that name all the time, confusing and ugly.

Anyway, with this in place you can do nice stuff like: current_user.newsletters or @my_mag.old_users. It's cool, but still very elementary. And though you can do much more than this, there are still some loose ends. Sometimes you'll want to have the subscription, because you'll want to update it, or destroy it, or whatever. Here is one of many solutions:

class Newsletter < ActiveRecord::Base

  # amongst all the other stuff

  # find the subscription, call it like this:
  #   @newsletter.subscription_by(current_user).created_at
  def subscription_by(user)
    self.subscriptions.find_by_user_id(user.id)
  end

  # Creates a new subscription or updates the one already there, with the given attributes
  def save_subscription_for(user, attributes = {})
    s = self.subscription_by(user) || self.subscriptions.new(:user => user)
    s.update_attributes(attributes)
  end

end

There is more and more elegant ways to do this. I'll get back to you on that. Leave any suggestions in the comments.

To rid yourself of the problem once and for all, add this to your ApplicationController:

def url_for(options)
  url = super(options)
  url.gsub!("%2F","/") if has_nice_url?(url)
  url
end

def has_nice_url?(link)
  rs = ::ActionController::Routing::Routes
  segments = rs.recognize_path link
  rs.named_routes.routes.each do |key,value|
    return true if
      value.defaults.has_value?(segments[:controller]) and
      value.defaults.has_value?(segments[:action]) and
      value.defaults.include?(:nice_url)
  end
rescue ::ActionController::RoutingError
  logger.debug{"RoutingError has occured"}
end

Now there is no need for overloading link_to or redirected_to. Remember, you'll need this in your config/routes.rb, to make it all work:

map.show_article 'article/:id/*nice_url', :controller => 'articles', :action => 'show', :nice_url => nil

And in your model, you have to add:

def to_param
  self.id.to_s+'/'+self.title.gsub(/\W+/,'-').downcase+'.html'
end

Now you can make awesome links like this:

link_to h(@article.title), show_article_url(@article)
redirect_to show_article_url(@article)

First you get the id, than you get a nice version of the title ending with .html. This is a nice way of making links, scoring high for a googlebot and is incredibly easy to read.

I first tried to use only the title as an identifier. Now normally there would be a problem with having titles in your uri. First of all you might want to have special characters in your title. Rails automatically converts them back into the characters they are when evaluating the routes, so it would result in this problem: /news/my%2Ftitle.html would evaluate to /news/my/title.html, which the Rails Router doesn't understand.

Besides, it doesn't look good. But when changing the title to my-title.html, just for output, there is no good way of getting it back to the original title. Even more problematic is my/title and my-title would lead to the same page. I concluded that you'll definitely need an id in your uri. But how would I have the title in it then?

The solution is a nice named route, like this one:

map.news 'news/:id/*nice_url', :controller => 'news', :action => 'show'

Now to get the title to appear automatically, so you don't have to code it every time you make a link. Go to the model and add this method:

def to_param
  self.id.to_s+'/'+self.title.gsub(/\W/, '-').squeeze('-').downcase+'.html'
end

Now every time you use news_url(@news) it adds the title nicely formatted. One downside though: Because it is a parameter Ruby converts it to %2F. As it should, I might add. But in this case we don't want it, it looks silly. But it works. Fixing this is a bit tricky. You must overload the link_to function. I've done it like this:

def link_to(text, link, *options)
  super(text, convert_nice_url(link), *options)
end

private

  def bare_path(txt)
    txt.sub(/^\/*/, '/').sub(index_url,'')
  end

  def convert_nice_url(link)
    link = url_for(link) unless link.is_a?(String)
    rs = ::ActionController::Routing::Routes
    segments = rs.recognize_path(bare_path(link))
    has_nice_url = false
    rs.named_routes.routes.each do |key,value|
      has_nice_url = true if
        value.defaults.has_value?(segments[:controller]) and
        value.defaults.has_value?(segments[:action]) and
        value.defaults.include?(:nice_url)
    end
    link.gsub!("%2F","/") if has_nice_url
    return link
  rescue ::ActionController::RoutingError
    return link
  end

It looks if your route has the parameter nice_url and in that case it replaces %2F with genuine forward slashes. You might want to do this for link_to_remote and redirect_to as well.

Update: In routes.rb, don't forget to add a named route called index, pointing to '', as a default route. This script needs that. Furthermore, you need to make the default of the parameter nice_url nil. This is the final version of routes.rb:

map.index '', :controller => 'news', :action=>'index'
map.news 'news/:id/*nice_url', :controller => 'news', :action => 'show', :nice_url => nil

Update 2: I will be following up on this item, to properly implement this. Come back again later!