Skip to content

Commit 5ed1c5c

Browse files
wepposweppos
committed
Move the docs to the README
1 parent f9775d8 commit 5ed1c5c

File tree

1 file changed

+173
-46
lines changed

1 file changed

+173
-46
lines changed

‎README.md

Lines changed: 173 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
## Requirements
88

9-
- Rails 3 or Rails 4
9+
- Rails >= 3 or Rails 4
1010

1111
Please note
1212

@@ -16,7 +16,7 @@ Please note
1616

1717
## Installation
1818

19-
[RubyGems](http://rubygems.org) is the preferred way to install <tt>BreadcrumbsOnRails</tt> and the best way if you want install a stable version.
19+
[RubyGems](https://rubygems.org) is the preferred way to install <tt>BreadcrumbsOnRails</tt> and the best way if you want install a stable version.
2020

2121
$ gem install breadcrumbs_on_rails
2222

@@ -27,69 +27,197 @@ Specify the Gem dependency in the [Bundler](http://bundler.io/) `Gemfile`.
2727
Use [Bundler](http://bundler.io/) and the `:git` option if you want to grab the latest version from the Git repository.
2828

2929

30-
## Basic Usage
30+
## Usage
3131

3232
Creating a breadcrumb navigation menu in your Rails app using <tt>BreadcrumbsOnRails</tt> is really straightforward.
3333

3434
In your controller, call `add_breadcrumb` to push a new element on the breadcrumb stack. `add_breadcrumb` requires two arguments: the name of the breadcrumb and the target path.
3535

36-
class MyController
37-
38-
add_breadcrumb "home", :root_path
39-
add_breadcrumb "my", :my_path
40-
41-
def index
42-
# ...
43-
44-
add_breadcrumb "index", index_path
45-
end
46-
47-
end
36+
```ruby
37+
class MyController
4838

49-
The third, optional argument is a Hash of options to customize the breadcrumb link.
39+
add_breadcrumb "home", :root_path
40+
add_breadcrumb "my", :my_path
5041

51-
class MyController
52-
add_breadcrumb "home", :root_path, :options => { :title => "Home" }
42+
def index
43+
# ...
5344

54-
def index
55-
add_breadcrumb "index", index_path, :title => "Back to the Index"
56-
end
57-
end
45+
add_breadcrumb "index", index_path
46+
end
47+
48+
end
49+
```
50+
51+
See the section "Breadcrumb Element" for more details about name and target class types.
52+
53+
The third, optional argument is a Hash of options to customize the breadcrumb link.
54+
55+
```ruby
56+
class MyController
57+
def index
58+
add_breadcrumb "index", index_path, :title => "Back to the Index"
59+
end
60+
end
61+
```
5862

5963
In your view, you can render the breadcrumb menu with the `render_breadcrumbs` helper.
6064

61-
<!DOCTYPE html>
62-
<html>
63-
<head>
64-
<title>untitled</title>
65-
</head>
66-
67-
<body>
68-
<%= render_breadcrumbs %>
69-
</body>
70-
</html>
65+
```html
66+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
67+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
68+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
69+
<head>
70+
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
71+
<title>untitled</title>
72+
</head>
73+
74+
<body>
75+
<%= render_breadcrumbs %>
76+
</body>
77+
</html>
78+
```
7179

7280
`render_breadcrumbs` understands a limited set of options. For example, you can pass change the default separator with the `:separator` option.
7381

74-
<body>
75-
<%= render_breadcrumbs :separator => ' / ' %>
76-
</body>
82+
```html
83+
<body>
84+
<%= render_breadcrumbs :separator => ' / ' %>
85+
</body>
86+
```
7787

7888
Current possible options are:
7989
- `:separator`
8090
- `:tag`
8191

8292
To use with Bootstrap you might use the following:
8393

84-
<body>
85-
<ol class="breadcrumb">
86-
<%= render_breadcrumbs :tag => :li, :separator => "" %>
87-
</ol>
88-
</body>
94+
```html
95+
<body>
96+
<ol class="breadcrumb">
97+
<%= render_breadcrumbs :tag => :li, :separator => "" %>
98+
</ol>
99+
</body>
100+
```
101+
102+
More complex customizations require a custom @Builder@.
103+
104+
### Breadcrumb Element
105+
106+
A breadcrumbs menu is composed by a number of `Element` objects. Each object contains two attributes: the name of the breadcrumb and the target path.
107+
108+
When you call `add_breadcrumb`, the method automatically creates a new `Element` object for you and append it to the breadcrumbs stack. `Element` name and path can be one of the following Ruby types:
109+
110+
- `Symbol`
111+
- `Proc`
112+
- `String`
113+
114+
#### Symbol
115+
116+
If the value is a `Symbol`, the library calls the corresponding method defined in the same context the and sets the `Element` attribute to the returned value.
117+
118+
```ruby
119+
class MyController
120+
121+
# The Name is set to the value returned by
122+
# the :root_name method.
123+
add_breadcrumb :root_name, "/"
124+
125+
protected
126+
127+
def root_name
128+
"the name"
129+
end
130+
131+
end
132+
```
133+
134+
#### Proc
135+
136+
If the value is a `Proc`, the library calls the proc passing the current view context as argument and sets the `Element` attribute to the returned value. This is useful if you want to postpone the execution to get access to some special methods/variables created in your controller action.
137+
138+
```ruby
139+
class MyController
140+
141+
# The Name is set to the value returned by
142+
# the :root_name method.
143+
add_breadcrumb Proc.new { |c| c.my_helper_method },
144+
"/"
145+
146+
end
147+
```
148+
149+
#### String
150+
151+
If the value is a `String`, the library sets the `Element` attribute to the string value.
152+
153+
```ruby
154+
class MyController
155+
156+
# The Name is set to the value returned by
157+
# the :root_name method.
158+
add_breadcrumb "homepage", "/"
159+
160+
end
161+
```
162+
163+
### Restricting breadcrumb scope
164+
165+
The `add_breadcrumb` method understands all options you are used to pass to a Rails controller filter. In fact, behind the scenes this method uses a `before_filter` to store the tab in the `@breadcrumbs` variable.
166+
167+
Taking advantage of Rails filter options, you can restrict a tab to a selected group of actions in the same controller.
168+
169+
```ruby
170+
class PostsController < ApplicationController
171+
add_breadcrumb "admin", :admin_path
172+
add_breadcrumb "posts", :posts_path, :only => %w(index show)
173+
end
174+
175+
class ApplicationController < ActionController::Base
176+
add_breadcrumb "admin", :admin_path, :if => :admin_controller?
177+
178+
def admin_controller?
179+
self.class.name =~ /^Admin(::|Controller)/
180+
end
181+
end
182+
```
183+
184+
### Internationalization and Localization
185+
186+
<tt>BreadcrumbsOnRails</tt> is compatible with the standard Rails internationalization framework.
187+
188+
For example, if you want to localize your menu, define a new breadcrumbs node in your `.yml` file with all the keys for your elements.
189+
190+
```yaml
191+
# config/locales/en.yml
192+
en:
193+
breadcrumbs:
194+
homepage: Homepage
195+
first: First
196+
second: Second
197+
third: Third
198+
199+
# config/locales/it.yml
200+
it:
201+
breadcrumbs:
202+
homepage: Homepage
203+
first: Primo
204+
second: Secondo
205+
third: Terzo
206+
```
207+
208+
In your controller, use the `I18n.t` method.
89209

90-
More complex customizations require a custom Builder.
210+
```ruby
211+
class PostsController < ApplicationController
212+
add_breadcrumb I18n.t("breadcrumbs.first"), :first_path
213+
add_breadcrumb I18n.t("breadcrumbs.second"), :second_path, :only => %w(second)
214+
add_breadcrumb I18n.t("breadcrumbs.third"), :third_path, :only => %w(third)
215+
end
91216
92-
Read the [documentation](http://simonecarletti.com/code/breadcrumbs_on_rails/docs/) to learn more about advanced usage and builders.
217+
class ApplicationController < ActionController::Base
218+
add_breadcrumb I18n.t("breadcrumbs.homepage"), :root_path
219+
end
220+
```
93221

94222

95223
## Credits
@@ -108,12 +236,11 @@ Report issues or feature requests to [GitHub Issues](https://github.com/weppos/b
108236

109237
## More Information
110238

111-
- [Homepage](http://simonecarletti.com/code/breadcrumbs_on_rails)
112-
- [RubyGems](http://rubygems.org/gems/breadcrumbs_on_rails)
113-
- [Documentation](http://simonecarletti.com/code/breadcrumbs_on_rails/docs/)
239+
- [Homepage](http://simonecarletti.com/code/breadcrumbs-on-rails)
240+
- [RubyGems](https://rubygems.org/gems/breadcrumbs_on_rails)
114241
- [Issues](https://github.com/weppos/breadcrumbs_on_rails/issues)
115242

116243

117244
## License
118245

119-
<tt>BreadcrumbsOnRails</tt> is Copyright (c) 2009-2014 Simone Carletti. This is Free Software distributed under the MIT license.
246+
<tt>BreadcrumbsOnRails</tt> is Copyright (c) 2009-2015 Simone Carletti. This is Free Software distributed under the MIT license.

0 commit comments

Comments
 (0)