tiny_navigation 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Coroutine
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,107 @@
+= Tiny Navigation
+
+== Installation
+
+=== As a Plugin
+
+* For Rails 2.x
+    
+    script/generate plugin install git@github.com:coroutine/tiny_navigation.git
+    
+=== As a gem
+
+    gem install tiny_navigation
+
+
+Then, simply call:
+
+    script/generate tiny_navigation
+    
+This will place the tiny_navigation.rb config file into your config directory.
+
+== Usage
+
+TinyNavigation provides an easy-to-use DSL for defining navigation structures;
+these structures are defined in config/tiny_navigation.rb.
+
+=== Here are a few things TinyNavigation WILL do:
+
+* It provides the ability to define and map menu items to resources using the 
+  convention set forth in the Rails 3 router.  For example, to map a menu item 
+  _Foo_ to the <tt>show</tt> action of the <tt>foos_controller</tt> simply do:
+
+    navigation :top_tabs do
+      item "Foo", :to => "foos#show"
+    end
+
+  If one were to omit the specified action from the <tt>:to</tt> option, the
+  navigation item's action would default to <tt>index</tt>.
+
+  The URL generated from this mapping can be accessed via the <tt>url</tt>
+  method of the navigation item.
+
+* It provides a <tt>selected</tt> method for getting the selected menu items of
+  a navigational structure.  For example, for this definition:
+
+    navigation :main do
+      item "Foo", :to => "foos#index"
+      item "Bar", :to => "bars#index" do
+        item "Baz", :to => "bazzs#index"
+      end
+    end
+
+  If the menu item _Foo_ is selected, an array containing that menu item is
+  returned.  However, if the menu item _Baz_ is selected, an array containing
+  the _Bar_ and the _Baz_ menu items.  This is useful for generating bread-crumbs
+  or simply highlighting both the main nav item and its selected sub-nav item.
+  
+* It allows for the declaration of custom attributes on nav items.  For instance,
+  given the configuration in the previous example, we want to right-align the _Bar_
+  navigation item.  To do this we could simply add another option to the item:
+
+    navigation :main do
+      item "Foo", :to => "foos#index", :align => :left
+      item "Bar", :to => "bars#index", :align => :right do
+        item "Baz", :to => "bazzs#index"
+      end
+    end
+
+  Now, when we render the navigation items we can call <tt>align</tt> on
+  the item to get its value:
+
+    navigation(:main).each do |item|
+      if item.align == :right
+        ...
+      end
+    end
+
+* It delegates controller method calls made from within the config file to the 
+  current controller.  For instance, let's say you're using Ryan Bates' fantastic
+  CanCan gem for authorization--which adds a some methods to the controller, namely 
+  the <tt>can?</tt> method--and you want to show or hide navigation items based upon
+  a user's ability.  You can do that!  Check it:
+
+    navigation :main do
+      item("Foo", :to => "foos#index") if can? :read, Foo
+      item "Bar", :to => "bars#index" do
+        item "Baz", :to => "bazzs#index"
+      end
+    end
+
+  *IMPORTANT* if a custom attribute is defined on an item, as mentioned earlier,
+  it will take precedence over a controller attribute of the same name, thus
+  hiding access to the controller attribute.
+
+=== Here are a couple things that TinyNavigation WILL NOT do:
+
+* TinyNavigation makes no attempt at rendering the navigation.  That's up
+  to you.  You may want to render your nav items into <tt>div</tt> tags, while
+  I may want to use an unordered list.  That's fine, go for it.
+
+* TinyNavigation does provide authorization logic for limiting access to
+  navigation items; that's a separate concern.  It's easy enough to use
+  an authorization gem that does that job quite well, and by allowing for calls
+  to the current controller from within config/tiny_navigation.rb, you can
+  do that.
+
+Copyright (c) 2010 Coroutine, released under the MIT license

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the tiny_navigation plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the tiny_navigation plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'TinyNavigation'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name        = "tiny_navigation"
+    gemspec.summary     = "TinyNavigation provides an easy-to-use DSL for defining navigation structures."
+    gemspec.description = "TinyNavigation makes it easy to define site navigation using a small DSL."
+    gemspec.email       = "gems@coroutine.com"
+    gemspec.homepage    = "http://github.com/coroutine/tiny_navigation"
+    gemspec.authors     = ["Coroutine", "Tim Lowrimore"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/generators/tiny_navigation/USAGE

@@ -0,0 +1,5 @@
+Call:
+
+    rails generate tiny_navigation
+    
+to generate the config/tiny_navigation.rb file.

data/generators/tiny_navigation/templates/tiny_navigation.rb

@@ -0,0 +1,11 @@
+# Within this file you'll define your navigation data.
+
+# navigation :main do
+#   # Menu Item
+#   item "Foos", :to => "foos#index"
+#   
+#   # Menu Item with a sub-menu item
+#   item "Bars", :to => "bars#index" do
+#     item "Bazzes", :to => "bazzes#index"
+#   end
+# end

data/generators/tiny_navigation/tiny_navigation_generator.rb

@@ -0,0 +1,7 @@
+class TinyNavigationGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      m.file "tiny_navigation.rb", "config/tiny_navigation.rb"
+    end
+  end
+end

data/init.rb

@@ -0,0 +1,2 @@
+require "tiny_navigation"
+ActionController::Base.class_eval { include Coroutine::TinyNavigation::ControllerMethods }

data/lib/tiny_navigation.rb

@@ -0,0 +1,128 @@
+require 'tiny_navigation/item'
+require 'tiny_navigation/navigation'
+
+module Coroutine
+  
+  # TinyNavigation provides an easy-to-use DSL for defining navigation structures;
+  # these structures are defined in config/tiny_navigation.rb.
+  # 
+  # == Here are a few things TinyNavigation WILL do:
+  # 
+  #   * It provides the ability to define and map menu items to resources using the 
+  #     convention set forth in the Rails 3 router.  For example, to map a menu item 
+  #     _Foo_ to the <tt>show</tt> action of the <tt>foos_controller</tt> simply do:
+  # 
+  #       navigation :top_tabs do
+  #         item "Foo", :to => "foos#show"
+  #       end
+  # 
+  #     If one were to omit the specified action from the <tt>:to</tt> option, the
+  #     navigation item's action would default to <tt>index</tt>.
+  # 
+  #     The URL generated from this mapping can be accessed via the <tt>url</tt>
+  #     method of the navigation item.
+  # 
+  #   * It provides a <tt>selected</tt> method for getting the selected menu items of
+  #     a navigational structure.  For example, for this definition:
+  #
+  #       navigation :main do
+  #         item "Foo", :to => "foos#index"
+  #         item "Bar", :to => "bars#index" do
+  #           item "Baz", :to => "bazzs#index"
+  #         end
+  #       end
+  # 
+  #     If the menu item _Foo_ is selected, an array containing that menu item is
+  #     returned.  However, if the menu item _Baz_ is selected, an array containing
+  #     the _Bar_ and the _Baz_ menu items.  This is useful for generating bread-crumbs
+  #     or simply highlighting both the main nav item and its selected sub-nav item.
+  # 
+  #   * It allows for the declaration of custom attributes on nav items.  For instance,
+  #     given the configuration in the previous example, we want to right-align the _Bar_
+  #     navigation item.  To do this we could simply add another option to the item:
+  # 
+  #       navigation :main do
+  #         item "Foo", :to => "foos#index", :align => :left
+  #         item "Bar", :to => "bars#index", :align => :right do
+  #           item "Baz", :to => "bazzs#index"
+  #         end
+  #       end
+  # 
+  #     Now, when we render the navigation items we can call <tt>right_align</tt> on
+  #     the item to get its value:
+  # 
+  #       navigation(:main).each do |item|
+  #         if item.align == :right
+  #           ...
+  #         end
+  #       end
+  #
+  #   * It delegates controller method calls made from within the config file to the 
+  #     current controller.  For instance, let's say you're using Ryan Bates' fantastic
+  #     CanCan gem for authorization--which adds a some methods to the controller, namely 
+  #     the <tt>can?</tt> method--and you want to show or hide navigation items based upon
+  #     a user's ability.  You can do that!  Check it:
+  # 
+  #       navigation :main do
+  #         item("Foo", :to => "foos#index") if can? :read, Foo
+  #         item "Bar", :to => "bars#index" do
+  #           item "Baz", :to => "bazzs#index"
+  #         end
+  #       end
+  # 
+  #     *IMPORTANT* if a custom attribute is defined on an item, as mentioned earlier,
+  #     it will take precedence over a controller attribute of the same name, thus
+  #     hiding access to the controller attribute.
+  # 
+  # == Here are a couple things that TinyNavigation WILL NOT do:
+  # 
+  #   * TinyNavigation makes no attempt at rendering the navigation.  That's up
+  #     to you.  You may want to render your nav items into <tt>div</tt> tags, while
+  #     I may want to use an unordered list.  That's fine, go for it.
+  # 
+  #   * TinyNavigation does provide authorization logic for limiting access to
+  #     navigation items; that's a separate concern.  It's easy enough to use
+  #     an authorization gem that does that job quite well, and by allowing for calls
+  #     to the current controller from within config/tiny_navigation.rb you can
+  #     do that.
+  module TinyNavigation
+    class Config #:nodoc:
+      
+      attr_reader :nav
+      
+      def initialize(current_controller, conf=File.join(Rails.root, "config", "tiny_navigation.rb"))
+        @current_controller = current_controller
+        @nav = {}
+        
+        # Make sure we only load the config file the first time the navigation is loaded
+        # and never again.
+        Config.class_eval { class << self; attr_reader :file end; @file ||= File.read(conf) }
+        self.instance_eval(Config.file);
+      end
+      
+      private
+      
+      def navigation(name, &block)
+        raise "Navigation names must be unique.  You specified '#{name}' twice." if @nav.has_key?(name)
+        @nav[name] = Navigation.new(name, @current_controller, &block)
+      end
+    end
+    
+    # This module adds the navigation method to ActionController::Base and makes
+    # the method available as a helper.
+    module ControllerMethods
+      def self.included(base) #:nodoc:
+        base.send :helper_method, :navigation
+      end
+      
+      private
+      
+      # Returns a Coroutine::TinyNavigation::Navigation object for the supplied
+      # navigation name.
+      def navigation(which_navigation)
+        config = Coroutine::TinyNavigation::Config.new self
+        config.nav[which_navigation]
+      end
+    end
+  end
+end

data/lib/tiny_navigation/item.rb

@@ -0,0 +1,66 @@
+require 'tiny_navigation/navigation'
+
+module Coroutine
+  module TinyNavigation
+    class Item < Navigation
+      
+      # Creates a new instance of a navigation item.
+      # 
+      # <tt>name</tt> is the name of the navigation item.  The name should
+      # be used for the label text when rendering the navigation item.
+      # 
+      # <tt>current_controller</tt> the currently loaded controller
+      #
+      # <tt>options</tt> provide configuration options and custom properties
+      # to the nav item.  Currently, the only configuration option is
+      # <tt>:to</tt> which is used to generate the URL of the navigation item.
+      # All other options provided to via the <tt>options</tt> hash will be
+      # treated as custom properties on the navigation item.  These custom
+      # properties can be accessed as methods on the navigation item.
+      # 
+      # The block given to the navigation item is used to define sub-navigation
+      # items of this item.
+      def initialize(name, current_controller, options={}, &block)
+        super name, current_controller, &block
+        set_controller_and_action options.delete(:to)
+        @extra_options = options
+      end
+      
+      # Indicates whether the navigation item is currently selected.  This
+      # takes into account any sub-nav items such that a parent item is selected
+      # if it has a selected child.
+      def selected?
+        @controller_name == @current_controller.controller_name || @items.any?(&:selected?)
+      end
+      
+      # Returns the URL to which the navigation item points.  This should be
+      # used in a scenario where the navigation item represents a link and the
+      # URL is the href of that link.
+      def url
+        @current_controller.url_for :controller => @controller_name, :action => @action_name
+      end
+      
+      def method_missing(method_name, *args) #:nodoc:
+        
+        # The extra_options hash takes precendence when looking for the
+        # called method.  Otherwise, we'll let the super-class forward
+        # the method call to the current controller.
+        if @extra_options.has_key? method_name
+          @extra_options[method_name]
+        else
+          super method_name, *args
+        end
+      end
+      
+      private
+      
+      def set_controller_and_action(to)
+        if to
+          controller_and_action = to.split "#"
+          @controller_name      = controller_and_action.shift
+          @action_name          = controller_and_action.shift || "index"
+        end
+      end
+    end
+  end
+end

data/lib/tiny_navigation/navigation.rb

@@ -0,0 +1,47 @@
+module Coroutine
+  module TinyNavigation
+    class Navigation
+      
+      attr_reader :name, :items
+      
+      # Creates a new navigation.
+      # 
+      # <tt>name</tt> is the unique identifer of the navigation.
+      # 
+      # <tt>current_controller</tt> the currently loaded controller
+      # 
+      # The block given to the navigation item is used to define navigation
+      # items of this navigation object.
+      def initialize(name, current_controller, &block)
+        @items                    = []
+        @name                     = name
+        @current_controller     = current_controller
+        
+        self.instance_eval(&block) if block_given?
+      end
+      
+      # Returns an array of selected navigation items.  The array represents a
+      # bread-crumb list in that the head of the list represents a top-level
+      # navigation item, and the tail of the list represents selected sub-navigation
+      # items.
+      def selected(item=self)
+        items = []
+        item.items.each do |item|
+          items << item << selected(item) if item.selected?
+        end
+        items.flatten
+      end
+      
+      def method_missing(method_name, *args) #:nodoc:
+        @current_controller.send method_name, *args
+      end
+      
+      private
+      
+      def item(name, options={}, &block)
+        @items << Item.new(name, @current_controller, options, &block)
+      end
+      
+    end
+  end
+end

data/simple_navigation.gemspec

@@ -0,0 +1,54 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{tiny_navigation}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Coroutine", "Tim Lowrimore"]
+  s.date = %q{2010-05-13}
+  s.description = %q{TinyNavigation makes it easy to define site navigation using a small DSL.}
+  s.email = %q{gems@coroutine.com}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    "MIT-LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "generators/tiny_navigation/USAGE",
+     "generators/tiny_navigation/tiny_navigation_generator.rb",
+     "generators/tiny_navigation/templates/tiny_navigation.rb",
+     "init.rb",
+     "lib/tiny_navigation.rb",
+     "lib/tiny_navigation/item.rb",
+     "lib/tiny_navigation/navigation.rb",
+     "test/navigation_test.rb",
+     "test/test_helper.rb",
+     "uninstall.rb"
+  ]
+  s.homepage = %q{http://github.com/coroutine/tiny_navigation}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{TinyNavigation provides an easy-to-use DSL for defining navigation structures.}
+  s.test_files = [
+    "test/navigation_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/test/navigation_test.rb

@@ -0,0 +1,49 @@
+require 'test_helper'
+require 'tiny_navigation/navigation'
+require 'tiny_navigation/item'
+
+class NavigationTest < ActiveSupport::TestCase
+  
+  def setup
+    @controller_class     = Struct.new(:controller_name)
+    @current_controller   = @controller_class.new("tests")
+  end
+  
+  test "can create a navigation with an item" do
+    nav = navigation do
+      item "Foos", :to => "foos#index"
+    end
+    
+    assert_equal nav.items.length, 1
+  end
+  
+  test "has correct selected item in one level of nesting" do
+    nav = navigation do
+      item "Tests", :to => "tests"
+    end
+    
+    assert_equal nav.selected.length, 1
+    assert_equal nav.selected.first.name, "Tests"
+  end
+  
+  test "has correct selected items in multiple levels of nesting" do
+    nav = navigation do
+      item "Foos", :to => "foos#index" do
+        item "Tests", :to => "tests#index"
+      end
+    end
+    
+    assert_equal nav.selected.length, 2
+    assert_equal nav.selected.map(&:name), ["Foos", "Tests"]
+  end
+  
+  # ------------------------------------------------------------------------------
+  # Helpers
+  # ------------------------------------------------------------------------------
+  
+  private
+  
+  def navigation(name = :main, current_controller = @current_controller, &block)
+    Coroutine::TinyNavigation::Navigation.new(name, current_controller, &block)
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'test/unit'
+require 'active_support'

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification 
+name: tiny_navigation
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Coroutine
+- Tim Lowrimore
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-13 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: TinyNavigation makes it easy to define site navigation using a small DSL.
+email: gems@coroutine.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- generators/tiny_navigation/USAGE
+- generators/tiny_navigation/templates/tiny_navigation.rb
+- generators/tiny_navigation/tiny_navigation_generator.rb
+- init.rb
+- lib/tiny_navigation.rb
+- lib/tiny_navigation/item.rb
+- lib/tiny_navigation/navigation.rb
+- pkg/simple_navigation-0.1.0.gem
+- simple_navigation.gemspec
+- test/navigation_test.rb
+- test/test_helper.rb
+- uninstall.rb
+has_rdoc: true
+homepage: http://github.com/coroutine/tiny_navigation
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: TinyNavigation provides an easy-to-use DSL for defining navigation structures.
+test_files: 
+- test/navigation_test.rb
+- test/test_helper.rb