Many web applications have screens in which the user is prompted to agree to terms of service or some similar concept, usually involving a check box. No actual database column matching the attribute declared in the validation is required; when you call this method, it will create virtual attributes automatically for each named attribute you specify. I see this validation as a type of syntax sugar since it is so specific to web application programming.

class Account < ActiveRecord::Base
  validates_acceptance_of :privacy_policy, :terms_of_service
end

class Cancellation < ActiveRecord::Base
  validates_acceptance_of :account_cancellation, :accept => 'YES'
end

When a given model has associated model objects that also need to be valid when it is saved, you use the validates_associated method, which works with any kind of association. When the validation is invoked (on save, by default), the valid? method of each associated object will be called.

class Invoice < ActiveRecord::Base
  has_many :line_items
  validates_associated :line_items
end

It’s worth noting that careless use of validates_associated can result in a circular dependency and cause infinite recursion. Well, not infinite, but it will blow up. Given the preceding example, do not do the following on the LineItem class:

class LineItem < ActiveRecord::Base
  belongs_to :invoice
  validates_associated :invoice
end

This validation will not fail if the association is nil because it hasn’t been set yet. If you want to make sure that the association is populated and valid, you have to use validates_associated in conjunction with validates_presence_of (covered later in this chapter).

The validates_confirmation_of method is another case of syntactic sugar for web applications, since it is so common to include dual-entry text fields to make sure that the user entered critical data such as passwords and e-mail address correctly. This validation will create a virtual attribute for the confirmation value and compare the two attributes to make sure they match in order for the model to be valid.

Here’s an example, using our fictional Account model again:

class Account < ActiveRecord::Base
  validates_confirmation_of :email, :password
end

The user interface used to set values for the Account model would need to include extra text fields named with a _confirmation suffix, and when submitted, the value of those fields would have to match in order for this validation to pass.

The validates_each method is a little more free-form than its companions in the validation family in that it doesn’t have a predefined validation function. Instead, you give it an array of attribute names to check, and supply a Ruby block to be used in checking each attribute’s validity.

The block function designates the model object as valid or not by merit of adding to its errors array or not. The return value of the block is ignored.

There aren’t too many situations where this method is necessary, but one plausible example is when interacting with external services for validation. You might wrap the external validation in a façade specific to your application, and then call it using a validates_each block:

class Invoice < ActiveRecord::Base
  validates_each :supplier_id, :purchase_order do |record, attr,
value|
    record.errors.add(attr) unless PurchasingSystem.validate(attr,
value)
  end
end

Notice that parameters for the model instance (record), the name of the attribute, and the value to check are passed as block parameters.

The validates_inclusion_of method and its complement, validates_exclusion_of, are pretty cool, but unless you’re super-thorough with your application requirements, I’ll bet a small sum that you haven’t realized yet why you need them.

These methods take a variable number of attribute names and an :in option. When they run, they check to make sure that the value of the attribute is included (or excluded, respectively) in the enumerable object passed as the :in option.

The examples in the Rails docs are probably some of the best illustrations of their use, so I’ll take inspiration from them:

class Person < ActiveRecord::Base
  validates_inclusion_of :gender, :in => ['m','f'],
                         :message => 'O RLY?'

class Account
  validates_exclusion_of :login,
                         :in => ['admin', 'root', 'superuser'],
                         :message => 'Borat says "Naughty, naughty!"'
end

Notice that in the examples I’ve introduced usage of the :message option, common to all validation methods, to customize the error message constructed and added to the Errors collection when the validation fails. We’ll cover the default error messages and how to effectively customize them a little further along in the chapter.

This validation is provided by a plugin, but I’ve found it so useful in day-to-day work that I had to include it. It checks that a foreign key in a belongs_to association references an exisiting record in the database. You can think of it as a foreign-key constraint, except in your Rails code. It also works fine with polymorphic belongs_to associations.

class Person < ActiveRecord::Base
  belongs_to :address
  validates_existence_of :address
end

Josh Susser came up with the idea and the plugin and described it on his blog:

To install the plugin just type the following in your project directory:

$ script/plugin install
http://svn.hasmanythrough.com/public/plugins/validates_existence/

As for options, if :allow_nil => true, then the key itself may be nil and no validation will occur. A non-nil key will cause a query to be issued to make sure that the foreign object exists in the database. The default error message is “does not exist”, but can be overriden just like other validations using the :message option.

To use validates_format_of, you’ll have to know how to use Ruby regular expressions. Pass the method one or more attributes to check, and a regular expression as the (required) :with option. A good example, as shown in the Rails docs, is checking for a valid e-mail address format:

class Person < ActiveRecord::Base
  validates_format_of :email,
    :with => /A([^@s]+)@((?:[-a-z0-9]+.)+[a-z]{2,})/i
end

By the way, that example is totally not an RFC-compliant email address format checker^[1].

