simple-navigation-ext 0.0.1

data/lib/simple_navigation/core/item.rb

@@ -0,0 +1,117 @@
+require 'ruby-debug'
+
+module SimpleNavigation
+
+  # Represents an item in your navigation. Gets generated by the item method in the config-file.
+  class Item
+    attr_reader :key, :name, :url, :sub_navigation, :method, :highlights_on, :exclude_highlighting
+    attr_writer :html_options
+
+    # see ItemContainer#item
+    #
+    # The subnavigation (if any) is either provided by a block or passed in directly as <tt>items</tt>
+    def initialize(container, key, name, url, options, items=nil, &sub_nav_block)
+      @container = container
+      @container.dom_class = options.delete(:container_class) if options[:container_class]
+      @container.dom_id = options.delete(:container_id) if options[:container_id]
+      @key = key
+      @method = options.delete(:method)
+      @name = name
+      @url = url.instance_of?(Proc) ? url.call : url
+      @highlights_on = options.delete(:highlights_on)
+      @exclude_highlighting = options.delete(:exclude_highlight_if)
+      @html_options = options
+      if sub_nav_block || items
+        @sub_navigation = ItemContainer.new(@container.level + 1)
+        sub_nav_block.call @sub_navigation if sub_nav_block
+        @sub_navigation.items = items if items
+      end
+    end
+
+    # Returns true if this navigation item should be rendered as 'selected'.
+    # An item is selected if
+    #
+    # * it has been explicitly selected in a controller or
+    # * it has a subnavigation and one of its subnavigation items is selected or
+    # * its url matches the url of the current request (auto highlighting)
+    #
+    def selected?
+      @selected = (@selected || selected_by_config? || selected_by_subnav? || selected_by_url?)
+    end
+
+    # Returns the html-options hash for the item, i.e. the options specified for this item in the config-file.
+    # It also adds the 'selected' class to the list of classes if necessary.
+    def html_options
+      default_options = self.autogenerate_item_ids? ? {:id => autogenerated_item_id} : {}
+      options = default_options.merge(@html_options)
+      options[:class] = [@html_options[:class], self.selected_class].flatten.compact.join(' ')
+      options.delete(:class) if options[:class].nil? || options[:class] == ''
+      options
+    end
+    
+    def item_excluded
+      if exclude_highlighting
+        raise ArgumentError, ':exclude_highlight_if must be a regexp' unless exclude_highlighting.instance_of?(Regexp)
+        SimpleNavigation.request_uri =~ exclude_highlighting
+      end
+    end
+
+    # Returns the configured selected_class if the item is selected, nil otherwise
+    def selected_class
+      if selected?
+        self.item_excluded ? nil : SimpleNavigation.config.selected_class
+        # SimpleNavigation.config.selected_class
+      else
+        nil
+      end
+    end
+
+    protected
+
+    # Returns true if item has a subnavigation and the sub_navigation is selected
+    def selected_by_subnav?
+      sub_navigation && sub_navigation.selected?
+    end
+
+    def selected_by_config?
+      false
+    end
+
+    # Returns true if the item's url matches the request's current url.
+    def selected_by_url?
+      if highlights_on
+        raise ArgumentError, ':highlights_on must be a regexp' unless highlights_on.instance_of?(Regexp)
+        SimpleNavigation.request_uri =~ highlights_on
+      elsif auto_highlight?
+        !!(root_path_match? || SimpleNavigation.current_page?(url_without_anchor))
+      else
+        false
+      end
+    end
+
+    # Returns true if both the item's url and the request's url are root_path
+    def root_path_match?
+      url == '/' && SimpleNavigation.request_path == '/'
+    end
+
+    # Returns true if the item's id should be added to the rendered output.
+    def autogenerate_item_ids?
+      SimpleNavigation.config.autogenerate_item_ids
+    end
+
+    # Returns the item's id which is added to the rendered output.
+    def autogenerated_item_id
+      SimpleNavigation.config.id_generator.call(key)
+    end
+
+    # Return true if auto_highlight is on for this item.
+    def auto_highlight?
+      SimpleNavigation.config.auto_highlight && @container.auto_highlight
+    end
+
+    def url_without_anchor
+      url.split('#').first  
+    end
+
+  end
+end

data/lib/simple_navigation/core/item_adapter.rb

@@ -0,0 +1,63 @@
+require 'forwardable'
+
+module SimpleNavigation
+
+  # This class acts as an adapter to items that are not defined using the DSL in the config/navigation.rb, but directly provided inside the application.
+  # When defining the items that way, every item you provide needs to define the following methods:
+  #
+  # * <tt>key</tt>
+  # * <tt>name</tt>
+  # * <tt>url</tt>
+  #
+  # and optionally
+  #
+  # * <tt>options</tt>
+  # * <tt>items</tt> - if one of your items has a subnavigation it must respond to <tt>items</tt> providing the subnavigation.
+  #
+  # You can also specify your items as a list of hashes. The hashes will be converted to objects automatically.
+  # The hashes representing the items obviously must have the keys :key, :name and :url and optionally the keys :options and :items.
+  #
+  # See SimpleNavigation::ItemContainer#item for the purpose of these methods.
+  class ItemAdapter
+    extend Forwardable
+    
+    def_delegators :item, :key, :name, :url
+
+    attr_reader :item
+
+    def initialize(item)
+      @item = item.instance_of?(Hash) ? to_object(item) : item
+    end
+
+    # Returns the options for this item. If the wrapped item does not implement an options method, an empty hash is returned.
+    def options
+      @item.respond_to?(:options) ? @item.options : {}
+    end
+
+    # Returns the items (subnavigation) for this item if it responds to :items and the items-collection is not empty. Returns nil otherwise.
+    def items
+      (@item.respond_to?(:items) && !(@item.items.nil? || @item.items.empty?)) ? @item.items : nil
+    end
+
+    # Converts this Item into a SimpleNavigation::Item
+    def to_simple_navigation_item(item_container)
+      SimpleNavigation::Item.new(item_container, key, name, url, options, items)
+    end
+
+    protected
+    
+    # Converts the specified hash into an object. Each key will be added as method.
+    #
+    def to_object(hash)
+      mod = Module.new do
+        hash.each_pair do |key, value|
+          define_method key do
+            value
+          end
+        end
+      end
+      Object.new.extend(mod)
+    end
+
+  end
+end

data/lib/simple_navigation/core/item_container.rb

