Rails plugin: Expanded helpers section

4 files changed, 78 insertions, 111 deletions

diff --git a/railties/doc/guides/html/creating_plugins.html b/railties/doc/guides/html/creating_plugins.html
index 3fa7bff260..023a4ddbab 100644
--- a/railties/doc/guides/html/creating_plugins.html
+++ b/railties/doc/guides/html/creating_plugins.html
@@ -258,7 +258,7 @@ ul#navMain {
 					<a href="#_add_a_controller">Add a controller</a>
 					</li>
 					<li>
-					<a href="#_create_a_tt_squawk_info_for_tt_view_helper">Create a <tt>squawk_info_for</tt> view helper</a>
+					<a href="#_add_a_helper">Add a helper</a>
 					</li>
 					<li>
 					<a href="#_add_a_custom_route">Add a Custom Route</a>
@@ -1330,79 +1330,56 @@ http://www.gnu.org/software/src-highlite -->
 </tt></pre></div></div>

 <div class="para"><p>Now your test should be passing, and you should be able to use the Woodpeckers controller in your app.  If you add a route for the woodpeckers controller you can start up your server and go to <a href="http://localhost:3000/woodpeckers">http://localhost:3000/woodpeckers</a> to see your controller in action.</p></div>

 </div>

-<h2 id="_create_a_tt_squawk_info_for_tt_view_helper">8. Create a <tt>squawk_info_for</tt> view helper</h2>

+<h2 id="_add_a_helper">8. Add a helper</h2>

 <div class="sectionbody">

-<div class="para"><p>Creating a view helper is a 3-step process:</p></div>

-<div class="ilist"><ul>

-<li>

-<p>

-Add an appropriately named file to the <em>lib</em> directory.

-</p>

-</li>

-<li>

-<p>

-Require the file and hooks in <em>init.rb</em>.

-</p>

-</li>

-<li>

-<p>

-Write the tests.

-</p>

-</li>

-</ul></div>

-<div class="para"><p>First, create the test to define the functionality you want:</p></div>

-<div class="para"><p><strong>vendor/plugins/yaffle/test/view_helpers_test.rb</strong></p></div>

+<div class="para"><p>This section describes how to add a helper named <em>WoodpeckersHelper</em> to your plugin that will behave the same as a helper in your main app.  This is very similar to adding a model and a controller.</p></div>

+<div class="para"><p>You can test your plugin's helper as you would test any other helper:</p></div>

+<div class="para"><p><strong>vendor/plugins/yaffle/test/woodpeckers_helper_test.rb</strong></p></div>

 <div class="listingblock">

 <div class="content"><!-- Generator: GNU source-highlight 2.9

 by Lorenzo Bettini

 http://www.lorenzobettini.it

 http://www.gnu.org/software/src-highlite -->

 <pre><tt><span style="font-weight: bold"><span style="color: #000080">require</span></span> File<span style="color: #990000">.</span>dirname<span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">__FILE__</span></span><span style="color: #990000">)</span> <span style="color: #990000">+</span> <span style="color: #FF0000">'/test_helper.rb'</span>

-<span style="font-weight: bold"><span style="color: #0000FF">include</span></span> YaffleViewHelper

+<span style="font-weight: bold"><span style="color: #0000FF">include</span></span> WoodpeckersHelper

 

-<span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ViewHelpersTest <span style="color: #990000">&lt;</span> Test<span style="color: #990000">::</span>Unit<span style="color: #990000">::</span>TestCase

-  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> test_squawk_info_for_should_return_the_text_and_date

-    time <span style="color: #990000">=</span> Time<span style="color: #990000">.</span>now

-    hickwall <span style="color: #990000">=</span> Hickwall<span style="color: #990000">.</span>new

-    hickwall<span style="color: #990000">.</span>last_squawk <span style="color: #990000">=</span> <span style="color: #FF0000">"Hello World"</span>

-    hickwall<span style="color: #990000">.</span>last_squawked_at <span style="color: #990000">=</span> time

-    assert_equal <span style="color: #FF0000">"Hello World, #{time.to_s}"</span><span style="color: #990000">,</span> squawk_info_for<span style="color: #990000">(</span>hickwall<span style="color: #990000">)</span>

+<span style="font-weight: bold"><span style="color: #0000FF">class</span></span> WoodpeckersHelperTest <span style="color: #990000">&lt;</span> Test<span style="color: #990000">::</span>Unit<span style="color: #990000">::</span>TestCase

+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> test_tweet

+    assert_equal <span style="color: #FF0000">"Tweet! Hello"</span><span style="color: #990000">,</span> tweet<span style="color: #990000">(</span><span style="color: #FF0000">"Hello"</span><span style="color: #990000">)</span>

   <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

 </tt></pre></div></div>

