From ca99beb4a9fc983603e2427255afa97c63cc4cfc Mon Sep 17 00:00:00 2001 From: Andrew White Date: Mon, 12 Mar 2012 15:02:18 +0000 Subject: [PATCH] Add documentation for find_or_create_by_{attribute}! method. --- activerecord/lib/active_record/base.rb | 3 +++ railties/guides/source/active_record_querying.textile | 2 ++ 2 files changed, 5 insertions(+) diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index d4d0220fb7..d25a821688 100644 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -201,6 +201,9 @@ module ActiveRecord #:nodoc: # # Now 'Bob' exist and is an 'admin' # User.find_or_create_by_name('Bob', :age => 40) { |u| u.admin = true } # + # Adding an exclamation point (!) on to the end of find_or_create_by_ will + # raise an ActiveRecord::RecordInvalid error if the new record is invalid. + # # Use the find_or_initialize_by_ finder if you want to return a new record without # saving it first. Protected attributes won't be set unless they are given in a block. # diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile index d9a62f7574..8e23a577e2 100644 --- a/railties/guides/source/active_record_querying.textile +++ b/railties/guides/source/active_record_querying.textile @@ -1133,6 +1133,8 @@ Client.where(:first_name => 'Andy').first_or_create!(:locked => false) # => ActiveRecord::RecordInvalid: Validation failed: Orders count can't be blank +As with +first_or_create+ there is a +find_or_create_by!+ method but the +first_or_create!+ method is preferred for clarity. + h4. +first_or_initialize+ The +first_or_initialize+ method will work just like +first_or_create+ but it will not call +create+ but +new+. This means that a new model instance will be created in memory but won't be saved to the database. Continuing with the +first_or_create+ example, we now want the client named 'Nick':