railties 3.0.20 → 3.1.0.beta1

data/guides/source/active_record_basics.textile

@@ -180,7 +180,7 @@ Active Record provides a rich API for accessing data within a database. Below ar
 
 <ruby>
   # find all users named David who are Code Artists and sort by created_at in reverse chronological order
-  users = User.all(:conditions => { :name => 'David', :occupation => 'Code Artist'}, :order => 'created_at DESC')
+  users = User.where(:name => 'David', :occupation => 'Code Artist').order('created_at DESC')
 </ruby>
 
 You can learn more about querying an Active Record model in the "Active Record Query Interface":"active_record_querying.html" guide.

data/guides/source/active_record_querying.textile

@@ -19,8 +19,6 @@ Code examples throughout this guide will refer to one or more of the following m
 
 TIP: All of the following models use +id+ as the primary key, unless specified otherwise.
 
-<br />
-
 <ruby>
 class Client < ActiveRecord::Base
   has_one :address
@@ -58,6 +56,7 @@ The methods are:
 * +select+
 * +group+
 * +order+
+* +reorder+
 * +limit+
 * +offset+
 * +joins+
@@ -78,7 +77,7 @@ Primary operation of <tt>Model.find(options)</tt> can be summarized as:
 
 h4. Retrieving a Single Object
 
-Active Record lets you retrieve a single object using three different ways.
+Active Record lets you retrieve a single object using five different ways.
 
 h5. Using a Primary Key
 
@@ -132,6 +131,40 @@ SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1
 
 <tt>Model.last</tt> returns +nil+ if no matching record is found. No exception will be raised.
 
+h5. +first!+
+
+<tt>Model.first!</tt> finds the first record. For example:
+
+<ruby>
+client = Client.first!
+=> #<Client id: 1, first_name: "Lifo">
+</ruby>
+
+SQL equivalent of the above is:
+
+<sql>
+SELECT * FROM clients LIMIT 1
+</sql>
+
+<tt>Model.first!</tt> raises +RecordNotFound+ if no matching record is found.
+
+h5. +last!+
+
+<tt>Model.last!</tt> finds the last record. For example:
+
+<ruby>
+client = Client.last!
+=> #<Client id: 221, first_name: "Russel">
+</ruby>
+
+SQL equivalent of the above is:
+
+<sql>
+SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1
+</sql>
+
+<tt>Model.last!</tt> raises +RecordNotFound+ if no matching record is found.
+
 h4. Retrieving Multiple Objects
 
 h5. Using Multiple Primary Keys
@@ -150,7 +183,7 @@ SQL equivalent of the above is:
 SELECT * FROM clients WHERE (clients.id IN (1,10))
 </sql>
 
-<tt>Model.find(array_of_primary_key)</tt> will raise an +ActiveRecord::RecordNotFound+ exception unless a matching record is found for <strong>all</strong> of the supplied primary keys.
+WARNING: <tt>Model.find(array_of_primary_key)</tt> will raise an +ActiveRecord::RecordNotFound+ exception unless a matching record is found for <strong>all</strong> of the supplied primary keys.
 
 h4. Retrieving Multiple Objects in Batches
 
@@ -337,7 +370,7 @@ This code will generate SQL like this:
 SELECT * FROM clients WHERE (clients.orders_count IN (1,3,5))
 </sql>
 
-h4. Ordering
+h3. Ordering
 
 To retrieve records from the database in a specific order, you can use the +order+ method.
 
@@ -361,7 +394,7 @@ Or ordering by multiple fields:
 Client.order("orders_count ASC, created_at DESC")
 </ruby>
 
-h4. Selecting Specific Fields
+h3. Selecting Specific Fields
 
 By default, <tt>Model.find</tt> selects all the fields from the result set using +select *+.
 
@@ -386,7 +419,7 @@ SELECT viewable_by, locked FROM clients
 Be careful because this also means you're initializing a model object with only the fields that you've selected. If you attempt to access a field that is not in the initialized record you'll receive:
 
 <shell>