-<div class="para"><p>Then add the following statements to init.rb:</p></div>

-<div class="para"><p><strong>vendor/plugins/yaffle/init.rb</strong></p></div>

+<div class="para"><p>This is just a simple test to make sure the helper is being loaded correctly.  After watching it fail with <tt>rake</tt>, you can make it pass like so:</p></div>

+<div class="para"><p><strong>vendor/plugins/yaffle/lib/yaffle.rb:</strong></p></div>

 <div class="listingblock">

 <div class="content"><!-- Generator: GNU source-highlight 2.9

 by Lorenzo Bettini

 http://www.lorenzobettini.it

 http://www.gnu.org/software/src-highlite -->

-<pre><tt><span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">"view_helpers"</span>

-ActionView<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>send <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span><span style="color: #990000">,</span> YaffleViewHelper

+<pre><tt><span style="color: #990000">%</span>w<span style="color: #FF0000">{</span> models controllers helpers <span style="color: #FF0000">}</span><span style="color: #990000">.</span>each <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>dir<span style="color: #990000">|</span>

+  path <span style="color: #990000">=</span> File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>File<span style="color: #990000">.</span>dirname<span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">__FILE__</span></span><span style="color: #990000">),</span> <span style="color: #FF0000">'app'</span><span style="color: #990000">,</span> dir<span style="color: #990000">)</span>

+  <span style="color: #009900">$LOAD_PATH</span> <span style="color: #990000">&lt;&lt;</span> path

+  ActiveSupport<span style="color: #990000">::</span>Dependencies<span style="color: #990000">.</span>load_paths <span style="color: #990000">&lt;&lt;</span> path

+  ActiveSupport<span style="color: #990000">::</span>Dependencies<span style="color: #990000">.</span>load_once_paths<span style="color: #990000">.</span>delete<span style="color: #990000">(</span>path<span style="color: #990000">)</span>

+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

+

+ActionView<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>send <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span><span style="color: #990000">,</span> WoodpeckersHelper

 </tt></pre></div></div>

-<div class="para"><p>Then add the view helpers file and</p></div>

-<div class="para"><p><strong>vendor/plugins/yaffle/lib/view_helpers.rb</strong></p></div>

+<div class="para"><p><strong>vendor/plugins/yaffle/lib/app/helpers/woodpeckers_helper.rb:</strong></p></div>

 <div class="listingblock">

 <div class="content"><!-- Generator: GNU source-highlight 2.9

 by Lorenzo Bettini

 http://www.lorenzobettini.it

 http://www.gnu.org/software/src-highlite -->

-<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">module</span></span> YaffleViewHelper

-  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> squawk_info_for<span style="color: #990000">(</span>yaffle<span style="color: #990000">)</span>

-    returning <span style="color: #FF0000">""</span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>result<span style="color: #990000">|</span>

