And now he has written a book, a really good book, about advanced Rails programming techniques, called Crafting Rails Applications.

The book is only 180 pages long, and contains 7 chapters. I wish more books was this thin. The books is written in a clear concise way. José's lightweight test-driven approach clearly introduces every problem it intends to solve, and then solves the problem by introducing a new concept in the Rails framework. Most of the solutions are only a few lines of code, showing the power of Rails and also showing the power of having intimate knowledge of the framework. By hooking into the framework at appropriate places, José is able to provide elegant solutions to a range of problems.

I highly recommend the book to anyone interested in Rails.

If this was an ordinary book, this review could have ended here, but since the book is full of things I really wanted to know but didn't take the time to learn I decided to internalize them by describing parts of the book in my own words.

Chapter 1, Creating our own renderer

In this chapter we learn how to add a new renderer Rails. We add a renderer that handles generating PDF files with Prawn, allowing us to write code that looks like this.

class HomeController < ApplicationController
  def index
    respond_to do |format|
      format.html
      # This is the new capability, pdf rendering.
      format.pdf { render :pdf => "contents" }
    end
  end
end

To allow the following we first have to register pdf as a mime type. We can do this with:

require "action_controller"
# Register a new mime type
Mime::Type.register "application/pdf", :pdf

# Registering the type allows us to write
respond_to do |format|
  format.pdf
end

With that out of the way all we have to do is to register a renderer, that will handle the actual rendering of the registered mime type. This is done with:

require "prawn" 

# Adds a new renderer to ActionController.Renderers
ActionController::Renderers.add :pdf do |filename, options|
  pdf = Prawn::Document.new pdf.text render_to_string(options)
  send_data(pdf.render, :filename => "#{filename}.pdf",
      :type => "application/pdf", :disposition => "attachment")
end

This is all that is needed to add a rendering of a new type to Rails. José also goes into details about other points of interest where the rendering stack can be customized.

Chapter 2, Easy models with Active Model

Active Model is a Rails module that abstracts common behavior needed by different kinds om models such as Active Record, Active Resource and third party modules like Mongoid. Apart from giving developers of new models utility functionality. Active Model also provides tests for being Active Model compliant. To be compliant means to play well with the Rails view and controllers.

José implements a model for creating sending mail. In doing so he introduces us to a bunch of Active Model modules that will do our work for us.

Here are the modules in alphabetical order:

ActiveModel::AttributeMethods

When you include ActiveModel::AttributeMethods in your model, you get access to helper methods that will help you define additional methods for dealing with the attributes of your model. An example

class Tapir
  include ActiveModel::AttributeMethods

  # Define the attributes 
  attr_accessor 'name', 'color'

  # We want to create clear methods for every attribute
  attribute_method_prefix 'clear_'

  # We also want to have query methods for every attribute
  attribute_method_suffix '?'

  # Define the attribute methods that will call the protected methods below
  define_attribute_methods ['name', 'color']

protected
  # The name of this method corresponds to the prefix above
  def clear_attribute(attribute)
    send("#{attribute}=", nil)
  end

  # The name of this method corresponds to the suffix above
  def attribute?(attribute)
    send(attribute).present?
  end
end

   t = Tapir.new
 => #<Tapir:0x00000102769b90> 
> t.name?
 => false
> t.name= 'kalle'
 => "kalle"
> t.name?
 => true
> t.clear_name
 => nil
> t.name?
 => false
> t.name

This is the gist of attribute methods, there is also an affix method that will allow you to add both a suffix and a prefix to your attributes. It is also worth taking a look inside the implmentation of this module, since the methods are defined on first usage through method_missing.

ActiveModel::Callbacks

