loaf 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0cb34b106f14868575b5831d9de8255e52e94f2d
-  data.tar.gz: 8f3fdcef497c132f17cd4496b124a60b92cbc67a
+  metadata.gz: bd80cf0439e9736d7c29811f8465ac55b161e3ec
+  data.tar.gz: b42620aee3caec07147186d72fbd24eeec24102e
 SHA512:
-  metadata.gz: 568cd3729c360ab6d1aa4a8c19d9618d8d6dfb8312a57693896c940d94cddd5f4979e8f656ad0c3cd76db67b2b62c9d9f3fb0d5dce802bb2048a3dcc9d7aa344
-  data.tar.gz: 8cb65d4d05998f474f9356490f7cfe9a923b65de0e7ec8855a9bad4057f3306941a6f9bb38fea283d100e28a6349015beb79a708f84e278fe437285adef5bdab
+  metadata.gz: fe8ffab119f314dd4cc95905e0e6b0f70dbf58145740e2c07670adeb9cde9f5570fce875e3c5248b30e9c181b16a7b5b761425138f15154c2f4c55b1cc283783
+  data.tar.gz: 1df8f9471b34d22ca69fb606dba529ba05dc65903329461aea28a1044c11bb1b10f655c1bbc9279062723513ad36b8a5c74673b85e6670f8c9c12bb4e8bb18db

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+0.5.0 (January 31, 2015)
+
+* Add generator for locales file
+* Add breadcrumbs scope for translations
+* Change breadcrumb formatter to use translations for title formatting
+* Add ability to pass proc as title and/or url for breadcrumb helper inside controller
+
 0.4.0 (January 10, 2015)
 
 * Change breadcrumbs view method to return enumerator without block

data/Gemfile

@@ -2,6 +2,7 @@ source 'https://rubygems.org'
 
 gemspec
 
+gem 'ammeter', '~> 1.1.2'
 gem 'bundler', '~> 1.3'
 gem 'appraisal', '~> 1.0.2'
 gem 'rake',     '~> 10.4.2'

data/README.md

@@ -18,8 +18,9 @@
 ## Features
 
 * Uses controllers or views to specify breadcrumb trails
+* Specify urls using Rails conventions
 * No markup assumptions for breadcrumbs rendering
-* Use locales file for names - optional
+* Use locales file for breadcrumb names
 * Tested with Rails 3.2, 4.0, 4.1, 4.2
 
 ## Installation
@@ -42,11 +43,17 @@ Or install it yourself as:
 gem install loaf
 ```
 
+Then run the generator:
+
+```ruby
+rails generate loaf:install
+```
+
 ## 1. Usage
 
 **Loaf** allows you to add breadcrumbs in controllers and views.
 
-In order to add breadcrumbs in controller use `breadcrumb` method. Outside of controller actions the `breadcrumb` helper behaviour is similar to filters and as such you can limit breadcrumb scope with familiar options `:only`, `:except`. Any breadcrumb specified inside actions creates another level in breadcrumbs trail.
+In order to add breadcrumbs in controller use `breadcrumb` method ([see 1.1](#11-breadcrumb)). Outside of controller actions the `breadcrumb` helper behaviour is similar to filters and as such you can limit breadcrumb scope with familiar options `:only`, `:except`. Any breadcrumb specified inside actions creates another level in breadcrumbs trail.
 
 ```ruby
 class Blog::CategoriesController < ApplicationController
@@ -54,15 +61,15 @@ class Blog::CategoriesController < ApplicationController
   breadcrumb 'Article Categories', :blog_categories_path, only: [:show]
 
   def show
-    breadcrumb "#{@category.title}", blog_category_path(@category)
+    breadcrumb @category.title, blog_category_path(@category)
   end
 end
 ```
 
-**Loaf** adds `breadcrumb` helper also to the views. Together with controller breadcrumbs, the view breadcrumbs are appended as the last. For instance, to specify view breadcrumb do:
+**Loaf** adds `breadcrumb` helper also to the views. Together with controller breadcrumbs, the view breadcrumbs are appended as the last in breadcrumb trail. For instance, to specify view breadcrumb do:
 
 ```ruby