validates_format_of :name, :with =>
/^((localhost)|#{DOMAIN}|#{NUMERIC_IP})#{PORT}$/

PORT = /(([:]d+)?)/
DOMAIN = /([a-z0-9-]+.?)*([a-z0-9]{2,}).[a-z]{2,}/
NUMERIC_IP = /(?>(?:1?d?d|2[0-4]d|25[0-
5]).){3}(?:1?d?d|2[0-4]d|25[0-
5])(?:/(?:[12]?d|3[012])|-(?> (?:1?d?d|2[0-
4]d|25[0-5]).){3}(?:1?d?d|2[0-4]d|25[0-5]))?/

The validates_length_of method takes a variety of different options to let you concisely specify length constraints for a given attribute of your model.

class Account < ActiveRecord::Base
  validates_length_of :login, :minimum => 5
end

class Account < ActiveRecord::Base
  validates_length_of :login, :within => 5..20
end

class Account < ActiveRecord::Base
  validates_length_of :account_number, :is => 16
end

class Account < ActiveRecord::Base
  validates_length_of :account_number, :is => 16,
                      :wrong_length => "should be %d characters long"
end

The somewhat clumsily named validates_numericality_of method is used to ensure that an attribute can only hold a numeric value. The :integer_only option lets you further specify that the value should only be an integral value and defaults to false.

class Account < ActiveRecord::Base
  validates_numericality_of :account_number, :integer_only => true
end

Last but not least is one of the more common validation methods, :validates_presence_of, which is used to denote mandatory attributes. This method checks whether the attribute is blank via Rails’ blank? method, defined on Object, which returns true for values that are nil or a blank string "".

class Account < ActiveRecord::Base
  validates_presence_of :login, :email, :account_number
end

The validates_uniqueness_of method ensures that the value of an attribute is unique for all models of the same type. This validation does not work by adding a uniqueness constraint at the database level. It does work by constructing and executing a query looking for a matching record in the database. If any record is returned when this method does its query, the validation fails.

class Account < ActiveRecord::Base
  validates_uniqueness_of :login
end

By specifying a :scope option, additional attributes can be used to determine uniqueness. You may pass :scope one or more attribute names as symbols (putting multiple symbols in an array).

class Address < ActiveRecord::Base
  validates_uniqueness_of :line_two, :scope => [:line_one, :city,
:zip]
end

It’s also possible to specify whether to make the uniqueness constraint case-sensitive or not, via the :case_sensitive option (ignored for nontextual attributes).

class Student < ActiveRecord::Base
  has_many :registrations
  has_many :courses, :through => :registrations
end

class Registration < ActiveRecord::Base
  belongs_to :student
  belongs_to :course
end

class Course < ActiveRecord::Base
  has_many :registrations
  has_many :students, :through => :registrations
end

class Registration < ActiveRecord::Base
  belongs_to :student
  belongs_to :course

  validates_uniqueness_of :student_id, :scope => :course_id,
                          :message => "can only register once per
course"
end

Whenever you do so-called bang operations (such as save!) or operations that save behind the scenes, and a validation fails, you should be prepared to rescue ActiveRecord::RecordInvalid. Validation failures will cause RecordInvalid to be raised and its message will contain a description of the failures.

Here’s a quick example from one of my applications that has pretty restrictive validations on its User model:

>> u = User.new
=> #<User ...>
>> u.save!
ActiveRecord::RecordInvalid: Validation failed: Name can't be blank,
Password confirmation can't be blank, Password is too short (minimum
is 5 characters), Email can't be blank, Email address format is bad

In many cases, you only want to trigger a validation if a value is present and the absence of a value is not a problem. The :allow_nil option skips the validation if the value of the attribute is nil. Remember that this option only checks for nil, and empty strings "" are not considered nil.

The :if option is covered in the next section, “Conditional Validation.”

As we’ve discussed earlier in the chapter, the way that the validation process registers failures is by adding items to the Errors collection of the model object being checked. Part of the error item is a specific message describing the validation failure. All of the validation methods accept a :message option so that you can override the default error message format.

class Account < ActiveRecord::Base
  validates_uniqueness_of :login, :message => "is already taken"
end

By default, validations are run on save (both create and update operations). If you need to do so, for whatever reason, you can limit a given validation to just one of those operations by passing the :on option either :create or :update.

One good use for :on => :create is in conjunction with validates_uniqueness_of, since checking uniqueness with a query on large datasets can be time-consuming.

class Account < ActiveRecord::Base
  validates_uniqueness_of :login, :on => :create
end

But wait a minute—wouldn’t that pose a problem if the account model was updated later on with a nonunique value? That’s where attr_protected comes in. Sensitive attributes of your model should be protected from mass assignment using the attr_protected method. In your controller action that creates new accounts, you’ll have to grab the login parameter and set it manually.

When does it make sense to use conditional validations? The answer is: whenever an object can be validly persisted in more than one state.

A very common example, since it is used by the acts_as_authenticated plugin, involves the User (or Person) model, used for login and authentication.

validates_presence_of :password, :if => :password_required?
validates_presence_of :password_confirmation, :if =>
:password_required?
validates_length_of :password, :within => 4..40,
:if=>:password_required?
validates_confirmation_of :password, :if => :password_required?

This code is not DRY (meaning that it is repetitive). You can learn how to refactor it using the with_options method described in Chapter 14, “Login and Authentication.” Usage and implementation of the acts_as_authenticated plugin is covered in greater detail in Chapter 14.

There are only two cases when a (plaintext) password field should be required in order for the model to be valid.

protected

  def password_required?
    crypted_password.blank? || !password.blank?
  end

The first case is if the crypted_password attribute is blank, because that means we are dealing with a new User instance that has not been given a password yet. The other case is when the password attribute itself is not blank; perhaps this is happening during an update operation and the user is attempting to reset her password.

Some methods are provided to allow you to add validation errors to the collection manually and alter the state of the Errors collection.

It’s also possible to check the Errors object for validation failures on specific attributes with a couple of methods.