@@ -0,0 +1,146 @@
+module SimpleNavigation
+
+  # Holds the Items for a navigation 'level'.
+  class ItemContainer
+
+    attr_reader :items, :level
+    attr_accessor :renderer, :dom_id, :dom_class, :auto_highlight
+
+    def initialize(level=1) #:nodoc:
+      @level = level
+      @items = []
+      @renderer = SimpleNavigation.config.renderer
+      @auto_highlight = true
+    end
+
+    # Creates a new navigation item.
+    #
+    # The <tt>key</tt> is a symbol which uniquely defines your navigation item in the scope of the primary_navigation or the sub_navigation.
+    #
+    # The <tt>name</tt> will be displayed in the rendered navigation. This can also be a call to your I18n-framework.
+    #
+    # The <tt>url</tt> is the address that the generated item points to. You can also use url_helpers (named routes, restful routes helper, url_for etc.)
+    #
+    # The <tt>options</tt> can be used to specify the following things:
+    # * <tt>any html_attributes</tt> - will be included in the rendered navigation item (e.g. id, class etc.)
+    # * <tt>:if</tt> - Specifies a proc to call to determine if the item should
+    #   be rendered (e.g. <tt>:if => Proc.new { current_user.admin? }</tt>). The
+    #   proc should evaluate to a true or false value and is evaluated in the context of the view.
+    # * <tt>:unless</tt> - Specifies a proc to call to determine if the item should not
+    #   be rendered (e.g. <tt>:unless => Proc.new { current_user.admin? }</tt>). The
+    #   proc should evaluate to a true or false value and is evaluated in the context of the view.
+    # * <tt>:method</tt> - Specifies the http-method for the generated link - default is :get.
+    # * <tt>:highlights_on</tt> - if autohighlighting is turned off and/or you want to explicitly specify
+    #   when the item should be highlighted, you can set a regexp which is matched againstthe current URI.
+    #
+    # The <tt>block</tt> - if specified - will hold the item's sub_navigation.
+    def item(key, name, url, options={}, &block)
+      (@items << SimpleNavigation::Item.new(self, key, name, url, options, nil, &block)) if should_add_item?(options)
+    end
+
+    def items=(items)
+      items.each do |item|
+        item = SimpleNavigation::ItemAdapter.new(item)
+        (@items << item.to_simple_navigation_item(self)) if should_add_item?(item.options)
+      end
+    end
+
+    # Returns the Item with the specified key, nil otherwise.
+    #
+    def [](navi_key)
+      items.find {|i| i.key == navi_key}
+    end
+
+    # Returns the level of the item specified by navi_key.
+    # Recursively works its way down the item's sub_navigations if the desired item is not found directly in this container's items.
+    # Returns nil item cannot be found.
+    #
+    def level_for_item(navi_key)
+      my_item = self[navi_key]
+      return self.level if my_item
+      items.each do |i|
+        if i.sub_navigation
+          level = i.sub_navigation.level_for_item(navi_key)
+          return level unless level.nil?
+        end
+      end
+      return nil
+    end
+
+    # Renders the items in this ItemContainer using the configured renderer.
+    #
+    # The options are the same as in the view's render_navigation call (they get passed on)
+    def render(options={})
+      renderer_instance = if options[:renderer]
+        if options[:renderer].instance_of?(Symbol) && SimpleNavigation.registered_renderers.key?(options[:renderer])
+          SimpleNavigation.registered_renderers[options[:renderer]].new(options)
+        else
+          options[:renderer].new(options)
+        end
+      else
+        self.renderer.new(options)
+      end
+      renderer_instance.render(self)
+    end
+
+    # Returns true if any of this container's items is selected.
+    #
+    def selected?
+      items.any? {|i| i.selected?}
+    end
+
+    # Returns the currently selected item, nil if no item is selected.
+    #
+    def selected_item
+      items.find {|i| i.selected?}
+    end
+
+    # Returns the active item_container for the specified level
+    # (recursively looks up items in selected sub_navigation if level is deeper than this container's level).
+    #
+    def active_item_container_for(desired_level)
+      return self if self.level == desired_level
+      return nil unless selected_sub_navigation?
+      return selected_item.sub_navigation.active_item_container_for(desired_level)
+    end
+    
+    # Returns the deepest possible active item_container. 
+    # (recursively searches in the sub_navigation if this container has a selected sub_navigation). 
+    def active_leaf_container
+      if selected_sub_navigation?
+        selected_item.sub_navigation.active_leaf_container
+      else
+        self
+      end
+    end
+
+    # Returns true if there are no items defined for this container.
+    def empty?
+      items.empty?
+    end
+
+    private
+
+    def selected_sub_navigation?
+      !!(selected_item && selected_item.sub_navigation)
+    end
+
+    # partially borrowed from ActionSupport::Callbacks
+    def should_add_item?(options) #:nodoc:
+      [options.delete(:if)].flatten.compact.all? { |m| evaluate_method(m) } &&
+      ![options.delete(:unless)].flatten.compact.any? { |m| evaluate_method(m) }
+    end
+
+    # partially borrowed from ActionSupport::Callbacks
+    def evaluate_method(method) #:nodoc:
+      case method
+        when Proc, Method
+          method.call
+        else
+          raise ArgumentError, ":if or :unless must be procs or lambdas"
+      end
+    end
+
+  end
+
+end

data/lib/simple_navigation/core/items_provider.rb

@@ -0,0 +1,35 @@
+module SimpleNavigation
+
+  # Acts as a proxy to navigation items that are passed into the SimpleNavigation::Configuration#items method. It hides the logic
+  # for finding items from the Configuration object.
+  #
+  class ItemsProvider
+
+    attr_reader :provider
+
+    # It accepts the following types of provider:
+    # * methodname as symbol - the specified method should return the relevant items and has to be available in the view (a helper method)
+    # * object that responds to :items
+    # * enumerable object that represents the items
+    #
+    # See SimpleNavigation::ItemAdapter for the requirements that need to be fulfilled by the provided items.
+    #
+    def initialize(provider)
+      @provider = provider
+    end
+
+    # Returns the navigation items
+    def items
+      if provider.instance_of?(Symbol)
+        SimpleNavigation.context_for_eval.send(provider)
+      elsif provider.respond_to?(:items)
+        provider.items
+      elsif provider.respond_to?(:each)
+        provider
+      else
+        raise "items_provider either must be a symbol specifying the helper-method to call, an object with an items-method defined or an enumerable representing the items"
+      end
+    end
+
+  end
+end