-<% breadcrumb "#{@category.title}", blog_category_path(@category) %>
+<% breadcrumb @category.title, blog_category_path(@category) %>
 ```
 
 Finally, in your view layout add semantic markup to show breadcrumbs:
@@ -80,6 +87,85 @@ Finally, in your view layout add semantic markup to show breadcrumbs:
 
 Usually best practice is to put such snippet inside its own partial.
 
+### 1.1 breadcrumb
+
+Creation of breadcrumb in Rails is achieved by the `breadcrumb` helper.
+
+The `breadcrumb` method takes at minimum two arguments: the first is a name for the crumb that will be displayed and the second is a url that the name points to. The url parameter uses the familiar Rails conventions.
+
+When using path variable `blog_categories_path`:
+
+```ruby
+breadcrumb 'Categories', blog_categories_path
+```
+
+When using an instance `@category`:
+
+```ruby
+breadcrumb @category.title, blog_category_path(@category)
+```
+
+You can also use set of objects:
+
+```ruby
+breadcrumb @category.title, [:blog, @category]
+```
+
+You can specify segments of the url:
+
+```ruby
+breadcrumb @category.title, {controller: 'categories', action: 'show', id: @category.id}
+```
+
+#### 1.1.1 breadcrumb in controller
+
+Breadcrumbs are inherited, so if you set a breadcrumb in `ApplicationController`, it will be inserted as a first element inside every breadcrumb trail. It is customary to set root breadcrumb like so:
+
+```ruby
+class ApplicationController < ActionController::Base
+  breadcrumb 'Home', :root_path
+end
+```
+
+In controller outside of any action the `breadcrumb` acts as filter.
+
+```ruby
+class ArticlesController < ApplicationController
+  breadcrumb 'All Articles', :articles_path, only: [:new, :create]
+end
+```
+
+**Loaf** allows you to call controller instance methods inside the `breadcrumb` helper outside of any action. This is useful if your breadcrumb has parameterized behaviour. For example, to dynamically evaluate parameters for breadcrumb title do:
+
+```ruby
+class CommentsController < ApplicationController
+  breadcrumb ->(c) { c.find_article(c.params[:post_id]).title }, :articles_path
+end
+```
+
+Also, to dynamically evalute parameters inside the url argument do:
+
+```ruby
+class CommentsController < ApplicationController
+  breadcrumb 'All Comments', ->(c) { c.post_comments_path(c.params[:post_id]) }
+end
+```
+
+### 1.2 force
+
+**Loaf** allows you to force a breadcrumb to be current.
+
+For example, on the create action as you are likely want the breadcrumb to be similar as for new action.
+
+```ruby
+class PostsController < ApplicationController
+  def create
+    breadcrumb 'New Post', new_post_path, force: true
+    render action: :new
+  end
+end
+```
+
 ## 2. Configuration
 
 There is a small set of custom opinionated defaults. The following options are valid parameters:
@@ -108,32 +194,33 @@ Loaf.configure do |config|
 end
 ```
 
-## 3. Locale
+## 3. Translation
 
-When adding breadcrumbs one can use locales for their titles. The only assumption it makes is that all breadcrumb names are scoped inside `breadcrumbs` namespace. However, this can be easily changed by passing `:scope => 'new_scope_name'` configuration option
+You can use locales files for breadcrumbs' titles. **Loaf** assumes that all breadcrumb names are scoped inside `breadcrumbs` namespace inside `loaf` scope. However, this can be easily changed by passing `scope: 'new_scope_name'` configuration option.
 
 ```ruby
 en:
-  breadcrumbs:
-    controller:
-      action:
+  loaf:
+    breadcrumbs:
+      name: 'my-breadcrumb-name'
 ```
 
