Plugin guide: update acts_as section

3 files changed, 97 insertions, 108 deletions

diff --git a/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt b/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt
index 06878543e4..41ffa61537 100644
--- a/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt
+++ b/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt
@@ -1,8 +1,8 @@
-== Add an `acts_as_yaffle` method to ActiveRecord ==
+== Add an `acts_as_yaffle` method to Active Record ==
 
-A common pattern in plugins is to add a method called `acts_as_something` to models.  In this case, you want to write a method called `acts_as_yaffle` that adds a `squawk` method to your models.
+A common pattern in plugins is to add a method called 'acts_as_something' to models.  In this case, you want to write a method called 'acts_as_yaffle' that adds a 'squawk' method to your models.
 
-To keep things clean, create a new test file called 'acts_as_yaffle_test.rb' in your plugin's test directory and require your test helper.
+To begin, set up your files so that you have:
 
 *vendor/plugins/yaffle/test/acts_as_yaffle_test.rb*
 
@@ -10,25 +10,31 @@ To keep things clean, create a new test file called 'acts_as_yaffle_test.rb' in
 ------------------------------------------------------
 require File.dirname(__FILE__) + '/test_helper.rb'
 
-class Hickwall < ActiveRecord::Base
-  acts_as_yaffle
-end
-
 class ActsAsYaffleTest < Test::Unit::TestCase
 end
 ------------------------------------------------------
 
-*vendor/plugins/lib/acts_as_yaffle.rb*
+*vendor/plugins/yaffle/lib/yaffle.rb*
+
+[source, ruby]
+------------------------------------------------------
+require 'yaffle/acts_as_yaffle'
+------------------------------------------------------
+
+*vendor/plugins/yaffle/lib/yaffle/acts_as_yaffle.rb*
 
 [source, ruby]
 ------------------------------------------------------
 module Yaffle
+  # your code will go here
 end
 ------------------------------------------------------
 
-One of the most common plugin patterns for `acts_as_yaffle` plugins is to structure your file like so:
+Note that after requiring 'acts_as_yaffle' you also have to include it into ActiveRecord::Base so that your plugin methods will be available to the rails models.
+
+One of the most common plugin patterns for 'acts_as_yaffle' plugins is to structure your file like so:
 
-*vendor/plugins/lib/acts_as_yaffle.rb*
+*vendor/plugins/yaffle/lib/yaffle/acts_as_yaffle.rb*
 
 [source, ruby]
 ------------------------------------------------------
@@ -52,20 +58,11 @@ end
 
 With structure you can easily separate the methods that will be used for the class (like `Hickwall.some_method`) and the instance (like `@hickwell.some_method`).
 
-Let's add class method named `acts_as_yaffle` - testing it out first.  You already defined the ActiveRecord models in your test helper, so if you run tests now they will fail.
+=== Add a class method ===
 
-Back in your `acts_as_yaffle` file, update ClassMethods like so:
+This plugin will expect that you've added a method to your model named 'last_squawk'.  However, the plugin users might have already defined a method on their model named 'last_squawk' that they use for something else.  This plugin will allow the name to be changed by adding a class method called 'yaffle_text_field'.
 
-[source, ruby]
-------------------------------------------------------
-module ClassMethods
-  def acts_as_yaffle(options = {})
-    send :include, InstanceMethods
-  end
-end
-------------------------------------------------------
-
-Now that test should pass.  Since your plugin is going to work with field names, you need to allow people to define the field names, in case there is a naming conflict.  You can write a few simple tests for this:
+To start out, write a failing test that shows the behavior you'd like:
 
 *vendor/plugins/yaffle/test/acts_as_yaffle_test.rb*
 
@@ -73,28 +70,28 @@ Now that test should pass.  Since your plugin is going to work with field names,
 ------------------------------------------------------
 require File.dirname(__FILE__) + '/test_helper.rb'
 
+class Hickwall < ActiveRecord::Base
+  acts_as_yaffle
+end
+
+class Wickwall < ActiveRecord::Base
+  acts_as_yaffle :yaffle_text_field => :last_tweet
+end
+
 class ActsAsYaffleTest < Test::Unit::TestCase
   def test_a_hickwalls_yaffle_text_field_should_be_last_squawk
     assert_equal "last_squawk", Hickwall.yaffle_text_field
   end
 
-  def test_a_hickwalls_yaffle_date_field_should_be_last_squawked_at
-    assert_equal "last_squawked_at", Hickwall.yaffle_date_field
-  end
-
   def test_a_wickwalls_yaffle_text_field_should_be_last_tweet
     assert_equal "last_tweet", Wickwall.yaffle_text_field
   end
-
-  def test_a_wickwalls_yaffle_date_field_should_be_last_tweeted_at
-    assert_equal "last_tweeted_at", Wickwall.yaffle_date_field
-  end
 end
 ------------------------------------------------------
 
 To make these tests pass, you could modify your `acts_as_yaffle` file like so:
 
