Permalink
Browse files

Merge branch 'master' of git://github.com/lifo/docrails

  • Loading branch information...
fxn committed Feb 21, 2011
2 parents cd12c36 + b481574 commit f826e058355606d1b0503b0395519728335324f4
Showing with 152 additions and 80 deletions.
  1. +3 −0 activemodel/lib/active_model/observing.rb
  2. +23 −0 activemodel/lib/active_model/serializers/xml.rb
  3. +2 −2 activemodel/lib/active_model/validations.rb
  4. +3 −3 activemodel/lib/active_model/validations/acceptance.rb
  5. +3 −2 activemodel/lib/active_model/validations/confirmation.rb
  6. +3 −0 activemodel/lib/active_model/validations/exclusion.rb
  7. +3 −1 activemodel/lib/active_model/validations/format.rb
  8. +3 −0 activemodel/lib/active_model/validations/inclusion.rb
  9. +3 −1 activemodel/lib/active_model/validations/length.rb
  10. +3 −1 activemodel/lib/active_model/validations/numericality.rb
  11. +3 −2 activemodel/lib/active_model/validations/presence.rb
  12. +8 −0 activerecord/lib/active_record/relation.rb
  13. +16 −2 activerecord/lib/active_record/validations.rb
  14. +3 −1 activerecord/lib/active_record/validations/associated.rb
  15. +1 −1 activerecord/test/cases/autosave_association_test.rb
  16. +5 −5 activesupport/lib/active_support/core_ext/module/attr_accessor_with_default.rb
  17. +19 −5 activesupport/lib/active_support/core_ext/object/with_options.rb
  18. +4 −4 railties/guides/source/active_support_core_extensions.textile
  19. +6 −0 railties/guides/source/i18n.textile
  20. +3 −1 railties/guides/source/layouts_and_rendering.textile
  21. +9 −9 railties/guides/source/performance_testing.textile
  22. +1 −3 railties/guides/source/rails_application_templates.textile
  23. +2 −2 railties/guides/source/rails_on_rack.textile
  24. +1 −1 railties/guides/source/security.textile
  25. +1 −1 railties/lib/rails/generators/rails/app/templates/public/javascripts/jquery.js
  26. +21 −33 railties/lib/rails/railtie.rb
