Permalink
Browse files

Merge docrails

  • Loading branch information...
lifo committed Sep 13, 2008
1 parent 9605541 commit a17027d13a48e1e64b14a28e7d58e341812f8cb4
@@ -10,32 +10,32 @@ module RoutingAssertions
# and a :method containing the required HTTP verb.
#
# # assert that POSTing to /items will call the create action on ItemsController
- # assert_recognizes({:controller => 'items', :action => 'create'}, {:path => 'items', :method => :post})
+ # assert_recognizes {:controller => 'items', :action => 'create'}, {:path => 'items', :method => :post}
#
# You can also pass in +extras+ with a hash containing URL parameters that would normally be in the query string. This can be used
# to assert that values in the query string string will end up in the params hash correctly. To test query strings you must use the
# extras argument, appending the query string on the path directly will not work. For example:
#
# # assert that a path of '/items/list/1?view=print' returns the correct options
- # assert_recognizes({:controller => 'items', :action => 'list', :id => '1', :view => 'print'}, 'items/list/1', { :view => "print" })
+ # assert_recognizes {:controller => 'items', :action => 'list', :id => '1', :view => 'print'}, 'items/list/1', { :view => "print" }
#
# The +message+ parameter allows you to pass in an error message that is displayed upon failure.
#
# ==== Examples
# # Check the default route (i.e., the index action)
- # assert_recognizes({:controller => 'items', :action => 'index'}, 'items')
+ # assert_recognizes {:controller => 'items', :action => 'index'}, 'items'
#
# # Test a specific action
- # assert_recognizes({:controller => 'items', :action => 'list'}, 'items/list')
+ # assert_recognizes {:controller => 'items', :action => 'list'}, 'items/list'
#
# # Test an action with a parameter
- # assert_recognizes({:controller => 'items', :action => 'destroy', :id => '1'}, 'items/destroy/1')
+ # assert_recognizes {:controller => 'items', :action => 'destroy', :id => '1'}, 'items/destroy/1'
#
# # Test a custom route
- # assert_recognizes({:controller => 'items', :action => 'show', :id => '1'}, 'view/item1')
+ # assert_recognizes {:controller => 'items', :action => 'show', :id => '1'}, 'view/item1'
#
# # Check a Simply RESTful generated route
- # assert_recognizes(list_items_url, 'items/list')
+ # assert_recognizes list_items_url, 'items/list'
def assert_recognizes(expected_options, path, extras={}, message=nil)
if path.is_a? Hash
request_method = path[:method]
@@ -67,13 +67,13 @@ def assert_recognizes(expected_options, path, extras={}, message=nil)
#
# ==== Examples
# # Asserts that the default action is generated for a route with no action
- # assert_generates("/items", :controller => "items", :action => "index")
+ # assert_generates "/items", :controller => "items", :action => "index"
#
# # Tests that the list action is properly routed
- # assert_generates("/items/list", :controller => "items", :action => "list")
+ # assert_generates "/items/list", :controller => "items", :action => "list"
#
# # Tests the generation of a route with a parameter
- # assert_generates("/items/list/1", { :controller => "items", :action => "list", :id => "1" })
+ # assert_generates "/items/list/1", { :controller => "items", :action => "list", :id => "1" }
#
# # Asserts that the generated route gives us our custom route
# assert_generates "changesets/12", { :controller => 'scm', :action => 'show_diff', :revision => "12" }
@@ -104,19 +104,19 @@ def assert_generates(expected_path, options, defaults={}, extras = {}, message=n
#
# ==== Examples
# # Assert a basic route: a controller with the default action (index)
- # assert_routing('/home', :controller => 'home', :action => 'index')
+ # assert_routing '/home', :controller => 'home', :action => 'index'
#
# # Test a route generated with a specific controller, action, and parameter (id)
- # assert_routing('/entries/show/23', :controller => 'entries', :action => 'show', id => 23)
+ # assert_routing '/entries/show/23', :controller => 'entries', :action => 'show', id => 23
#
# # Assert a basic route (controller + default action), with an error message if it fails
- # assert_routing('/store', { :controller => 'store', :action => 'index' }, {}, {}, 'Route for store index not generated properly')
+ # assert_routing '/store', { :controller => 'store', :action => 'index' }, {}, {}, 'Route for store index not generated properly'
#
# # Tests a route, providing a defaults hash
# assert_routing 'controller/action/9', {:id => "9", :item => "square"}, {:controller => "controller", :action => "action"}, {}, {:item => "square"}
#
# # Tests a route with a HTTP method
- # assert_routing({ :method => 'put', :path => '/product/321' }, { :controller => "product", :action => "update", :id => "321" })
+ # assert_routing { :method => 'put', :path => '/product/321' }, { :controller => "product", :action => "update", :id => "321" }
def assert_routing(path, options, defaults={}, extras={}, message=nil)
assert_recognizes(options, path, extras, message)
@@ -95,7 +95,7 @@ def visual_effect(name, element_id = false, js_options = {})
# * <tt>:containment</tt> - Takes an element or array of elements to treat as
# potential drop targets (defaults to the original target element).
#
- # * <tt>:only</tt> - A CSS class name or arry of class names used to filter
+ # * <tt>:only</tt> - A CSS class name or array of class names used to filter
# out child elements as candidates.
#
# * <tt>:scroll</tt> - Determines whether to scroll the list during drag
@@ -252,6 +252,10 @@ def simplified_type(field_type)
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 @@ def add_column_options!(sql, options)
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 @@ def [](name)
# * <tt>:scale</tt> -
# Specifies the scale for a <tt>:decimal</tt> 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
# <tt>:decimal</tt> columns:
# * The SQL standard says the default scale should be 0, <tt>:scale</tt> <=
@@ -374,6 +404,10 @@ def [](name)
# 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.
@@ -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"
@@ -259,6 +259,8 @@ def to_xml(options={})
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 @@ def to_xml(options={})
# 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 @@ def self.included(base) # :nodoc:
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 <tt>validates_..._of</tt> 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 (<tt>validates_..._of</tt> 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 ClassMethods
: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 @@ def validates_presence_of(*attr_names)
#
# 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 @@ def validates_presence_of(*attr_names)
# * <tt>:in</tt> - A synonym(or alias) for <tt>:within</tt>.
# * <tt>:allow_nil</tt> - Attribute may be +nil+; skip validation.
# * <tt>:allow_blank</tt> - Attribute may be blank; skip validation.
- # * <tt>:too_long</tt> - The error message if the attribute goes over the maximum (default is: "is too long (maximum is %d characters)").
- # * <tt>:too_short</tt> - The error message if the attribute goes under the minimum (default is: "is too short (min is %d characters)").
- # * <tt>:wrong_length</tt> - The error message if using the <tt>:is</tt> method and the attribute is the wrong size (default is: "is the wrong length (should be %d characters)").
+ # * <tt>:too_long</tt> - The error message if the attribute goes over the maximum (default is: "is too long (maximum is {{count}} characters)").
+ # * <tt>:too_short</tt> - The error message if the attribute goes under the minimum (default is: "is too short (min is {{count}} characters)").
+ # * <tt>:wrong_length</tt> - The error message if using the <tt>:is</tt> method and the attribute is the wrong size (default is: "is the wrong length (should be {{count}} characters)").
# * <tt>:message</tt> - The error message to use for a <tt>:minimum</tt>, <tt>:maximum</tt>, or <tt>:is</tt> violation. An alias of the appropriate <tt>too_long</tt>/<tt>too_short</tt>/<tt>wrong_length</tt> message.
# * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
# * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
@@ -731,7 +744,7 @@ def validates_format_of(*attr_names)
# 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 @@ def validates_inclusion_of(*attr_names)
# 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:
Oops, something went wrong.

0 comments on commit a17027d

Please sign in to comment.