-ActiveRecord::MissingAttributeError: missing attribute: <attribute>
+ActiveModel::MissingAttributeError: missing attribute: <attribute>
 </shell>
 
 Where +&lt;attribute&gt;+ is the attribute you asked for. The +id+ method will not raise the +ActiveRecord::MissingAttributeError+, so just be careful when working with associations because they need the +id+ method to function properly.
@@ -397,7 +430,7 @@ You can also call SQL functions within the select option. For example, if you wo
 Client.select("DISTINCT(name)")
 </ruby>
 
-h4. Limit and Offset
+h3. Limit and Offset
 
 To apply +LIMIT+ to the SQL fired by the +Model.find+, you can specify the +LIMIT+ using +limit+ and +offset+ methods on the relation.
 
@@ -422,10 +455,10 @@ Client.limit(5).offset(30)
 will return instead a maximum of 5 clients beginning with the 31st. The SQL looks like:
 
 <sql>
-SELECT * FROM clients LIMIT 5, 30
+SELECT * FROM clients LIMIT 5 OFFSET 30
 </sql>
 
-h4. Group
+h3. Group
 
 To apply a +GROUP BY+ clause to the SQL fired by the finder, you can specify the +group+ method on the find.
 
@@ -440,10 +473,10 @@ And this will give you a single +Order+ object for each date where there are ord
 The SQL that would be executed would be something like this:
 
 <sql>
-SELECT * FROM orders GROUP BY date(created_at)
+SELECT * FROM orders GROUP BY date(created_at) ORDER BY created_at
 </sql>
 
-h4. Having
+h3. Having
 
 SQL uses the +HAVING+ clause to specify conditions on the +GROUP BY+ fields. You can add the +HAVING+ clause to the SQL fired by the +Model.find+ by adding the +:having+ option to the find.
 
@@ -461,7 +494,63 @@ SELECT * FROM orders GROUP BY date(created_at) HAVING created_at > '2009-01-15'
 
 This will return single order objects for each day, but only for the last month.
 
-h4. Readonly Objects
+h3. Overriding Conditions
+
+h4. +except+
+
+You can specify certain conditions to be excepted by using the +except+ method. For example:
+
+<ruby>
+Post.where('id > 10').limit(20).order('id asc').except(:order)
+</ruby>
+
+The SQL that would be executed:
+
+<sql>
+SELECT * FROM posts WHERE id > 10 LIMIT 20
+</sql>
+
+h4. +only+
+
+You can also override conditions using the +only+ method. For example:
+
+<ruby>
+Post.where('id > 10').limit(20).order('id desc').only(:order, :where)
+</ruby>
+
+The SQL that would be executed:
+
+<sql>
+SELECT * FROM posts WHERE id > 10 ORDER BY id DESC
+</sql>
+
+h4. +reorder+
+
+The +reorder+ method overrides the default scope order. For example:
+
+<ruby>
+class Post < ActiveRecord::Base
+  ..
+  ..
+  has_many :comments, :order => 'posted_at DESC'
+end
+
+Post.find(10).comments.reorder('name')
+</ruby>
+
+The SQL that would be executed:
+
+<sql>
+SELECT * FROM posts WHERE id = 10 ORDER BY name
+</sql>
+
+In case the +reorder+ clause is not used, the SQL executed would be:
+
+<sql>
+SELECT * FROM posts WHERE id = 10 ORDER BY posted_at DESC
+</sql>
+
+h3. Readonly Objects
 
 Active Record provides +readonly+ method on a relation to explicitly disallow modification or deletion of any of the returned object. Any attempt to alter or destroy a readonly record will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception.
 
@@ -471,9 +560,9 @@ client.visits += 1
 client.save
 </ruby>
 
-As +client+ is explicitly set to be a readonly object, the above code will raise an +ActiveRecord::ReadOnlyRecord+ exception when calling +client.save+ with an updated value of _visists_.
+As +client+ is explicitly set to be a readonly object, the above code will raise an +ActiveRecord::ReadOnlyRecord+ exception when calling +client.save+ with an updated value of _visits_.
 