-Therefore in your controller/view one would have
+Therefore, in your controller/view you would do:
 
 ```ruby
 class Blog::CategoriesController < ApplicationController
-
-  breadcrumb 'blog.categories', 'blog_categories_path'
-
+  breadcrumb 'blog.categories', :blog_categories_path
 end
+```
 
-And corresponding entry in locale:
+And corresponding entry in locale would be:
 
+```ruby
 en:
-  breadcrumbs:
-    blog:
-      categories: 'Article Categories'
+  loaf:
+    breadcrumbs:
+      blog:
+        categories: 'Article Categories'
 ```
 
 ## Contributing

data/config/locales/loaf.en.yml

@@ -0,0 +1,6 @@
+en:
+  loaf:
+    errors:
+      invalid_options: "Invalid option :%{invalid}. Valid options are: %{valid}, make sure these are the ones you are using."
+    breadcrumbs:
+      home: 'Home'

data/gemfiles/rails3.2.gemfile

@@ -2,9 +2,10 @@
 
 source "https://rubygems.org"
 
+gem "ammeter"
 gem "bundler", "~> 1.3"
 gem "appraisal", "~> 1.0.2"
-gem "rake", "~> 10.3.2"
+gem "rake", "~> 10.4.2"
 gem "yard", "~> 0.8.7"
 gem "sqlite3", "~> 1.3.10", :platforms => :ruby
 gem "activerecord-jdbcsqlite3-adapter", "~> 1.3.10", :platforms => :jruby

data/gemfiles/rails4.0.gemfile

@@ -2,9 +2,10 @@
 
 source "https://rubygems.org"
 
+gem "ammeter"
 gem "bundler", "~> 1.3"
 gem "appraisal", "~> 1.0.2"
-gem "rake", "~> 10.3.2"
+gem "rake", "~> 10.4.2"
 gem "yard", "~> 0.8.7"
 gem "sqlite3", "~> 1.3.10", :platforms => :ruby
 gem "activerecord-jdbcsqlite3-adapter", "~> 1.3.10", :platforms => :jruby

data/gemfiles/rails4.1.gemfile

@@ -2,9 +2,10 @@
 
 source "https://rubygems.org"
 
+gem "ammeter"
 gem "bundler", "~> 1.3"
 gem "appraisal", "~> 1.0.2"
-gem "rake", "~> 10.3.2"
+gem "rake", "~> 10.4.2"
 gem "yard", "~> 0.8.7"
 gem "sqlite3", "~> 1.3.10", :platforms => :ruby
 gem "activerecord-jdbcsqlite3-adapter", "~> 1.3.10", :platforms => :jruby

data/gemfiles/rails4.2.gemfile

@@ -2,9 +2,10 @@
 
 source "https://rubygems.org"
 
+gem "ammeter"
 gem "bundler", "~> 1.3"
 gem "appraisal", "~> 1.0.2"
-gem "rake", "~> 10.3.2"
+gem "rake", "~> 10.4.2"
 gem "yard", "~> 0.8.7"
 gem "sqlite3", "~> 1.3.10", :platforms => :ruby
 gem "activerecord-jdbcsqlite3-adapter", "~> 1.3.10", :platforms => :jruby

data/lib/generators/loaf/install_generator.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+
+require 'rails/generators'
+
+module Loaf
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../..", __FILE__)
+
+      desc 'Copy locale file to your application'
+
+      def copy_locale
+        copy_file "#{self.class.source_root}/config/locales/loaf.en.yml", "config/locales/loaf.en.yml"
+      end
+    end # InstallGenerator
+  end # Generators
+end # Loaf

data/lib/loaf.rb

@@ -11,9 +11,6 @@ require 'loaf/view_extensions'
 require 'loaf/crumb_formatter'
 require 'loaf/options_validator'
 