data/lib/simple_navigation/core.rb

@@ -0,0 +1,5 @@
+require 'simple_navigation/core/configuration'
+require 'simple_navigation/core/item_adapter'
+require 'simple_navigation/core/item'
+require 'simple_navigation/core/item_container'
+require 'simple_navigation/core/items_provider'

data/lib/simple_navigation/rails_controller_methods.rb

@@ -0,0 +1,144 @@
+module SimpleNavigation
+
+  class << self
+
+    def explicit_navigation_args
+      self.adapter.controller.instance_variable_get(:"@sn_current_navigation_args")
+    end
+
+    # Reads the current navigation for the specified level from the controller.
+    # Returns nil if there is no current navigation set for level.
+    def current_navigation_for(level)
+      self.adapter.controller.instance_variable_get(:"@sn_current_navigation_#{level}")
+    end
+
+    # If any navigation has been explicitely set in the controller this method evaluates the specified args set in the controller and sets
+    # the correct instance variable in the controller.
+    def handle_explicit_navigation
+      if SimpleNavigation.explicit_navigation_args
+        level, navigation = parse_explicit_navigation_args
+        self.adapter.controller.instance_variable_set(:"@sn_current_navigation_#{level}", navigation)
+      end
+    end
+
+    # TODO: refactor this ugly thing to make it nice and short
+    def parse_explicit_navigation_args
+      args = SimpleNavigation.explicit_navigation_args
+      args = [Hash.new] if args.empty?
+      if args.first.kind_of? Hash
+        options = args.first
+      else # args is a list of current navigation for several levels
+        options = {}
+        if args.size == 1 #only one navi-key has been specified, try to find out level
+          level = SimpleNavigation.primary_navigation.level_for_item(args.first)
+          options[:"level_#{level}"] = args.first if level
+        else
+          args.each_with_index {|arg, i| options[:"level_#{i + 1}"] = arg}
+        end
+      end
+      #only the deepest level is relevant
+      level = options.inject(0) do |max, kv|
+        kv.first.to_s =~ /level_(\d)/
+        max = $1.to_i if $1.to_i > max
+        max
+      end
+      raise ArgumentError, "Invalid level specified or item key not found" if level == 0
+      [level, options[:"level_#{level}"]]
+    end
+    
+  end  
+  
+  # Adds methods for explicitely setting the current 'active' navigation to the controllers.
+  # Since version 2.0.0 the simple_navigation plugin determines the active navigation based on the current url by default (auto highlighting),
+  # so explicitely defining the active navigation in the controllers is only needed for edge cases where automatic highlighting does not work.
+  # 
+  # On the controller class level, use the <tt>navigation</tt> method to set the active navigation for all actions in the controller.
+  # Let's assume that we have a primary navigation item :account which in turn has a sub navigation item :settings.
+  # 
+  # ==== Examples
+  #   class AccountController << ActionController
+  #     navigation :account
+  #     ...
+  #   end
+  #
+  #   class AccountSettingsController << ActionController
+  #     navigation :settings
+  #     ...
+  #   end
+  #
+  # The first example sets the current primary navigation to :account for all actions. No active sub_navigation.
+  # The second example sets the current sub navigation to :settings and since it is a child of :account the current primary navigation is set to :account.
+  # 
+  # On the controller instance level, use the <tt>current_navigation</tt> method to define the active navigation for a specific action. 
+  # The navigation item that is set in <tt>current_navigation</tt> overrides the one defined on the controller class level (see <tt>navigation</tt> method).
+  # Thus if you have an :account primary item with a :special sub navigation item:
+  #
+  # ==== Example
+  #   class AccountController << ActionController
+  #     navigation :account
+  #     
+  #     def your_special_action
+  #       ...
+  #       current_navigation :special
+  #     end
+  #   end
+  #
+  # The code above still sets the active primary navigation to :account for all actions, but sets the sub_navigation to :account -> :special for 'your_special_action'.
+  #
+  # Note 1: As you can see above you just have to set the navigation item of your 'deepest' navigation level as active and all its parents are marked as active, too.
+  #
+  # Note 2: The specified symbols must match the keys for your navigation items in your config/navigation.rb file.
+  module ControllerMethods
+    def self.included(base) #:nodoc:
+      base.class_eval do
+        extend ClassMethods
+        include InstanceMethods
+      end
+    end
+  
+    module ClassMethods
+      # Sets the active navigation for all actions in this controller.
+      #
+      # The specified symbol must match the keys for your navigation items in your config/navigation.rb file.  
+      def navigation(*args)
+        self.class_eval do
+          define_method :sn_set_navigation do
+            current_navigation(*args)
+          end
+          protected :sn_set_navigation
+          before_filter :sn_set_navigation
+        end
+      end
+    end
+  
+    module InstanceMethods
+      # Sets the active navigation. Call this method in any action to override the controller-wide active navigation
+      # specified by navigation.
+      #
+      # The specified symbol must match the keys for your navigation items in your config/navigation.rb file.
+      def current_navigation(*args)
+        @sn_current_navigation_args = args
+      end
+    end
+
+  end
+  
+  class Item
+    
+    def selected_by_config?
+      key == SimpleNavigation.current_navigation_for(@container.level)
+    end
+    
+  end
+  
+  class ItemContainer
+    
+    def selected_item
+      self[SimpleNavigation.current_navigation_for(self.level)] || items.find {|i| i.selected?}
+    end
+    
+  end
+  
+end
+  
+ActionController::Base.send(:include, SimpleNavigation::ControllerMethods)