ActiveModel::Callbacks provides methods for creating before_, after_, and `around_' callbacks to your model methods. An example:

class Tapir
  extend ActiveModel::Callbacks

  define_model_callbacks :snort

  def snort
    _run_snort_callbacks do
      snort_snort_snort
    end
  end

end

Then in inheriting classes I can use the callbacks as such:

class MountainTapir < Tapir
  before_snort :do_before_snort

  def before_snort
    i_am_so_cold
  end
end

ActiveModel::Conversion

This module assists with converting to, and representing a specific model instance. It contains three methods.

• to_model, used for converting to an active model compliant model, in the default case it just returns self.
• to_param, used for representing a model in routing.
• to_key, used for representing a model from in a dom page.

ActiveModel::Naming and ActiveModel::Translation

ActiveModel::Naming contains one method model_name, that returns a subclass of String, that handles pluralization, etc. It has methods such as plural, human.

ActiveModel::Translation deals with I18N by adding functionality to human that handles the name lookup by keys using the preferred I18n.backend.

ActiveModel::Validations

The last, but not least of the models, ActiveModel::Validations, deals with validations. José demostrates how naming convetions and Rails constant lookup allow us to add new validators to Rails with ease. An example:

module Validators
  class TapirKindValidator < ActiveModel::EachValidator
    def validate_each(record, attribute, value)
      unless [:baird, :mountain, :malayan, :lowland].include? value
        record.errors.add(attribute, :invalid, options)
      end
    end
  end
end

If I now include my new validator wherever I want to use it. I can write code like:

class Tapir
  include Validators

  attr_accessor :kind
  validates :kind, :tapir_kind => true
end

t = Tapir.new :kind => :mexican
t.valid?
# => false
t.errors[:kind]
# ["is invalid"]

This example is unnecessarily complicated, since the validation could be fixed with:

class Tapir
    attr_accessor :kind
    validates_inclusion_of :kind, :in =>  [:baird, :mountain, :malayan, :lowland]
end

append_view_path

There is one more interesting thing in this chapter, append_view_path. It can be used to add a directory inside a gem to the view lookup path. This is essential to be able to deliver custom Rails components, Railties, with default views.

Chapter 3, Building a template management system

In the third chapter of the book,José takes on view resolvers. A resolver is responsible for looking up the appropriate template for a given request. The traditional resolver looks up the templates by path in the file system, but José guides us through creating a resolver that looks up the template in a database. Perfect for the core of a CMS system. I'm going to alter José's resolver to do the lookup in MongoDB instead.

# Most of this code is borrowed directly from José Valim
# Only the Mongoid Part is written by me  
require 'mongoid'
require 'singleton'

class MongoTemplate
  include Mongoid::Document
  field :body
  field :path
  field :locale
  field :format
  field :handler
  field :partial, :type => Boolean
  field :updated_at, :type => Date

  validates :body, :path, :presence => true
  validates :format, :inclusion => Mime::SET.symbols.map(&:to_s)
  validates :locale, :inclusion => I18n.available_locales.map(&:to_s)
  validates :handler, :inclusion =>
    ActionView::Template::Handlers.extensions.map(&:to_s)

  class Resolver < ActionView::Resolver
    include Singleton
  protected
    def find_templates(name, prefix, partial, details)
      conditions = {
        :path => normalize_path(name, prefix),
        :locale => normalize_array(details[:locale]).first,
        :format => normalize_array(details[:formats]).first,
        :handler.in => normalize_array(details[:handlers]),
        :partial => partial || false
      }

      MongoTemplate.where(conditions).map do |record|
        initialize_template(record)
      end
    end

    # Normalize name and prefix, so the tuple ["index", "users"] becomes 
    # "users/index" and the tuple ["template", nil] becomes "template". 
    def normalize_path(name, prefix)
      prefix.present? ? "#{prefix}/#{name}" : name
    end

    # Normalize arrays by converting all symbols to strings.
    def normalize_array(array)
      array.map(&:to_s)
    end

    # Initialize an ActionView::Template object based on the record found.
    def initialize_template(record)
      source = record.body
      identifier = "MongoTemplate - #{record.id} - #{record.path.inspect}"
      handler = ActionView::Template.registered_template_handler(record.handler)
      details = {
        :format => Mime[record.format],
        :updated_at => record.updated_at,
        :virtual_path => virtual_path(record.path, record.partial)
      }
      ActionView::Template.new(source, identifier, handler, details)
    end

    # Make paths as "users/user" become "users/_user" for partials.
    def virtual_path(path, partial)
      return path unless partial
      if index = path.rindex("/")
        path.insert(index + 1, "_")
      else
        "_#{path}"
      end
    end
  end
end

A Resolver is implemented by extending ActionView::Resolver and implementing the method find_templates(name, prefix, partial, details) There are a lot of extra information in the book, about caching etc. Obviously Rails caches the templates since it would be too slow to create a template every time. That is why we have the template as a singleton and that is why we clear the cache in the after_save hook above. The hook in Mongoid works exactly the same as in Active Record. Thank you Active Model!

Chapter 4, Multipart Emails with Markdown and Erb

In this chapter José walks us through three topics. The template handler API, Rails generators and Railties. I'm going to skip over the last two in this chapter. Generators are a large topic and they deserve a blog post of their own. José does a great job desribing how they work. The same goes for Railties and Rails Engines, they are definitely worthy of a blog post of their own.

# 
# Again most of the code is stolen from José  
#
module ScrambleHandler

  # Lookup the ERb handler
  def self.erb_handler
    @@erb_handler ||= ActionView::Template.registered_template_handler(:erb)
  end

  def self.call(template)
    # Call the erb handler, then call the new scrambler method.
    source = erb_handler.call(template)
    if template.formats.include?(:html)
      "Scrambler.from_html(begin;#{source};end).to_s"
    else
      "Scrambler.from_text(begin;#{source};end).to_s"
    end
  end

end

# Register our new handler, it handles index.html.scramble, show.html.scramble, ...
ActionView::Template.register_template_handler :scramble, ScrambleHandler

# This module scrambles text.
# Scrambler.from_text('Once upon a time a beautiful tapir came.')
# -> Ocne upon a time a baeuuitfl tpiar came.
module Scrambler
  def self.from_html html
    doc = Nokogiri::HTML(html)
    doc.xpath('//text()').each do |node|
      node.content = from_text(node.content)
    end
    doc.to_html
  end

  def self.from_text text
    tokenize(text).map{|token| scramble(token)}.join('')
  end

  def self.tokenize text
    return nil unless text
    text.scan(/(\p{Word}+|\W+|)/um).flatten
  end

  def self.scramble word
    return word if word =~ /\W/
    return word if word.size < 4
    arr = word.split(//)
    arr[0] + arr[1...-1].shuffle.join('') + arr[-1]
  end
end

Chapter 5, Publishing and subscribing to your applications events

In this chapter José uses the Notifications API to store notifcations in a MongoDB. He also shows how to use Rack middleware to configure what request to log. In order to configure the middleware he uses a Rails Engine. I'm just going to show how the Notifications API works here, and I'll let you read the rest in the book.

# Subscribe to all events and print them to the console
ActiveSupport::Notifications.subscribe do |*args|
  p ActiveSupport::Notifications::Event.new(*args)
end

# Instrument the rendering of Foo
ActiveSupport::Notifications.instrument(:render, :extra => :information) do
  render :text => "Foo"
end

Chapter 6, DRY controllers with Responders

In this chapter José goes through the implementation of responders. This implementation allows you to DRY up your controllers by factoring out common behavior.

def index
  @users = User.all
  respond_to do |format|
    format.html # index.html.erb 
    format.xml { render :xml => @users }
  end
end

# becomes

def index
  @users = User.all
  respond_with(@users)
end

# and
def create
  @user = User.new(params[:user])
  respond_to do |format|
  if @user.save
    format.html { redirect_to(@user, :notice => 'User was successfully created.') }
    format.xml { render :xml => @user, :status => :created, :location => @user }
  else
    format.html { render :action => "new" }
    format.xml { render :xml => @user.errors, :status => :unprocessable_entity }
  end
end

# becomes
def create
  @user = User.new(params[:user])
  flash[:notice] = 'User was successfully created.' if @user.save
  respond_with(@user)
end

In this chapter we also learn how to replace the default generators with our own customized generators.

Chapter 7, Translatable app with I18n and Redis

In the final chapter José shows us how the I18N backed system works. He does this by creating a backend the uses Redis instead of the default YAML files. He also developes a simple Sinatra application that he hooks into the Rails routing with the mount method.

# Mount the Sinatra Translator::App at the /translator path.
mount Translator::App, :at => "/translator"

Rack applications normally get the full path inside ENV['PATH_INFO'], but when Rails mounts an application it removes the prefix before it sends it on /translator/en/pt/ becomes /en/pt/. The additional path is sent on in ENV['SCRIPT_NAME'] = '/translator'.

We also get a brief overview of Devise, the state-of-the-art authentication solution written by José himself.

Conclusion

One last thing, the book I have reviewed is a beta book, but the quality of it is higher than most published books I have seen. Congratulations to José and to the pragmatic bookshelf! There is not much more to say, get the book.

I figured that the six of them could probably scrape together a few decent people patterns, but I am a bit fed up with the whole pattern template style, so my expectations were not as high as they should have been.

Anyway, the book is amazing, the pattern template is really lightweight, basically, a name, an image, a statement, and a story. And the stories, are good. The authors have a remarkable ability to observe human nature and also the ability to write about what they see.

Some Patterns

The book contains 86 patterns, most of them are negative since they are funnier, as one of the authors said on a podcast.

Dead Fish

A dead fish is a project, that every one knows is impossible to start out with, but nobody says anything since the culture in the company is that way.
If you say something you may get responses like,

Prove it! Prove that it is not feasible that this project will succeed!

Or,

Are you a weenie or a layabout?

Projects like this are usually worked on until it is inevitable that they will be late, and then everybody acts surprised.

Nanny

A nanny is a project manager that is aware of the capabilities of her staff and nurtures them and lets them at their peek. The nanny is responsible for improving her staff and make responsible project citizen of them. A nanny enables workers to do their job.

Eye Contact

If your life depended on a project, would you want them working close together or in different corners of the world? Human communication goes way beyond words, and it is foolish to think that it is possible to work at full speed with people who don't know each other and live in different places.

Dashboards

A dashboard is a highly visible board, that enable the project members and others to get an instant view of the status of the project. It can be a web page or a board on the wall. What is significant with a dashboard is that it is updated as soon as anything important happens in the project. All project members care for the dashboard since that is the place where they can find out how they are doing. Dashboards contain just the right amount of data.

Film Critics

A film critic is a project member or someone related to the project who thinks that they can succeed even if the project is a failure. They may often have good points, but usually when it is too late to do something about it. It is no use to have a person like this on the team, since they are not really on the team if they don't go down with the ship.

Natural Authority

The word authority have several meanings. The meaning of an authority is a person who knows a great deal about something. Another meaning, in authority, is a person who is in charge. A person who is an authority and in authority is a natural authority. This is the healthy pattern.

The White Line

The white line is the line on a tennis court. The line is a clear signal if the ball is in or out. Occasional dispute may arise over a questionable judgment call, but the line is respected by everyone. Most projects don't have this line. Create a white line for your project so that you know what is inside the project scope and what is not.

Silence Gives Consent

If someone don't oppose an idea, it is, usually, taken as consent. Especially from people who come from different working areas, like management and programmers. Silent consent is not good for anyone, because nobody is sure what has been decided and what has not. A way to remedy this problem is to keep a list of commitments where it is written down who has promised who what. The Scrum sprint backlog is similar to such a list.

Time Removes Cards from Your Hand

The earlier a decision can be made, the better. If you know that a project will not make a deadline, the decision to change the scope should be made as early as possible, since that will allow the team to work on the most important features first. If a decision is delayed until it is too late, the decision is made implicitly by time.

Rhythm

Instead of being daunted by overwhelming tasks, projects with rhythm take small, regular steps thus establishing a regular beat that carries them toward their goal.

This journey of a thousand miles begins with a single step --Lao Tzu

False Quality Gates

False quality gates are quality checks that don't do anything to promote the quality of the project. It is a sign that more attention is concentrated on format, rather than content. It can be a glossary of terms with the wrong content or a word template where most of the sections are filled in with the words "This section must contain text to fulfill company guidelines".

Testing Before Testing

Testing before testing refers to the practice of thinking about how to test a feature at the same time you think about how to implement it. If it cannot be tested how can you know that it does what you say?

Cider House Rules

Cider house rules are rules written by someone unconnected to the project. Rules like this, that give no apparent value, are a burden to the project and therefore often ignored.

Nobody pays attention to them rules. Every year Olive writes them up and every year nobody pays any attention to them. -- John Irving, The Cider House Rules

Talk Then Write

The team makes decisions during conversation, and then immediately communicates the decisions in writing. This is a really important pattern that it is easy to forget!. A common place where this kind of decisions are written down is very helpful.

Practicing the End Game

A team that does not release often and regularly will often take a long time to make a release. The act of releasing a product should be practiced often so that is becomes a natural part of the project.

Data Quality

Data quality often sucks! A common solution is often to attack the problem with technology instead of putting in the manpower that is actually needed to improve the quality of the data. Company web-sites are the prime example of this. They are often full of completely useless information.

Undivided Attention

Complex work is hard and it requires undivided attention to be performed properly. Splitting people's attention over multiple project will severely hinder their performance.

By doing two things at once, you've cut your IQ in half, and believe me, those 40 points can really make a difference. -- Dale Dauden, The New York Times

Orphaned Deliverables

Orphaned deliverables are deliverables that no-one values enough to pay for. Always make sure that there is a sponsor for every artifact that you are developing.

Hidden Beauty

Hidden beauty inside a program, that little extra thing, that may seem unnecessary, is what shows that the creator cares about his work. It is not unnecessary! This caring is what separates a quality product from garbage.

I Don't Know

If you are afraid of saying the words, "I don't know!", you are probably working in an organization where saying it means that you will be taken for a fool. In a healthy organization, "I don't know!", means that you don't know, but you will in a while, if it is important enough.

Loud and Clear

Having a clear goal, that everyone agrees to, is vital to a project. Clear goals allows you to focus the project activity if it starts to move away from its purpose. A PAM statement, that contains the Purpose, Advantage, and Measurements of a project is very helpful.

Conclusion

The patterns described above are just my short summaries, and I don't do them justice, but hopefully I have awoken your interest in this wonderful book.

It made my top-ten list and I recommend it to everyone from programmer to president. I like that the authors don't always provide a solution, but instead just describe the way they see it, it is up to you to figure out a solution to the problem yourself.