Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wbotelhos/breadcrumby
:bread: A solid Breadcrumb for Rails
https://github.com/wbotelhos/breadcrumby
breadcrumb breadcrumb-navigation breadcrumb-trail breadcrumbs rails
Last synced: 20 days ago
JSON representation
:bread: A solid Breadcrumb for Rails
- Host: GitHub
- URL: https://github.com/wbotelhos/breadcrumby
- Owner: wbotelhos
- License: mit
- Created: 2017-04-26T06:14:01.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-01-08T17:21:06.000Z (almost 7 years ago)
- Last Synced: 2024-11-29T15:53:26.241Z (23 days ago)
- Topics: breadcrumb, breadcrumb-navigation, breadcrumb-trail, breadcrumbs, rails
- Language: Ruby
- Homepage:
- Size: 63.5 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Breadcrumby
[](https://travis-ci.org/wbotelhos/breadcrumby)
[](https://badge.fury.io/rb/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
Add the following code on your `Gemfile` and run `bundle install`:
```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
```
- `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
```
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
Turmas
```
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! (: