README.md in gretel-trails-0.0.2 vs README.md in gretel-trails-0.0.3
- old
+ new
@@ -27,11 +27,13 @@
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](#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::UrlStore.secret = 'your_key_here' # Must be changed to something else to be secure
+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:
@@ -49,21 +51,25 @@
## Custom trail param
The default trail param is `params[:trail]`. You can change it in an initializer:
```ruby
-Gretel::Trails.trail_param = :other_param
+Gretel::Trails.configure do |config|
+ config.trail_param = :other_param
+end
```
## Hiding trails in URLs
Gretel::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*:
```ruby
-Gretel::Trails.strategy = :hidden
+Gretel::Trails.configure do |config|
+ config.strategy = :hidden
+end
```
Add a data attribute with the trail to your `<body>` tag, in *application.html.erb*:
```erb
@@ -115,28 +121,34 @@
<% end %>
```
The link will now have a URL without the trail param and `data-trail` containing the trail.
-## Customization
+### Customization
-### JS selector
+#### JS selector
If you want to customize the JS selector (the default is `.js-append-trail`), you can do so in an initializer:
```ruby
-Gretel::Trails::HiddenStrategy.js_selector = ".my-other-selector"
+Gretel::Trails.configure do |config|
+ config.strategy = :hidden
+ config.hidden.js_selector = ".my-other-selector"
+end
```
It supports all [CSS selectors](http://api.jquery.com/category/selectors/) that you can use in jQuery.
-### Data attribute
+#### Data attribute
The default trail data attribute for `<body>` and links is `data-trail` but you can change this in an initializer:
```ruby
-Gretel::Trails::HiddenStrategy.data_attribute = "other-data-attribute"
+Gretel::Trails.configure do |config|
+ config.strategy = :hidden
+ config.hidden.data_attribute = "other-data-attribute"
+end
```
`data-` is added automatically, so if for example you want the attribute to be `data-my-attr`, you just set it to `my-attr`.
## Stores
@@ -148,12 +160,14 @@
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*:
```ruby
-Gretel::Trails.store = :url # Not really needed as this is the default
-Gretel::Trails::UrlStore.secret = 'your_key_here' # Must be changed to something else to be secure
+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
+end
```
The secret is used to prevent cross-site scripting attacks. You can generate a secure one using `SecureRandom.hex(64)` or `rake secret`.
### Database store
@@ -161,11 +175,13 @@
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*:
```ruby
-Gretel::Trails.store = :db
+Gretel::Trails.configure do |config|
+ config.store = :db
+end
```
You also need to create a migration for the database table that holds the trails:
```bash
@@ -185,29 +201,37 @@
If you need a gem for managing recurring tasks, [Whenever](https://github.com/javan/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:
```ruby
-Gretel::Trails::ActiveRecordStore.expires_in = 2.days
+Gretel::Trails.configure do |config|
+ config.store = :db
+ config.store.expires_in = 2.days
+end
```
### Redis store
If you want to store trails in [Redis](https://github.com/redis/redis), you can use the Redis store.
To use the Redis store, set it in an initializer, e.g. *config/initializers/gretel.rb*:
```ruby
-Gretel::Trails.store = :redis
-Gretel::Trails::RedisStore.connect_options = { host: "10.0.1.1", port: 6380 }
+Gretel::Trails.configure do |config|
+ config.store = :redis
+ config.store.connect_options = { host: "10.0.1.1", port: 6380 }
+end
```
Trails are now stored in Redis and expired automatically after 1 day (by default).
To set a custom expiration period, in an initializer:
```ruby
-Gretel::Trails::RedisStore.expires_in = 2.days
+Gretel::Trails.configure do |config|
+ config.store = :redis
+ config.store.expires_in = 2.days
+end
```
## Requirements
* Ruby >= 1.9.3 (1.9.2 may work)