railties 3.0.0.beta3 → 3.0.0.beta4

data/guides/source/activerecord_validations_callbacks.textile

@@ -115,17 +115,17 @@ end
 >> p = Person.new
 => #<Person id: nil, name: nil>
 >> p.errors
-=> #<ActiveRecord::Errors..., @errors={}>
+=> {}
   
 >> p.valid?
 => false
 >> p.errors
-=> #<ActiveRecord::Errors..., @errors={"name"=>["can't be blank"]}>
+=> {:name=>["can't be blank"]}
 
 >> p = Person.create
 => #<Person id: nil, name: nil>
 >> p.errors
-=> #<ActiveRecord::Errors..., @errors={"name"=>["can't be blank"]}>
+=> {:name=>["can't be blank"]}
   
 >> p.save
 => false
@@ -139,17 +139,19 @@ end
 
 +invalid?+ is simply the inverse of +valid?+. +invalid?+ triggers your validations and returns true if any errors were added to the object, and false otherwise.
 
-h4. +errors.invalid?+
+h4(#validations_overview-errors). +errors[]+
 
-To verify whether or not a particular attribute of an object is valid, you can use the +errors.invalid?+ method. This method is only useful _after_ validations have been run, because it only inspects the errors collection and does not trigger validations itself. It's different from the +ActiveRecord::Base#invalid?+ method explained above because it doesn't verify the validity of the object as a whole. It only checks to see whether there are errors found on an individual attribute of the object.
+To verify whether or not a particular attribute of an object is valid, you can use +errors[:attribute]+ that returns an array with all attribute errors, when there are no errors on the specified attribute, an empty array is returned.
+
+This method is only useful _after_ validations have been run, because it only inspects the errors collection and does not trigger validations itself. It's different from the +ActiveRecord::Base#invalid?+ method explained above because it doesn't verify the validity of the object as a whole. It only checks to see whether there are errors found on an individual attribute of the object.
 
 <ruby>
 class Person < ActiveRecord::Base
   validates_presence_of :name
 end
 
->> Person.new.errors.invalid?(:name) # => false
->> Person.create.errors.invalid?(:name) # => true
+>> Person.new.errors[:name].any? # => false
+>> Person.create.errors[:name].any? # => true
 </ruby>
 
 We'll cover validation errors in greater depth in the "Working with Validation Errors":#working-with-validation-errors section. For now, let's turn to the built-in validation helpers that Rails provides by default.
@@ -234,7 +236,7 @@ This helper validates that the attributes' values are not included in a given se
 <ruby>
 class Account < ActiveRecord::Base
   validates_exclusion_of :subdomain, :in => %w(www),
-    :message => "Subdomain {{value}} is reserved."
+    :message => "Subdomain %{value} is reserved."
 end
 </ruby>
 
@@ -262,7 +264,7 @@ This helper validates that the attributes' values are included in a given set. I
 <ruby>
 class Coffee < ActiveRecord::Base
   validates_inclusion_of :size, :in => %w(small medium large),
-    :message => "{{value}} is not a valid size"
+    :message => "%{value} is not a valid size"
 end
 </ruby>
 
@@ -290,12 +292,12 @@ The possible length constraint options are:
 * +:in+ (or +:within+) - The attribute length must be included in a given interval. The value for this option must be a range.
 * +:is+ - The attribute length must be equal to the given value.
 
-The default error messages depend on the type of length validation being performed. You can personalize these messages using the +:wrong_length+, +:too_long+, and +:too_short+ options and <tt>{{count}}</tt> as a placeholder for the number corresponding to the length constraint being used. You can still use the +:message+ option to specify an error message.
+The default error messages depend on the type of length validation being performed. You can personalize these messages using the +:wrong_length+, +:too_long+, and +:too_short+ options and <tt>%{count}</tt> as a placeholder for the number corresponding to the length constraint being used. You can still use the +:message+ option to specify an error message.
 
 <ruby>
 class Person < ActiveRecord::Base
   validates_length_of :bio, :maximum => 1000,
-    :too_long => "{{count}} characters is the maximum allowed"
+    :too_long => "%{count} characters is the maximum allowed"
 end
 </ruby>
 
@@ -307,8 +309,8 @@ class Essay < ActiveRecord::Base
     :minimum   => 300,
     :maximum   => 400,
     :tokenizer => lambda { |str| str.scan(/\w+/) },
-    :too_short => "must have at least {{count}} words",
-    :too_long  => "must have at most {{count}} words"
+    :too_short => "must have at least %{count} words",
+    :too_long  => "must have at most %{count} words"
 end
 </ruby>
 
@@ -337,11 +339,11 @@ end
 
 Besides +:only_integer+, the +validates_numericality_of+ helper also accepts the following options to add constraints to acceptable values:
 
-* +:greater_than+ - Specifies the value must be greater than the supplied value. The default error message for this option is "_must be greater than {{count}}_".
-* +:greater_than_or_equal_to+ - Specifies the value must be greater than or equal to the supplied value. The default error message for this option is "_must be greater than or equal to {{count}}_".
-* +:equal_to+ - Specifies the value must be equal to the supplied value. The default error message for this option is "_must be equal to {{count}}_".
-* +:less_than+ - Specifies the value must be less than the supplied value. The default error message for this option is "_must be less than {{count}}_".
-* +:less_than_or_equal_to+ - Specifies the value must be less than or equal the supplied value. The default error message for this option is "_must be less or equal to {{count}}_".
+* +:greater_than+ - Specifies the value must be greater than the supplied value. The default error message for this option is "_must be greater than %{count}_".
+* +:greater_than_or_equal_to+ - Specifies the value must be greater than or equal to the supplied value. The default error message for this option is "_must be greater than or equal to %{count}_".
+* +:equal_to+ - Specifies the value must be equal to the supplied value. The default error message for this option is "_must be equal to %{count}_".
+* +:less_than+ - Specifies the value must be less than the supplied value. The default error message for this option is "_must be less than %{count}_".
+* +:less_than_or_equal_to+ - Specifies the value must be less than or equal the supplied value. The default error message for this option is "_must be less or equal to %{count}_".
 * +:odd+ - Specifies the value must be an odd number if set to true. The default error message for this option is "_must be odd_".
 * +:even+ - Specifies the value must be an even number if set to true. The default error message for this option is "_must be even_".
 
@@ -469,7 +471,7 @@ The +:allow_nil+ option skips the validation when the value being validated is +
 <ruby>
 class Coffee < ActiveRecord::Base
   validates_inclusion_of :size, :in => %w(small medium large),
-    :message => "{{value}} is not a valid size", :allow_nil => true
+    :message => "%{value} is not a valid size", :allow_nil => true
 end
 </ruby>
 
@@ -595,21 +597,53 @@ In addition to the +valid?+ and +invalid?+ methods covered earlier, Rails provid
 
 The following is a list of the most commonly used methods. Please refer to the +ActiveRecord::Errors+ documentation for a list of all the available methods.
 
-h4. +errors.add_to_base+
+h4(#working_with_validation_errors-errors). +errors+
 
-The +add_to_base+ method lets you add errors messages that are related to the object's state as a whole, instead of being related to a specific attribute. You can use this method when you want to say that the object is invalid, no matter the values of its attributes. +add_to_base+ simply receives a string and uses this as the error message.
+Returns an OrderedHash with all errors. Each key is the attribute name and value is an array of strings with all errors.
 
 <ruby>
 class Person < ActiveRecord::Base
-  def a_method_used_for_validation_purposes
-    errors.add_to_base("This person is invalid because ...")
-  end
+  validates_presence_of :name
+  validates_length_of :name, :minimum => 3
+end
+
+person = Person.new
+person.valid? # => false
+person.errors
+ # => {:name => ["can't be blank", "is too short (minimum is 3 characters)"]}
+ 
+person = Person.new(:name => "John Doe")
+person.valid? # => true
+person.errors # => []
+</ruby>
+
+h4(#working_with_validation_errors-errors-2). +errors[]+
+
++errors[]+ is used when you want to check the error messages for a specific attribute. It returns an array of strings with all error messages for the given attribute, each string with one error message. If there are no errors related to the attribute returns an empty array.
+
+<ruby>
+class Person < ActiveRecord::Base
+  validates_presence_of :name
+  validates_length_of :name, :minimum => 3
 end
+
+person = Person.new(:name => "John Doe")
+person.valid? # => true
+person.errors[:name] # => []
+
+person = Person.new(:name => "JD")
+person.valid? # => false
+person.errors[:name] # => ["is too short (minimum is 3 characters)"]
+
+person = Person.new
+person.valid? # => false
+person.errors[:name]
+ # => ["can't be blank", "is too short (minimum is 3 characters)"]
 </ruby>
 
 h4. +errors.add+
 
-The +add+ method lets you manually add messages that are related to particular attributes. You can use the +full_messages+ method to view the messages in the form they might be displayed to a user. Those particular messages get the attribute name prepended (and capitalized). +add+ receives the name of the attribute you want to add the message to, and the message itself.
+The +add+ method lets you manually add messages that are related to particular attributes. You can use the +errors.full_messages+ or +errors.to_a+ methods to view the messages in the form they might be displayed to a user. Those particular messages get the attribute name prepended (and capitalized). +add+ receives the name of the attribute you want to add the message to, and the message itself.
 
 <ruby>
 class Person < ActiveRecord::Base
@@ -620,37 +654,44 @@ end
 
 person = Person.create(:name => "!@#")
 
-person.errors.on(:name)
- # => "cannot contain the characters !@#%*()_-+="
+person.errors[:name]
+ # => ["cannot contain the characters !@#%*()_-+="]
 
 person.errors.full_messages
  # => ["Name cannot contain the characters !@#%*()_-+="]
 </ruby>
+  
+Another way to do this is using +[]=+ setter
 
-h4. +errors.on+
+<ruby>
+  class Person < ActiveRecord::Base
+    def a_method_used_for_validation_purposes
+      errors[:name] = "cannot contain the characters !@#%*()_-+="
+    end
+  end
+
+  person = Person.create(:name => "!@#")
+
+  person.errors[:name]
+   # => ["cannot contain the characters !@#%*()_-+="]
+
+  person.errors.to_a
+   # => ["Name cannot contain the characters !@#%*()_-+="]
+</ruby>
+
+h4. +errors[:base]+
 
-The +on+ method is used when you want to check the error messages for a specific attribute. It returns different kinds of objects depending on the state of the +errors+ collection for the given attribute. If there are no errors related to the attribute +on+ returns +nil+. If there is just one error message for this attribute +on+ returns a string with the message. When +errors+ holds two or more error messages for the attribute, +on+ returns an array of strings, each one with one error message.
+You can add errors messages that are related to the object's state as a whole, instead of being related to a specific attribute. You can use this method when you want to say that the object is invalid, no matter the values of its attributes. Since +errors[:base]+ is an array, you can simply add a string to the array and uses it as the error message.
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_presence_of :name
-  validates_length_of :name, :minimum => 3
+  def a_method_used_for_validation_purposes
+    errors[:base] << "This person is invalid because ..."
+  end
 end
+</ruby>
 
-person = Person.new(:name => "John Doe")
-person.valid? # => true
-person.errors.on(:name) # => nil
-
-person = Person.new(:name => "JD")
-person.valid? # => false
-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)"]
-</ruby>
 
 h4. +errors.clear+
 
@@ -664,7 +705,7 @@ end
 
 person = Person.new
 person.valid? # => false
-person.errors.on(:name)
+person.errors[:name]
  # => ["can't be blank", "is too short (minimum is 3 characters)"]
 
 person.errors.clear
@@ -672,7 +713,7 @@ person.errors.empty? # => true
 
 p.save # => false
 
-p.errors.on(:name)
+p.errors[:name]
  # => ["can't be blank", "is too short (minimum is 3 characters)"]
 </ruby>
 
@@ -838,32 +879,28 @@ Here is a list with all the available Active Record callbacks, listed in the sam
 h4. Creating an Object
 
 * +before_validation+
-* +before_validation_on_create+
 * +after_validation+
-* +after_validation_on_create+
 * +before_save+
+* +after_save+
 * +before_create+
-* INSERT OPERATION
+* +around_create+
 * +after_create+
-* +after_save+
 
 h4. Updating an Object
 
 * +before_validation+
-* +before_validation_on_update+
 * +after_validation+
-* +after_validation_on_update+
 * +before_save+
+* +after_save+
 * +before_update+
-* UPDATE OPERATION
+* +around_update+
 * +after_update+
-* +after_save+
 
 h4. Destroying an Object
 
 * +before_destroy+
-* DELETE OPERATION
 * +after_destroy+
+* +around_destroy+
 
 WARNING. +after_save+ runs both on create and update, but always _after_ the more specific callbacks +after_create+ and +after_update+, no matter the order in which the macro calls were executed.
 
@@ -1075,6 +1112,10 @@ h4. Creating Observers
 
 For example, imagine a +User+ model where we want to send an email every time a new user is created. Because sending emails is not directly related to our model's purpose, we could create an observer to contain this functionality.
 
+<shell>
+rails generate observer User
+</shell>
+
 <ruby>
 class UserObserver < ActiveRecord::Observer
   def after_create(model)
@@ -1121,6 +1162,8 @@ h3. Changelog
 
 "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213/tickets/26-active-record-validations-and-callbacks
 
+* May 24, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
+* May 15, 2010: Validation Errors section updated by "Emili Parreño":http://www.eparreno.com
 * March 7, 2009: Callbacks revision by Trevor Turk
 * February 10, 2009: Observers revision by Trevor Turk
 * February 5, 2009: Initial revision by Trevor Turk

data/guides/source/association_basics.textile

@@ -1262,7 +1262,7 @@ end
 
 TIP: In any case, Rails will not create foreign key columns for you. You need to explicitly define them as part of your migrations.
 
-h6(:has_many-group). +:group+
+h6(#has_many-group). +:group+
 
 The +:group+ option supplies an attribute name to group the result set by, using a +GROUP BY+ clause in the finder SQL.
 

data/guides/source/caching_with_rails.textile

@@ -57,7 +57,7 @@ class ProductsController < ActionController
   end
 
   def create
-    expire_page :action => :list
+    expire_page :action => :index
   end
 
 end

data/guides/source/command_line.textile

@@ -31,7 +31,7 @@ h4. +rails+
 
 The first thing we'll want to do is create a new Rails application by running the +rails+ command after installing Rails.
 
-WARNING: You know you need the rails gem installed by typing +gem install rails+ first, if you don't have this installed, follow the instructions in the "Rails 3 Release Notes":/3_0_release_notes.textile
+WARNING: You know you need the rails gem installed by typing +gem install rails+ first, if you don't have this installed, follow the instructions in the "Rails 3 Release Notes":/3_0_release_notes.html
 
 <shell>
 $ rails commandsapp
@@ -64,12 +64,13 @@ Without any prodding of any kind, +rails server+ will run our new shiny Rails ap
 <shell>
 $ cd commandsapp
 $ rails server
-=> Booting WEBrick...
-=> Rails 2.2.0 application started on http://0.0.0.0:3000
-=> Ctrl-C to shutdown server; call with --help for options
-[2008-11-04 10:11:38] INFO  WEBrick 1.3.1
-[2008-11-04 10:11:38] INFO  ruby 1.8.5 (2006-12-04) [i486-linux]
-[2008-11-04 10:11:38] INFO  WEBrick::HTTPServer#start: pid=18994 port=3000
+=> Booting WEBrick
+=> Rails 3.0.0 application starting in development on http://0.0.0.0:3000
+=> Call with -d to detach
+=> Ctrl-C to shutdown server
+[2010-04-18 03:20:33] INFO  WEBrick 1.3.1
+[2010-04-18 03:20:33] INFO  ruby 1.8.7 (2010-01-10) [x86_64-linux]
+[2010-04-18 03:20:33] INFO  WEBrick::HTTPServer#start: pid=26086 port=3000
 </shell>
 
 With just three commands we whipped up a Rails server listening on port 3000. Go to your browser and open "http://localhost:3000":http://localhost:3000, you will see a basic rails app running.
@@ -237,7 +238,7 @@ The migration requires that we *migrate*, that is, run some Ruby code (living in
 
 <shell>
 $ rake db:migrate
-(in /Users/mikel/rails_programs/commandsapp)
+(in /home/foobar/commandsapp)
 ==  CreateHighScores: migrating ===============================================
 -- create_table(:high_scores)
    -> 0.0026s
@@ -320,21 +321,20 @@ h4. +about+
 Check it: Version numbers for Ruby, RubyGems, Rails, the Rails subcomponents, your application's folder, the current Rails environment name, your app's database adapter, and schema version! +about+ is useful when you need to ask for help, check if a security patch might affect you, or when you need some stats for an existing Rails installation.
 
 <shell>
-$ rails about
+$ rake about
 About your application's environment
-Ruby version              1.8.6 (i486-linux)
-RubyGems version          1.3.1
-Rails version             2.2.0
-Active Record version     2.2.0
-Action Pack version       2.2.0
-Active Resource version   2.2.0
-Action Mailer version     2.2.0
-Active Support version    2.2.0
-Edge Rails revision       unknown
-Application root          /home/commandsapp
+Ruby version              1.8.7 (x86_64-linux)
+RubyGems version          1.3.6
+Rack version              1.1
+Rails version             3.0.0
+Active Record version     3.0.0
+Action Pack version       3.0.0
+Active Resource version   3.0.0
+Action Mailer version     3.0.0
+Active Support version    3.0.0
+Middleware                ActionDispatch::Static, Rack::Lock, Rack::Runtime, Rails::Rack::Logger, ActionDispatch::ShowExceptions, ActionDispatch::RemoteIp, Rack::Sendfile, ActionDispatch::Callbacks, ActionDispatch::Cookies, ActionDispatch::Session::CookieStore, ActionDispatch::Flash, ActionDispatch::ParamsParser, Rack::MethodOverride, ActionDispatch::Head
+Application root          /home/foobar/commandsapp
 Environment               development
-Database adapter          sqlite3
-Database schema version   20081217073400
 </shell>
 
 h3. The Rails Advanced Command Line
@@ -526,11 +526,11 @@ You can get a list of Rake tasks available to you, which will often depend on yo
 
 <shell>
  rake --tasks
-(in /home/developer/commandsapp)
+(in /home/foobar/commandsapp)
 rake db:abort_if_pending_migrations       # Raises an error if there are pending migrations
 rake db:charset                           # Retrieves the charset for the current environment's database
 rake db:collation                         # Retrieves the collation for the current environment's database
-rake db:create                            # Create the database defined in config/database.yml for the current RAILS_ENV
+rake db:create                            # Create the database defined in config/database.yml for the current Rails.env
 ...
 ...
 rake tmp:pids:clear                       # Clears all files in tmp/pids

data/guides/source/configuring.textile

@@ -63,8 +63,6 @@ h4. Rails General Configuration
 
 * +config.logger+ accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then used to log information from Action Controller. Set to nil to disable logging.
 
-* +config.metals+ accepts an array used as the metals to load. If this is set to nil, all metals will be loaded in alphabetical order. If this is set to [], no metals will be loaded. Otherwise metals will be loaded in the order specified 
-
 * +config.plugin_loader+ overrides the class that handles loading each plugin. Defaults to +Rails::Plugin::Loader+.
 
 * +config.plugin_locators+ overrides the class that handle finding the desired plugins that you‘d like to load for your application. By default it is the +Rails::Plugin::FileSystemLocator+.
@@ -163,7 +161,7 @@ WARNING: Threadsafe operation in incompatible with the normal workings of develo
 
 The caching code adds two additional settings:
 
-* +ActionController::Base.page_cache_directory+ sets the directory where Rails will create cached pages for your web server. The default is +Rails.public_path+ (which is usually set to +RAILS_ROOT + "/public"+).
+* +ActionController::Base.page_cache_directory+ sets the directory where Rails will create cached pages for your web server. The default is +Rails.public_path+ (which is usually set to +Rails.root + "/public"+).
 
 * +ActionController::Base.page_cache_extension+ sets the extension to be used when generating pages for the cache (this is ignored if the incoming request already has an extension). The default is +.html+.
 

data/guides/source/contribute.textile

@@ -6,33 +6,37 @@ endprologue.
 
 h3. How to Contribute?
 
-* We have an open commit policy: anyone is welcome to contribute, but you'll need to ask for commit access.
-* PM lifo at "GitHub":http://github.com asking for "docrails":http://github.com/lifo/docrails/tree/master commit access.
-* Guides are written in Textile, and reside at railties/guides/source in the docrails project.
+* We have an open commit policy: anyone is welcome to contribute and to review contributions.
+* "docrails is hosted on GitHub":http://github.com/lifo/docrails and has public write access.
+* Guides are written in Textile, and reside at +railties/guides/source+ in the docrails project.
+* Follow the "Rails Guides Conventions":http://wiki.github.com/lifo/docrails/rails-guides-conventions.
 * Assets are stored in the +railties/guides/assets+ directory.
-* Sample format : "Active Record Associations":http://github.com/lifo/docrails/blob/3e56a3832415476fdd1cb963980d0ae390ac1ed3/railties/guides/source/association_basics.textile
-* Sample output : "Active Record Associations":association_basics.html
+* Sample format : "Active Record Associations":http://github.com/lifo/docrails/blob/3e56a3832415476fdd1cb963980d0ae390ac1ed3/railties/guides/source/association_basics.textile.
+* Sample output : "Active Record Associations":association_basics.html.
 * You can build the Guides during testing by running +rake generate_guides+ in the +railties+ directory.
+* You're encouraged to validate XHTML for the generated guides before commiting your changes by running +rake validate_guides+ in the +railties+ directory.
+* Edge guides "can be consulted online":http://edgeguides.rubyonrails.org/. That website is generated periodically from docrails.
 
 h3. What to Contribute?
 
 * We need authors, editors, proofreaders, and translators. Adding a single paragraph of quality content to a guide is a good way to get started.
 * The easiest way to start is by improving an existing guide:
-** Improve the structure to make it more coherent
-** Add missing information
-** Correct any factual errors
-** Fix typos or improve style
-** Bring it up to date with the latest Edge Rails
-* We're also open to suggestions for entire new guides
-** Contact lifo or mikeg1a in IRC or via "email":mailto:MikeG1@larkfarm.com to get your idea approved
-** If you're the main author on a significant guide, you're eligible for the prizes
-
-h3. How to Commit
-
-* If you have a small change or typo fix, just ask lifo for commit access and commit it to the project.
-* If your change is more significant, post a patch or a message on Lighthouse, and commit after you get a +1 from lifo or mikeg1a.
-* If the guide is already marked done, you should get a +1 before pushing your changes.
-* Put [#<ticket number>] in your commit message to enable GitHub/Lighthouse integration.
+** Improve the structure to make it more coherent.
+** Add missing information.
+** Correct any factual errors.
+** Fix typos or improve style.
+** Bring it up to date with the latest Edge Rails.
+* We're also open to suggestions for entire new guides:
+** Contact lifo or fxn to get your idea approved. See the Contact section below.
+** If you're the main author on a significant guide, you're eligible for the prizes.
+
+h3. How is the process?
+
+* The preferred way to contribute is to commit to docrails directly.
+* A new guide is only edited by its author until finished though. In that case feedback can be given in its LH ticket.
+* If you are writing a new guide freely commit to docrails partial work and ping lifo or fxn when done with a first draft.
+* Guides reviewers will then provide feedback, some of it possibly in form of direct commits to agilize the process.
+* Eventually the guide will be approved and added to the index.
 
 h3. Prizes
 
@@ -59,13 +63,8 @@ h3. Mailing List
 
 "Ruby on Rails: Documentation":http://groups.google.com/group/rubyonrails-docs is the mailing list for all the guides/documentation related discussions.
 
-h3. IRC Channel
-
-==#docrails @ irc.freenode.net==
-
 h3. Contact
 
-If you have any questions or need any clarification, feel free to contact:
-
-* IRC : lifo, mikeg1a or fxn in #docrails
-* Email : pratiknaik aT gmail
+* IRC : #docrails channel in irc.freenode.net
+* Twitter: "@docrails":http://twitter.com/docrails, "@lifo":http://twitter.com/lifo, "@fxn":http://twitter.com/fxn
+* Email : pratiknaik aT gmail, fxn aT hashref dot com