Gretel::Trails makes it possible to set Gretel breadcrumb trails via the URL – params[:trail].
This makes it possible to link back to a different breadcrumb trail than the one specified in your breadcrumb, for example if you have a
store with products that have a default parent to their category, but when visiting from the reviews section, you want to link back to the reviews instead.
You can also hide trails from the user using the :hidden strategy, so they don't see them in URLs when navigating your site. See below for more info.
Add this line to your Gemfile:
gem 'gretel-trails'And run:
$ bundleGretel::Trails has different stores that are used to serialize and deserialize the trails for use in URLs.
The default store is the URL store that encodes trails directly in the URL. Note that a trail stored in the URL can get very long, so the recommended way is to use the database or Redis store. See Stores below for more info.
In order to use the URL store, you must set a secret that's used to prevent cross-site scripting attacks. In an initializer, e.g. config/initializers/gretel.rb:
Gretel::Trails.configure do |config|
config.store.secret = 'your_key_here' # Must be changed to something else to be secure
end
You can generate a secret using SecureRandom.hex(64) or rake secret.
Then you can set the breadcrumb trail:
<% breadcrumb :reviews %>
...
<% @products.each do |product| %>
<%= link_to @product.name, product_path(product, trail: breadcrumb_trail) %>
<% end %>The product view will now have the breadcrumb trail from the first page (reviews) instead of its default parent.
The default trail param is params[:trail]. You can change it in an initializer:
Gretel::Trails.configure do |config|
config.trail_param = :other_param
endGretel::Trails has a :hidden strategy that can be used to hide trails in URLs from the user while the server sees them. This is done via data attributes and history.replaceState in browsers that support it.
To hide trails, you set the strategy in an initializer, e.g. config/initializers/gretel.rb:
Gretel::Trails.configure do |config|
config.strategy = :hidden
endAdd a data attribute with the trail to your <body> tag, in application.html.erb:
<body data-trail="<%= breadcrumb_trail %>">
...And finally, at the bottom of app/assets/javascripts/application.js:
//= require gretel.trails.hiddenBreadcrumb trails are now hidden from the user so they don't see them in URLs. It uses data attributes and history.replaceState to hide the trails from the URL.
For older browsers it falls back gracefully to showing trails in the URL, as specified by Gretel::Trails.trail_param.
Note: If you use Turbolinks, it's important that you add the require after you require Turbolinks. Else it won't work.
When you want to invisibly add the current trail when the user clicks a link, you add a special JS selector to the link where you want the trail added on click:
<% @products.each do |product| %>
<%= link_to "My product", product, class: "js-append-trail" %>
<% end %>Trails are now transferred invisibly to the next page when the user clicks a link.
See Customization below for info on changing the .js-append-trail selector.
If you need to set the trail directly on a link without the JS selector, you can do so:
<%= link_to "My Link", my_link_path, data: { trail: breadcrumb_trail } %>See Customization below for info on changing the data-trail attribute to something else.
Inside breadcrumbs, the links are automatically transformed with trails removed from the URLs and applied as data attributes instead.
If you want to do custom breadcrumb links with these changes applied, you can use the breadcrumb_link_to helper:
<% parent_breadcrumb do |parent| %>
<%= breadcrumb_link_to "Back to #{parent.text}", parent.url %>
<% end %>The link will now have a URL without the trail param and data-trail containing the trail.
If you want to customize the JS selector (the default is .js-append-trail), you can do so in an initializer:
Gretel::Trails.configure do |config|
config.strategy = :hidden
config.hidden.js_selector = ".my-other-selector"
endIt supports all CSS selectors that you can use in jQuery.
The default trail data attribute for <body> and links is data-trail but you can change this in an initializer:
Gretel::Trails.configure do |config|
config.strategy = :hidden
config.hidden.data_attribute = "other-data-attribute"
enddata- is added automatically, so if for example you want the attribute to be data-my-attr, you just set it to my-attr.
Gretel::Trails comes with different stores for encoding and decoding trails for use in the URL.
The default store is the URL store which is great for simple use, but if you have longer trails, it can get very long.
To use the URL store, set it in an initializer, e.g. config/initializers/gretel.rb:
Gretel::Trails.configure do |config|
config.store = :url # Not really needed as this is the default
config.store.secret = 'your_key_here' # Must be changed to something else to be secure
endThe secret is used to prevent cross-site scripting attacks. You can generate a secure one using SecureRandom.hex(64) or rake secret.
The database store stores trails in the database so the trail keys have a maximum length of 40 characters (a SHA1 of the trail).
To use the database store, set it an initializer, e.g. config/initializers/gretel.rb:
Gretel::Trails.configure do |config|
config.store = :db
endYou also need to create a migration for the database table that holds the trails:
$ rails generate gretel:trails:migrationThis creates a table named gretel_trails that hold the trails.
ActiveRecord doesn't delete expired records automatically, so to delete expired trails you need to run the following rake task, for example once daily:
$ rake gretel:trails:delete_expiredYou can also run Gretel::Trails.delete_expired directly.
If you need a gem for managing recurring tasks, Whenever is a solution that handles cron jobs via Ruby code.
The default expiration period is 1 day. To set a custom expiration period, in an initializer:
Gretel::Trails.configure do |config|
config.store = :db
config.store.expires_in = 2.days
endIf you want to store trails in Redis, you can use the Redis store.
To use the Redis store, set it in an initializer, e.g. config/initializers/gretel.rb:
Gretel::Trails.configure do |config|
config.store = :redis
config.store.connect_options = { host: "10.0.1.1", port: 6380 }
endTrails are now stored in Redis and expired automatically after 1 day (by default).
To set a custom expiration period, in an initializer:
Gretel::Trails.configure do |config|
config.store = :redis
config.store.expires_in = 2.days
end- Ruby >= 1.9.3 (1.9.2 may work)
- Rails >= 3.2.0
- Gretel >= 3.0.0
- jQuery
You are very welcome to contribute with bug fixes or new features. To contribute:
- Fork the project
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add feature') - Push to the branch (
git push origin my-new-feature) - Create new pull request
Follows semantic versioning.
Copyright (c) 2013 Lasse Bunk, released under the MIT license