From a17027d13a48e1e64b14a28e7d58e341812f8cb4 Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Sat, 13 Sep 2008 20:28:01 +0100 Subject: Merge docrails --- .../abstract/schema_definitions.rb | 38 ++++++++- activerecord/lib/active_record/locale/en-US.yml | 29 ++++++- activerecord/lib/active_record/validations.rb | 97 ++++++++++++---------- 3 files changed, 116 insertions(+), 48 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb index 75032efe57..22304edfc9 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb @@ -252,6 +252,10 @@ module ActiveRecord class IndexDefinition < Struct.new(:table, :name, :unique, :columns) #:nodoc: end + # Abstract representation of a column definition. Instances of this type + # are typically created by methods in TableDefinition, and added to the + # +columns+ attribute of said TableDefinition object, in order to be used + # for generating a number of table creation or table changing SQL statements. class ColumnDefinition < Struct.new(:base, :name, :type, :limit, :precision, :scale, :default, :null) #:nodoc: def sql_type @@ -275,9 +279,29 @@ module ActiveRecord end end - # Represents a SQL table in an abstract way. - # Columns are stored as a ColumnDefinition in the +columns+ attribute. + # Represents the schema of an SQL table in an abstract way. This class + # provides methods for manipulating the schema representation. + # + # Inside migration files, the +t+ object in +create_table+ and + # +change_table+ is actually of this type: + # + # class SomeMigration < ActiveRecord::Migration + # def self.up + # create_table :foo do |t| + # puts t.class # => "ActiveRecord::ConnectionAdapters::TableDefinition" + # end + # end + # + # def self.down + # ... + # end + # end + # + # The table definitions + # The Columns are stored as a ColumnDefinition in the +columns+ attribute. class TableDefinition + # An array of ColumnDefinition objects, representing the column changes + # that have been defined. attr_accessor :columns def initialize(base) @@ -321,6 +345,12 @@ module ActiveRecord # * :scale - # Specifies the scale for a :decimal column. # + # For clarity's sake: the precision is the number of significant digits, + # while the scale is the number of digits that can be stored following + # the decimal point. For example, the number 123.45 has a precision of 5 + # and a scale of 2. A decimal with a precision of 5 and a scale of 2 can + # range from -999.99 to 999.99. + # # Please be aware of different RDBMS implementations behavior with # :decimal columns: # * The SQL standard says the default scale should be 0, :scale <= @@ -374,6 +404,10 @@ module ActiveRecord # td.column(:huge_integer, :decimal, :precision => 30) # # => huge_integer DECIMAL(30) # + # # Defines a column with a database-specific type. + # td.column(:foo, 'polygon') + # # => foo polygon + # # == Short-hand examples # # Instead of calling +column+ directly, you can also work with the short-hand definitions for the default types. diff --git a/activerecord/lib/active_record/locale/en-US.yml b/activerecord/lib/active_record/locale/en-US.yml index 8148f31a81..421f0ebd60 100644 --- a/activerecord/lib/active_record/locale/en-US.yml +++ b/activerecord/lib/active_record/locale/en-US.yml @@ -25,9 +25,30 @@ en-US: even: "must be even" # Append your own errors here or at the model/attributes scope. + # You can define own errors for models or model attributes. + # The values :model, :attribute and :value are always available for interpolation. + # + # For example, + # models: + # user: + # blank: "This is a custom blank message for {{model}}: {{attribute}}" + # attributes: + # login: + # blank: "This is a custom blank message for User login" + # Will define custom blank validation message for User model and + # custom blank validation message for login attribute of User model. models: - # Overrides default messages - - attributes: - # Overrides model and default messages. + + # Translate model names. Used in Model.human_name(). + #models: + # For example, + # user: "Dude" + # will translate User model name to "Dude" + + # Translate model attribute names. Used in Model.human_attribute_name(attribute). + #attributes: + # For example, + # user: + # login: "Handle" + # will translate User attribute "login" as "Handle" diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb index 577e30ec86..518b59e433 100644 --- a/activerecord/lib/active_record/validations.rb +++ b/activerecord/lib/active_record/validations.rb @@ -259,6 +259,8 @@ module ActiveRecord end + # Please do have a look at ActiveRecord::Validations::ClassMethods for a higher level of validations. + # # Active Records implement validation by overwriting Base#validate (or the variations, +validate_on_create+ and # +validate_on_update+). Each of these methods can inspect the state of the object, which usually means ensuring # that a number of attributes have a certain value (such as not empty, within a given range, matching a certain regular expression). @@ -297,8 +299,6 @@ module ActiveRecord # person.save # => true (and person is now saved in the database) # # An Errors object is automatically created for every Active Record. - # - # Please do have a look at ActiveRecord::Validations::ClassMethods for a higher level of validations. module Validations VALIDATIONS = %w( validate validate_on_create validate_on_update ) @@ -313,9 +313,50 @@ module ActiveRecord base.define_callbacks *VALIDATIONS end - # All of the following validations are defined in the class scope of the model that you're interested in validating. - # They offer a more declarative way of specifying when the model is valid and when it is not. It is recommended to use - # these over the low-level calls to +validate+ and +validate_on_create+ when possible. + # Active Record classes can implement validations in several ways. The highest level, easiest to read, + # and recommended approach is to use the declarative validates_..._of class methods (and + # +validates_associated+) documented below. These are sufficient for most model validations. + # + # Slightly lower level is +validates_each+. It provides some of the same options as the purely declarative + # validation methods, but like all the lower-level approaches it requires manually adding to the errors collection + # when the record is invalid. + # + # At a yet lower level, a model can use the class methods +validate+, +validate_on_create+ and +validate_on_update+ + # to add validation methods or blocks. These are ActiveSupport::Callbacks and follow the same rules of inheritance + # and chaining. + # + # The lowest level style is to define the instance methods +validate+, +validate_on_create+ and +validate_on_update+ + # as documented in ActiveRecord::Validations. + # + # == +validate+, +validate_on_create+ and +validate_on_update+ Class Methods + # + # Calls to these methods add a validation method or block to the class. Again, this approach is recommended + # only when the higher-level methods documented below (validates_..._of and +validates_associated+) are + # insufficient to handle the required validation. + # + # This can be done with a symbol pointing to a method: + # + # class Comment < ActiveRecord::Base + # validate :must_be_friends + # + # def must_be_friends + # errors.add_to_base("Must be friends to leave a comment") unless commenter.friend_of?(commentee) + # end + # end + # + # Or with a block which is passed the current record to be validated: + # + # class Comment < ActiveRecord::Base + # validate do |comment| + # comment.must_be_friends + # end + # + # def must_be_friends + # errors.add_to_base("Must be friends to leave a comment") unless commenter.friend_of?(commentee) + # end + # end + # + # This usage applies to +validate_on_create+ and +validate_on_update+ as well. module ClassMethods DEFAULT_VALIDATION_OPTIONS = { :on => :save, @@ -329,34 +370,6 @@ module ActiveRecord :equal_to => '==', :less_than => '<', :less_than_or_equal_to => '<=', :odd => 'odd?', :even => 'even?' }.freeze - # Adds a validation method or block to the class. This is useful when - # overriding the +validate+ instance method becomes too unwieldy and - # you're looking for more descriptive declaration of your validations. - # - # This can be done with a symbol pointing to a method: - # - # class Comment < ActiveRecord::Base - # validate :must_be_friends - # - # def must_be_friends - # errors.add_to_base("Must be friends to leave a comment") unless commenter.friend_of?(commentee) - # end - # end - # - # Or with a block which is passed the current record to be validated: - # - # class Comment < ActiveRecord::Base - # validate do |comment| - # comment.must_be_friends - # end - # - # def must_be_friends - # errors.add_to_base("Must be friends to leave a comment") unless commenter.friend_of?(commentee) - # end - # end - # - # This usage applies to +validate_on_create+ and +validate_on_update+ as well. - # Validates each attribute against a block. # # class Person < ActiveRecord::Base @@ -509,13 +522,13 @@ module ActiveRecord # # class Person < ActiveRecord::Base # validates_length_of :first_name, :maximum=>30 - # validates_length_of :last_name, :maximum=>30, :message=>"less than %d if you don't mind" + # validates_length_of :last_name, :maximum=>30, :message=>"less than {{count}} if you don't mind" # validates_length_of :fax, :in => 7..32, :allow_nil => true # validates_length_of :phone, :in => 7..32, :allow_blank => true # validates_length_of :user_name, :within => 6..20, :too_long => "pick a shorter name", :too_short => "pick a longer name" - # validates_length_of :fav_bra_size, :minimum => 1, :too_short => "please enter at least %d character" - # validates_length_of :smurf_leader, :is => 4, :message => "papa is spelled with %d characters... don't play me." - # validates_length_of :essay, :minimum => 100, :too_short => "Your essay must be at least %d words."), :tokenizer => lambda {|str| str.scan(/\w+/) } + # validates_length_of :fav_bra_size, :minimum => 1, :too_short => "please enter at least {{count}} character" + # validates_length_of :smurf_leader, :is => 4, :message => "papa is spelled with {{count}} characters... don't play me." + # validates_length_of :essay, :minimum => 100, :too_short => "Your essay must be at least {{count}} words."), :tokenizer => lambda {|str| str.scan(/\w+/) } # end # # Configuration options: @@ -526,9 +539,9 @@ module ActiveRecord # * :in - A synonym(or alias) for :within. # * :allow_nil - Attribute may be +nil+; skip validation. # * :allow_blank - Attribute may be blank; skip validation. - # * :too_long - The error message if the attribute goes over the maximum (default is: "is too long (maximum is %d characters)"). - # * :too_short - The error message if the attribute goes under the minimum (default is: "is too short (min is %d characters)"). - # * :wrong_length - The error message if using the :is method and the attribute is the wrong size (default is: "is the wrong length (should be %d characters)"). + # * :too_long - The error message if the attribute goes over the maximum (default is: "is too long (maximum is {{count}} characters)"). + # * :too_short - The error message if the attribute goes under the minimum (default is: "is too short (min is {{count}} characters)"). + # * :wrong_length - The error message if using the :is method and the attribute is the wrong size (default is: "is the wrong length (should be {{count}} characters)"). # * :message - The error message to use for a :minimum, :maximum, or :is violation. An alias of the appropriate too_long/too_short/wrong_length message. # * :on - Specifies when this validation is active (default is :save, other options :create, :update). # * :if - Specifies a method, proc or string to call to determine if the validation should @@ -731,7 +744,7 @@ module ActiveRecord # class Person < ActiveRecord::Base # validates_inclusion_of :gender, :in => %w( m f ), :message => "woah! what are you then!??!!" # validates_inclusion_of :age, :in => 0..99 - # validates_inclusion_of :format, :in => %w( jpg gif png ), :message => "extension %s is not included in the list" + # validates_inclusion_of :format, :in => %w( jpg gif png ), :message => "extension {{value}} is not included in the list" # end # # Configuration options: @@ -765,7 +778,7 @@ module ActiveRecord # class Person < ActiveRecord::Base # validates_exclusion_of :username, :in => %w( admin superuser ), :message => "You don't belong here" # validates_exclusion_of :age, :in => 30..60, :message => "This site is only for under 30 and over 60" - # validates_exclusion_of :format, :in => %w( mov avi ), :message => "extension %s is not allowed" + # validates_exclusion_of :format, :in => %w( mov avi ), :message => "extension {{value}} is not allowed" # end # # Configuration options: -- cgit v1.2.3