mariner 0.0.2

data/.autotest

@@ -0,0 +1,10 @@
+Autotest.add_hook(:initialize) {|at|
+  at.add_exception %r{^\.git}
+  at.add_exception %r{^./tmp}
+  at.add_exception %r{^./spec/rails_app/tmp}
+  at.add_exception %r{^./spec/rails_app/log}
+  at.add_mapping(%r{^lib/.*\.rb$}) {|f, _|
+    Dir['spec/**/*_spec.rb']
+  }
+  nil
+}

data/.gitignore

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

data/.pairs

@@ -0,0 +1,6 @@
+pairs:
+  aa: Adam Albrecht
+  jt: Jesse Trimble
+email:
+  prefix: pair
+  domain: factorylabs.com

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,12 @@
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in mariner.gemspec
+gemspec
+
+gem 'rake'
+gem 'rspec-rails'
+gem 'capybara'
+gem 'autotest'
+gem 'pivotal_git_scripts'
+gem 'yard'
+gem 'redcarpet'

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Jesse Trimble
+
+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,59 @@
+# Mariner
+
+[![Build Status](https://secure.travis-ci.org/jtrim/mariner.png)](http://travis-ci.org/jtrim/mariner)
+
+Mariner helps you manage your site's navigation through a friendly DSL.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'mariner'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mariner
+
+## Usage
+
+Mariner helps you define trees of links through a friendly DSL:
+
+    Mariner.configure do
+
+      topbar do # <= arbitrarily-named
+
+        # Defining Urls is as easy as calling the
+        # Rails route helper you want to use:
+
+        root_path 'Home'
+
+        # by default, the above renders <a href="/">Home</a>
+
+        dropdown do # <= also arbitrarily-named
+
+          # If you specify options, they're passed on to the renderer
+          destroy_user_session_path "Logout", "data-method" => :destroy
+
+        end
+
+      end
+
+    end
+
+After creating your nav, render it in your views with:
+
+    <%= render_navigation :topbar %>
+
+See Mariner::Helper for usage on `render_navigation`.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes and tests (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,13 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+begin
+  require 'rspec/core/rake_task'
+
+  desc "Run all examples"
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    t.rspec_opts = %w[--color]
+  end
+
+  task :default => [:spec]
+rescue LoadError; end

data/lib/mariner.rb

@@ -0,0 +1,49 @@
+$:.unshift(File.expand_path('..', __FILE__)) unless $:.include? File.expand_path('..', __FILE__)
+
+require 'abyss'
+
+require 'mariner/version'
+require 'mariner/errors'
+require 'mariner/renderer/base'
+require 'mariner/unordered_list_renderer'
+require 'mariner/url'
+require 'mariner/store'
+
+require 'mariner/helper'
+require 'mariner/railtie'
+
+module Mariner
+
+  class << self
+    attr_accessor :configuration, :rendering_strategies
+  end
+
+  @rendering_strategies = {
+    :default => UnorderedListRenderer.new
+  }
+
+  # Public: The public interface to navigation API
+  #
+  # Examples:
+  #
+  #     Mariner.configure do
+  #       an_arbitrary_group do
+  #         root_path "Go Home"                                     #=> where `root_path` is a Rails route helper
+  #         users_path "Manage Users", { "data-name" => "go-home" } #=> note the optional attributes hash. This
+  #                                                                 #   is used by rendering strategies
+  #       end
+  #     end
+  #
+  def self.configure(&block)
+    self.configuration ||= Store.new.tap { |s| s.virtual = true }
+    self.configuration.instance_eval &block
+  end
+
+  def self.include_helper
+    ActiveSupport.on_load(:action_controller) do
+      include Mariner::Helper
+      helper_method :render_navigation #:notest:
+    end
+  end
+
+end

data/lib/mariner/errors.rb

@@ -0,0 +1,26 @@
+module Mariner
+
+  module Errors
+
+    # Private: This error is raised when Url tries to use a route helper
+    # method that's unavailable or undefined
+    #
+    class InvalidUrlHelperMethod < RuntimeError
+      attr_accessor :name
+
+      def initialize(name)
+        self.name = name
+      end
+
+      def message
+        "Unknown url helper method used in navigation configuration: #{name.inspect}"
+      end
+
+      def to_s
+        message
+      end
+    end
+
+  end
+
+end

data/lib/mariner/helper.rb

@@ -0,0 +1,96 @@
+module Mariner
+
+  # Public: Gets included in controllers (see the Railtie)
+  #
+  module Helper
+
+    # Public: A shortcut for rendering navigation. Made available to both
+    # controllers and views.
+    #
+    # config_path - A symbol or slash-separated string path to the
+    # configuration group you want to render.
+    #
+    # renderer - The rendering strategy to use.
+    # Can be a symbol or actual
+    # rendering stragey.  When a symbol, looks in the
+    # `Mariner.rendering_strategies` hash using the given symbol as the key.
+    # Raises an error if not found.  When a rendering strategy, passes the
+    # strategy on to the target group's #render method.
+    #
+    # Examples:
+    #
+    #     Mariner.configure do
+    #       a_group do
+    #         root_path "Home"
+    #
+    #         a_sub_group do
+    #           users_path "Manage Users"
+    #         end
+    #       end
+    #     end
+    #
+    #     render_navigation
+    #     #=> renders the entire nav tree
+    #
+    #     render_navigation :a_group
+    #     #=> renders the `a_group` nav tree
+    #
+    #     render_navigation "a_group/a_sub_group"
+    #     #=> renders the nav tree of `a_sub_group` under `a_group`
+    #
+    #     render_navigation :a_group, FakeRenderingStrategy.new
+    #     #=> renders `a_group` with a FakeRenderingStrategy instance
+    #
+    def render_navigation(config_path=nil, renderer=nil)
+      target   = target_from_path(config_path)
+      strategy = rendering_strategy_from(renderer)
+
+      strategy ? target.render(strategy) : target.render
+    end
+
+    # Public: For when you want to render all the configurations under
+    # a given group but you don't want to render the group itself.
+    #
+    # Examples:
+    #
+    #     Mariner.configure do
+    #       group_a do
+    #         root_path "Home"
+    #       end
+    #
+    #       group_b do
+    #         users_path "Manage Users"
+    #       end
+    #     end
+    #
+    #     render_navigations
+    #     #=> renders the group_a and group_b trees and joins the result
+    #
+    def render_navigations(config_path=nil, renderer=nil)
+      target = target_from_path(config_path)
+      strategy = rendering_strategy_from(renderer)
+
+      target.configurations.map do |c|
+        _, entity = c
+        strategy ? entity.render(strategy) : entity.render
+      end.join
+    end
+
+    private
+
+    def target_from_path(config_path)
+      path   = config_path ? config_path.to_s.split("/") : []
+      path.reduce(Mariner.configuration) { |acc, g| acc.send g }
+    end
+
+    def rendering_strategy_from(renderer)
+      return nil unless renderer
+      return renderer if renderer && renderer.respond_to?(:render)
+      raise "Rendering strategy not found: #{renderer}" if Mariner.rendering_strategies[renderer].nil?
+
+      Mariner.rendering_strategies[renderer]
+    end
+
+  end
+
+end

data/lib/mariner/railtie.rb

@@ -0,0 +1,21 @@
+module Mariner
+
+  # Private: After Rails initializes:
+  # * mixes `Rails.application.routes.url_helpers` into Mariner::Url
+  # * includes Mariner::Helper into ActionController::Base
+  # * makes a #helper_method out of Helper#render_navigation
+  #
+  class Railtie < ::Rails::Railtie
+
+    config.after_initialize do
+      Mariner::Url.class_eval { include Rails.application.routes.url_helpers }
+
+      ActiveSupport.on_load(:action_controller) do
+        include Mariner::Helper
+        helper_method :render_navigation, :render_navigations
+      end
+    end
+
+  end
+
+end

data/lib/mariner/renderer/base.rb

@@ -0,0 +1,42 @@
+module Mariner
+
+  module Renderer
+
+    # Public: The base class for renderers used in a rendering strategy.
+    #
+    # Examples:
+    #
+    #     class FakeRenderingStrategy
+    #
+    #       def factory(type, subject)
+    #         case type
+    #         when :group then FakeRenderer.new(subject, self)
+    #         ...
+    #
+    #       class FakeRenderer < Mariner::Renderer::Base
+    #
+    #         def render
+    #           ...
+    #
+    class Base
+
+      # Public: The subject (a Store or a Url) to render
+      #
+      attr_accessor :subject
+
+      # Public: The rendering strategy used that responds to #factory
+      #
+      attr_accessor :rendering_strategy
+
+      # Public: Creates a new renderer and assigns #subject and
+      # #rendering_strategy
+      #
+      def initialize(subject, rendering_strategy)
+        @subject, @rendering_strategy = subject, rendering_strategy
+      end
+
+    end
+
+  end
+
+end

data/lib/mariner/store.rb

@@ -0,0 +1,76 @@
+require 'active_support/core_ext/string/inflections'
+
+module Mariner
+
+  # Public: Uses the Abyss library to provide arbitrarily-deep sets of
+  # navigation groups / urls. Think of this as the group when
+  # defining nav trees.
+  #
+  # Examples:
+  #
+  #     Mariner.configure do
+  #
+  #       a_group do         # <= This effectivly creates a new Mariner::Store, ...
+  #         root_path "Home" # <= and this creates a new Mariner::Url within said store.
+  #       end
+  #
+  #     end
+  #
+  class Store < ::Abyss::DeepStore
+
+    # Public: If the group is virtual, the rendering strategy shouldn't
+    # generate any output around its nested configurations when.
+    # e.g. The UnorderedListRenderer doesn't generate `ul` or `li` tags when
+    # the target group is virtual.
+    #
+    attr_accessor :virtual
+    alias :virtual? :virtual
+
+    # Public: Sets virtual to false by default and defers to
+    # ::Abyss::DeepStore for initialization.
+    #
+    def initialize(*)
+      @virtual = false
+      super
+    end
+
+    # Public: Abstract method override - overrides ::Abyss::DeepStore#assign
+    # to store Urls. This is only called when NOT dealing with a nested
+    # group.
+    #
+    # e.g.:
+    #
+    #     Mariner.configure do
+    #
+    #       a_group do
+    #         root_path "Home" # <= #assign gets called.
+    #       end
+    #
+    #     end
+    #
+    def assign(method_name, values)
+      raise ArgumentError, "Wrong number of values specified (#{values.size} for <= 2)" if values.size > 2
+
+      values[1] ||= {} # link options
+      title, options = values
+      self.configurations[method_name] = Url.new(method_name, title, options)
+    end
+
+    # Public: Uses a rendering strategy to render itself.
+    #
+    # rendering_strategy - The rendering strategy to use when rendering.
+    #
+    # Examples:
+    #
+    #     Mariner.configuration #=> An Mariner::Store instance
+    #
+    #     Mariner.configuration.render
+    #     Mariner.configuration.render(SomeRenderingStrategy.new)
+    #
+    def render(rendering_strategy=Mariner.rendering_strategies[:default])
+      rendering_strategy.factory(:group, self).render
+    end
+
+  end
+
+end