navigatrix 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 28321e32d4430f1d16823c1a3d23121d25a1d2a3
+  data.tar.gz: 8c466c5479a7330322bb2989a49d11621e13f81a
+SHA512:
+  metadata.gz: d7c652b8c6d1e5ddbda0e997b1829307828d2951ae775a680c3407d1c2ff040e2fa444375a0e2facfddfa43d83a6092aa5d993b77a01af0007f758559accbebf
+  data.tar.gz: 0eeb7a60fc49e5f7ce8a2e8c683bda0d10716694cb09f65a10d0dcf006310fd9f9245cddd599c87ecc9577fb994489f2c38dccb72ce705501ba979dd13c20568

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - "1.9.3"
+  - jruby-19mode # JRuby in 1.9 mode
+script: bundle exec rspec spec

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in navigatrix.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Ben Eddy
+
+MIT License
+
+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.md

@@ -0,0 +1,144 @@
+# Navigatrix
+[![Build Status](https://api.travis-ci.org/foraker/navigatrix.png?branch=master)](http://travis-ci.org/foraker/navigatrix)
+[![Code Climate](https://codeclimate.com/github/foraker/navigatrix.png)](https://codeclimate.com/github/foraker/navigatrix)
+
+Navigation generation for Rails and Sinatra.
+
+## Installation
+Add `gem "navigatrix", github: "foraker/navigatrix"` to your Gemfile and run `bundle install`.
+
+### The Simplest Possible Navigation
+```ERB
+<%= render_navigation({
+  "Home"     => "/",
+  "About Us" => "/about-us",
+  "Blog"     => "/blog",
+  "Contact"  => "/contact"
+}) %>
+```
+Assuming we're on the "/about-us" path, the resulting HTML will look like this:
+```HTML
+<ul>
+  <li><a href="/">Home</a></li>
+  <li class="active">About Us</li>
+  <li><a href="/blog">Blog</a></li>
+  <li><a href="/contact">Contact</a></li>
+</ul>
+```
+
+### A More Sophisticated Configuration
+```ERB
+<%= render_navigation({
+  "Home" => "/",
+  "Users" => {
+    :path   => "/users",
+    :active_states => [
+      {:path => "/my_account"},
+      {:path  => /\/users\/\d*/},
+    ]
+  },
+  "Sign In" => {
+    :path   => "/sign_in",
+    :render? => !user_signed_in?
+  },
+  "Sign Out" => {
+    :path   => "/sign_out",
+    :render? => user_signed_in?
+  }
+}, {
+  :active_class    => "active-nav-item",
+  :html_attributes => {
+    :class => "nav"
+  }
+}) %>
+```
+
+Assuming we're on the "/users/1" path, and a User is signed in, the resulting HTML will look like this:
+```HTML
+<ul class="nav">
+  <li><a href="/">Home</a></li>
+  <li class="active-nav-item">Users</li>
+  <li><a href="/sign_out">Sign Out</a></li>
+</ul>
+```
+The "Users" item is active and not linked because the path "/users/1" matches the pattern `/\/users\/\d*/`.  The "Home" item is linked because we are not on the path "/".
+
+
+## List Item Configuration Options
+##### `:path`
+Specifies where the navigation item should link to.
+
+##### `:active_states`
+An array of state specification hashes used to control when a list item is considered "active".  By default, when an item is active, it receives an HTML class of "active". For example:
+```Ruby
+active_states: [
+  {controller: "users", actions: ["index"]},
+  {path: "/my-account"}
+]
+```
+The first state specification dictates that the item will be active when the current controller is the `UsersController` and the current controller action is `index`.  If we wanted the item to be active for any `UsersController` action, the specification should be `{controller: "users"}`.
+
+The second state specification dictates that the item will be active with the current path is "/my-account".  `:path` can be a string or regular expression.
+
+##### `:unlinked_states`
+Also an array of state specification hashes (like `:active_states`).  The state specifications determine if the item should be linked.  By default, the item is unlinked if the current path is the same as the item path.  The `:unlinked_states` option can be used to override this behavior.
+
+##### `:html_attributes`
+HTML attributes added to an item.
+```Ruby
+  "Item 3" => {
+    :path => "/item_path"
+    :html_attributes => {:id => "nav-3"}
+  }
+```
+Results in the following HTML.
+```HTML
+<li id="nav-3"><a href="item_path">Item 3</a></li>
+```
+
+##### `:children`
+Used for creating nested navigations.  The `:children` should contain a navigation configuration.
+```Ruby
+"Parent" => {
+  :path => "/parent_path"
+  :children => {
+    "Child 1" => "/child_1_path",
+    "Child 2" => {
+      :path => "/child_2_path",
+      :children => {
+        "Grandchild" => "/grandchild_path"
+      }
+    }
+  }
+}
+```
+Results in the following HTML.
+```HTML
+<ul>
+  <li>
+    <a href="/parent_path">Parent</a>
+    <ul>
+      <li><a href="/child_1_path">Child 1</a></li>
+      <li>
+        <a href="/child_2_path">Child 2</a>
+        <ul>
+          <li href="/grandchild_path">Grandchild</li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+</ul>
+```
+
+##### `:render?`
+Determines if the navigation item is rendered.
+
+## List Configuration Options
+##### `:html_attributes`
+HTML attributes added to an the list.
+
+##### `:active_class`
+Determines which HTML class is applied to list items when the item is active.
+
+##### `:inactive_class`
+Determines which HTML class is applied to list items when the item is *not* active.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/navigatrix.rb

@@ -0,0 +1,9 @@
+require "navigatrix/version"
+require "navigatrix/item"
+require "navigatrix/item_collection"
+require "navigatrix/renderer"
+require 'navigatrix/integration/rails' if defined?(Rails)
+require 'navigatrix/integration/sinatra' if defined?(Sinatra)
+
+module Navigatrix
+end

data/lib/navigatrix/configuration.rb

@@ -0,0 +1,51 @@
+require "active_support/core_ext"
+
+module Navigatrix
+  module Configuration
+    def self.wrap(wrapped)
+      wrapped.is_a?(Hash) ? AdvancedConfig.new(wrapped) : BasicConfig.new(wrapped)
+    end
+
+    class BasicConfig < Struct.new(:path)
+      def active_states
+        [{path: path}]
+      end
+
+      def unlinked_states
+        active_states
+      end
+
+      def children
+        {}
+      end
+
+      def html_attributes
+        {}
+      end
+
+      def render?
+        true
+      end
+    end
+
+    class AdvancedConfig < OpenStruct
+      DEFAULTS = {
+        :html_attributes => {},
+        :render?         => true,
+        :children        => {}
+      }
+
+      def initialize(raw_config)
+        super(DEFAULTS.merge(raw_config) || {})
+      end
+
+      def active_states
+        Array.wrap(super)
+      end
+
+      def unlinked_states
+        Array.wrap(super)
+      end
+    end
+  end
+end

data/lib/navigatrix/integration/rails.rb

@@ -0,0 +1,9 @@
+require "navigatrix/view_helpers"
+
+module Navigatrix
+  class Railtie < ::Rails::Railtie
+    initializer "navigatrix.view_helpers" do
+      ActionView::Base.send :include, Navigatrix::ViewHelpers
+    end
+  end
+end

data/lib/navigatrix/integration/sinatra.rb

@@ -0,0 +1,3 @@
+require "navigatrix/view_helpers"
+
+::Sinatra::Application.send(:helpers, Navigatrix::ViewHelpers)

data/lib/navigatrix/item.rb

@@ -0,0 +1,109 @@
+require "ostruct"
+require 'forwardable'
+require "navigatrix/configuration"
+
+module Navigatrix
+  class Item < Struct.new(:name, :config, :context)
+    extend Forwardable
+    delegate :current_path => :context
+    delegate [:render?, :html_attributes] => :config
+
+    def active?
+      applicable_active_state? ||
+      active_children? ||
+      unlinked?
+    end
+
+    def linked?
+      !unlinked?
+    end
+
+    def unlinked?
+      unlinked_states_specified? ? unlinked_states.any?(&:applicable?) : currently_on_path?
+    end
+
+    def has_children?
+      children.any?
+    end
+
+    def children
+      @children ||= ItemCollection.new(config.children, context).items
+    end
+
+    def path
+      @path ||= Path.new(config.path).call(context).to_s
+    end
+
+    private
+
+    def active_children?
+      children.any?(&:active?)
+    end
+
+    def applicable_active_state?
+      active_states.any?(&:applicable?)
+    end
+
+    def currently_on_path?
+      current_path == path
+    end
+
+    def unlinked_states_specified?
+      unlinked_states.any?
+    end
+
+    def active_states
+      @active_states ||= config.active_states.map { |active_state| State.new(active_state, context) }
+    end
+
+    def unlinked_states
+      @unlinked_states ||= config.unlinked_states.map { |unlinked_state| State.new(unlinked_state, context) }
+    end
+
+    def config
+      @config ||= Configuration.wrap(super)
+    end
+
+    class Path < Struct.new(:source)
+      def call(context)
+        source.respond_to?(:call) ? source.call(context) : source
+      end
+    end
+
+    class State < OpenStruct
+      extend Forwardable
+      delegate [:current_path, :controller_name, :action_name] => :context
+
+      attr_reader :context
+
+      def initialize(config, context)
+        @context = context
+        super(config)
+      end
+
+      def applicable?
+        path ? path_matches? : (controller_matches? && action_matches?)
+      end
+
+      def controller_matches?
+        match?(controller, controller_name)
+      end
+
+      def action_matches?
+        actions.empty? || actions.include?(action_name)
+      end
+
+      def path_matches?
+        match?(path, current_path)
+      end
+
+      def match?(pattern, target)
+        pattern.is_a?(Regexp) ? target[pattern] : pattern == target
+      end
+
+      def actions
+        Array.wrap(super)
+      end
+    end
+  end
+end

data/lib/navigatrix/item_collection.rb

@@ -0,0 +1,10 @@
+module Navigatrix
+  class ItemCollection < Struct.new(:configuration, :context)
+    extend Forwardable
+    def_delegator :items, :each
+
+    def items
+      configuration.map { |name, config| Item.new(name, config, context) }
+    end
+  end
+end

data/lib/navigatrix/renderer.rb

@@ -0,0 +1,41 @@
+require "navigatrix/rendering/context"
+require "navigatrix/rendering/strategies/list"
+require "navigatrix/rendering/strategies/bootstrap/navbar"
+require "navigatrix/rendering/strategies/bootstrap/tabs"
+
+module Navigatrix
+  class Renderer
+    attr_reader :configuration, :strategy, :render_context, :render_options
+
+    REGISTERED_STRATEGIES = {
+      :unordered_list   => Rendering::Strategies::List,
+      :bootstrap_navbar => Rendering::Strategies::Bootstrap::Navbar,
+      :bootstrap_tabs   => Rendering::Strategies::Bootstrap::Tabs
+    }
+
+    class MissingStrategy < NameError ; end
+
+    def initialize(configuration, options)
+      @configuration  = configuration
+      @strategy       = find_strategy(options.delete(:strategy))
+      @render_context = Rendering::Context.new(options.delete(:render_context))
+      @render_options = options
+    end
+
+    def render
+      strategy.new(item_collection.items, render_options).render
+    end
+
+    private
+
+    def item_collection
+      ItemCollection.new(configuration, render_context)
+    end
+
+    def find_strategy(strategy_or_name)
+      return strategy_or_name if strategy_or_name.is_a?(Class)
+      strategy_or_name ||= :unordered_list
+      REGISTERED_STRATEGIES[strategy_or_name] || raise(MissingStrategy, "can't find strategy #{strategy_name}")
+    end
+  end
+end