navigation_builder 1.0.0.beta1 → 1.0.0.beta2

data/README.md

@@ -1,7 +1,115 @@
 Navigation Builder
 ==================
 
+While at [RailsConf](http://www.railsconf.com) in the Spring/Summer of 2011, [Bruce Williams](http://github.com/bruce) mentioned a gem he wrote called ["Goose"](http://github.com/bruce/goose) that made generating navigation really easy. After looking through the code, I immediately thought of some tweaks that I wanted to make.
 
+Rather than dealing with forks and pull requests, I just decided to spin off my own implementation from scratch, modeling the API after ActionView's FormBuilder.
+
+#### That's great, let me see some code. ####
+
+    <% navigation_for :main do |nav| %>
+      <%= nav.link_to 'Home', '#' %>
+    <% end %>
+
+Generates:
+
+    <ul>
+      <li>
+        <a href="#">Home</a>
+      </li>
+    </ul>
+
+#### How do you mark a link as selected? ####
+
+    <% navigation_select 'Home' %>
+
+Make sure that is called *before* the navigation is rendered in the view.
+
+That will generate:
+
+    <ul>
+      <li class="selected">
+        <a href="#">Home</a>
+      </li>
+    </ul>
+
+#### I don't want to use the class "selected". I'd rather use "current-page" ####
+
+    <% navigation_for :main, :selected_class => "current-page" do |nav| %>
+      <%= nav.link_to 'Home', '#' %>
+    <% end %>
+
+#### But my links need additional HTML! ####
+
+NavigationBuilder supports the same options that the `link_to` helper does:
+
+    <% navigation_for :sub_nav do |nav| %>
+      <% nav.link_to '#' do %>
+        <em>Home</em>
+        <span>Go to your home! Are you too good for your home?!</span>
+      <% end %>
+    <% end %>
+
+#### Doesn't that mean that I need to repeat the entire `link_to` block when marking a link as selected? ####
+
+Not at all, just use a regular expression:
+
+    <% navigation_select /Home/ %>
+
+#### But what if I have multiple blocks of navigation on the page? ####
+
+    <% navigation_select 'Home', :in => :sub_nav %>
+
+And in your layout:
+
+    <% navigation_for :sub_nav do |nav| %>
+      <%= nav.link_to 'Home', '#' %>
+    <% end %>
+
+#### Well... what if I need an Ordered List! ####
+
+    <% navigation_for :main, :wrapper_tag => :ol do |nav| %>
+      <%= nav.link_to 'Home', '#' %>
+    <% end %>
+
+Generates:
+
+    <ol>
+      <li class="selected">
+        <a href="#">Home</a>
+      </li>
+    </ol>
+
+#### Nevermind, I hate lists. I just want DIVs. ####
+
+    <% navigation_for :main, :nav_item_tag => :div do |nav| %>
+      <%= nav.link_to 'Home', '#' %>
+    <% end %>
+
+Generates:
+
+    <div class="selected">
+      <a href="#">Home</a>
+    </div>
+
+#### My designer just said that's DIV-soup. ####
+
+    <% navigation_for :main, :nav_item_tag => false do |nav| %>
+      <%= nav.link_to 'Home', '#' %>
+    <% end %>
+
+Generates:
+
+    <a href="#" class="selected">Home</a>
+
+#### Why didn't you name this Gem "Wolfman" ####
+
+Originally I was going to. But if you came across a method named "wolfman" in your view code, it would not be entirely clear as to what it was going to do.
+So I just went with something boring and generic.
+
+#### Well, you've thought of everything, haven't you! ####
+
+Probably not, let me know if you have any feature requests!
 
 TODOs
 =====

data/VERSION

@@ -1 +1 @@
-1.0.0.beta1
+1.0.0.beta2

data/lib/action_view/helpers/navigation_builder.rb

@@ -3,15 +3,19 @@ module ActionView
 
     module NavigationBuilderHelper
 
+      # Holds references to the currently selected links for each navigation block on the page.
       def navigation_builder
         @navigation_builder ||= { :main => nil }
       end
 
-      # <% navigation_for :popup do |n| %>
-      #   <%= nav_to 'Design', :action => :design %>
-      # <% end %>
-      # 
-      # <%= navigation_select 'Design', :in => :popup %>
+      # Generates a block of navigation to be rendered to the page.
+      #
+      # Example:
+      #   <% navigation_for :popup do |n| %>
+      #     <%= nav_to 'Members', members_path %>
+      #   <% end %>
+      #
+      # Generally speaking, this should go in your layout.
       def navigation_for( nav_name, options = {}, &block )
         raise ArgumentError, "Missing block" unless block_given?
 
@@ -27,11 +31,24 @@ module ActionView
         concat( tag(options[:wrapper_tag], options[:html], true) ) if navigation_has_wrapper?( options )
         yield builder.new(self, nav_name, options, block)
         concat("</#{options[:wrapper_tag]}>".html_safe) if navigation_has_wrapper?( options )
+
+        # Mark the navigation block has having been rendered
+        navigation_builder[nav_name] = true
       end
 
+      # Make sure this is called *before* your navigation is rendered.
+      # Ideally, this should go in your views and navigation_for() should
+      # be in your layout.
+      #
+      # Example:
+      #   <%= navigation_select 'Members', :in => :popup %>
       def navigation_select( link_name, options = {} )
-        options.reverse_merge!( :in => :main )
-        navigation_builder[options[:in]] = link_name
+        if navigation_builder[options[:in]] == true
+          raise RuntimeError, "The #{options[:in]} navigation block has already been rendered. You cannot call navigation_select if navigation_for has already been called."
+        else
+          options.reverse_merge!( :in => :main )
+          navigation_builder[options[:in]] = link_name
+        end
       end
 
     private
@@ -44,21 +61,28 @@ module ActionView
 
     class NavigationBuilder
 
+      # Initializes the NavigationBuilder.
+      # You'll mostly likely never call this method directly.
       def initialize( template, nav_name, options, proc )
         @template, @nav_name, @options, @proc = template, nav_name, options, proc
       end
 
+      # Builds a link_to tag within the context of the current navigation block.
+      # This accepts all of the same parameters that ActiveView's link_to method
+      #
+      # Example:
+      #   <%= nav.link_to 'Home', '#' %>
       def link_to( *args, &link_block )
         if block_given?
           name         = @template.capture(&link_block)
           options      = args.first || {}
-          html_options = args.second
+          html_options = args.second || {}
 
           link_to_in_block( name, options, html_options, &link_block )
         else
           name         = args[0]
           options      = args[1] || {}
-          html_options = args[2]
+          html_options = args[2] || {}
 
           link_to_in_html( name, options, html_options )
         end
@@ -69,7 +93,7 @@ module ActionView
       def link_to_in_block( name, options, html_options, &link_block )
         item_html_options = extract_item_options!( html_options )
 
-        set_selected_link( name, item_html_options ) if is_selected?( name )
+        set_selected_link( name, html_options, item_html_options ) if is_selected?( name )
 
         @template.concat( @template.tag( @options[:nav_item_tag], item_html_options, true) ) if @options[:nav_item_tag]
         @template.link_to(options, html_options, &link_block)
@@ -79,7 +103,7 @@ module ActionView
       def link_to_in_html( name, options, html_options )
         item_html_options = extract_item_options!( html_options )
 
-        set_selected_link( name, item_html_options ) if is_selected?( name )
+        set_selected_link( name, html_options, item_html_options ) if is_selected?( name )
 
         link_html = @template.link_to(name, options, html_options)
 
@@ -94,8 +118,16 @@ module ActionView
         options.try(:delete, :item_html) || {}
       end
 
-      def set_selected_link( name, item_html_options )
-        ((item_html_options[:class] ||= '') << " #{@options[:selected_class]}").strip!
+      def set_selected_link( name, html_options, item_html_options )
+        (selected_tag_options( html_options, item_html_options ) << " #{@options[:selected_class]}").strip!
+      end
+
+      def selected_tag_options( html_options, item_html_options )
+        if @options[:nav_item_tag]
+          item_html_options[:class] ||= ''
+        else
+          html_options[:class] ||= ''
+        end
       end
 
       def is_selected?( name )

data/navigation_builder.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{navigation_builder}
-  s.version = "1.0.0.beta1"
+  s.version = "1.0.0.beta2"
 
   s.required_rubygems_version = Gem::Requirement.new("> 1.3.1") if s.respond_to? :required_rubygems_version=
   s.authors = ["Derek Lindahl"]

data/test/test_navigation_builder.rb

@@ -187,8 +187,19 @@ class TestNavigationBuilder < ActionView::TestCase
     assert_dom_equal expected, output_buffer
   end
 
+  should "generate HTML that highlights the currently selected navigation link even where there is no item tag" do
+    navigation_select 'Foo', :in => :main
+
+    navigation_for :main, :nav_item_tag => false do |nav|
+      concat nav.link_to( 'Foo', '#' )
+    end
 
-# TODO: Add test for "selected" class when there is no item tag
+    expected = [
+      "<a href=\"#\" class=\"selected\">Foo</a>"
+    ].join('')
+
+    assert_dom_equal expected, output_buffer
+  end
 
   should "generate HTML that highlights the currently selected navigation link by using a Regular Expression" do
     navigation_select /Foo/, :in => :main
@@ -211,4 +222,13 @@ class TestNavigationBuilder < ActionView::TestCase
     assert_dom_equal expected, output_buffer
   end
 
+  should "raise an exception if a link is selected AFTER the navigation has been rendered" do
+    assert_raises RuntimeError do
+      navigation_for :main do |nav|
+        concat nav.link_to( 'Foo', '#' )
+      end
+      navigation_select 'Foo', :in => :main
+    end
+  end
+
 end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification 
 name: navigation_builder
 version: !ruby/object:Gem::Version 
-  hash: 62196353
+  hash: 62196359
   prerelease: 6
   segments: 
   - 1
   - 0
   - 0
   - beta
-  - 1
-  version: 1.0.0.beta1
+  - 2
+  version: 1.0.0.beta2
 platform: ruby
 authors: 
 - Derek Lindahl