-h4. Locking Records for Update
+h3. Locking Records for Update
 
 Locking is helpful for preventing race conditions when updating records in the database and ensuring atomic updates.
 
@@ -482,9 +571,9 @@ Active Record provides two locking mechanisms:
 * Optimistic Locking
 * Pessimistic Locking
 
-h5. Optimistic Locking
+h4. Optimistic Locking
 
-Optimistic locking allows multiple users to access the same record for edits, and assumes a minimum of conflicts with the data.  It does this by checking whether another process has made changes to a record since it was opened. An +ActiveRecord::StaleObjectError+ exception is thrown if that has occurred and the update is ignored.
+Optimistic locking allows multiple users to access the same record for edits, and assumes a minimum of conflicts with the data. It does this by checking whether another process has made changes to a record since it was opened. An +ActiveRecord::StaleObjectError+ exception is thrown if that has occurred and the update is ignored.
 
 <strong>Optimistic locking column</strong>
 
@@ -517,7 +606,7 @@ class Client < ActiveRecord::Base
 end
 </ruby>
 
-h5. Pessimistic Locking
+h4. Pessimistic Locking
 
 Pessimistic locking uses a locking mechanism provided by the underlying database. Using +lock+ when building a relation obtains an exclusive lock on the selected rows. Relations using +lock+ are usually wrapped inside a transaction for preventing deadlock conditions.
 
@@ -569,9 +658,7 @@ SELECT clients.* FROM clients LEFT OUTER JOIN addresses ON addresses.client_id =
 
 h4. Using Array/Hash of Named Associations
 
-WARNING: This method only works with +INNER JOIN+,
-
-<br />
+WARNING: This method only works with +INNER JOIN+.
 
 Active Record lets you use the names of the "associations":association_basics.html defined on the model as a shortcut for specifying +JOIN+ clause for those associations when using the +joins+ method.
 
@@ -666,7 +753,7 @@ Eager loading is the mechanism for loading the associated records of the objects
 Consider the following code, which finds 10 clients and prints their postcodes:
 
 <ruby>
-clients = Client.all(:limit => 10)
+clients = Client.limit(10)
 
 clients.each do |client|
   puts client.address.postcode
@@ -721,15 +808,117 @@ h4. Specifying Conditions on Eager Loaded Associations
 
 Even though Active Record lets you specify conditions on the eager loaded associations just like +joins+, the recommended way is to use "joins":#joining-tables instead.
 