-*vendor/plugins/yaffle/lib/acts_as_yaffle.rb*
+*vendor/plugins/yaffle/lib/yaffle/acts_as_yaffle.rb*
 
 [source, ruby]
 ------------------------------------------------------
@@ -105,19 +102,20 @@ module Yaffle
 
   module ClassMethods
     def acts_as_yaffle(options = {})
-      cattr_accessor :yaffle_text_field, :yaffle_date_field
+      cattr_accessor :yaffle_text_field
       self.yaffle_text_field = (options[:yaffle_text_field] || :last_squawk).to_s
-      self.yaffle_date_field = (options[:yaffle_date_field] || :last_squawked_at).to_s
-      send :include, InstanceMethods
     end
   end
-
-  module InstanceMethods
-  end
 end
+
+ActiveRecord::Base.send :include, Yaffle
 ------------------------------------------------------
 
-Now you can add tests for the instance methods, and the instance method itself:
+=== Add an instance method ===
+
+This plugin will add a method named 'squawk' to any Active Record objects that call 'acts_as_yaffle'.  The 'squawk' method will simply set the value of one of the fields in the database.
+
+To start out, write a failing test that shows the behavior you'd like:
 
 *vendor/plugins/yaffle/test/acts_as_yaffle_test.rb*
 
@@ -125,47 +123,40 @@ Now you can add tests for the instance methods, and the instance method itself:
 ------------------------------------------------------
 require File.dirname(__FILE__) + '/test_helper.rb'
 
-class ActsAsYaffleTest < Test::Unit::TestCase
+class Hickwall < ActiveRecord::Base
+  acts_as_yaffle
+end
+
+class Wickwall < ActiveRecord::Base
+  acts_as_yaffle :yaffle_text_field => :last_tweet
+end
 
+class ActsAsYaffleTest < Test::Unit::TestCase
   def test_a_hickwalls_yaffle_text_field_should_be_last_squawk
     assert_equal "last_squawk", Hickwall.yaffle_text_field
   end
-  def test_a_hickwalls_yaffle_date_field_should_be_last_squawked_at
-    assert_equal "last_squawked_at", Hickwall.yaffle_date_field
-  end
 
-  def test_a_wickwalls_yaffle_text_field_should_be_last_squawk
+  def test_a_wickwalls_yaffle_text_field_should_be_last_tweet
     assert_equal "last_tweet", Wickwall.yaffle_text_field
   end
-  def test_a_wickwalls_yaffle_date_field_should_be_last_squawked_at
-    assert_equal "last_tweeted_at", Wickwall.yaffle_date_field
-  end
-
+  
   def test_hickwalls_squawk_should_populate_last_squawk
     hickwall = Hickwall.new
     hickwall.squawk("Hello World")
     assert_equal "squawk! Hello World", hickwall.last_squawk
-  end
-  def test_hickwalls_squawk_should_populate_last_squawked_at
-    hickwall = Hickwall.new
-    hickwall.squawk("Hello World")
-    assert_equal Date.today, hickwall.last_squawked_at
-  end
-
-  def test_wickwalls_squawk_should_populate_last_tweet
-    wickwall = Wickwall.new
-    wickwall.squawk("Hello World")
-    assert_equal "squawk! Hello World", wickwall.last_tweet
-  end
+  end  
+  
   def test_wickwalls_squawk_should_populate_last_tweeted_at
     wickwall = Wickwall.new
     wickwall.squawk("Hello World")
-    assert_equal Date.today, wickwall.last_tweeted_at
-  end
+    assert_equal "squawk! Hello World", wickwall.last_tweet
+  end  
 end
 ------------------------------------------------------
 
-*vendor/plugins/yaffle/lib/acts_as_yaffle.rb*
+Run this test to make sure the last two tests fail, then update 'acts_as_yaffle.rb' to look like this:
+
+*vendor/plugins/yaffle/lib/yaffle/acts_as_yaffle.rb*
 
 [source, ruby]
 ------------------------------------------------------
@@ -176,9 +167,8 @@ module Yaffle
 
   module ClassMethods
     def acts_as_yaffle(options = {})
-      cattr_accessor :yaffle_text_field, :yaffle_date_field
+      cattr_accessor :yaffle_text_field
       self.yaffle_text_field = (options[:yaffle_text_field] || :last_squawk).to_s
-      self.yaffle_date_field = (options[:yaffle_date_field] || :last_squawked_at).to_s
       send :include, InstanceMethods
     end
   end
@@ -186,10 +176,11 @@ module Yaffle
   module InstanceMethods
     def squawk(string)
       write_attribute(self.class.yaffle_text_field, string.to_squawk)
