jordanyeo-simple-navigation 3.11.0

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.rb

@@ -0,0 +1,12 @@
+require 'simple_navigation/rendering/helpers'
+require 'simple_navigation/rendering/renderer/base'
+
+module SimpleNavigation
+  module Renderer
+    autoload :List, 'simple_navigation/rendering/renderer/list'
+    autoload :Links, 'simple_navigation/rendering/renderer/links'
+    autoload :Breadcrumbs, 'simple_navigation/rendering/renderer/breadcrumbs'
+    autoload :Text, 'simple_navigation/rendering/renderer/text'
+    autoload :Json, 'simple_navigation/rendering/renderer/json'
+  end
+end

data/lib/simple_navigation/rendering/helpers.rb

@@ -0,0 +1,123 @@
+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).
+    #
+    # Instead of using the <tt>:items</tt> option, a block can be passed to specify the items dynamically
+    #
+    #   render_navigation do |menu|
+    #     menu.item :posts, "Posts", posts_path
+    #   end
+    #
+    def render_navigation(options={},&block)
+      container = active_navigation_item_container(options,&block)
+      container && container.render(options)
+    end
+
+    # Returns the name of the currently active navigation item belonging to the specified level.
+    #
+    # See Helpers#active_navigation_item for supported options.
+    #
+    # Returns an empty string if no active item can be found for the specified options
+    def active_navigation_item_name(options={})
+      active_navigation_item(options,'') { |item| item.name(:apply_generator => false) }
+    end
+
+    # Returns the key of the currently active navigation item belonging to the specified level.
+    #
+    # See Helpers#active_navigation_item for supported options.
+    #
+    # Returns <tt>nil</tt> if no active item can be found for the specified options
+    def active_navigation_item_key(options={})
+      active_navigation_item(options) { |item| item.key }
+    end
+
+    # Returns 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 the supplied <tt>value_for_nil</tt> object (<tt>nil</tt>
+    # by default) if no active item can be found for the specified
+    # options
+    def active_navigation_item(options={},value_for_nil = nil)
+      options[:level] = :leaves if options[:level].nil? || options[:level] == :all
+      container = active_navigation_item_container(options)
+      if container && (item = container.selected_item)
+        block_given? ? yield(item) : item
+      else
+        value_for_nil
+      end
+    end
+
+    # Returns the currently active item container belonging to the specified level.
+    #
+    # The following options are supported:
+    # * <tt>:level</tt> - defaults to :all which returns the least specific/shallowest selected item.
+    #   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 <tt>nil</tt> if no active item container can be found
+    def active_navigation_item_container(options={},&block)
+      options = SimpleNavigation::Helpers::apply_defaults(options)
+      SimpleNavigation::Helpers::load_config(options,self,&block)
+      container = SimpleNavigation.active_item_container_for(options[:level])
+    end
+
+    class << self
+      def load_config(options,includer,&block)
+        ctx = options.delete(:context)
+        SimpleNavigation.init_adapter_from includer
+        SimpleNavigation.load_config(ctx)
+        SimpleNavigation::Configuration.eval_config(ctx)
+        if block_given? || options[:items]
+          SimpleNavigation.config.items(options[:items],&block)
+        end
+        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
+end

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

@@ -0,0 +1,107 @@
+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
+
+      # to allow overriding when there is specific logic determining
+      # when a link should not be rendered (eg. breadcrumbs renderer
+      # does not render the final breadcrumb as a link when instructed
+      # not to do so.)
+      def suppress_link?(item)
+        item.url.nil?
+      end
+
+      # determine and return link or static content depending on
+      # item/renderer conditions.
+      def tag_for(item)
+        if suppress_link?(item)
+          content_tag('span', item.name, link_options_for(item).except(:method))
+        else
+          link_to("<div class=\"menubg\"></div><i class=\"icon-#{item.name.downcase}\"></i><span>" + item.name + '</span>', item.url, options_for(item))
+        end
+      end
+
+      # to allow overriding when link options should be special-cased
+      # (eg. links renderer uses item options for the a-tag rather
+      # than an li-tag).
+      def options_for(item)
+        link_options_for(item)
+      end
+
+      # Extracts the options relevant for the generated link
+      #
+      def link_options_for(item)
+        special_options = {:method => item.method, :class => item.selected_class}.reject {|k, v| v.nil? }
+        link_options = item.html_options[:link]
+        return special_options unless link_options
+        opts = special_options.merge(link_options)
+        opts[:class] = [link_options[:class], item.selected_class].flatten.compact.join(' ')
+        opts.delete(:class) if opts[:class].nil? || opts[:class] == ''
+        opts
+      end            
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+module SimpleNavigation
+  module Renderer
+
+    # Renders an ItemContainer as a <div> element and its containing items as <a> elements.
+    # It only renders 'selected' elements.
+    #
+    # By default, the renderer sets the item's key as dom_id for the rendered <a> element unless the config option <tt>autogenerate_item_ids</tt> is set to false.
+    # The id can also be explicitely specified by setting the id in the html-options of the 'item' method in the config/navigation.rb file.
+    # The ItemContainer's dom_class and dom_id are applied to the surrounding <div> element.
+    #
+    class Breadcrumbs < SimpleNavigation::Renderer::Base
+
+      def render(item_container)
+        content = a_tags(item_container).join(join_with)
+        content_tag(:div,
+          prefix_for(content) + content,
+          {:id => item_container.dom_id, :class => item_container.dom_class})
+      end
+
+      protected
+
+      def a_tags(item_container)
+        item_container.items.inject([]) do |list, item|
+          if item.selected?
+            list << tag_for(item)
+            if include_sub_navigation?(item)
+              list.concat a_tags(item.sub_navigation)
+            end
+          end
+          list
+        end
+      end
+
+      def join_with
+        @join_with ||= options[:join_with] || " "
+      end
+
+      def suppress_link?(item)
+        super || (options[:static_leaf] && item.active_leaf_class)
+      end
+
+      def prefix_for(content)
+        content.empty? ? '' : options[:prefix] || ''
+      end
+
+      # Extracts the options relevant for the generated link
+      #
+      def link_options_for(item)
+        if options[:allow_classes_and_ids]
+          opts = super
+          opts[:id] = "breadcrumb_#{opts[:id]}" if opts[:id]
+          opts
+        else
+          {:method => item.method}.merge(item.html_options.except(:class,:id))
+        end
+      end
+    end
+  end
+end