-      result <span style="color: #990000">&lt;&lt;</span> yaffle<span style="color: #990000">.</span>read_attribute<span style="color: #990000">(</span>yaffle<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #0000FF">class</span></span><span style="color: #990000">.</span>yaffle_text_field<span style="color: #990000">)</span>

-      result <span style="color: #990000">&lt;&lt;</span> <span style="color: #FF0000">", "</span>

-      result <span style="color: #990000">&lt;&lt;</span> yaffle<span style="color: #990000">.</span>read_attribute<span style="color: #990000">(</span>yaffle<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #0000FF">class</span></span><span style="color: #990000">.</span>yaffle_date_field<span style="color: #990000">).</span>to_s

-    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">module</span></span> WoodpeckersHelper

+

+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> tweet<span style="color: #990000">(</span>text<span style="color: #990000">)</span>

+    <span style="color: #FF0000">"Tweet! #{text}"</span>

   <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

+

 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

 </tt></pre></div></div>

-<div class="para"><p>You can also test this in script/console by using the <tt>helper</tt> method:</p></div>

-<div class="listingblock">

-<div class="content">

-<pre><tt>$ ./script/console

-&gt;&gt; helper.squawk_info_for(@some_yaffle_instance)</tt></pre>

-</div></div>

+<div class="para"><p>Now your test should be passing, and you should be able to use the Woodpeckers helper in your app.</p></div>

 </div>

 <h2 id="_add_a_custom_route">9. Add a Custom Route</h2>

 <div class="sectionbody">

diff --git a/railties/doc/guides/source/creating_plugins/helpers.txt b/railties/doc/guides/source/creating_plugins/helpers.txt
new file mode 100644
index 0000000000..51b4cebb01
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/helpers.txt
@@ -0,0 +1,51 @@
+== Add a helper ==
+
+This section describes how to add a helper named 'WoodpeckersHelper' to your plugin that will behave the same as a helper in your main app.  This is very similar to adding a model and a controller.
+
+You can test your plugin's helper as you would test any other helper:
+
+*vendor/plugins/yaffle/test/woodpeckers_helper_test.rb*
+
+[source, ruby]
+---------------------------------------------------------------
+require File.dirname(__FILE__) + '/test_helper.rb'
+include WoodpeckersHelper
+
+class WoodpeckersHelperTest < Test::Unit::TestCase
+  def test_tweet
+    assert_equal "Tweet! Hello", tweet("Hello")
+  end
+end
+---------------------------------------------------------------
+
+This is just a simple test to make sure the helper is being loaded correctly.  After watching it fail with `rake`, you can make it pass like so:
+
+*vendor/plugins/yaffle/lib/yaffle.rb:*
+
+[source, ruby]
+----------------------------------------------
+%w{ models controllers helpers }.each do |dir|
+  path = File.join(File.dirname(__FILE__), 'app', dir)
+  $LOAD_PATH << path
+  ActiveSupport::Dependencies.load_paths << path
+  ActiveSupport::Dependencies.load_once_paths.delete(path)
+end
+
+ActionView::Base.send :include, WoodpeckersHelper
+----------------------------------------------
+
+
+*vendor/plugins/yaffle/lib/app/helpers/woodpeckers_helper.rb:*
+
+[source, ruby]
+----------------------------------------------
+module WoodpeckersHelper
+  
+  def tweet(text)
+    "Tweet! #{text}"
+  end
+  
+end
+----------------------------------------------
+
+Now your test should be passing, and you should be able to use the Woodpeckers helper in your app.
diff --git a/railties/doc/guides/source/creating_plugins/index.txt b/railties/doc/guides/source/creating_plugins/index.txt
index 67e6aec39c..19484e2830 100644
--- a/railties/doc/guides/source/creating_plugins/index.txt
+++ b/railties/doc/guides/source/creating_plugins/index.txt
@@ -43,7 +43,7 @@ include::models.txt[]
 
 include::controllers.txt[]
 
-include::view_helper.txt[]
+include::helpers.txt[]
 
 include::custom_route.txt[]
 
diff --git a/railties/doc/guides/source/creating_plugins/view_helper.txt b/railties/doc/guides/source/creating_plugins/view_helper.txt
deleted file mode 100644
index 4eaec93824..0000000000
--- a/railties/doc/guides/source/creating_plugins/view_helper.txt
+++ /dev/null
@@ -1,61 +0,0 @@
-== Create a `squawk_info_for` view helper ==
-
-Creating a view helper is a 3-step process:
-
- * Add an appropriately named file to the 'lib' directory.
- * Require the file and hooks in 'init.rb'.
- * Write the tests.
-
-First, create the test to define the functionality you want:
-
-*vendor/plugins/yaffle/test/view_helpers_test.rb*
-
-[source, ruby]
----------------------------------------------------------------
-require File.dirname(__FILE__) + '/test_helper.rb'
-include YaffleViewHelper
-
-class ViewHelpersTest < Test::Unit::TestCase
-  def test_squawk_info_for_should_return_the_text_and_date
-    time = Time.now
-    hickwall = Hickwall.new
-    hickwall.last_squawk = "Hello World"
-    hickwall.last_squawked_at = time
-    assert_equal "Hello World, #{time.to_s}", squawk_info_for(hickwall)
-  end
-end
----------------------------------------------------------------
-
-Then add the following statements to init.rb:
-
-*vendor/plugins/yaffle/init.rb*
-
-[source, ruby]
----------------------------------------------------------------
-require "view_helpers"
-ActionView::Base.send :include, YaffleViewHelper
----------------------------------------------------------------
-
-Then add the view helpers file and
-
-*vendor/plugins/yaffle/lib/view_helpers.rb*
-
-[source, ruby]
----------------------------------------------------------------
-module YaffleViewHelper
-  def squawk_info_for(yaffle)
-    returning "" do |result|
-      result << yaffle.read_attribute(yaffle.class.yaffle_text_field)
-      result << ", "
-      result << yaffle.read_attribute(yaffle.class.yaffle_date_field).to_s
-    end
-  end
-end
----------------------------------------------------------------
-
-You can also test this in script/console by using the `helper` method:
-
----------------------------------------------------------------
-$ ./script/console
->> helper.squawk_info_for(@some_yaffle_instance)
----------------------------------------------------------------