data/lib/simple_navigation/rendering/helpers.rb

@@ -0,0 +1,82 @@
+module SimpleNavigation
+
+  # View helpers to render the navigation.
+  #
+  # Use render_navigation as following to render your navigation:
+  # * call <tt>render_navigation</tt> without :level option to render your complete navigation as nested tree.
+  # * call <tt>render_navigation(:level => x)</tt> to render a specific navigation level (e.g. :level => 1 to render your primary navigation, :level => 2 to render the sub navigation and so forth)
+  # * call <tt>render_navigation(:level => 2..3)</tt> to render navigation levels 2 and 3).
+  #   For example, you could use render_navigation(:level => 1) to render your primary navigation as tabs and render_navigation(:level => 2..3) to render the rest of the navigation as a tree in a sidebar.
+  #
+  # ==== Examples (using Haml)
+  #   #primary_navigation= render_navigation(:level => 1)
+  #
+  #   #sub_navigation= render_navigation(:level => 2)
+  #
+  #   #nested_navigation= render_navigation
+  #
+  #   #top_navigation= render_navigation(:level => 1..2)
+  #   #sidebar_navigation= render_navigation(:level => 3)
+  module Helpers
+
+    # Renders the navigation according to the specified options-hash.
+    #
+    # The following options are supported:
+    # * <tt>:level</tt> - defaults to :all which renders the the sub_navigation for an active primary_navigation inside that active primary_navigation item.
+    #   Specify a specific level to only render that level of navigation (e.g. :level => 1 for primary_navigation etc...).
+    #   Specifiy a Range of levels to render only those specific levels (e.g. :level => 1..2 to render both your first and second levels, maybe you want to render your third level somewhere else on the page)
+    # * <tt>:expand_all</tt> - defaults to false. If set to true the all specified levels will be rendered as a fully expanded tree (always open). This is useful for javascript menus like Superfish.
+    # * <tt>:context</tt> - specifies the context for which you would render the navigation. Defaults to :default which loads the default navigation.rb (i.e. config/navigation.rb).
+    #   If you specify a context then the plugin tries to load the configuration file for that context, e.g. if you call <tt>render_navigation(:context => :admin)</tt> the file config/admin_navigation.rb
+    #   will be loaded and used for rendering the navigation.
+    # * <tt>:items</tt> - you can specify the items directly (e.g. if items are dynamically generated from database). See SimpleNavigation::ItemsProvider for documentation on what to provide as items.
+    # * <tt>:renderer</tt> - specify the renderer to be used for rendering the navigation. Either provide the Class or a symbol matching a registered renderer. Defaults to :list (html list renderer).
+    def render_navigation(options={})
+      options = apply_defaults(options)
+      load_config(options)
+      active_item_container = SimpleNavigation.active_item_container_for(options[:level])
+      active_item_container.render(options) unless active_item_container.nil?
+    end
+
+    # Returns the name of the currently active navigation item belonging to the specified level.
+    #
+    # The following options are supported:
+    # * <tt>:level</tt> - defaults to :all which returns the most specific/deepest selected item (the leaf).
+    #   Specify a specific level to only look for the selected item in the specified level of navigation (e.g. :level => 1 for primary_navigation etc...).
+    # * <tt>:context</tt> - specifies the context for which you would like to find the active navigation item. Defaults to :default which loads the default navigation.rb (i.e. config/navigation.rb).
+    #   If you specify a context then the plugin tries to load the configuration file for that context, e.g. if you call <tt>active_navigation_item_name(:context => :admin)</tt> the file config/admin_navigation.rb
+    #   will be loaded and used for searching the active item.
+    # * <tt>:items</tt> - you can specify the items directly (e.g. if items are dynamically generated from database). See SimpleNavigation::ItemsProvider for documentation on what to provide as items.
+    #
+    # Returns an empty string if no active item can be found for the specified options
+    def active_navigation_item_name(options={})
+      options = apply_defaults(options)
+      load_config(options)
+      options[:level] = :leaves if options[:level] == :all
+      active_item_container = SimpleNavigation.active_item_container_for(options[:level])
+      if active_item_container && !active_item_container.selected_item.nil?
+        active_item_container.selected_item.name
+      else
+        ''
+      end
+    end
+
+    private
+
+    def load_config(options)
+      ctx = options.delete(:context)
+      SimpleNavigation.init_adapter_from self
+      SimpleNavigation.load_config(ctx) 
+      SimpleNavigation::Configuration.eval_config(ctx) 
+      SimpleNavigation.config.items(options[:items]) if options[:items]
+      SimpleNavigation.handle_explicit_navigation if SimpleNavigation.respond_to?(:handle_explicit_navigation)
+      raise "no primary navigation defined, either use a navigation config file or pass items directly to render_navigation" unless SimpleNavigation.primary_navigation
+    end
+
+    def apply_defaults(options)
+      options[:level] = options.delete(:levels) if options[:levels]
+      {:context => :default, :level => :all}.merge(options)
+    end
+
+  end
+end

