Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: ec9acc9dc5
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 120 lines (84 sloc) 2.668 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120
When
====

When adds :if and :unless conditions to ActiveRecord callbacks
and validations and ActionController filters. It works exactly
the way as the current implementation of #validates_acceptance_of.

It works on the 12 regular callbacks:

before_validation
before_validation_on_create
after_validation
after_validation_on_create
before_save
before_create
before_update
after_create
after_update
after_save
before_destroy
after_destroy

3 validations:

validate
validate_on_create
validate_on_update

and 1 filter:

before_filter

It works when :if or :unless is passed a Symbol, a Proc or a String.
They return or evaluate to a true or false value.

Example
=======

class Address < ActiveRecord::Base

  before_save :geolocate

  def geolocate
    if complete?
      ...
    end
  end

  def complete?
    street? && city? && state? && zip?
  end

end

In this case, we want to find the latitude and longitude of an address only if
the address is complete.

Wrapping the entirety of a callback method with conditional logic is bad form.
The callback should execute WHEN the model's life cycle reaches its
"before_save" point and WHEN its address is "complete."

With When, the WHEN responsibility is moved to where it belongs:
as part of the callback.

class Address < ActiveRecord::Base

  before_save :geolocate,
    :if => :complete?

  def geolocate
    ...
  end

  def complete?
    street? && city? && state? && zip?
  end

end

before_create's single responsibility is to execute code WHEN certain conditions are met.
geolocate's single responsibility is to ... geolocate. It should not contain its own
preconditions.

More Examples
=============

before_create :encrypt_password,
  :unless => lambda {|user| user.password_confirmation.blank?}

before_filter :log_in!,
  :only => [:new, :create],
  :unless => :logged_in?

What When does NOT support
==========================

# ActiveRecord Class callbacks
before_create PasswordEncryptor,
  :unless => lambda {|user| user.password_confirmation.blank?}

# ActionController Class filters
before_filter Authorizer,
  :unless => :logged_in?

When will not work if your code contains any of these.

In our experience we've never used class callbacks or filters and find them to be overkill.

Obsolete after Rails 2.0.3
==========================

Whenever the next release after Rails 2.0.2 comes out, this feature will be baked into Rails
via the ActiveSupport::Callbacks module. Happy coding!

Installation
============

piston import https://svn.thoughtbot.com/plugins/when/trunk vendor/plugins/when

Copyright (c) 2008 Jared Carroll, Dan Croak, and thoughtbot, inc. released under the MIT license
Something went wrong with that request. Please try again.