breadcrumbs_on_rails 0.1.1 → 0.2.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (7) hide show
  1. data/CHANGELOG.rdoc +5 -0
  2. data/README.rdoc +153 -7
  3. data/breadcrumbs_on_rails.gemspec +1 -1
  4. data/lib/breadcrumbs_on_rails/breadcrumbs.rb +1 -1
  5. data/lib/breadcrumbs_on_rails/controller_mixin.rb +5 -5
  6. data/lib/breadcrumbs_on_rails/version.rb +2 -2
  7. metadata +1 -1
data/CHANGELOG.rdoc CHANGED
@@ -1,6 +1,11 @@
1
1
  = Changelog
2
2
 
3
3
 
4
+ == Release 0.2.0
5
+
6
+ * Releasing the library as open source project.
7
+
8
+
4
9
  == Release 0.1.1
5
10
 
6
11
  * ADDED: documentation file.
data/README.rdoc CHANGED
@@ -3,8 +3,6 @@
3
3
  BreadcrumbsOnRails is a simple Ruby on Rails plugin for creating and managing a breadcrumb navigation for a Rails project.
4
4
  It provides helpers for creating navigation elements with a flexible interface.
5
5
 
6
- Note. This documentation file is a work in progress. Please be patient.
7
-
8
6
 
9
7
  == Requirements
10
8
 
@@ -19,7 +17,7 @@ Note. This documentation file is a work in progress. Please be patient.
19
17
  This is the preferred way to install BreadcrumbsOnRails and the best way if you want install a stable version.