data/lib/simple_navigation/rendering/renderer/base.rb

@@ -0,0 +1,71 @@
+require 'forwardable'
+
+module SimpleNavigation
+  module Renderer
+
+    # This is the base class for all renderers.
+    #
+    # A renderer is responsible for rendering an ItemContainer and its containing items to HTML.
+    class Base
+      extend Forwardable
+            
+      attr_reader :options, :adapter
+      
+      def_delegators :adapter, :link_to, :content_tag
+            
+      def initialize(options) #:nodoc:
+        @options = options
+        @adapter = SimpleNavigation.adapter
+      end
+
+      def expand_all?
+        !!options[:expand_all]
+      end
+
+      def level
+        options[:level] || :all
+      end
+
+      def skip_if_empty?
+        !!options[:skip_if_empty]
+      end
+
+      def include_sub_navigation?(item)
+        consider_sub_navigation?(item) && expand_sub_navigation?(item)
+      end
+
+      def render_sub_navigation_for(item)
+        item.sub_navigation.render(self.options)
+      end
+                  
+      # Renders the specified ItemContainer to HTML.
+      #
+      # When implementing a renderer, please consider to call include_sub_navigation? to determin
+      # whether an item's sub_navigation should be rendered or not.
+      #
+      def render(item_container)
+        raise 'subclass responsibility'
+      end
+
+      protected
+
+      def consider_sub_navigation?(item)
+        return false if item.sub_navigation.nil?
+        case level
+        when :all
+          return true
+        when Integer
+          return false
+        when Range
+          return item.sub_navigation.level <= level.max
+        end
+        false
+      end
+
+      def expand_sub_navigation?(item)
+        expand_all? || item.selected?
+      end
+            
+    end
+  end
+end