breadcrumbs_on_rails 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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