@@ -48,19 +48,22 @@ def instantiate_observers
observers.each { |o| instantiate_observer(o) }
end
+ # Add a new observer to the pool.
def add_observer(observer)
unless observer.respond_to? :update
raise ArgumentError, "observer needs to respond to `update'"
end
observer_instances << observer
end
+ # Notify list of observers of a change.
def notify_observers(*arg)
for observer in observer_instances
observer.update(*arg)
end
end
+ # Total number of observers.
def count_observers
observer_instances.size
end
@@ -134,6 +134,29 @@ def add_procs
# Returns XML representing the model. Configuration can be
# passed through +options+.
+ #
+ # Without any +options+, the returned XML string will include all the model's
+ # attributes. For example:
+ #
+ # konata = User.find(1)
+ # konata.to_xml
+ #
+ # <?xml version="1.0" encoding="UTF-8"?>
+ # <user>
+ # <id type="integer">1</id>
+ # <name>David</name>
+ # <age type="integer">16</age>
+ # <created-at type="datetime">2011-01-30T22:29:23Z</created-at>
+ # </user>
+ #
+ # The <tt>:only</tt> and <tt>:except</tt> options can be used to limit the attributes
+ # included, and work similar to the +attributes+ method.
+ #
+ # To include the result of some method calls on the model use <tt>:methods</tt>.
+ #
+ # To include associations use <tt>:include</tt>.
+ #
+ # For further documentation see activerecord/lib/active_record/serializers/xml_serializer.xml.
def to_xml(options = {}, &block)
Serializer.new(self, options).serialize(&block)
end
@@ -71,8 +71,8 @@ module ClassMethods
# end
#
# Options:
- # * <tt>:on</tt> - Specifies when this validation is active (default is
- # <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+ # * <tt>:on</tt> - Specifies the context where this validation is active
+ # (e.g. <tt>:on => :create</tt> or <tt>:on => :custom_validation_context</tt>)
# * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+.
# * <tt>:allow_blank</tt> - Skip validation if attribute is blank.
# * <tt>:if</tt> - Specifies a method, proc or string to call to determine
@@ -37,9 +37,9 @@ module HelperMethods
# Configuration options:
# * <tt>:message</tt> - A custom error message (default is: "must be
# accepted").
- # * <tt>:on</tt> - Specifies when this validation is active (default is
- # <tt>:save</tt>, other options are <tt>:create</tt> and
- # <tt>:update</tt>).
+ # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
+ # validation contexts by default (+nil+), other options are <tt>:create</tt>
+ # and <tt>:update</tt>.
# * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+ (default
# is true).
# * <tt>:accept</tt> - Specifies value that is considered accepted.
@@ -45,8 +45,9 @@ module HelperMethods
# Configuration options:
# * <tt>:message</tt> - A custom error message (default is: "doesn't match
# confirmation").
- # * <tt>:on</tt> - Specifies when this validation is active (default is
- # <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+ # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
+ # validation contexts by default (+nil+), other options are <tt>:create</tt>
+ # and <tt>:update</tt>.
# * <tt>:if</tt> - Specifies a method, proc or string to call to determine
# if the validation should occur (e.g. <tt>:if => :allow_validation</tt>,
# or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The
@@ -29,6 +29,9 @@ module HelperMethods
# * <tt>:message</tt> - Specifies a custom error message (default is: "is reserved").
# * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute is +nil+ (default is +false+).
# * <tt>:allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is +false+).
+ # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
+ # validation contexts by default (+nil+), other options are <tt>:create</tt>
+ # and <tt>:update</tt>.
# * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
# occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The
# method, proc or string should return or evaluate to a true or false value.
@@ -51,7 +51,9 @@ module HelperMethods
# * <tt>:allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is +false+).
# * <tt>:with</tt> - Regular expression that if the attribute matches will result in a successful validation.
# * <tt>:without</tt> - Regular expression that if the attribute does not match will result in a successful validation.
- # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+ # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
+ # validation contexts by default (+nil+), other options are <tt>:create</tt>
+ # and <tt>:update</tt>.
# * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
# occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The
# method, proc or string should return or evaluate to a true or false value.
@@ -38,6 +38,9 @@ module HelperMethods
# * <tt>:message</tt> - Specifies a custom error message (default is: "is not included in the list").
# * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute is +nil+ (default is +false+).
# * <tt>:allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is +false+).
+ # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
+ # validation contexts by default (+nil+), other options are <tt>:create</tt>
+ # and <tt>:update</tt>.
# * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
# occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The
# method, proc or string should return or evaluate to a true or false value.
@@ -83,7 +83,9 @@ module HelperMethods
# * <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>:on</tt> - Specifies when this validation is active. Runs in all
+ # validation contexts by default (+nil+), other options are <tt>:create</tt>
+ # and <tt>:update</tt>.
# * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
# occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The
# method, proc or string should return or evaluate to a true or false value.
@@ -93,7 +93,9 @@ module HelperMethods
#
# Configuration options:
# * <tt>:message</tt> - A custom error message (default is: "is not a number").
- # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+ # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
+ # validation contexts by default (+nil+), other options are <tt>:create</tt>
+ # and <tt>:update</tt>.
# * <tt>:only_integer</tt> - Specifies whether the value has to be an integer, e.g. an integral value (default is +false+).
# * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+ (default is +false+). Notice that for fixnum and float columns empty strings are converted to +nil+.
# * <tt>:greater_than</tt> - Specifies the value must be greater than the supplied value.
@@ -26,8 +26,9 @@ module HelperMethods
#
# Configuration options:
# * <tt>message</tt> - A custom error message (default is: "can't be blank").
- # * <tt>on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>,
- # <tt>:update</tt>).
+ # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
+ # validation contexts by default (+nil+), other options are <tt>:create</tt>
+ # and <tt>:update</tt>.
# * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
# occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).
# The method, proc or string should return or evaluate to a true or false value.
@@ -176,6 +176,12 @@ def scoping
#
# # Update all books that match conditions, but limit it to 5 ordered by date
# Book.update_all "author = 'David'", "title LIKE '%Rails%'", :order => 'created_at', :limit => 5
+ #
+ # # Conditions from the current relation also works
+ # Book.where('title LIKE ?', '%Rails%').update_all(:author => 'David')
+ #
+ # # The same idea applies to limit and order
+ # Book.where('title LIKE ?', '%Rails%').order(:created_at).limit(5).update_all(:author => 'David')
def update_all(updates, conditions = nil, options = {})
if conditions || options.present?
where(conditions).apply_finder_options(options.slice(:limit, :order)).update_all(updates)
@@ -249,6 +255,7 @@ def update(id, attributes)
#
# Person.destroy_all("last_login < '2004-04-04'")
# Person.destroy_all(:status => "inactive")
+ # Person.where(:age => 0..18).destroy_all
def destroy_all(conditions = nil)
if conditions
where(conditions).destroy_all
@@ -298,6 +305,7 @@ def destroy(id)
#
# Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')")
# Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else'])
+ # Post.where(:person_id => 5).where(:category => ['Something', 'Else']).delete_all
#
# Both calls delete the affected posts all at once with a single DELETE statement.
# If you need to destroy dependent associations or call your <tt>before_*</tt> or
@@ -1,5 +1,5 @@
module ActiveRecord
- # = Active Record Validations
+ # = Active Record RecordInvalid
#
# Raised by <tt>save!</tt> and <tt>create!</tt> when the record is invalid. Use the
# +record+ method to retrieve the record which did not validate.
@@ -18,6 +18,13 @@ def initialize(record)
end
end
+ # = Active Record Validations
+ #
+ # Active Record includes the majority of its validations from <tt>ActiveModel::Validations</tt>
+ # all of which accept the <tt>:on</tt> argument to define the context where the
+ # validations are active. Active Record will always supply either the context of
+ # <tt>:create</tt> or <tt>:update</tt> dependent on whether the model is a
+ # <tt>new_record?</tt>.
module Validations
extend ActiveSupport::Concern
include ActiveModel::Validations
@@ -49,7 +56,14 @@ def save!(options={})
perform_validations(options) ? super : raise(RecordInvalid.new(self))
end
- # Runs all the specified validations and returns true if no errors were added otherwise false.
+ # Runs all the validations within the specified context. Returns true if no errors are found,
+ # false otherwise.
+ #
+ # If the argument is false (default is +nil+), the context is set to <tt>:create</tt> if
+ # <tt>new_record?</tt> is true, and to <tt>:update</tt> if it is not.
+ #
+ # Validations with no <tt>:on</tt> option will run no matter the context. Validations with
+ # some <tt>:on</tt> option will only run in the specified context.
def valid?(context = nil)
context ||= (new_record? ? :create : :update)
output = super(context)
@@ -33,7 +33,9 @@ module ClassMethods
#
# Configuration options:
# * <tt>:message</tt> - A custom error message (default is: "is invalid")
- # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+ # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
+ # validation contexts by default (+nil+), other options are <tt>:create</tt>
+ # and <tt>:update</tt>.
# * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
# occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The
# method, proc or string should return or evaluate to a true or false value.
@@ -743,7 +743,7 @@ def test_should_rollback_destructions_if_an_exception_occurred_while_saving_has_
2.times { |i| @pirate.birds.create!(:name => "birds_#{i}") }
before = @pirate.birds.map { |c| c.mark_for_destruction ; c }
- # Stub the destroy method of the the second child to raise an exception
+ # Stub the destroy method of the second child to raise an exception
class << before.last
def destroy(*args)
super
@@ -7,11 +7,11 @@ class Module
# attr_accessor_with_default :age, 25
# end
#
- # some_person.age
- # => 25
- # some_person.age = 26
- # some_person.age
- # => 26
+ # person = Person.new
+ # person.age # => 25
+ #
+ # person.age = 26
+ # person.age # => 26
#
# To give attribute <tt>:element_name</tt> a dynamic default value, evaluated
# in scope of self:
@@ -7,13 +7,27 @@ class Object
# provided. Each method called on the block variable must take an options
# hash as its final argument.
#
- # with_options :order => 'created_at', :class_name => 'Comment' do |post|
- # post.has_many :comments, :conditions => ['approved = ?', true], :dependent => :delete_all
- # post.has_many :unapproved_comments, :conditions => ['approved = ?', false]
- # post.has_many :all_comments
+ # Without with_options, this code contains duplication:
+ #
+ # class Account < ActiveRecord::Base
+ # has_many :customers, :dependent => :destroy
+ # has_many :products, :dependent => :destroy
+ # has_many :invoices, :dependent => :destroy
+ # has_many :expenses, :dependent => :destroy
+ # end
+ #
+ # Using with_options, we can remove the duplication:
+ #
+ # class Account < ActiveRecord::Base
+ # with_options :dependent => :destroy do |assoc|
+ # assoc.has_many :customers
+ # assoc.has_many :products
+ # assoc.has_many :invoices
+ # assoc.has_many :expenses
+ # end
# end
#
- # Can also be used with an explicit receiver:
+ # It can also be used with an explicit receiver:
#
# map.with_options :controller => "people" do |people|
# people.connect "/people", :action => "index"
@@ -20,7 +20,7 @@ Thus, after a simple require like:
require 'active_support'
</ruby>
-objects do not even respond to +blank?+, let's see how to load its definition.
+objects do not even respond to +blank?+. Let's see how to load its definition.
h5. Cherry-picking a Definition
@@ -42,7 +42,7 @@ h5. Loading Grouped Core Extensions
The next level is to simply load all extensions to +Object+. As a rule of thumb, extensions to +SomeClass+ are available in one shot by loading +active_support/core_ext/some_class+.
-Thus, if that would do, to have +blank?+ available we could just load all extensions to +Object+:
+Thus, to load all extensions to +Object+ (including +blank?+):
<ruby>
require 'active_support/core_ext/object'
@@ -432,7 +432,7 @@ h4. +require_library_or_gem+
The convenience method +require_library_or_gem+ tries to load its argument with a regular +require+ first. If it fails loads +rubygems+ and tries again.
-If the first attempt is a failure and +rubygems+ can't be loaded the method raises +LoadError+. On the other hand, if +rubygems+ is available but the argument is not loadable as a gem, the method gives up and +LoadError+ is also raised.
+If the first attempt is a failure and +rubygems+ can't be loaded the method raises +LoadError+. A +LoadError+ is also raised if +rubygems+ is available but the argument is not loadable as a gem.
For example, that's the way the MySQL adapter loads the MySQL library:
@@ -503,7 +503,7 @@ Model attributes have a reader, a writer, and a predicate. You can alias a model
<ruby>
class User < ActiveRecord::Base
# let me refer to the email column as "login",
- # much meaningful for authentication code
+ # possibly meaningful for authentication code
alias_attribute :login, :email
end
</ruby>
@@ -809,6 +809,12 @@ That does not mean you're stuck with these limitations, though. The Ruby I18n ge
I18n.backend = Globalize::Backend::Static.new
</ruby>
+You can also use the Chain backend to chain multiple backends together. This is useful when you want to use standard translations with a Simple backend but store custom application translations in a database or other backends. For example, you could use the ActiveRecord backend and fall back to the (default) Simple backend:
+
+<ruby>
+I18n.backend = I18n::Backend::Chain.new(I18n::Backend::ActiveRecord.new, I18n.backend)
+</ruby>
+
h4. Using Different Exception Handlers
The I18n API defines the following exceptions that will be raised by backends when the corresponding unexpected conditions occur:
@@ -1006,11 +1006,13 @@ h5. Partial Layouts
A partial can use its own layout file, just as a view can use a layout. For example, you might call a partial like this:
<erb>
-<%= render "link_area", :layout => "graybar" %>
+<%= render :partial => "link_area", :layout => "graybar" %>
</erb>
This would look for a partial named +_link_area.html.erb+ and render it using the layout +_graybar.html.erb+. Note that layouts for partials follow the same leading-underscore naming as regular partials, and are placed in the same folder with the partial that they belong to (not in the master +layouts+ folder).
+Also note that explicitly specifying +:partial+ is required when passing additional options such as +:layout+.
+
h5. Passing Local Variables
You can also pass local variables into partials, making them even more powerful and flexible. For example, you can use this technique to reduce duplication between new and edit pages, while still keeping a bit of distinct content:
Oops, something went wrong.

0 comments on commit f826e05

Please sign in to comment.