+However if you must do this, you may use +where+ as you would normally.
+
+<ruby>
+Post.includes(:comments).where("comments.visible", true)
+</ruby>
+
+This would generate a query which contains a +LEFT OUTER JOIN+ whereas the +joins+ method would generate one using the +INNER JOIN+ function instead.
+
+<ruby>
+  SELECT "posts"."id" AS t0_r0, ... "comments"."updated_at" AS t1_r5 FROM "posts" LEFT OUTER JOIN "comments" ON "comments"."post_id" = "posts"."id" WHERE (comments.visible = 1)
+</ruby>
+
+If there was no +where+ condition, this would generate the normal set of two queries.
+
+If, in the case of this +includes+ query, there were no comments for any posts, all the posts would still be loaded. By using +joins+ (an INNER JOIN), the join conditions *must* match, otherwise no records will be returned.
+
+h3. Scopes
+
+Scoping allows you to specify commonly-used ARel queries which can be referenced as method calls on the association objects or models. With these scopes, you can use every method previously covered such as +where+, +joins+ and +includes+. All scope methods will return an +ActiveRecord::Relation+ object which will allow for further methods (such as other scopes) to be called on it.
+
+To define a simple scope, we use the +scope+ method inside the class, passing the ARel query that we'd like run when this scope is called:
+
+<ruby>
+class Post < ActiveRecord::Base
+  scope :published, where(:published => true)
+end
+</ruby>
+
+Just like before, these methods are also chainable:
+
+<ruby>
+class Post < ActiveRecord::Base
+  scope :published, where(:published => true).joins(:category)
+end
+</ruby>
+
+Scopes are also chainable within scopes:
+
+<ruby>
+class Post < ActiveRecord::Base
+  scope :published, where(:published => true)
+  scope :published_and_commented, published.and(self.arel_table[:comments_count].gt(0))
+end
+</ruby>
+
+To call this +published+ scope we can call it on either the class:
+
+<ruby>
+Post.published => [published posts]
+</ruby>
+
+Or on an association consisting of +Post+ objects:
+
+<ruby>
+category = Category.first
+category.posts.published => [published posts belonging to this category]
+</ruby>
+
+h4. Working with times
+
+If you're working with dates or times within scopes, due to how they are evaluated, you will need to use a lambda so that the scope is evaluated every time.
+
+<ruby>
+class Post < ActiveRecord::Base
+  scope :last_week, lambda { where("created_at < ?", Time.zone.now ) }
+end
+</ruby>
+
+Without the +lambda+, this +Time.zone.now+ will only be called once.
+
+h4. Passing in arguments
+
+When a +lambda+ is used for a +scope+, it can take arguments:
+
+<ruby>
+class Post < ActiveRecord::Base
+  scope :1_week_before, lambda { |time| where("created_at < ?", time)
+end
+</ruby>
+
+This may then be called using this:
+
+<ruby>
+Post.1_week_before(Time.zone.now)
+</ruby>
+
+However, this is just duplicating the functionality that would be provided to you by a class method.
+
+<ruby>
+class Post < ActiveRecord::Base
+  def self.1_week_before(time)
+    where("created_at < ?", time)
+  end
+end
+</ruby>
+
+Using a class method is the preferred way to accept arguments for scopes. These methods will still be accessible on the association objects:
+
+<ruby>
+category.posts.1_week_before(time)
+</ruby>
+
 h3. Dynamic Finders
 
-For every field (also known as an attribute) you define in your table, Active Record provides a finder method. If you have a field called +first_name+ on your +Client+ model for example, you get +find_by_first_name+ and +find_all_by_first_name+ for free from Active Record. If you have also have a +locked+ field on the +Client+ model, you also get +find_by_locked+ and +find_all_by_locked+.
+For every field (also known as an attribute) you define in your table, Active Record provides a finder method. If you have a field called +first_name+ on your +Client+ model for example, you get +find_by_first_name+ and +find_all_by_first_name+ for free from Active Record. If you have a +locked+ field on the +Client+ model, you also get +find_by_locked+ and +find_all_by_locked+ methods.
 
-You can do +find_last_by_*+ methods too which will find the last record matching your argument.
+You can also use +find_last_by_*+ methods which will find the last record matching your argument.
 
 You can specify an exclamation point (<tt>!</tt>) on the end of the dynamic finders to get them to raise an +ActiveRecord::RecordNotFound+ error if they do not return any records, like +Client.find_by_name!("Ryan")+
 
-If you want to find both by name and locked, you can chain these finders together by simply typing +and+ between the fields for example +Client.find_by_first_name_and_locked("Ryan", true)+.
+If you want to find both by name and locked, you can chain these finders together by simply typing +and+ between the fields. For example, +Client.find_by_first_name_and_locked("Ryan", true)+.
 
 
 There's another set of dynamic finders that let you find or create/initialize objects if they aren't found. These work in a similar fashion to the other finders and can be used like +find_or_create_by_first_name(params[:first_name])+. Using this will first perform a find and then create if the find returns +nil+. The SQL looks like this for +Client.find_or_create_by_first_name("Ryan")+:
@@ -831,7 +1020,7 @@ Client.count
 # SELECT count(*) AS count_all FROM clients
 </ruby>
 
-Or on a relation :
+Or on a relation:
 
 <ruby>
 Client.where(:first_name => 'Ryan').count
@@ -898,10 +1087,11 @@ If you want to find the sum of a field for all records in your table you can cal
 Client.sum("orders_count")
 </ruby>
 
-For options, please see the parent section,  "Calculations":#calculations.
+For options, please see the parent section, "Calculations":#calculations.
 
 h3. Changelog
 
+* December 23 2010: Add documentation for the +scope+ method. "Ryan Bigg":http://ryanbigg.com
 * April 7, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
 * February 3, 2010: Update to Rails 3 by "James Miller":credits.html#bensie
 * February 7, 2009: Second version by "Pratik":credits.html#lifo

data/guides/source/active_record_validations_callbacks.textile

@@ -84,6 +84,7 @@ The following methods skip validations, and will save the object to the database
 * +toggle!+
 * +update_all+
 * +update_attribute+
+* +update_column+
 * +update_counters+
 
 Note that +save+ also has the ability to skip validations if passed +:validate => false+ as argument. This technique should be used with caution.
@@ -96,7 +97,7 @@ To verify whether or not an object is valid, Rails uses the +valid?+ method. You
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_presence_of :name
+  validates :name, :presence => true
 end
 
 Person.create(:name => "John Doe").valid? # => true
@@ -109,7 +110,7 @@ Note that an object instantiated with +new+ will not report errors even if it's
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_presence_of :name
+  validates :name, :presence => true
 end
 
 >> p = Person.new
@@ -147,7 +148,7 @@ This method is only useful _after_ validations have been run, because it only in
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_presence_of :name
+  validates :name, :presence => true
 end
 
 >> Person.new.errors[:name].any? # => false
@@ -197,7 +198,7 @@ end
 
 This validation will work with all of the association types.
 
-CAUTION: Don't use +validates_associated+ on both ends of your associations, they would call each other in an infinite loop.
+CAUTION: Don't use +validates_associated+ on both ends of your associations. They would call each other in an infinite loop.
 
 The default error message for +validates_associated+ is "_is invalid_". Note that each associated object will contain its own +errors+ collection; errors do not bubble up to the calling model.
 
@@ -235,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),
+  validates_exclusion_of :subdomain, :in => %w(www us ca jp),
     :message => "Subdomain %{value} is reserved."
 end
 </ruby>
