Cheatsheet • Validations

Class convenience methods Common options

‹‹validates_acceptance_of
:message a custom error message
Encapsulates the pattern of wanting to validate the acceptance of a terms of service check
box (or similar agreement). :on specifies when this validation is active (default is :save, other options
validates_acceptance_of :terms_of_service :create, :update)
validates_acceptance_of :eula, :message => "must be abided" :allow_nil skip validation if attribute is nil (default is false). Notice that for fix-
num and float columns empty strings are converted to nil
If the database column does not exist, the terms_of_service attribute is entirely virtual.
This check is performed only if terms_of_service is not nil and by default on save. :allow_blank if set to true, skips this validation if the attribute is blank (default is
false)
:accept Specifies value that is considered accepted. The default value is a string "1", :if specifies a method, proc or "string" to call to determine if the valida-
which makes it easy to relate to an HTML checkbox. This should be set to true tion should occur (e.g. :if => :allow_validation, or :if => Proc.
if you are validating a database column, since the attribute is typecast from new { |user| user.signup_step > 2 }). The method, proc or string
"1" to true before validation. should return or evaluate to a true or false value.
‹‹validates_associated :unless specifies a method, proc or "string" to call to determine if the
validation should not occur (e.g. :unless => :skip_validation, or
Validates whether the associated object or objects are all valid themselves. Works with any :unless => Proc.new { |user| user.signup_step <= 2 }). The
kind of association. method, proc or string should return or evaluate to a true or false
has_many :pages value.
belongs_to :library
validates_associated :pages, :library
 validates_length_of :smurf_leader, :is => 4, :message => "papa is
Warning! If, after the above definition, you then wrote... spelled with %d characters... don't play me."
belongs_to :book validates_length_of :essay, :minimum => 100, :too_short => "Your essay
validates_associated :book must be at least %d words."), :tokenizer => lambda {|str| str.scan(/\
...this would specify a circular dependency and cause infinite recursion. w+/) }

This validation will not fail if the association hasn't been assigned. If you want to ensure :minimum The minimum size of the attribute
that the association is both present and guaranteed to be valid, you also need to use :maximum The maximum size of the attribute
validates_presence_of
‹‹validates_confirmation_of :is The exact size of the attribute
Encapsulates the pattern of wanting to validate a password or email address field with a :within A range specifying the minimum and maximum size of the attribute
confirmation. Example: :in Alias for :within
Model class Person < ActiveRecord::Base :too_long The error message if the attribute goes over the maximum (default
validates_confirmation_of :user_name, :password is: "is too long (maximum is %d characters)")
validates_confirmation_of :email_address, :message => "should :too_short The error message if the attribute goes under the minimum (default
match confirmation" is: "is too short (min is %d characters)")
end :wrong_length The error message if using the :is method and the attribute is the
View <%= password_field "person", "password" %> wrong size (default is: "is the wrong length (should be %d
<%= password_field "person", "password_confirmation" %> characters)")
:tokenizer Specifies how to split up the attribute string. (e.g. :tokenizer =>
The added password_confirmation attribute is virtual: it exists only as an in-memory lambda {|str| str.scan(/\w+/)} to count words as in above
attribute for validating the password. To achieve this, the validation adds accessors to the example.) Defaults to lambda{ |value| value.split(//) } which
model for the confirmation attribute. This check is performed only if password_confirma- counts individual characters
tion is not nil, and by default only on save. To require confirmation, make sure to add a
presence check for the confirmation attribute: ‹‹validates_numericality_of
validates_presence_of :password_confirmation, :if => :password_changed Validates whether the value of the specified attribute is numeric by trying to convert
‹‹validates_each it to a float with Kernel.Float (if only_integer is false) or applying it to the regular
expression /\A[+\-]?\d+\Z/ (if only_integer is set to true).
Validates each attribute against a block.
validates_numericality_of :age, :greater_than => 18
validates_each :first_name, :last_name do |record, attr, value|
record.errors.add attr, 'starts with z.' if value[0] == ?z :only_integer Specifies whether the value has to be an integer, e.g. an integral
end value (default is false)
‹‹validates_exclusion_of :greater_than Specifies the value must be greater than the supplied value
Validates that the value of the specified attribute is not in a particular enumerable object. :greater_than_ Specifies the value must be greater than or equal the supplied
validates_exclusion_of :username, :in => %w( admin superuser ), :message or_equal_to value
=> "You don't belong here" :equal_to Specifies the value must be equal to the supplied value
validates_exclusion_of :age, :in => 30..60, :message => "This site is :less_than Specifies the value must be less than the supplied value
only for under 30 and over 60"
validates_exclusion_of :format, :in => %w( mov avi ), :message => "exten- :less_than_or_ Specifies the value must be less than or equal the supplied value
sion %s is not allowed" equal_to
:odd Specifies the value must be an odd number
:in An enumerable object of items that the value shouldn't be part of
:even Specifies the value must be an even number
‹‹validates_format_of
‹‹validates_presence_of
Validates whether the value of the specified attribute is of the correct form by matching it
against the regular expression provided. Validates that the specified attributes are not blank (as defined by blank?). Happens by
default on save.
validates_format_of :email, :with => /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]
{2,})\Z/i, :on => :create validates_presence_of :first_name
Note: use \A and \Z to match the start and end of the string, ^ and $ match the start/end The first_name attribute must be in the object and it cannot be blank.
of a line. If you want to validate the presence of a boolean field (where the real values are true
A regular expression must be provided or else an exception will be raised. and false), you will want to use validates_inclusion_of :field_name, :in =>
[true, false] This is due to the way blank? handles boolean values.
:with The regular expression used to validate the format with
‹‹validates_size_of
‹‹validates_inclusion_of Alias for validates_length_of
Validates whether the value of the specified attribute is available in a particular enumer- ‹‹validates_uniqueness_of
able object. Validates whether the value of the specified attributes are unique across the system.
validates_inclusion_of :gender, :in => %w( m f ), :message => "woah! what Useful for making sure that only one user can be named "davidhh".
are you then!??!!" validates_uniqueness_of :user_name
validates_inclusion_of :age, :in => 0..99
validates_inclusion_of :format, :in => %w( jpg gif png ), :message => It can also validate whether the value of the specified attributes are unique based on
"extension %s is not included in the list"
multiple scope parameters. For example, making sure that a teacher can only be on the
schedule once per semester for a particular class.
:in An enumerable object of items that the value shouldn't be part of validates_uniqueness_of :teacher_id, :scope => [:semester_id, :class_
id]
‹‹validates_length_of
When the record is created, a check is performed to make sure that no record exists in
Validates that the specified attribute matches the length restrictions supplied. Only one the database with the given value for the specified attribute (that maps to a column).
option can be used at a time: When the record is updated, the same check is made but disregarding the record itself.
validates_length_of :first_name, :maximum => 30
Because this check is performed outside the database there is still a chance that dupli-
validates_length_of :last_name, :maximum => 30, :message=>"less than %d cate values will be inserted in two parallel transactions. To guarantee against this you
if you don't mind" should create a unique index on the field. See add_index for more information.
validates_length_of :fax, :in => 7..32, :allow_nil => true
validates_length_of :phone, :in => 7..32, :allow_blank => true :scope One or more columns by which to limit the scope of the unique-
validates_length_of :user_name, :within => 6..20, :too_long => "pick a ness constraint
shorter name", :too_short => "pick a longer name" :case_sensitive Looks for an exact match. Ignored by non-text columns (false by
validates_length_of :fav_bra_size, :minimum => 1, :too_short => "please default)
enter at least %d character" 