-# Add English load path by default
-I18n.load_path << File.join(File.dirname(__FILE__), 'config', 'locales', 'en.yml')
-
 module Loaf
   # Set global configuration
   #

data/lib/loaf/controller_extensions.rb

@@ -12,26 +12,29 @@ module Loaf
     end
 
     module ClassMethods
+      # Add breacrumb to the trail in controller as class method
+      #
       # @param [String]
       #
       # @api public
       def breadcrumb(name, url, options = {})
+        normalizer = method(:_normalize_name)
         before_filter(options) do |instance|
-          # instance.send(:add_breadcrumb, _normalize_name(name), url)
-          instance.send(:breadcrumb, name, url, options)
+          normalized_name = normalizer.call(name, instance)
+          normalized_url  = normalizer.call(url, instance)
+          instance.send(:breadcrumb, normalized_name, normalized_url, options)
         end
       end
       alias_method :add_breadcrumb, :breadcrumb
 
       private
 
-      def _normalize_name(name=nil)
+      # @api private
+      def _normalize_name(name, instance)
         case name
         when NilClass
         when Proc
-          name.call
-        when Symbol
-          name.to_s
+          name.call(instance)
         else
           name
         end
@@ -57,7 +60,7 @@ module Loaf
         end
       end
 
-      # Add breadcrumb
+      # Add breadcrumb in controller as instance method
       #
       # @param [String] name
       #

data/lib/loaf/crumb_formatter.rb

@@ -8,9 +8,10 @@ module Loaf
     #
     # @api public
     def format_name(name, options = {})
-      return if name.nil?
+      return name if name.nil? || name.empty?
 
       formatted = name.to_s.dup
+      formatted = Loaf::Translation.find_title(formatted)
       formatted = formatted.capitalize if options[:capitalize]
       if options[:crumb_length]
         formatted = truncate(formatted, length: options[:crumb_length])

data/lib/loaf/errors.rb

@@ -5,7 +5,7 @@ module Loaf #:nodoc:
   # Default Loaf error for all custom errors.
   #
   class LoafError < StandardError
-    BASE_KEY = "loaf.errors.messages"
+    BASE_KEY = "loaf.errors"
 
     def error_message(key, attributes)
       translate(key, attributes)

data/lib/loaf/translation.rb

@@ -5,8 +5,8 @@ module Loaf
     extend self
 
     # Returns translation lookup
-    def i18n_scope
-      :breadcrumbs
+    def translation_scope
+      "loaf.breadcrumbs"
     end
 
     # Translate breadcrumb title
@@ -19,13 +19,11 @@ module Loaf
     #   The default translation
     #
     # @api public
-    def breadcrumb_title(title, options = {})
-      defaults  = []
-      defaults << :"#{i18n_scope}.#{title}"
-      defaults << options.delete(:default) if options[:default]
-
-      options.reverse_merge! count: 1, default: defaults
-      I18n.t(title, options)
+    def find_title(title, options = {})
+      options[:scope] ||= translation_scope
+      options[:default] = Array(options[:default])
+      options[:default] << title if options[:default].empty?
+      I18n.t("#{title}", options)
     end
   end # Translation
 end # Loaf

data/lib/loaf/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module Loaf
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end # Loaf

data/spec/integration/crumbs_routing_spec.rb

@@ -33,7 +33,7 @@ RSpec.describe "crumbs routing" do
     end
   end
 
-  it 'should be current when forced' do
+  it 'is current when forced' do
     visit new_post_path
     click_button "Create"
 
@@ -43,4 +43,11 @@ RSpec.describe "crumbs routing" do
       expect(page).to have_selector('.selected')
     end
   end
+
+  it "allows for procs in name and url" do
+    visit post_comments_path(1)
+    within '#breadcrumbs' do
+      expect(page.html).to include('<a href="/posts/1/comments">Post comments</a>')
+    end
+  end
 end

