From c3f53f412cd170fc295b46e48aa81837ad15ec83 Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Fri, 19 Dec 2008 14:27:43 +0000 Subject: Merge docrails --- .../html/activerecord_validations_callbacks.html | 81 ++++++++++++++-------- 1 file changed, 52 insertions(+), 29 deletions(-) (limited to 'railties/doc/guides/html/activerecord_validations_callbacks.html') diff --git a/railties/doc/guides/html/activerecord_validations_callbacks.html b/railties/doc/guides/html/activerecord_validations_callbacks.html index cb381e7191..039e3d1891 100644 --- a/railties/doc/guides/html/activerecord_validations_callbacks.html +++ b/railties/doc/guides/html/activerecord_validations_callbacks.html @@ -231,7 +231,7 @@ ul#navMain {
  • The validates_length_of helper
    • -
  • The validates_numericallity_of helper
    • +
  • The validates_numericality_of helper
  • The validates_presence_of helper
    • @@ -338,7 +338,7 @@ Create your own custom validation methods

  • -Work with the error messages generated by the validation proccess +Work with the error messages generated by the validation process

  • @@ -405,7 +405,7 @@ http://www.gnu.org/software/src-highlite --> >> p.new_record? => false -

    Saving new records means sending an SQL insert operation to the database, while saving existing records (by calling either save or update_attributes) will result in a SQL update operation. Active Record will use this facts to perform validations upon your objects, avoiding then to be recorded to the database if their inner state is invalid in some way. You can specify validations that will be beformed every time a object is saved, just when you're creating a new record or when you're updating an existing one.

    +

    Saving new records means sending an SQL insert operation to the database, while saving existing records (by calling either save or update_attributes) will result in a SQL update operation. Active Record will use these facts to perform validations upon your objects, avoiding then to be recorded to the database if their inner state is invalid in some way. You can specify validations that will be beformed every time a object is saved, just when you're creating a new record or when you're updating an existing one.

    @@ -524,7 +524,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
    class MovieFile < ActiveRecord::Base
-  validates_exclusion_of :format, :in => %w(mov avi), :message => "Extension %s is not allowed"
+  validates_exclusion_of :format, :in => %w(mov avi),
+    :message => "Extension %s is not allowed"
 end

    The validates_exclusion_of helper has an option :in that receives the set of values that will not be accepted for the validated attributes. The :in option has an alias called :within that you can use for the same purpose, if you'd like to. In the previous example we used the :message option to show how we can personalize it with the current attribute's value, through the %s format mask.

    @@ -537,7 +538,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
    class Product < ActiveRecord::Base
-  validates_format_of :description, :with => /^[a-zA-Z]+$/, :message => "Only letters allowed"
+  validates_format_of :description, :with => /^[a-zA-Z]+$/,
+    :message => "Only letters allowed"
 end

    The default error message for validates_format_of is "is invalid".

    @@ -549,7 +551,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
    class Coffee < ActiveRecord::Base
-  validates_inclusion_of :size, :in => %w(small medium large), :message => "%s is not a valid size"
+  validates_inclusion_of :size, :in => %w(small medium large),
+    :message => "%s is not a valid size"
 end

    The validates_inclusion_of helper has an option :in that receives the set of values that will be accepted. The :in option has an alias called :within that you can use for the same purpose, if you'd like to. In the previous example we used the :message option to show how we can personalize it with the current attribute's value, through the %s format mask.

    @@ -602,7 +605,7 @@ http://www.gnu.org/software/src-highlite --> end

    This helper has an alias called validates_size_of, it's the same helper with a different name. You can use it if you'd like to.

    -

    3.9. The validates_numericallity_of helper

    +

    3.9. The validates_numericality_of helper

    This helper validates that your attributes have only numeric values. By default, it will match an optional sign followed by a integral or floating point number. Using the :integer_only option set to true, you can specify that only integral numbers are allowed.

    If you use :integer_only set to true, then it will use the /\A[+\-]?\d+\Z/ regular expression to validate the attribute's value. Otherwise, it will try to convert the value using Kernel.Float.

    @@ -611,11 +614,11 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
    class Player < ActiveRecord::Base
-  validates_numericallity_of :points
-  validates_numericallity_of :games_played, :integer_only => true
+  validates_numericality_of :points
+  validates_numericality_of :games_played, :integer_only => true
 end
    -

    The default error message for validates_numericallity_of is "is not a number".

    +

    The default error message for validates_numericality_of is "is not a number".

    3.10. The validates_presence_of helper

    This helper validates that the attributes are not empty. It uses the blank? method to check if the value is either nil or an empty string (if the string has only spaces, it will still be considered empty).

    @@ -673,7 +676,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
    class Holiday < ActiveRecord::Base
-  validates_uniqueness_of :name, :scope => :year, :message => "Should happen once per year"
+  validates_uniqueness_of :name, :scope => :year,
+    :message => "Should happen once per year"
 end

    There is also a :case_sensitive option that you can use to define if the uniqueness contraint will be case sensitive or not. This option defaults to true.

    @@ -692,7 +696,7 @@ http://www.gnu.org/software/src-highlite -->

    There are some common options that all the validation helpers can use. Here they are, except for the :if and :unless options, which we'll cover right at the next topic.

    4.1. The :allow_nil option

    -

    You may use the :allow_nil option everytime you just want to trigger a validation if the value being validated is not nil. You may be asking yourself if it makes any sense to use :allow_nil and validates_presence_of together. Well, it does. Remember, validation will be skipped only for nil attributes, but empty strings are not considered nil.

    +

    You may use the :allow_nil option everytime you want to trigger a validation only if the value being validated is not nil. You may be asking yourself if it makes any sense to use :allow_nil and validates_presence_of together. Well, it does. Remember, validation will be skipped only for nil attributes, but empty strings are not considered nil.

    class Person < ActiveRecord::Base
