breadcrumb_trail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6d8214c00eb8560928ec5a0e2b977abb28a21a13
+  data.tar.gz: 4484fad9e6f341e0779cc8abdf334a9554fb1e9f
+SHA512:
+  metadata.gz: 5c2caf6f7ccabf9ad5d60ca820044f20f948e8a7a9eda77fbff66c25a3af49dfa751d6cffe62dee52125afbeacfa1d56bddbbbbd7829566e59b47ff21f010e2c
+  data.tar.gz: faa2216d0e9f9aeda187e95912222fe9de9610e5967cc7854d3ebf36e4c9dd86de2d3bd434b22335c13b17b2c321fa8feb60ba6460ada3c8f048838ced21fc60

data/.gitignore

@@ -0,0 +1,6 @@
+.bundle/
+log/*.log
+pkg/
+spec/dummy/log/*.log
+spec/dummy/tmp/
+spec/dummy/.sass-cache

data/.rspec

@@ -0,0 +1,3 @@
+--format d
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+cache: bundler
+sudo: false
+rvm:
+  - 2.0.0
+  - 2.1.5
+  - 2.2.0
+script: bundle exec rspec spec
+addons:
+  code_climate:
+    repo_token: 871ec12915a92c1f4f85af1b78f22652ff35f86de0dea210d8aeea1f35f31df2

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Declare your gem's dependencies in breadcrumb_trail.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+gemspec

data/Gemfile.lock

@@ -0,0 +1,142 @@
+PATH
+  remote: .
+  specs:
+    breadcrumb_trail (0.1.0)
+      rails (>= 3.0, < 5)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionmailer (4.2.0)
+      actionpack (= 4.2.0)
+      actionview (= 4.2.0)
+      activejob (= 4.2.0)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+    actionpack (4.2.0)
+      actionview (= 4.2.0)
+      activesupport (= 4.2.0)
+      rack (~> 1.6.0)
+      rack-test (~> 0.6.2)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.1)
+    actionview (4.2.0)
+      activesupport (= 4.2.0)
+      builder (~> 3.1)
+      erubis (~> 2.7.0)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.1)
+    activejob (4.2.0)
+      activesupport (= 4.2.0)
+      globalid (>= 0.3.0)
+    activemodel (4.2.0)
+      activesupport (= 4.2.0)
+      builder (~> 3.1)
+    activerecord (4.2.0)
+      activemodel (= 4.2.0)
+      activesupport (= 4.2.0)
+      arel (~> 6.0)
+    activesupport (4.2.0)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    arel (6.0.0)
+    builder (3.2.2)
+    codeclimate-test-reporter (0.4.6)
+      simplecov (>= 0.7.1, < 1.0.0)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    erubis (2.7.0)
+    globalid (0.3.3)
+      activesupport (>= 4.1.0)
+    hike (1.2.3)
+    i18n (0.7.0)
+    json (1.8.2)
+    loofah (2.0.1)
+      nokogiri (>= 1.5.9)
+    mail (2.6.3)
+      mime-types (>= 1.16, < 3)
+    mime-types (2.4.3)
+    mini_portile (0.6.2)
+    minitest (5.5.1)
+    multi_json (1.10.1)
+    nokogiri (1.6.6.2)
+      mini_portile (~> 0.6.0)
+    rack (1.6.0)
+    rack-test (0.6.3)
+      rack (>= 1.0)
+    rails (4.2.0)
+      actionmailer (= 4.2.0)
+      actionpack (= 4.2.0)
+      actionview (= 4.2.0)
+      activejob (= 4.2.0)
+      activemodel (= 4.2.0)
+      activerecord (= 4.2.0)
+      activesupport (= 4.2.0)
+      bundler (>= 1.3.0, < 2.0)
+      railties (= 4.2.0)
+      sprockets-rails
+    rails-deprecated_sanitizer (1.0.3)
+      activesupport (>= 4.2.0.alpha)
+    rails-dom-testing (1.0.5)
+      activesupport (>= 4.2.0.beta, < 5.0)
+      nokogiri (~> 1.6.0)
+      rails-deprecated_sanitizer (>= 1.0.1)
+    rails-html-sanitizer (1.0.1)
+      loofah (~> 2.0)
+    railties (4.2.0)
+      actionpack (= 4.2.0)
+      activesupport (= 4.2.0)
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (10.4.2)
+    rspec-core (3.2.0)
+      rspec-support (~> 3.2.0)
+    rspec-expectations (3.2.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-mocks (3.2.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-rails (3.2.0)
+      actionpack (>= 3.0, <= 4.2)
+      activesupport (>= 3.0, <= 4.2)
+      railties (>= 3.0, <= 4.2)
+      rspec-core (~> 3.2.0)
+      rspec-expectations (~> 3.2.0)
+      rspec-mocks (~> 3.2.0)
+      rspec-support (~> 3.2.0)
+    rspec-support (3.2.1)
+    simplecov (0.9.1)
+      docile (~> 1.1.0)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    sprockets (2.12.3)
+      hike (~> 1.2)
+      multi_json (~> 1.0)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sprockets-rails (2.2.4)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      sprockets (>= 2.8, < 4.0)
+    thor (0.19.1)
+    thread_safe (0.3.4)
+    tilt (1.4.1)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+    yard (0.8.7.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  breadcrumb_trail!
+  bundler (~> 1.7)
+  codeclimate-test-reporter
+  rake (~> 10.0)
+  rspec-rails (~> 3.0)
+  yard

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Jeremy Rodi
+
+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,136 @@
+# Breadcrumb Trail
+[![Code Climate](https://codeclimate.com/github/medcat/breadcrumb_trail/badges/gpa.svg)](https://codeclimate.com/github/medcat/breadcrumb_trail) [![Build Status](https://travis-ci.org/medcat/breadcrumb_trail.svg)](https://travis-ci.org/medcat/breadcrumb_trail) [![Test Coverage](https://codeclimate.com/github/medcat/breadcrumb_trail/badges/coverage.svg)](https://codeclimate.com/github/medcat/breadcrumb_trail)
+
+Helps you create a breadcrumb system for your Rails application.
+Better than any other library, guarenteed<sup>*</sup>.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'breadcrumb_trail'
+```
+
+And you're done!
+
+## Usage
+
+The gem adds some nice methods to your controller:
+
+```Ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+
+  breadcrumb name: "Home", path: :root_path
+end
+```
+
+```Ruby
+# app/controllers/articles_controller.rb
+class ArticlesController < ApplicationController
+  breadcrumb name: "Articles", path: :articles_path
+
+  def show
+    @article = Article.find(params[:id])
+    breadcrumb name: @article.name, path: article_path(@article)
+    breadcrumbs # => returns all of your breadcrumbs
+  end
+end
+```
+
+```HTML
+<!-- app/views/layouts/application.html.erb -->
+<!-- ... -->
+<%= render_breadcrumbs outer: "ul" %>
+<!-- ... -->
+```
+
+...all results in _(with some assumptions)_:
+
+```HTML
+<!-- ... -->
+<ul>
+  <li><a href="/">Home</a></li>
+  <li><a href="/articles">Articles</a></li>
+  <li><a href="/articles/1">Hello, World</a></li>
+</ul>
+<!-- ... -->
+```
+
+You can pass `#breadcrumb` some options, which it'll use as
+HTML options by default.
+
+Simple, right?
+
+### Builders
+
+`#render_breadcrumbs` takes an option for a builder, or defaults to
+one if you don't provide it.  There are two default builders:
+`HTMLBuilder` and `BlockBuilder`.  If you provide a block to
+`#render_breadcrumbs`, then `BlockBuilder` is used; otherwise,
+`HTMLBuilder` is used.
+
+#### `HTMLBuilder`
+
+`HTMLBuilder` builds a sensible block of HTML based on some options.
+The exact options you can provide are:
+
+- `outer`: The outer tag that is used.  The default for this is `ol`.
+  If this is `nil`, then no outer tag is rendered.
+- `inner`: The inner tag that is used.  The default for this is `li`.
+  If this is `nil`, then no inner tag is rendered.
+- `outer_options`: The html attributes that are used for the outer
+  tag.  By default, there are no options.  If you want to add
+  `class="some-class"`, this is the place to provide it.
+- `inner_options`: The html attributes that are used for the inner
+  tag.  By default, there are no options.  If you want to add
+  `class="some-class"`, this is the place to provide it.
+
+That's it!
+
+#### `BlockBuilder`
+
+`BlockBuilder` yields each breadcrumb to the given block.  Each
+breadcrumb has three attributes: `name`, `path`, and `options`.
+To recreate the default output of `HTMLBuilder`, you'd have to do
+this with `BlockBuilder`:
+
+```
+<!-- ... -->
+<ol>
+<%= render_breadcrumbs do |breadcrumb| %>
+  <li><%= link_to(breadcrumb.name, breadcrumb.path, breadcrumb.options) %></li>
+<%= end %>
+</ol>
+<!-- ... -->
+```
+
+#### Your Own Builder
+
+You don't have to use one of these.  You can use your own builder.
+However, if you're using a builder because the default builders don't
+provide a feature you like, open an issue!
+
+Your builder only needs to subclass `BreadcrumbTrail::Builder` and
+define the method `#call`, and that's it!  Then, you pass the builder
+to `#render_breadcrumbs` with the `builder` option:
+
+```
+<!-- ... -->
+<%= render_breadcrumbs builder: MyCustomBuilder %>
+<!-- ... -->
+```
+
+Any options passed to `#render_breadcrumbs` are passed to your
+builder's `#initialize` via the last argument.
+
+## Contributing
+
+1. Fork it (<https://github.com/medcat/breadcrumb_trail/fork>)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+<sup>*</sup>: Not guarenteed.

data/Rakefile

@@ -0,0 +1,28 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'BreadcrumbTrail'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/breadcrumb_trail.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'breadcrumb_trail/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "breadcrumb_trail"
+  spec.version       = BreadcrumbTrail::VERSION
+  spec.authors       = ["Jeremy Rodi"]
+  spec.email         = ["redjazz96@gmail.com"]
+  spec.summary       = %q{A basic breadcrumb trail plugin.}
+  spec.description   = %q{A breadcrumb trail plugin that provides shortcuts to make your life easier.}
+  spec.homepage      = "https://github.com/medcat/breadcrumb_trail"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec-rails", "~> 3.0"
+  spec.add_development_dependency "yard"
+  spec.add_development_dependency "codeclimate-test-reporter"
+
+  # I don't know what 5 will be like...
+  spec.add_dependency "rails", ">= 3.0", "< 5"
+
+end

data/lib/breadcrumb_trail/action_controller.rb

@@ -0,0 +1,79 @@
+module BreadcrumbTrail
+
+  # A module to extend Controllers with.  It provides the main methods
+  # that are used within the application, namely `breadcrumbs` and
+  # `render_breadcrumbs`.
+  module ActionController
+    extend ActiveSupport::Concern
+
+    included do
+      include HelperMethods
+      helper HelperMethods
+      helper_method :breadcrumb, :breadcrumbs
+    end
+
+    # This extends a controller, providing the `breadcrumb` method to
+    # the class as a method.
+    module ClassMethods
+
+      # Creates a before action that defines a breadcrumb before the
+      # action takes place.  See {HelperMethods#breadcrumb}.
+      #
+      # @param (see HelperMethods#breadcrumb)
+      # @return [void]
+      def breadcrumb(options, &block)
+        before_action(options.delete(:action) || {}) do
+          breadcrumb(options, &block)
+        end
+      end
+    end
+
+    # This is both included in the controller and used as a helper,
+    # so any methods defined here are usable in both the controller
+    # and in the views.  These methods are the primary interface
+    # that the developer uses to define and render breadcrumbs.
+    module HelperMethods
+
+      # Define a breadcrumb with the given options.  All of this
+      # information is passed directly to the Breadcrumb initializer.
+      #
+      # @see Breadcrumb#initialize
+      # @params options [Hash] A hash of options to pass directly to
+      #   the Breadcrumb.
+      # @yield
+      # @return [void]
+      def breadcrumb(options, &block)
+        breadcrumbs << Breadcrumb.new(**options, &block)
+      end
+
+      # All of the defined breadcrumbs, in order.
+      #
+      # @return [Array<Breadcrumb>]
+      def breadcrumbs
+        @_breadcrumbs ||= []
+      end
+
+      # Renders the defined breadcrumbs, with the given options.
+      #
+      # @param options [Hash] The options that are passed to the
+      #   builder to help render the breadcrumbs.
+      # @option options [Hash] :builder (Builder) The builder to use.
+      #   If this isn't provided, a sensible default is used.
+      # @yield
+      # @return [String]
+      def render_breadcrumbs(options = {}, &block)
+        block_given = block_given?
+        builder = options.fetch(:builder) do
+          if block_given
+            BlockBuilder
+          else
+            HTMLBuilder
+          end
+        end
+
+        builder.new(self, breadcrumbs, options, &block).call
+      end
+
+    end
+  end
+end

data/lib/breadcrumb_trail/breadcrumb.rb

@@ -0,0 +1,95 @@
+module BreadcrumbTrail
+
+  # A single representation of a breadcrumb.
+  class Breadcrumb
+
+    # The name of the breadcrumb.  Normally, this represents the text
+    # that is displayed in place of the link to give meaning to the
+    # breadcrumb.
+    #
+    # @return [String, Symbol, Proc, nil]
+    attr_reader :name
+
+    # The path the breadcrumb represents.  Normally, this is where the
+    # breadcrumb should take the user when clicked.
+    #
+    # @return [String, Symbol, Proc, Hash]
+    attr_reader :path
+
+    # Options for the breadcrumb.  Normally, these are HTML attributes
+    # that are used for the link tag.
+    #
+    # @return [Hash]
+    attr_reader :options
+
+    # Initialize the breadcrumb.  If a block is given, and a path is
+    # not, then the path is set to be the block.
+    #
+    # @param name [String, Symbol, Proc, nil] The name of the
+    #   breadcrumb.  See {#name}.
+    # @param path [String, Symbol, Proc, Hash] The path of the
+    #   breadcrumb.  See {#path}.
+    # @param options [Hash] Options that are used as HTML attributes.
+    #   See {#options}.
+    #
+    def initialize(name: nil, path: nil, **options, &block)
+      @name    = name
+      @path    = path || block
+      @options = options
+    end
+
+    # Creates a version of the breadcrumb that has a computed name and
+    # path.  This is used, for example, in a builder that exposes a
+    # breadcrumb to application code.
+    #
+    # @see #computed_path
+    # @see #computed_name
+    # @param context [ActionView::Base] The context to compute the
+    #   elements under.
+    # @return [Breadcrumb]
+    def computed(context)
+      self.class.new(name: computed_name(context),
+                     path: computed_path(context),
+                     **@options)
+    end
+
+    # Computes the path of the breadcrumb under the given context.
+    #
+    # @return [String, Hash]
+    def computed_path(context)
+      @_path ||= case @path
+      when String, Hash
+        @path
+      when Symbol
+        context.public_send(@path) # todo
+      when Proc
+        context.instance_exec(&@path)
+      else
+        raise ArgumentError,
+          "Expected one of String, Symbol, or Proc, " \
+          "got #{@path.class}"
+      end
+    end
+
+    # Computes the name of the breadcrumb under the given context.
+    #
+    # @return [String]
+    def computed_name(context)
+      @_name ||= case @name
+      when String
+        @name
+      when Symbol
+        context.public_send(@name) # todo
+      when Proc
+        context.instance_exec(&@name)
+      when nil
+        computed_path(context)
+      else
+        raise ArgumentError,
+          "Expected one of String, Symbol, or Proc, " \
+          "got #{@name.class}"
+      end
+    end
+
+  end
+end

data/lib/breadcrumb_trail/builder.rb

@@ -0,0 +1,98 @@
+module BreadcrumbTrail
+
+  # A Builder that is used by
+  # {ActionController::HelperMethods#render_breadcrumbs}.  This should
+  # be subclassed and implemented.
+  #
+  # @abstract
+  class Builder
+
+    # Initialize the builder.
+    #
+    # @param context [ActionView::Base] The base of the view being
+    #   rendered.
+    # @param breadcrumbs [Array<Breadcrumb>] The breadcrumbs to
+    #   render.
+    # @param options [Hash] The options for the builder.
+    def initialize(context, breadcrumbs, options = {}, &block)
+      @context = context
+      @breadcrumbs = breadcrumbs
+      @options = options
+      @block = block
+    end
+
+    # Renders the breadcrumbs using the builder.  However, since this
+    # is the base, it raises an error.
+    #
+    # @raise [NotImplementedError]
+    # @return [String]
+    def call
+      raise NotImplementedError
+    end
+
+  end
+
+  # Used along with a block given to the initializer, this renders
+  # the breadcrumbs.
+  class BlockBuilder < Builder
+
+    # Creates a buffer, and iterates over every breadcrumb, yielding
+    # the breadcrumb to the block given on initialization.
+    #
+    # @return [String]
+    def call
+      buffer = ActiveSupport::SafeBuffer.new
+      @breadcrumbs.each do |breadcrumb|
+        buffer << @block.call(breadcrumb.computed(@context))
+      end
+
+      buffer
+    end
+  end
+
+  # Creates a structure of HTML elements to render the breadcrumbs.
+  class HTMLBuilder < Builder
+
+    include ActionView::Helpers
+
+    # Renders the breadcrumbs in HTML tags.  If no options were
+    # provided on initialization, it uses defaults.
+    #
+    # @option @options [String] :outer ("ol") The outer tag element
+    #   to use.
+    # @option @options [String] :inner ("li") The inner tag element
+    #   to use.
+    # @option @options [Hash] :outer_options (nil) The outer tag
+    #   element attributes to use.  Things like `class="some-class"`
+    #   are best placed here.
+    # @option @options [Hash] :inner_options (nil) The inner tag
+    #   element attributes to use.  Things like `class="some-class"`
+    #   are best placed here.
+    # @return [String]
+    def call
+      outer_tag = @options.fetch(:outer, "ol")
+      inner_tag = @options.fetch(:inner, "li")
+      outer = tag(outer_tag,
+                  @options.fetch(:outer_options, nil),
+                  true) if outer_tag
+      inner = tag(inner_tag,
+                  @options.fetch(:inner_options, nil),
+                  true) if inner_tag
+
+      buffer = ActiveSupport::SafeBuffer.new
+      buffer.safe_concat(outer) if outer_tag
+
+      @breadcrumbs.each do |breadcrumb|
+        buffer.safe_concat(inner) if inner_tag
+        buffer << link_to(breadcrumb.computed_name(@context),
+                          breadcrumb.computed_path(@context),
+                          breadcrumb.options)
+        buffer.safe_concat("</#{inner_tag}>") if inner_tag
+      end
+
+      buffer.safe_concat("</#{outer_tag}>") if outer_tag
+      buffer
+    end
+
+  end
+end

data/lib/breadcrumb_trail/railtie.rb

@@ -0,0 +1,11 @@
+module BreadcrumbTrail
+
+  # A railtie, to load the plugin when Rails is initialized.
+  class Railtie < Rails::Railtie
+    initializer "breadcrumb_trail.modify_controller" do
+      ActiveSupport.on_load :action_controller do
+        include BreadcrumbTrail::ActionController
+      end
+    end
+  end
+end

data/lib/breadcrumb_trail/version.rb

@@ -0,0 +1,5 @@
+module BreadcrumbTrail
+
+  # The current version of BreadcrumbTrail.
+  VERSION = "0.1.0"
+end