-      write_attribute(self.class.yaffle_date_field, Date.today)
     end
   end
 end
+
+ActiveRecord::Base.send :include, Yaffle
 ------------------------------------------------------
 
 .Editor's note:
diff --git a/railties/doc/guides/source/creating_plugins/core_ext.txt b/railties/doc/guides/source/creating_plugins/core_ext.txt
index 33d3dc8ce7..9bb7691b83 100644
--- a/railties/doc/guides/source/creating_plugins/core_ext.txt
+++ b/railties/doc/guides/source/creating_plugins/core_ext.txt
@@ -5,39 +5,6 @@ This section will explain how to add a method to String that will be available a
  * Writing tests for the desired behavior
  * Creating and requiring the correct files
 
-
-=== Working with init.rb ===
-
-When rails loads plugins it looks for the file named init.rb.  However, the plugin initializer script 'init.rb' is invoked via `eval` (not `require`) so it has slightly different behavior.
-
-Under certain circumstances if you reopen classes or modules in 'init.rb' itself, you may inadvertently create a new class, rather than reopening an existing class.  A better alternative is to reopen the class in a different file, and require that file from `init.rb`.
-
-If you must reopen a class in `init.rb` you can use `module_eval` or `class_eval`:
-
-*vendor/plugins/yaffle/init.rb*
-
-[source, ruby]
----------------------------------------------------
-Hash.class_eval do
-  def is_a_special_hash?
-    true
-  end
-end
----------------------------------------------------
-
-Another way is to explicitly define the top-level module space for all modules and classes, like `::Hash`:
-
-*vendor/plugins/yaffle/init.rb*
-
-[source, ruby]
----------------------------------------------------
-class ::Hash
-  def is_a_special_hash?
-    true
-  end
-end
----------------------------------------------------
-
 === Creating the test ===
 
 In this example you will add a method to String named `to_squawk`.  To begin, create a new test file with a few assertions:
@@ -75,7 +42,7 @@ Great - now you are ready to start development.
 
 === Organize your files ===
 
-A common pattern in rails plugins is to set up the file structure something like this:
+A common pattern in rails plugins is to set up the file structure like this:
 
 --------------------------------------------------------
 |-- init.rb
@@ -124,3 +91,34 @@ $ ./script/console
 => "squawk! Hello World"
 --------------------------------------------------------
 
+=== Working with init.rb ===
+
+When rails loads plugins it looks for the file named init.rb.  However, when the plugin is initialized, 'init.rb' is invoked via `eval` (not `require`) so it has slightly different behavior.
+
+Under certain circumstances if you reopen classes or modules in 'init.rb' you may inadvertently create a new class, rather than reopening an existing class.  A better alternative is to reopen the class in a different file, and require that file from `init.rb`, as shown above.
+
+If you must reopen a class in `init.rb` you can use `module_eval` or `class_eval` to avoid any issues:
+
+*vendor/plugins/yaffle/init.rb*
+
+[source, ruby]
+---------------------------------------------------
+Hash.class_eval do
+  def is_a_special_hash?
+    true
+  end
+end
+---------------------------------------------------
+
+Another way is to explicitly define the top-level module space for all modules and classes, like `::Hash`:
+
+*vendor/plugins/yaffle/init.rb*
+
+[source, ruby]
+---------------------------------------------------
+class ::Hash
+  def is_a_special_hash?
+    true
+  end
+end
+---------------------------------------------------
diff --git a/railties/doc/guides/source/creating_plugins/test_setup.txt b/railties/doc/guides/source/creating_plugins/test_setup.txt
index dc9ef6bc29..583d058494 100644
--- a/railties/doc/guides/source/creating_plugins/test_setup.txt
+++ b/railties/doc/guides/source/creating_plugins/test_setup.txt
@@ -155,12 +155,6 @@ ActiveRecord::Base.establish_connection(config[db_adapter])
 load(File.dirname(__FILE__) + "/schema.rb")
 
 require File.dirname(__FILE__) + '/../init.rb'
-
-class Hickwall < ActiveRecord::Base
-end
-
-class Wickwall < ActiveRecord::Base
-end
 ----------------------------------------------
 
 === Run the plugin tests ===
@@ -175,9 +169,15 @@ require File.dirname(__FILE__) + '/test_helper.rb'
 
 class YaffleTest < Test::Unit::TestCase
   
-  def test_active_record_classes_from_test_helper
-    assert_kind_of Hickwall, Hickwall.new
-    assert_kind_of Wickwall, Wickwall.new
+  class Hickwall < ActiveRecord::Base
+  end
+
+  class Wickwall < ActiveRecord::Base
+  end
+  
+  def test_schema_has_loaded_correctly
+    assert_equal [], Hickwall.all
+    assert_equal [], Wickwall.all
   end
   
 end