-  validates_uniqueness_of :email, :on => :create # => it will be possible to update email with a duplicated value
-  validates_numericallity_of :age, :on => :update # => it will be possible to create the record with a 'non-numerical age'
-  validates_presence_of :name, :on => :save # => that's the default
+  # => it will be possible to update email with a duplicated value
+  validates_uniqueness_of :email, :on => :create
+
+  # => it will be possible to create the record with a 'non-numerical age'
+  validates_numericality_of :age, :on => :update
+
+  # => the default
+  validates_presence_of :name, :on => :save
 end
    @@ -756,7 +765,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
    class Account < ActiveRecord::Base
-  validates_confirmation_of :password, :unless => Proc.new { |a| a.password.blank? }
+  validates_confirmation_of :password,
+    :unless => Proc.new { |a| a.password.blank? }
 end
    @@ -770,7 +780,8 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
    class Invoice < ActiveRecord::Base
   def validate_on_create
-    errors.add(:expiration_date, "can't be in the past") if !expiration_date.blank? and expiration_date < Date.today
+    errors.add(:expiration_date, "can't be in the past") if
+      !expiration_date.blank? and expiration_date < Date.today
   end
 end
    @@ -781,14 +792,17 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
    class Invoice < ActiveRecord::Base
-  validate :expiration_date_cannot_be_in_the_past, :discount_cannot_be_more_than_total_value
+  validate :expiration_date_cannot_be_in_the_past,
+    :discount_cannot_be_more_than_total_value
 
   def expiration_date_cannot_be_in_the_past
-    errors.add(:expiration_date, "can't be in the past") if !expiration_date.blank? and expiration_date < Date.today
+    errors.add(:expiration_date, "can't be in the past") if
+      !expiration_date.blank? and expiration_date < Date.today
   end
 
   def discount_cannot_be_greater_than_total_value
-    errors.add(:discount, "can't be greater than total value") unless discount <= total_value
+    errors.add(:discount, "can't be greater than total value") unless
+      discount <= total_value
   end
 end
    @@ -874,16 +888,18 @@ person.errors.< person = Person.new(:name => "JD") person.valid? # => false -person.errors.on(:name) # => "is too short (minimum is 3 characters)" +person.errors.on(:name) +# => "is too short (minimum is 3 characters)" person = Person.new person.valid? # => false -person.errors.on(:name) # => ["can't be blank", "is too short (minimum is 3 characters)"] +person.errors.on(:name) +# => ["can't be blank", "is too short (minimum is 3 characters)"]

    • -clear is used when you intentionally wants to clear all the messages in the errors collection. +clear is used when you intentionally want to clear all the messages in the errors collection. However, calling errors.clear upon an invalid object won't make it valid: the errors collection will now be empty, but the next time you call valid? or any method that tries to save this object to the database, the validations will run. If any of them fails, the errors collection will get filled again.

    @@ -898,10 +914,15 @@ http://www.gnu.org/software/src-highlite --> end person = Person.new -puts person.valid? # => false -person.errors.on(:name) # => ["can't be blank", "is too short (minimum is 3 characters)"] +person.valid? # => false +person.errors.on(:name) +# => ["can't be blank", "is too short (minimum is 3 characters)"] + person.errors.clear -person.errors # => nil +person.errors.empty? # => true +p.save # => false +p.errors.on(:name) +# => ["can't be blank", "is too short (minimum is 3 characters)"]

    8. Callbacks

    @@ -910,7 +931,7 @@ person.errors 8.1. Callbacks registration

    In order to use the available callbacks, you need to registrate them. There are two ways of doing that.

    8.2. Registering callbacks by overriding the callback methods

    -

    You can specify the callback method direcly, by overriding it. Let's see how it works using the before_validation callback, which will surprisingly run right before any validation is done.

    +

    You can specify the callback method directly, by overriding it. Let's see how it works using the before_validation callback, which will surprisingly run right before any validation is done.

    end

    12.1. Registering observers

    -

    If you payed attention, you may be wondering where Active Record Observers are referenced in our applications, so they get instantiate and begin to interact with our models. For observers to work we need to register then in our application's config/environment.rb file. In this file there is a commented out line where we can define the observers that our application should load at start-up.

    +

    If you payed attention, you may be wondering where Active Record Observers are referenced in our applications, so they get instantiate and begin to interact with our models. For observers to work we need to register them somewhere. The usual place to do that is in our application's config/environment.rb file. In this file there is a commented out line where we can define the observers that our application should load at start-up.

    # Activate observers that should always be running
 config.active_record.observers = :registration_observer, :auditor
    +

    You can uncomment the line with config.active_record.observers and change the symbols for the name of the observers that should be registered.

    +

    It's also possible to register callbacks in any of the files living at config/environments/, if you want an observer to work only in a specific environment. There is not a config.active_record.observers line at any of those files, but you can simply add it.

    12.2. Where to put the observers' source files

    By convention, you should always save your observers' source files inside app/models.

    -- cgit v1.2.3