www.dizzy.co.uk/cheatsheets This work is licensed under the Creative

Commons Attribution-NonCommercial-
NoDerivs 2.0 License. To view a copy
of this license, visit http://creativecom-
mons.org/licenses/by-nc-nd/2.0/uk
 Low level validations
You can create your own validations by implementing the validate method (or the
variations, validate_on_create and validate_on_update) in your model. The validate
method will be called by ActiveRecord before every save or update, whilst the vali-
date_on_create and validate_on_update methods will only be called when saving
new records or updating existing records respectively. Most validation methods
simply do two things:
„„Inspect the attributes of an object and check whether their values pass one or
more conditions (such as making sure a name attribute is not empty and/or that it
matches a certain regular expression)
„„If an attribute's value does not pass, add an error message to it
Errors
Each ActiveRecord object has its own errors object which stores a list of errors
related to that object and is accessible via the errors method on the object.
The errors object itself has a number of methods which enable you to both add to
the list of errors, or inspect the object for errors which have already been added. For
example, to add an error to the name attribute of an object, we would use the add
method...
object.errors.add(:name, "shouldn't be empty!")
...and to retrieve errors on the :name attribute we could read from the errors object...
object.errors.on(:name) # => "shouldn't be empty!"
You will find our cheatsheet ActiveRecord Validation Errors a useful resource for
manipulating the errors object.
Here are some examples of implementing low-level, roll-your-own validation meth-
ods...

‹‹Example

class Person < ActiveRecord::Base

protected
def validate
errors.add_on_empty %w( first_name last_name )
errors.add("phone_number", "has invalid format") unless phone_number
=~ /[0-9]*/
end

def validate_on_create # is only run the first time a new object is

saved
unless valid_discount?(membership_discount)
errors.add("membership_discount", "has expired")
end
end

def validate_on_update
errors.add_to_base("No changes have occurred") if unchanged_attri-
butes?
end
end

person = Person.new("first_name" => "David", "phone_number" => "what?")

person.save # => false (and doesn't do the save)
person.errors.empty? # => false
person.errors.count # => 2
person.errors.on "last_name" # => "can't be empty"
person.errors.on "phone_number" # => "has invalid format"
person.errors.each_full { |msg| puts msg }
# => "Last name can't be empty\n" +
"Phone number has invalid format"

person.attributes = { "last_name" => "Heinemeier", "phone_number" => "555-

555" }
person.save # => true (and person is now saved in the database)

This work is licensed under the Creative

Commons Attribution-NonCommercial-
NoDerivs 2.0 License. To view a copy
of this license, visit http://creativecom-
mons.org/licenses/by-nc-nd/2.0/uk