@@ -314,6 +315,8 @@ class Essay < ActiveRecord::Base
 end
 </ruby>
 
+Note that the default error messages are plural (e.g., "is too short (minimum is %{count} characters)"). For this reason, when +:minimum+ is 1 you should provide a personalized message or use +validates_presence_of+ instead. When +:in+ or +:within+ have a lower limit of 1, you should either provide a personalized message or call +validates_presence_of+ prior to +validates_length_of+.
+
 The +validates_size_of+ helper is an alias for +validates_length_of+.
 
 h4. +validates_numericality_of+
@@ -355,7 +358,7 @@ This helper validates that the specified attributes are not empty. It uses the +
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_presence_of :name, :login, :email
+  validates :name, :login, :email, :presence => true
 end
 </ruby>
 
@@ -415,7 +418,7 @@ class Person < ActiveRecord::Base
 end
 
 class GoodnessValidator < ActiveModel::Validator
-  def validate
+  def validate(record)
     if record.first_name == "Evil"
       record.errors[:base] << "This person is evil"
     end
@@ -425,10 +428,7 @@ end
 
 The +validates_with+ helper takes a class, or a list of classes to use for validation. There is no default error message for +validates_with+. You must manually add errors to the record's errors collection in the validator class.
 
-The validator class has two attributes by default:
-
-* +record+ - the record to be validated
-* +options+ - the extra options that were passed to +validates_with+
+To implement the validate method, you must have an +record+ parameter defined, which is the record to be validated.
 
 Like all other validations, +validates_with+ takes the +:if+, +:unless+ and +:on+ options. If you pass any other options, it will send those options to the validator class as +options+:
 
@@ -437,8 +437,8 @@ class Person < ActiveRecord::Base
   validates_with GoodnessValidator, :fields => [:first_name, :last_name]
 end
 
