Added TextHelper#current_cycle to return the current cycle for better design options.

[#417 state:resolved]

Signed-off-by: Jeremy Kemper <jeremy@bitsweat.net>

3 files changed, 76 insertions, 3 deletions

diff --git a/actionpack/CHANGELOG b/actionpack/CHANGELOG
index be490093ac..f6942b43f1 100644
--- a/actionpack/CHANGELOG
+++ b/actionpack/CHANGELOG
@@ -1,5 +1,7 @@
 *Edge*
 
+* Introduce current_cycle helper method to return the current value without bumping the cycle.  #417 [Ken Collins]
+
 * Allow polymorphic_url helper to take url options. #880 [Tarmo Tänav]
 
 * Switched integration test runner to use Rack processor instead of CGI [Josh Peek]
diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb
index ccd6c54cc8..a5d43b90f4 100644
--- a/actionpack/lib/action_view/helpers/text_helper.rb
+++ b/actionpack/lib/action_view/helpers/text_helper.rb
@@ -448,8 +448,10 @@ module ActionView
       # array every time it is called. This can be used for example, to alternate
       # classes for table rows.  You can use named cycles to allow nesting in loops.
       # Passing a Hash as the last parameter with a <tt>:name</tt> key will create a
-      # named cycle.  You can manually reset a cycle by calling reset_cycle and passing the
-      # name of the cycle.
+      # named cycle. The default name for a cycle without a +:name+ key is
+      # <tt>"default"</tt>. You can manually reset a cycle by calling reset_cycle
+      # and passing the name of the cycle. The current cycle string can be obtained
+      # anytime using the current_cycle method.
       #
       # ==== Examples
       #   # Alternate CSS classes for even and odd numbers...
@@ -496,6 +498,23 @@ module ActionView
         return cycle.to_s
       end
 
+      # Returns the current cycle string after a cycle has been started. Useful
+      # for complex table highlighing or any other design need which requires
+      # the current cycle string in more than one place.
+      #
+      # ==== Example
+      #   # Alternate background colors
+      #   @items = [1,2,3,4]
+      #   <% @items.each do |item| %>
+      #     <div style="background-color:<%= cycle("red","white","blue") %>">
+      #       <span style="background-color:<%= current_cycle %><%= item %></span>
+      #     </div>
+      #   <% end %>
+      def current_cycle(name = "default")
+        cycle = get_cycle(name)
+        cycle.current_value unless cycle.nil?
+      end
+
       # Resets a cycle so that it starts from the first element the next time
       # it is called. Pass in +name+ to reset a named cycle.
       #
@@ -532,11 +551,29 @@ module ActionView
           @index = 0
         end
 
+        def current_value
+          @values[previous_index].to_s
+        end
+
         def to_s
           value = @values[@index].to_s
-          @index = (@index + 1) % @values.size
+          @index = next_index
           return value
         end
+
+        private
+
+        def next_index
+          step_index(1)
+        end
+
+        def previous_index
+          step_index(-1)
+        end
+
+        def step_index(n)
+          (@index + n) % @values.size
+        end
       end
 
       private
diff --git a/actionpack/test/template/text_helper_test.rb b/actionpack/test/template/text_helper_test.rb
index a31d532567..5f9f715819 100644
--- a/actionpack/test/template/text_helper_test.rb
+++ b/actionpack/test/template/text_helper_test.rb
@@ -369,6 +369,40 @@ class TextHelperTest < ActionView::TestCase
     assert_equal("red", cycle("red", "blue", :name => "colors"))
   end
 
+  def test_current_cycle_with_default_name
+    cycle("even","odd")
+    assert_equal "even", current_cycle
+    cycle("even","odd")
+    assert_equal "odd", current_cycle
+    cycle("even","odd")
+    assert_equal "even", current_cycle
+  end
+
+  def test_current_cycle_with_named_cycles
+    cycle("red", "blue", :name => "colors")
+    assert_equal "red", current_cycle("colors")
+    cycle("red", "blue", :name => "colors")
+    assert_equal "blue", current_cycle("colors")
+    cycle("red", "blue", :name => "colors")
+    assert_equal "red", current_cycle("colors")
+  end
+
+  def test_current_cycle_safe_call
+    assert_nothing_raised { current_cycle }
+    assert_nothing_raised { current_cycle("colors") }
+  end
+
+  def test_current_cycle_with_more_than_two_names
+    cycle(1,2,3)
+    assert_equal "1", current_cycle
+    cycle(1,2,3)
+    assert_equal "2", current_cycle
+    cycle(1,2,3)
+    assert_equal "3", current_cycle
+    cycle(1,2,3)
+    assert_equal "1", current_cycle
+  end
+
   def test_default_named_cycle
     assert_equal("1", cycle(1, 2, 3))
     assert_equal("2", cycle(1, 2, 3, :name => "default"))