20
18
  The GEM is hosted on {Gemcutter}[http://gemcutter.org/gems/tabs_on_rails].
21
19
 
22
- $ gem install breadcrumbs_on_rails --source http://gemcutter.org/
20
+ $ gem install breadcrumbs_on_rails --source http://gemcutter.org
23
21
 
24
22
  With Rails >= 2.2, you can specify the GEM dependency in your environment.rb file so that Rails will automatically check the requirement on startup.
25
23
 
@@ -28,7 +26,7 @@ With Rails >= 2.2, you can specify the GEM dependency in your environment.rb fil
28
26
  # other configurations
29
27
  # ...
30
28
 
31
- config.gem "breadcrumbs_on_rails", :source => "http://gemcutter.org/"
29
+ config.gem "breadcrumbs_on_rails", :source => "http://gemcutter.org"
32
30
 
33
31
  end
34
32
 
@@ -41,7 +39,155 @@ This is the preferred way if you want to live on the edge and install a developm
41
39
 
42
40
  == Usage
43
41
 
44
- ...
42
+ Having a breadcrumb navigation menu in your Rails app using BreadcrumbsOnRails is really straightforward.
43
+
44
+ In your controller, call <tt>add_breadcrumb</tt> to push a new element on the breadcrumb stack. <tt>add_breadcrumb</tt> requires two arguments: the name of the breadcrumb and the target path.
45
+
46
+ class MyController
47
+
48
+ add_breadcrumb "home", root_path
49
+ add_breadcrumb "my", my_path
50
+
51
+ def index
52
+ # ...
53
+
54
+ add_breadcrumb "index", index_path
55
+ end
56
+
57
+ end
58
+
59
+ In your view, you can render the breadcrumb menu with the <tt>render_breadcrumbs</tt> helper.
60
+
61
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
62
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
63
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
64
+ <head>
65
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
66
+ <title>untitled</title>
67
+ </head>
68
+
69
+ <body>
70
+ <%= render_breadcrumbs %>
71
+ </body>
72
+ </html>
73
+
74
+ <tt>render_breadcrumbs</tt> understands a limited set of options. For example, you can pass change the default separator with the <tt>:separator</tt> option.
75
+
76
+ <body>
77
+ <%= render_breadcrumbs :separator => ' / ' %>
78
+ </body>
79
+
80
+ More complex customizations require a custom Builder (documentation yet to come).
81
+
82
+ === Breadcrumb Element
83
+
84
+ A breadcrumbs menu is composed by a number of <tt>Element</tt> objects. Each object contains two attributes: the name of the breadcrumb and the target path.
85
+
86
+ When you call <tt>add_breadcrumb</tt>, the method automatically creates a new <tt>Element</tt> object for you and append it to the breadcrumbs stack. <tt>Element</tt> name and path can be one of the following Ruby types:
87
+
88
+ <ul>
89
+ <li>Symbol</li>
90
+ <li>Proc</li>
91
+ <li>String</li>
92
+ </ul>
93
+
94
+ ==== Symbol
95
+
96
+ If the value is a Symbol, the library calls the corresponding method defined in the same context the and sets the <tt>Element</tt> attribute to the returned value.
97
+
98
+ class MyController
99
+
100
+ # The Name is set to the value returned by
101
+ # the :root_name method.
102
+ add_breadcrumb :root_name, root_path
103
+
104
+ protected
105
+
106
+ def root_name
107
+ "the name"
108
+ end
109
+
110
+ end
111
+
112
+ ==== Proc
113
+
114
+ If the value is a Proc, the library calls the proc passing the current view context as argument and sets the <tt>Element</tt> 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.
115
+
116
+ class MyController
117
+
118
+ # The Name is set to the value returned by
119
+ # the :root_name method.
120
+ add_breadcrumb Proc.new { |c| c.my_helper_method },
121
+ root_path
122
+
123
+ end
124
+
125
+ ==== String
126
+
127
+ If the value is a Proc, the library sets the <tt>Element</tt> attribute to the string value.
128
+
129
+ class MyController
130
+
131
+ # The Name is set to the value returned by
132
+ # the :root_name method.
133
+ add_breadcrumb "homepage", "http://example.com/"
134
+
135
+ end
136
+
137
+
138
+ === Restricting set_tab scope
139
+
140
+ The <tt>add_breadcrumb</tt> method understands all options you are used to pass to a Rails controller filter.
141
+ In fact, behind the scenes this method uses a <tt>before_filter</tt> to store the tab in the <tt>@breadcrumbs</tt> variable.
142
+
143
+ Taking advantage of Rails filter options, you can restrict a tab to a selected group of actions in the same controller.
144
+
145
+ class PostsController < ApplicationController
146
+ add_breadcrumb "admin", admin_path
147
+ add_breadcrumb "posts, posts_path, :only => %w(index show)
148
+ end
149
+
150
+ class ApplicationController < ActionController::Base
151
+ add_breadcrumb "admin", admin_path, :if => :admin_controller?
152
+
153
+ def admin_controller?
154
+ self.class.name =~ /^Admin(::|Controller)/
155
+ end
156
+ end
157
+
158
+ === Internationalization and Localization
159
+
160
+ BreadcrumbsOnRails is compatible with the standard Rails internationalization framework.
161
+
162
+ 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.
163
+
164
+ # config/locales/en.yml
165
+ en:
166
+ breadcrumbs:
167
+ homepage: Homepage
168
+ first: First
169
+ second: Second
170
+ third: Third
171
+
172
+ # config/locales/it.yml
173
+ it:
174
+ breadcrumbs:
175
+ homepage: Homepage
176
+ first: Primo
177
+ second: Secondo
178
+ third: Terzo
179
+
180
+ In your controller, use the <tt>I18n.t</tt> method.
181
+
182
+ class PostsController < ApplicationController
183
+ add_breadcrumb I18n.t("breadcrumbs.first"), first_path
184
+ add_breadcrumb I18n.t("breadcrumbs.second"), second_path, :only => %w(second)
185
+ add_breadcrumb I18n.t("breadcrumbs.third"), third_path, :only => %w(third)
186
+ end
187
+
188
+ class ApplicationController < ActionController::Base
189
+ add_breadcrumb I18n.t("breadcrumbs.homepage"), root_path
190
+ end
45
191
 
46
192
 
47
193
  == Documentation
@@ -52,13 +198,13 @@ For the full documentation, development roadmap and more information please visi
52
198
 
53
199
  == Credits
54
200
 
55
- Author:: {Simone Carletti}[http://www.simonecarletti.com/] <weppos@weppos.net>
201
+ Author:: {Simone Carletti}[http://www.simonecarletti.com] <weppos@weppos.net>
56
202
 
57
203
 
58
204
  == Resources
59
205
 
60
206
  * {Homepage}[http://code.simonecarletti.com/breadonrails]
61
- * {GitHub}[http://github.com/weppos/breadcrumbs_on_rails/]
207
+ * {GitHub}[http://github.com/weppos/breadcrumbs_on_rails]
62
208
 
63
209
 
64
210
  == License
data/breadcrumbs_on_rails.gemspec CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Gem::Specification.new do |s|
4
4
  s.name = %q{breadcrumbs_on_rails}
5
- s.version = "0.1.1"
5
+ s.version = "0.2.0"
6
6
 
7
7
  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
8
8
  s.authors = ["Simone Carletti"]
data/lib/breadcrumbs_on_rails/breadcrumbs.rb CHANGED
@@ -57,7 +57,7 @@ module BreadcrumbsOnRails
57
57
  raise NotImplementedError
58
58
  end
59
59
 
60
-
60
+
61
61
  protected
62
62
 
63
63
  def compute_name(element)
data/lib/breadcrumbs_on_rails/controller_mixin.rb CHANGED
@@ -15,9 +15,9 @@
15
15
 
16
16
 
17
17
  module BreadcrumbsOnRails
18
-
18
+
19
19
  module ControllerMixin
20
-
20
+
21
21
  def self.included(base)
22
22
  base.extend ClassMethods
23
23
  base.send :helper, HelperMethods
@@ -98,10 +98,10 @@ module BreadcrumbsOnRails
98
98
  else
99
99
  content
100
100
  end
101
- end
102
-
101
+ end
102
+
103
103
  end
104
-
104
+
105
105
  end
106
106
 
107
107
  end
data/lib/breadcrumbs_on_rails/version.rb CHANGED
@@ -18,8 +18,8 @@ module BreadcrumbsOnRails
18
18
 
19
19
  module Version
20
20
  MAJOR = 0
21
- MINOR = 1
22
- PATCH = 1
21
+ MINOR = 2
22
+ PATCH = 0
23
23
  ALPHA = nil
24
24
 
25
25
  STRING = [MAJOR, MINOR, PATCH, ALPHA].compact.join('.')
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: breadcrumbs_on_rails
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.1
4
+ version: 0.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Simone Carletti