-class GoodnessValidator < ActiveRecord::Validator
-  def validate
+class GoodnessValidator < ActiveModel::Validator
+  def validate(record)
     if options[:fields].any?{|field| record.send(field) == "Evil" }
       record.errors[:base] << "This person is evil"
     end
@@ -462,11 +462,11 @@ The block receives the model, the attribute's name and the attribute's value. Yo
 
 h3. Common Validation Options
 
-There are some common options that all the validation helpers can use. Here they are, except for the +:if+ and +:unless+ options, which are discussed later in "Conditional Validation":#conditional-validation.
+These are common validation options:
 
 h4. +:allow_nil+
 
-The +:allow_nil+ option skips the validation when the value being validated is +nil+. Using +:allow_nil+ with +validates_presence_of+ allows for +nil+, but any other +blank?+ value will still be rejected.
+The +:allow_nil+ option skips the validation when the value being validated is +nil+.
 
 <ruby>
 class Coffee < ActiveRecord::Base
@@ -475,6 +475,8 @@ class Coffee < ActiveRecord::Base
 end
 </ruby>
 
+TIP: +:allow_nil+ is ignored by the presence validator.
+
 h4. +:allow_blank+
 
 The +:allow_blank+ option is similar to the +:allow_nil+ option. This option will let validation pass if the attribute's value is +blank?+, like +nil+ or an empty string for example.
@@ -488,6 +490,8 @@ Topic.create("title" => "").valid? # => true
 Topic.create("title" => nil).valid? # => true
 </ruby>
 
+TIP: +:allow_blank+ is ignored by the presence validator.
+
 h4. +:message+
 
 As you've already seen, the +:message+ option lets you specify the message that will be added to the +errors+ collection when validation fails. When this option is not used, Active Record will use the respective default error message for each validation helper.
@@ -505,7 +509,7 @@ class Person < ActiveRecord::Base
   validates_numericality_of :age, :on => :update
 
   # the default (validates on both create and update)
-  validates_presence_of :name, :on => :save
+  validates :name, :presence => true, :on => :save
 end
 </ruby>
 
@@ -548,6 +552,21 @@ class Account < ActiveRecord::Base
 end
 </ruby>
 
+h4. Grouping conditional validations
+
+Sometimes it is useful to have multiple validations use one condition, it can be easily achieved using +with_options+.
+
+<ruby>
+class User < ActiveRecord::Base
+  with_options :if => :is_admin? do |admin|
+    admin.validates_length_of :password, :minimum => 10
+    admin.validates_presence_of :email
+  end
+end
+</ruby>
+
+All validations inside of +with_options+ block will have automatically passed the condition +:if => :is_admin?+
+
 h3. Creating Custom Validation Methods
 
 When the built-in validation helpers are not enough for your needs, you can write your own validation methods.
@@ -603,7 +622,7 @@ Returns an OrderedHash with all errors. Each key is the attribute name and the v
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_presence_of :name
+  validates :name, :presence => true
   validates_length_of :name, :minimum => 3
 end
 