data/spec/rails_app/app/controllers/comments_controller.rb

@@ -1,4 +1,17 @@
+class Article < Struct.new(:id, :title); end
+
 class CommentsController < ApplicationController
+
+  breadcrumb lambda { |c| c.find_article(c.params[:post_id]).title },
+             lambda { |c| c.post_comments_path(c.params[:post_id]) }
+
   def index
   end
+
+  def show
+  end
+
+  def find_article(id)
+    ::Article.new(id, 'Post comments')
+  end
 end

data/spec/rails_app/app/controllers/posts_controller.rb

@@ -5,7 +5,7 @@ class PostsController < ApplicationController
   breadcrumb 'Home', :root_path, only: :index
 
   def index
-    breadcrumb 'All Posts', posts_path
+    breadcrumb 'all_posts', posts_path
   end
 
   def show

data/spec/rails_app/app/views/comments/index.html.erb

@@ -0,0 +1 @@
+<h1>Post comments index</h1>

data/spec/rails_app/config/locales/loaf.en.yml

@@ -0,0 +1,6 @@
+en:
+  loaf:
+    errors:
+      invalid_options: "Invalid option :%{invalid}. Valid options are: %{valid}, make sure these are the ones you are using."
+    breadcrumbs:
+      all_posts: 'All Posts'

data/spec/spec_helper.rb

@@ -18,9 +18,8 @@ end
 # Configure Rails Environment
 ENV["RAILS_ENV"] = "test"
 
-require File.expand_path("../rails_app/config/environment.rb",  __FILE__)
+require 'rails_app/config/environment.rb'
 require 'rspec/rails'
-
 require 'loaf'
 
 Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}

data/spec/support/capybara.rb

@@ -2,9 +2,7 @@ require 'capybara/rails'
 require 'capybara/dsl'
 
 RSpec.configure do |c|
-  c.include Capybara::DSL, :example_group => {
-    :file_path => /\bspec\/integration\//
-  }
+  c.include Capybara::DSL, :file_path => /\bspec\/integration\//
 end
 Capybara.default_driver   = :rack_test
 Capybara.default_selector = :css

data/spec/support/load_routes.rb

@@ -1,6 +1,4 @@
 RSpec.configure do |c|
   c.include Rails.application.routes.url_helpers,
-    :example_group => {
-      :file_path => /\bspec\/integration\//
-    }
+  :file_path => /\bspec\/integration\//
 end

data/spec/unit/generators/install_generator_spec.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+require 'spec_helper'
+require 'generators/loaf/install_generator'
+
+RSpec.describe Loaf::Generators::InstallGenerator, type: :generator do
+  destination File.expand_path("../../../tmp", __FILE__)
+
+  before { prepare_destination }
+
+  it "copies loaf locales to the host application" do
+    run_generator
+    locale = file("config/locales/loaf.en.yml")
+    expect(locale).to exist
+  end
+end

data/spec/unit/translation_spec.rb

@@ -6,17 +6,19 @@ RSpec.describe Loaf::Translation do
 
   before { I18n.backend = I18n::Backend::Simple.new }
 
+  after { I18n.backend.reload! }
+
   it 'translates breadcrumb title' do
-    I18n.backend.store_translations 'en', breadcrumbs: { home: 'Home'}
-    expect(described_class.breadcrumb_title('breadcrumbs.home')).to eql('Home')
+    I18n.backend.store_translations 'en', loaf: { breadcrumbs: { home: 'Home'}}
+    expect(described_class.find_title('home')).to eql('Home')
   end
 
-  it 'translates breadcrumb name with default scope' do
+  it 'does not translates breadcrumb name with missing scope' do
     I18n.backend.store_translations 'en', breadcrumbs: {home: 'Home'}
-    expect(described_class.breadcrumb_title('home')).to eql('Home')
+    expect(described_class.find_title('home')).to eql('home')
   end
 
   it 'translates breadcrumb name using default option' do
