breadcrumby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4a1a44d7813b238cba249579dd22ea79f7c4cc26
+  data.tar.gz: 81d23babac7e3dd6de67f94fa49c1b2801f98fc9
+SHA512:
+  metadata.gz: 758338710ffca12ef1a421fa172b765b964d87589d08e8c84ee96c2466f8cb397ea44790b2850f82687c2f45517048748c8ed86f8175a6552cf1a78222ee7875
+  data.tar.gz: 5f39e94f2d620da90f97519283b20a942ca662851e71baacc9519baa275922578ca289c4819551548cb6723f9b0c7bcf6c60a48df04a0eaf6e52c26e3e1e659a

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 0.1.0
+
+- Automatic adition of contextual link before action crumbs;
+- Custom contextual link URL via model method;
+- Custom link text via model method or via I18n.
+- Custom link title via I18n with dinamic argument.
+- Custom link URL via model method;
+- Custom links via model method.
+- Generation of breadcrumb based on path navigation;
+- I18n to customize actions crumb;
+- Render aditional crumb based on some action;
+- Semantic Breadcrumb HTML from Google.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Washington Botelho
+
+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,221 @@
+# Breadcrumby
+
+[![Build Status](https://travis-ci.org/wbotelhos/breadcrumby.svg)](https://travis-ci.org/wbotelhos/breadcrumby)
+
+A solid Breadcrumb for Rails.
+You do not need to dirty your controllers with a bunch of code.
+Breadcrumby is a really relational breadcrumb.
+
+## Install
+
+```bash
+gem install breadcrumby
+```
+
+Or add the following code on your `Gemfile`:
+
+```ruby
+gem 'breadcrumby'
+```
+
+## Usage
+
+With the following example of `ActiveRecord` relations:
+
+```ruby
+class School
+  def show_path
+    "/schools/#{id}"
+  end
+end
+```
+
+```ruby
+class Course
+  belongs_to :school
+
+  def show_path
+    "/courses/#{id}"
+  end
+end
+```
+
+Let's make it know about the breadcrumb path:
+
+```ruby
+class School
+  breadcrumby
+
+  def show_path
+    "/schools/#{id}"
+  end
+end
+```
+
+Now school knows how to buid the breadcrumb but since it has no `path` it will be the last item.
+
+So, we need to teach the Course class how to follow the path until School:
+
+```ruby
+class Course
+  breadcrumby path: :school
+
+  belongs_to :school
+
+  def show_path
+    "/courses/#{id}"
+  end
+end
+```
+
+Now Breadcrumby know how to fetch the path, using the `belongs_to` relation.
+
+## View
+
+With a instance of Course that has a relation with School, we can build the breadcrumb:
+
+```ruby
+<%= breadcrumby @course %>
+```
+
+And the result will be: `Home / School / Course`
+
+## HTML
+
+Breadcrumby uses the [semantic Breadcrumb HTML from Google](https://developers.google.com/search/docs/data-types/breadcrumbs):
+
+```html
+<ol class="breadcrumby" itemscope itemtype="http://schema.org/BreadcrumbList">
+  <li itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem">
+    <a itemprop="item" itemscope itemtype="http://schema.org/Thing" title="{name}" href="{show_path}">
+      <span itemprop="name">{name}</span>
+    </a>
+
+    <meta content="1" itemprop="position">
+  </li>
+</ol>
+```
+
+- `name`: Fetched from method `name` of the model;
+- `show_path`: Fetched from method `show_path` of the model.
+
+> [I18n](I18n) configuration will always has priority over the model method.
+
+## Home
+
+As you could see, the Home crumb was generated automatically.
+You can customize the name with `I18n` and the `show_path` will be `root_path` or `/` by default.
+
+## Action
+
+You can add one last path on breadcrumb to indicate the current action you are doing, like a edition:
+
+```ruby
+class School
+  breadcrumby action: :edit
+end
+```
+
+It generates a muted link on the end: `Home / School / Edition`
+
+```ruby
+<ol class="breadcrumby" itemscope itemtype="http://schema.org/BreadcrumbList">
+  <li itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem">
+    <a itemprop="item" itemscope itemtype="http://schema.org/Thing" title="Edition" href="javascript:void(0);">
+      <span itemprop="name">Edition</span>
+    </a>
+
+    <meta content="3" itemprop="position">
+  </li>
+</ol>
+```
+
+All actions without `actions` option will try to follow `path` options.
+If it is a new object, it will have no relation and will raise error.
+
+### Custom Action Path
+
+For actions like `new` where the object will be a `new_record`, we can customize the candidate to represent the self object.
+This way we can build a minimum path, not just `Home / New`.
+Let's say you have `Unit` on session and wants to set it on breadcrumb to say you are creating a `Course` on that unit of your school:
+
+```ruby
+class Course
+  breadcrumby actions: {
+    new: -> (view) { Unit.find(view.session[:current_school][:id])
+  }
+end
+```
+
+Now the `self` object will be the `new` call result and the output will be:
+
+```ruby
+Home / School / Unit / Courses / New
+```
+
+As you can see, the path will be completed from the `self` (new result) object.
+Plus, since the new object is not `Unit`, we need a context. It will be related with original model with value of `index_path` as path:
+
+```ruby
+<a itemprop="item" itemscope="itemscope" itemtype="http://schema.org/Thing" title="List Courses" href="/courses">
+  <span itemprop="name">Turmas</span>
+</a>
+```
+
+Now it is possible to navigate to collection of items you want to create a new one.
+
+## I18n
+
+You can customize some attributes via I18n to be fast and global:
+
+```yaml
+en-US:
+  breadcrumby:
+    home:
+      name: Home
+      title: Home Page
+
+    school:
+      name: School
+      title: "School: %{name}"
+
+      actions:
+        edit: # new / index / method_name ...
+          name: Edition
+          title: "Editing: %{name}"
+```
+
+- `actions`: Properties to change the actions crumb;
+- `name`: The name of the crumb item;
+- `title`: The title of the crum item with possibility of to use the name `%{name}`.
+
+You can change the model key name, since the default search is the class method name:
+
+```ruby
+class School
+  breadcrumby i18n_key: :school_key
+end
+```
+
+And now use:
+
+```yaml
+en-US:
+  breadcrumby:
+    school_key:
+      name: School
+```
+
+To make translations more generic just take it of inside the model name and it will be used for all models:
+
+```yaml
+en-US:
+  breadcrumby:
+    actions:
+      edit:
+        name: Edition
+```
+
+## Love it!
+
+Via [PayPal](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=X8HEP2878NDEG&item_name=breadcrumby) or [Gittip](http://www.gittip.com/wbotelhos). Thanks! (:

data/lib/breadcrumby.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Breadcrumby
+end
+
+require 'breadcrumby/engine'
+require 'breadcrumby/models/extension'
+require 'breadcrumby/models/home'
+require 'breadcrumby/models/viewer'
+
+ActiveRecord::Base.include Breadcrumby::Extension

data/lib/breadcrumby/engine.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'breadcrumby/helpers/view_helper'
+
+module Breadcrumby
+  module Rails
+    class Engine < ::Rails::Engine
+      initializer 'breadcrumby.include_view_helper' do |_app|
+        ActiveSupport.on_load :action_view do
+          include ViewHelper
+        end
+      end
+    end
+  end
+end

data/lib/breadcrumby/helpers/view_helper.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Breadcrumby
+  module ViewHelper
+    def breadcrumby(object, options = {})
+      Viewer.new(object, options, self).breadcrumb
+    end
+  end
+end

data/lib/breadcrumby/models/extension.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Breadcrumby
+  module Extension
+    extend ActiveSupport::Concern
+
+    included do
+      def breadcrumby
+        path_option = breadcrumby_options[:path]
+
+        if !path_option.is_a?(Array) || path_option.blank?
+          path_option = [path_option].flatten.compact
+        end
+
+        extracting self, path_option.reverse, [self]
+      end
+
+      def breadcrumby_options
+        self.class.breadcrumby_options
+      end
+
+      private
+
+      def extract(models, index, object, objects)
+        if last_item?(models, index)
+          objects += object.breadcrumby
+        else
+          objects << object
+        end
+
+        objects
+      end
+
+      def extracting(object, models, objects)
+        return objects if models.blank?
+
+        models.each.with_index do |model, index|
+          if model.is_a? Array
+            object  = send(model.last)
+            index   = 0
+            objects = extract(model, index, object, objects)
+
+            unless last_item?(model, index)
+              extracting object, model.reverse.drop(1), objects
+            end
+          elsif !model.nil?
+            object  = object.send(model)
+            objects = extract(models, index, object, objects)
+          end
+        end
+
+        objects
+      end
+
+      def last_item?(collection, index)
+        collection.size - 1 == index
+      end
+    end
+
+    module ClassMethods
+      def breadcrumby(options = {})
+        @options = options.reverse_merge(
+          actions:     {},
+          i18n_key:    name.underscore,
+          method_name: :name
+        )
+      end
+
+      def breadcrumby_options
+        @options || {}
+      end
+    end
+  end
+end

data/lib/breadcrumby/models/home.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Breadcrumby
+  class Home
+    include Breadcrumby::Extension
+
+    def initialize(view)
+      @view = view
+    end
+
+    breadcrumby i18n_key: :home
+
+    def name
+      I18n.t 'breadcrumby.home.name', default: 'Home'
+    end
+
+    def show_path
+      return @view.root_path if @view.respond_to?(:root_path)
+
+      '/'
+    end
+  end
+end

data/lib/breadcrumby/models/viewer.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Breadcrumby
+  class Viewer
+    def initialize(object, options = {}, view = ActionController::Base.helpers)
+      @object  = object
+      @options = options
+      @view    = view
+    end
+
+    def breadcrumb
+      return '' unless @object.respond_to?(:breadcrumby)
+
+      list = breadcrumbs(current_object).map.with_index do |object, index|
+        item link(object) + meta(index + 1)
+      end
+
+      list += object_extra(list.size)
+
+      @view.content_tag :ol, list.join('').html_safe, list_options
+    end
+
+    def breadcrumbs(object)
+      items = object.breadcrumby
+      items << Breadcrumby::Home.new(@view)
+
+      items.reverse
+    end
+
+    def current_object
+      @current_object ||= begin
+        return @object if object_action.blank?
+
+        if object_action.respond_to?(:call)
+          object_action.call @view
+        else
+          object_action
+        end
+      end
+    end
+
+    def i18n_action_name(object, action)
+      label = "actions.#{action}.name"
+
+      I18n.t(label, scope: scope(object), default:
+        I18n.t(label, scope: scope(object, include_model: false), default:
+          I18n.t(action)))
+    end
+
+    def i18n_name(object)
+      I18n.t(:name,
+             scope:   scope(object),
+             default: object.send(object.breadcrumby_options[:method_name]) || '--')
+    end
+
+    def item(content, options = item_options)
+      @view.content_tag :li, content, options
+    end
+
+    def item_options
+      {
+        itemprop:  :itemListElement,
+        itemscope: true,
+        itemtype:  'http://schema.org/ListItem'
+      }
+    end
+
+    def link(object, action: nil)
+      @view.link_to(
+        link_tag_name(object, action),
+        link_action(object, action),
+        link_options(object, action)
+      )
+    end
+
+    def link_action(object, action)
+      return object.index_path if action == :index
+
+      # TODO: get current path to behaves like a refresh on the same page. @view.request.url?
+      action ? 'javascript:void(0);' : object.show_path
+    end
+
+    def link_options(object, action)
+      name       = i18n_name(object)
+      title_path = action ? "actions.#{action}.title" : :title
+      title      = I18n.t(title_path, scope: scope(object), name: name, default:
+                    I18n.t(title_path, scope: scope(object, include_model: false)))
+
+      {
+        itemprop:  :item,
+        itemscope: true,
+        itemtype:  'http://schema.org/Thing',
+        title:     title
+      }
+    end
+
+    def link_tag_name(object, action)
+      name = action ? i18n_action_name(object, action) : i18n_name(object)
+
+      @view.content_tag :span, name, link_tag_name_options
+    end
+
+    def link_tag_name_options
+      { itemprop: :name }
+    end
+
+    def list_options
+      {
+        class:     :breadcrumby,
+        itemscope: true,
+        itemtype:  'http://schema.org/BreadcrumbList'
+      }
+    end
+
+    def meta(index)
+      @view.tag :meta, content: index, itemprop: :position
+    end
+
+    def object_extra(index)
+      action = @options[:action]
+      result = []
+
+      return result if action.blank?
+
+      if @object != current_object
+        index += 1
+
+        result << item(link(@object, action: :index) + meta(index))
+      end
+
+      result << item(link(current_object, action: action) + meta(index + 1))
+
+      result
+    end
+
+    def scope(object, include_model: true)
+      result = [:breadcrumby]
+
+      result << object.breadcrumby_options[:i18n_key] if include_model
+
+      result
+    end
+
+    private
+
+    def object_action
+      @object_action ||= object_options[:actions][@options[:action]]
+    end
+
+    def object_options
+      @object.breadcrumby_options
+    end
+  end
+end