@@ -623,7 +642,7 @@ h4(#working_with_validation_errors-errors-2). +errors[]+
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_presence_of :name
+  validates :name, :presence => true
   validates_length_of :name, :minimum => 3
 end
 
@@ -699,7 +718,7 @@ The +clear+ method is used when you intentionally want to clear all the messages
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_presence_of :name
+  validates :name, :presence => true
   validates_length_of :name, :minimum => 3
 end
 
@@ -723,7 +742,7 @@ The +size+ method returns the total number of error messages for the object.
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_presence_of :name
+  validates :name, :presence => true
   validates_length_of   :name, :minimum => 3
   validates_presence_of :email
 end
@@ -739,7 +758,20 @@ person.errors.size # => 0
 
 h3. Displaying Validation Errors in the View
 
-Rails provides built-in helpers to display the error messages of your models in your view templates.
+Rails maintains an official plugin that provides helpers to display the error messages of your models in your view templates. You can install it as a plugin or as a Gem.
+
+h4. Installing as a plugin
+<shell>
+$ rails plugin install git://github.com/joelmoss/dynamic_form.git
+</shell>
+
+h4 Installing as a Gem
+Add this line on your Gemfile:
+<ruby>
+gem "dynamic_form"
+</ruby>
+
+Now you will have access to these two methods in your view templates:
 
 h4. +error_messages+ and +error_messages_for+
 
@@ -805,7 +837,7 @@ The selectors to customize the style of error messages are:
 * +#errorExplanation p+ - Style for the paragraph that holds the message that appears right below the header of the +div+ element.
 * +#errorExplanation ul li+ - Style for the list items with individual error messages.
 
-Scaffolding for example generates +public/stylesheets/scaffold.css+, which defines the red-based style you saw above.
+Scaffolding for example generates +app/assets/stylesheets/scaffold.css.scss+, which later compiles to +app/assets/stylesheets/scaffold.css+ and defines the red-based style you saw above.
 
 The name of the class and the id can be changed with the +:class+ and +:id+ options, accepted by both helpers.
 
@@ -865,8 +897,9 @@ The macro-style class methods can also receive a block. Consider using this styl
 class User < ActiveRecord::Base
   validates_presence_of :login, :email
 
-  before_create {|user| user.name = user.login.capitalize
-	if user.name.blank?}
+  before_create do |user|
+    user.name = user.login.capitalize if user.name.blank?
+  end
 end
 </ruby>
 
@@ -977,6 +1010,7 @@ Just as with validations, it's also possible to skip callbacks. These methods sh
 * +increment+
 * +increment_counter+
 * +toggle+
+* +update_column+
 * +update_all+
 * +update_counters+
 
@@ -1113,7 +1147,7 @@ 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
+$ rails generate observer User
 </shell>
 
 <ruby>
@@ -1158,8 +1192,43 @@ In this example, the +after_create+ method would be called whenever a +Registrat
 config.active_record.observers = :mailer_observer
 </ruby>
 
+h3. Transaction Callbacks
+
+There are two additional callbacks that are triggered by the completion of a database transaction: +after_commit+ and +after_rollback+. These callbacks are very similar to the +after_save+ callback except that they don't execute until after database changes have either been committed or rolled back. They are most useful when your active record models need to interact with external systems which are not part of the database transaction.
+
+Consider, for example, the previous example where the +PictureFile+ model needs to delete a file after a record is destroyed. If anything raises an exception after the +after_destroy+ callback is called and the transaction rolls back, the file will have been deleted and the model will be left in an inconsistent state. For example, suppose that +picture_file_2+ in the code below is not valid and the +save!+ method raises an error.
+
+<ruby>
+PictureFile.transaction do
+  picture_file_1.destroy
+  picture_file_2.save!
+end
+</ruby>
+
+By using the +after_commit+ callback we can account for this case.
+
+<ruby>
+class PictureFile < ActiveRecord::Base
+  attr_accessor :delete_file
+
+  after_destroy do |picture_file|
+    picture_file.delete_file = picture_file.filepath
+  end
+
+  after_commit do |picture_file|
+    if picture_file.delete_file && File.exist?(picture_file.delete_file)
+      File.delete(picture_file.delete_file)
+      picture_file.delete_file = nil
+    end
+  end
+end
+</ruby>
+
+The +after_commit+ and +after_rollback+ callbacks are guaranteed to be called for all models created, updated, or destroyed within a transaction block. If any exceptions are raised within one of these callbacks, they will be ignored so that they don't interfere with the other callbacks. As such, if your callback code could raise an exception, you'll need to rescue it and handle it appropriately within the callback.
+
 h3. Changelog
 
+* February 17, 2011: Add description of transaction callbacks.
 * July 20, 2010: Fixed typos and rephrased some paragraphs for clarity. "Jaime Iniesta":http://jaimeiniesta.com
 * 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