-    expect(described_class.breadcrumb_title('home', default: 'breadcrumb default name')).to eql('breadcrumb default name')
+    expect(described_class.find_title('home', default: 'breadcrumb default name')).to eql('breadcrumb default name')
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: loaf
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Piotr Murach
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-10 00:00:00.000000000 Z
+date: 2015-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -46,12 +46,13 @@ files:
 - README.md
 - Rakefile
 - bin/setup
+- config/locales/loaf.en.yml
 - gemfiles/rails3.2.gemfile
 - gemfiles/rails4.0.gemfile
 - gemfiles/rails4.1.gemfile
 - gemfiles/rails4.2.gemfile
 - init.rb
-- lib/config/locales/en.yml
+- lib/generators/loaf/install_generator.rb
 - lib/loaf.rb
 - lib/loaf/builder.rb
 - lib/loaf/configuration.rb
@@ -73,6 +74,7 @@ files:
 - spec/rails_app/app/controllers/comments_controller.rb
 - spec/rails_app/app/controllers/home_controller.rb
 - spec/rails_app/app/controllers/posts_controller.rb
+- spec/rails_app/app/views/comments/index.html.erb
 - spec/rails_app/app/views/home/index.html.erb
 - spec/rails_app/app/views/layouts/_breadcrumbs.html.erb
 - spec/rails_app/app/views/layouts/application.html.erb
@@ -94,6 +96,7 @@ files:
 - spec/rails_app/config/initializers/session_store.rb
 - spec/rails_app/config/initializers/wrap_parameters.rb
 - spec/rails_app/config/locales/en.yml
+- spec/rails_app/config/locales/loaf.en.yml
 - spec/rails_app/config/routes.rb
 - spec/rails_app/db/seeds.rb
 - spec/rails_app/lib/assets/.gitkeep
@@ -111,6 +114,7 @@ files:
 - spec/support/load_routes.rb
 - spec/unit/controller_extensions_spec.rb
 - spec/unit/crumb_formatter_spec.rb
+- spec/unit/generators/install_generator_spec.rb
 - spec/unit/options_validator_spec.rb
 - spec/unit/translation_spec.rb
 - spec/unit/view_extensions/breadcrumb_spec.rb
@@ -151,6 +155,7 @@ test_files:
 - spec/rails_app/app/controllers/comments_controller.rb
 - spec/rails_app/app/controllers/home_controller.rb
 - spec/rails_app/app/controllers/posts_controller.rb
+- spec/rails_app/app/views/comments/index.html.erb
 - spec/rails_app/app/views/home/index.html.erb
 - spec/rails_app/app/views/layouts/_breadcrumbs.html.erb
 - spec/rails_app/app/views/layouts/application.html.erb
@@ -172,6 +177,7 @@ test_files:
 - spec/rails_app/config/initializers/session_store.rb
 - spec/rails_app/config/initializers/wrap_parameters.rb
 - spec/rails_app/config/locales/en.yml
+- spec/rails_app/config/locales/loaf.en.yml
 - spec/rails_app/config/routes.rb
 - spec/rails_app/db/seeds.rb
 - spec/rails_app/lib/assets/.gitkeep
@@ -189,6 +195,7 @@ test_files:
 - spec/support/load_routes.rb
 - spec/unit/controller_extensions_spec.rb
 - spec/unit/crumb_formatter_spec.rb
+- spec/unit/generators/install_generator_spec.rb
 - spec/unit/options_validator_spec.rb
 - spec/unit/translation_spec.rb
 - spec/unit/view_extensions/breadcrumb_spec.rb

data/lib/config/locales/en.yml

@@ -1,6 +0,0 @@
-en:
-  loaf:
-    errors:
-      messages:
-        invalid_options: "Invalid option :%{invalid}. Valid options are: %{valid},          make sure these are the ones you are using."
-