loaf 0.5.0 → 0.6.0

data/README.md

@@ -1,27 +1,32 @@
+<div align="center">
+  <img width="237" src="https://cdn.rawgit.com/piotrmurach/loaf/master/assets/loaf_logo.png" alt="loaf logo" />
+</div>
+
 # Loaf
-[![Gem Version](https://badge.fury.io/rb/loaf.png)][gem]
-[![Build Status](https://secure.travis-ci.org/peter-murach/loaf.png?branch=master)][travis]
-[![Code Climate](https://codeclimate.com/github/peter-murach/loaf.png)][codeclimate]
-[![Dependency Status](https://gemnasium.com/peter-murach/loaf.png?travis)][gemnasium]
-[![Coverage Status](https://coveralls.io/repos/peter-murach/loaf/badge.png?branch=master)][coveralls]
-[![Inline docs](http://inch-ci.org/github/peter-murach/loaf.png?branch=master)][inchpages]
+
+[![Gem Version](https://badge.fury.io/rb/loaf.svg)][gem]
+[![Build Status](https://secure.travis-ci.org/piotrmurach/loaf.svg?branch=master)][travis]
+[![Code Climate](https://codeclimate.com/github/piotrmurach/loaf/badges/gpa.svg)][codeclimate]
+[![Dependency Status](https://gemnasium.com/piotrmurach/loaf.svg?travis)][gemnasium]
+[![Coverage Status](https://coveralls.io/repos/github/piotrmurach/loaf/badge.svg?branch=master)][coveralls]
+[![Inline docs](http://inch-ci.org/github/piotrmurach/loaf.svg?branch=master)][inchpages]
 
 [gem]: http://badge.fury.io/rb/loaf
-[travis]: http://travis-ci.org/peter-murach/loaf
-[codeclimate]: https://codeclimate.com/github/peter-murach/loaf
-[gemnasium]: https://gemnasium.com/peter-murach/loaf
-[coveralls]: https://coveralls.io/r/peter-murach/loaf
-[inchpages]: http://inch-ci.org/github/peter-murach/loaf
+[travis]: http://travis-ci.org/piotrmurach/loaf
+[codeclimate]: https://codeclimate.com/github/piotrmurach/loaf
+[gemnasium]: https://gemnasium.com/piotrmurach/loaf
+[coveralls]: https://coveralls.io/github/piotrmurach/loaf
+[inchpages]: http://inch-ci.org/github/piotrmurach/loaf
 
 > **Loaf** manages and displays breadcrumb trails in your Rails application.
 
 ## Features
 
-* Uses controllers or views to specify breadcrumb trails
+* Use controllers and/or views to specify breadcrumb trails
 * Specify urls using Rails conventions
-* No markup assumptions for breadcrumbs rendering
+* No markup assumptions for breadcrumbs trails rendering
 * Use locales file for breadcrumb names
-* Tested with Rails 3.2, 4.0, 4.1, 4.2
+* Tested with Rails `>= 3.2` and Ruby `>= 2.0.0`
 
 ## Installation
 
@@ -49,11 +54,23 @@ Then run the generator:
 rails generate loaf:install
 ```
 
+## Contents
+
+* [1. Usage](#1-usage)
+* [2. API](#2-api)
+  * [2.1 breadcrumb](#21-breadcrumb)
+    * [2.1.1 controller](#211-controller)
+    * [2.1.2 view](#212-view)
+    * [2.1.3 :match](#213-match)
+  * [2.2 breadcrumb_trail](#22-breadcrumb_trail)
+* [3. Configuration](#3-configuration)
+* [4. Translation](#4-translation)
+
 ## 1. Usage
 
 **Loaf** allows you to add breadcrumbs in controllers and views.
 
-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.
+In order to add breadcrumbs in controller use `breadcrumb` method ([see 2.1](#21-breadcrumb)).
 
 ```ruby
 class Blog::CategoriesController < ApplicationController
@@ -66,28 +83,11 @@ class Blog::CategoriesController < ApplicationController
 end
 ```
 
-**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) %>
-```
-
-Finally, in your view layout add semantic markup to show breadcrumbs:
+Then in your view render the breadcrumbs trail using [breadcrumb_trail](#22-breadcrumb_trail)
 
-```html
-<ul class='breadcrumbs'>
-  <% breadcrumbs do |name, url, styles| %>
-    <li class="<%= styles %>">
-      <%= link_to name, url %>
-      <span><%= styles == 'selected' ? '' : '::' %></span>
-    </li>
-  <% end %>
-</ul>
-```
+## 2. API
 
-Usually best practice is to put such snippet inside its own partial.
-
-### 1.1 breadcrumb
+### 2.1 breadcrumb
 
 Creation of breadcrumb in Rails is achieved by the `breadcrumb` helper.
 
@@ -117,7 +117,7 @@ You can specify segments of the url:
 breadcrumb @category.title, {controller: 'categories', action: 'show', id: @category.id}
 ```
 
-#### 1.1.1 breadcrumb in controller
+#### 2.1.1 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:
 
@@ -127,7 +127,7 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-In controller outside of any action the `breadcrumb` acts as filter.
+Outside of controller actions the `breadcrumb` helper behaviour is similar to filters/actions 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 ArticlesController < ApplicationController
@@ -135,6 +135,20 @@ class ArticlesController < ApplicationController
 end
 ```
 
+Each time you call the `breadcrumb` helper, a new element is added to a breadcrumb trial stack:
+
+```ruby
+class ArticlesController < ApplicationController
+  breadcrumb 'Home', :root_path
+  breadcrumb 'All Articles', :articles_path
+
+  def show
+    breadcrumb 'Article One', article_path(:one)
+    breadcrumb 'Article Two', article_path(:two)
+  end
+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
@@ -151,42 +165,92 @@ class CommentsController < ApplicationController
 end
 ```
 
-### 1.2 force
+#### 2.1.2 view
 
-**Loaf** allows you to force a breadcrumb to be current.
+**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:
 
-For example, on the create action as you are likely want the breadcrumb to be similar as for new action.
+```ruby
+<% breadcrumb @category.title, blog_category_path(@category) %>
+```
+
+#### 2.1.3 :match
+
+**Loaf** allows you to define matching conditions in order to make a breadcrumb current with the `:match` option.
+
+The `:match` key accepts the following values:
+
+* `:inclusive` - the default value, which matches nested paths
+* `:exact` - matches only the exact same path
+* `:exclusive` - matches only direct path and its query params if present
+* `/regex/` - matches based on regular expression
+* `{foo: bar}` - match based on query params
+
+For example, to force a breadcrumb to be the current regardless do:
 
 ```ruby
-class PostsController < ApplicationController
-  def create
-    breadcrumb 'New Post', new_post_path, force: true
-    render action: :new
-  end
+breadcrumb 'New Post', new_post_path, match: :exact
+```
+
+To make a breadcrumb current based on the query params do:
+
+```ruby
+breadcrumb 'Posts', posts_path(order: :desc), match: {order: :desc}
+```
+
+### 2.2 breadcrumb_trail
+
+In order to display breadcrumbs use the `breadcrumb_trail` view helper which as an argument accepts options and yeilds all breadcrumbs to a block:
+
+```ruby
+breadcrumb_trail do |crumb|
+  ...
 end
 ```
 
-## 2. Configuration
+The yielded pararmeter is a `Loaf::Crumb` object that provides the following methods:
+
+```ruby
+crumb.name     # => the name as string
+crumb.path     # => the path as string
+crumb.url      # => alias for path
+crumb.current? # => true or false
+```
+
+For example, you can add the following semantic markup to show breadcrumbs using the `breadcrumb_trail` helper like so:
+
+```erb
+<nav aria-label="Breadcrumb">
+  <ol class='breadcrumbs'>
+    <% breadcrumb_trail do |crumb| %>
+      <li class="<%= crumb.current? ? 'current' : '' %>">
+        <%= link_to crumb.name, crumb.url, (crumb.current? ? {'aria-current' => 'page'} : {}) %>
+        <% unless crumb.current? %><span>::</span><% end %>
+      </li>
+    <% end %>
+  </ol>
+</nav>
+```
+
+Usually best practice is to put such snippet inside its own partial.
+
+## 3. Configuration
 
 There is a small set of custom opinionated defaults. The following options are valid parameters:
 
 ```ruby
-:crumb_length  # breadcrumb length in integer, default length is 30 characters
-:root          # boolean, default is true, displays the home crumb
 :capitalize    # set breadcrumbs to have initial letter uppercase, default false
-:style_classes # CSS class to be used to style current breadcrumb,
-               # defaults to 'selected'
+:crumb_length  # breadcrumb length in integer, default length is 30 characters
 ```
 
 You can override them in your views by passing them to the view `breadcrumb` helper
 
-```ruby
-<% breadcrumbs crumb_length: 20 do |name, url, styles| %>
+```erb
+<% breadcrumb_trail crumb_length: 20 do |name, url, styles| %>
   ..
 <% end %>
 ```
 
-or by adding initializer in `config/initializers/loaf.rb`:
+or by configuring an option in `config/initializers/loaf.rb`:
 
 ```ruby
 Loaf.configure do |config|
@@ -194,7 +258,7 @@ Loaf.configure do |config|
 end
 ```
 
-## 3. Translation
+## 4. Translation
 
 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.
 
@@ -225,8 +289,8 @@ en:
 
 ## Contributing
 
-Questions or problems? Please post them on the [issue tracker](https://github.com/peter-murach/loaf/issues). You can contribute changes by forking the project and submitting a pull request. You can ensure the tests are passing by running `bundle` and `rake`.
+Questions or problems? Please post them on the [issue tracker](https://github.com/piotrmurach/loaf/issues). You can contribute changes by forking the project and submitting a pull request. You can ensure the tests are passing by running `bundle` and `rake`.
 
 ## Copyright
 
-Copyright (c) 2011-2015 Piotr Murach. See LICENSE.txt for further details.
+Copyright (c) 2011-2017 Piotr Murach. See LICENSE.txt for further details.

data/bin/appraisal

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'appraisal' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("appraisal", "appraisal")

data/bin/rake

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/gemfiles/rails3.2.gemfile

@@ -2,21 +2,23 @@
 
 source "https://rubygems.org"
 
-gem "ammeter"
-gem "bundler", "~> 1.3"
-gem "appraisal", "~> 1.0.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
-gem "capybara", "~> 2.4.4"
-gem "rspec-rails", "~> 3.1.0"
-gem "rails", "~> 3.2.21"
+gem "ammeter", "~> 1.1.4"
+gem "appraisal", "~> 2.2.0"
+gem "yard", "~> 0.9.9"
+gem "capybara", "~> 2.15.4"
+gem "rspec-rails", "~> 3.6.1"
+gem "nokogiri", "~> 1.6.8"
+gem "public_suffix", "~> 2.0.5"
+gem "sqlite3", "~> 1.3.13", platforms: :ruby
+gem "activerecord-jdbcsqlite3-adapter", "~> 1.3.23", platforms: :jruby
+gem "rails", "~> 3.2.22.5"
+gem "test-unit"
+gem "mime-types", "~> 2.99"
 
 group :metrics do
-  gem "coveralls", "~> 0.7.2"
-  gem "simplecov", "~> 0.9.1"
+  gem "coveralls", "0.8.17"
+  gem "simplecov", "~> 0.12.0"
   gem "yardstick", "~> 0.9.9"
 end
 
-gemspec :path => "../"
+gemspec path: "../"

data/gemfiles/rails4.0.gemfile

@@ -2,22 +2,23 @@
 
 source "https://rubygems.org"
 
-gem "ammeter"
-gem "bundler", "~> 1.3"
-gem "appraisal", "~> 1.0.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
-gem "capybara", "~> 2.4.4"
-gem "rspec-rails", "~> 3.1.0"
+gem "ammeter", "~> 1.1.4"
+gem "appraisal", "~> 2.2.0"
+gem "yard", "~> 0.9.9"
+gem "capybara", "~> 2.15.4"
+gem "rspec-rails", "~> 3.6.1"
+gem "nokogiri", "~> 1.6.8"
+gem "public_suffix", "~> 2.0.5"
+gem "sqlite3", "~> 1.3.13", platforms: :ruby
+gem "activerecord-jdbcsqlite3-adapter", "~> 1.3.23", platforms: :jruby
 gem "rails", "~> 4.0.13"
 gem "test-unit"
+gem "mime-types", "~> 2.99"
 
 group :metrics do
-  gem "coveralls", "~> 0.7.2"
-  gem "simplecov", "~> 0.9.1"
+  gem "coveralls", "0.8.17"
+  gem "simplecov", "~> 0.12.0"
   gem "yardstick", "~> 0.9.9"
 end
 
-gemspec :path => "../"
+gemspec path: "../"

data/gemfiles/rails4.1.gemfile

@@ -2,21 +2,22 @@
 
 source "https://rubygems.org"
 
-gem "ammeter"
-gem "bundler", "~> 1.3"
-gem "appraisal", "~> 1.0.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
-gem "capybara", "~> 2.4.4"
-gem "rspec-rails", "~> 3.1.0"
-gem "rails", "~> 4.1.9"
+gem "ammeter", "~> 1.1.4"
+gem "appraisal", "~> 2.2.0"
+gem "yard", "~> 0.9.9"
+gem "capybara", "~> 2.15.4"
+gem "rspec-rails", "~> 3.6.1"
+gem "nokogiri", "~> 1.6.8"
+gem "public_suffix", "~> 2.0.5"
+gem "sqlite3", "~> 1.3.13", platforms: :ruby
+gem "activerecord-jdbcsqlite3-adapter", "~> 1.3.23", platforms: :jruby
+gem "rails", "~> 4.1.16"
+gem "mime-types", "~> 2.99"
 
 group :metrics do
-  gem "coveralls", "~> 0.7.2"
-  gem "simplecov", "~> 0.9.1"
+  gem "coveralls", "0.8.17"
+  gem "simplecov", "~> 0.12.0"
   gem "yardstick", "~> 0.9.9"
 end
 
-gemspec :path => "../"
+gemspec path: "../"

data/gemfiles/rails4.2.gemfile

@@ -2,21 +2,22 @@
 
 source "https://rubygems.org"
 
-gem "ammeter"
-gem "bundler", "~> 1.3"
-gem "appraisal", "~> 1.0.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
-gem "capybara", "~> 2.4.4"
-gem "rspec-rails", "~> 3.1.0"
-gem "rails", "~> 4.2.0"
+gem "ammeter", "~> 1.1.4"
+gem "appraisal", "~> 2.2.0"
+gem "yard", "~> 0.9.9"
+gem "capybara", "~> 2.15.4"
+gem "rspec-rails", "~> 3.6.1"
+gem "nokogiri", "~> 1.6.8"
+gem "public_suffix", "~> 2.0.5"
+gem "sqlite3", "~> 1.3.13", platforms: :ruby
+gem "activerecord-jdbcsqlite3-adapter", "~> 1.3.23", platforms: :jruby
+gem "rails", "~> 4.2.9"
+gem "mime-types", "~> 2.99"
 
 group :metrics do
-  gem "coveralls", "~> 0.7.2"
-  gem "simplecov", "~> 0.9.1"
+  gem "coveralls", "0.8.17"
+  gem "simplecov", "~> 0.12.0"
   gem "yardstick", "~> 0.9.9"
 end
 
-gemspec :path => "../"
+gemspec path: "../"