gretel-trails 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 75ba4eea078b14bb0d61eb137262d08d24388554
-  data.tar.gz: aacf75c20b0fea1e345149b423e73a38dc165c6f
+  metadata.gz: e37b779cdb1997c44fbffe04b0e99cdcaeffa9ac
+  data.tar.gz: d90ed701b34331eae74e4d60ea6f3c465b3841f6
 SHA512:
-  metadata.gz: 1ccee9ba8ed783a89dc99844d5d090b562f582a28520e68360ebe1e97c13d9a1cde904d3ceb78b3cd7a626e6365a813905d5ee7ecbb46bea2934316b371d7b48
-  data.tar.gz: 304d444bfdde884621754e8e9b3499dad62554e6092f7c2361cd117e9006ecdca79874f259b99a02f8c7071a543c8747d05d677e8f22458818a9c20b434fba0d
+  metadata.gz: c5351e3714d5dbaf54f423248c1919876e129b02fab2f2260097b63962f43def0598b485a11ca18596bc0c526387efce9813dbc1f8f07d233de0f6518eb9a0d7
+  data.tar.gz: 0f29f72ea2058d12e67a32408fffe33e40d2040f614968d88c12a0f38ec3eecf86b1c3585860b633e783c0687dff2f03e299d0e590d898b8dd096afd2cfad620

data/Gemfile

@@ -15,4 +15,5 @@ gem "coffee-rails"
 # your gem to rubygems.org.
 
 # To use debugger
-# gem 'debugger'
+# gem 'debugger'
+gem "gretel", github: "lassebunk/gretel", branch: "3.0.0"

data/README.md

@@ -2,7 +2,11 @@
 
 # Gretel::Trails
 
-Gretel::Trails makes it easy to hide [Gretel](https://github.com/lassebunk/gretel) breadcrumb trails from the user, so they don't see them in URLs when navigating your site.
+Gretel::Trails makes it possible to set [Gretel](https://github.com/lassebunk/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.
 
 ## Installation
 
@@ -18,7 +22,43 @@ And run:
 $ bundle
 ```
 
-In an initializer, e.g. *config/initializers/gretel.rb*:
+Gretel::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](#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
+```
+
+You can generate a secret using `SecureRandom.hex(64)` or `rake secret`.
+
+Then you can set the breadcrumb trail:
+
+```erb
+<% 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.
+
+## Custom trail param
+
+The default trail param is `params[:trail]`. You can change it in an initializer:
+
+```ruby
+Gretel::Trails.trail_param = :other_param
+```
+
+## 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
@@ -38,11 +78,11 @@ And finally, at the bottom of *app/assets/javascripts/application.js*:
 ```
 
 Breadcrumb 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.trail_param`.
+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](https://github.com/rails/turbolinks), it's important that you add the require *after* you require Turbolinks. Else it won't work.
 
-## Usage
+### Usage
 
 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:
 
@@ -54,9 +94,17 @@ When you want to invisibly add the current trail when the user clicks a link, yo
 
 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.
+See [Customization](#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:
 
-### Custom links
+```erb
+<%= link_to "My Link", my_link_path, data: { trail: breadcrumb_trail } %>
+```
+
+See [Customization](#customization) below for info on changing the `data-trail` attribute to something else.
+
+### Breadcrumb links
 
 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:
@@ -89,14 +137,76 @@ The default trail data attribute for `<body>` and links is `data-trail` but you
 Gretel::Trails::HiddenStrategy.data_attribute = "other-data-attribute"
 ```
 
-That's it. :)
+`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
+
+Gretel::Trails comes with different stores for encoding and decoding trails for use in the URL.
+
+### URL store
+
+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
+```
+
+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
+
+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
+```
+
+You also need to create a migration for the database table that holds the trails:
+
+```bash
+$ rails generate gretel:trails:migration
+```
+
+This 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:
+
+```bash
+$ rake gretel:trails:delete_expired
+```
+
+You can also run `Gretel::Trails.delete_expired` directly.
+
+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
+```
+
+### 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 }
+```
 
-### Trail param
+Trails are now stored in Redis and expired automatically after 1 day (by default).
 
-The trail param that's hidden from the user is `params[:trail]` by default. You can change this in an initializer:
+To set a custom expiration period, in an initializer:
 
 ```ruby
-Gretel.trail_param = :other_param
+Gretel::Trails::RedisStore.expires_in = 2.days
 ```
 
 ## Requirements

data/gretel-trails.gemspec

@@ -17,12 +17,14 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^test/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "gretel", ">= 3.0.0.beta4"
+  spec.add_dependency "gretel", ">= 3.0.0.beta5"
   spec.add_dependency "rails", ">= 3.2.0"
   spec.add_development_dependency "rails", "~> 3.2.13"
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "sqlite3"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "fakeredis", "~> 0.4.2"
+  spec.add_development_dependency "timecop", "~> 0.6.3"
   spec.add_development_dependency "capybara", "~> 2.1.0"
   spec.add_development_dependency "capybara-webkit", "~> 1.0.0"
 end

data/lib/assets/javascripts/gretel.trails.hidden.js.coffee.erb

@@ -8,10 +8,10 @@ end
 
 # Remove trail from querystring
 removeTrailFromUrl = ->
+  return if location.href.indexOf("<%= Gretel::Trails.trail_param %>=") is -1
   if history.replaceState?
-    return if location.href.indexOf("<%= Gretel.trail_param %>=") is -1
     uri = new Gretel.Trails.Uri(location.href)
-    history.replaceState history.state, document.title, uri.deleteQueryParam("<%= Gretel.trail_param %>")
+    history.replaceState history.state, document.title, uri.deleteQueryParam("<%= Gretel::Trails.trail_param %>")
 
 # Remove trail on load
 removeTrailFromUrl()
@@ -26,7 +26,7 @@ $ ->
     if trail = $(this).data("<%= Gretel::Trails::HiddenStrategy.data_attribute %>") || $("body").data("<%= Gretel::Trails::HiddenStrategy.data_attribute %>")
       href = $(this).attr("href")
       uri = new Gretel.Trails.Uri(href)
-      href = uri.deleteQueryParam("<%= Gretel.trail_param %>").addQueryParam("<%= Gretel.trail_param %>", trail)
+      href = uri.deleteQueryParam("<%= Gretel::Trails.trail_param %>").addQueryParam("<%= Gretel::Trails.trail_param %>", trail)
       $(this).attr("href", href)
     else
       console?.log "[Gretel] No `data-<%= Gretel::Trails::HiddenStrategy.data_attribute %>` was found on the <body> tag or the link you just clicked. Please set it using the `breadcrumb_trail` helper or see the Gretel::Trails readme for more info."

data/lib/generators/gretel/USAGE

@@ -0,0 +1,8 @@
+Description:
+  Generates a sample breadcrumbs configuration file for Gretel.
+
+Example:
+  rails generate gretel:install
+
+  This will create:
+    config/breadcrumbs.rb

data/lib/generators/gretel/install_generator.rb

@@ -0,0 +1,19 @@
+require 'rails/generators'
+
+module Gretel
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('../templates', __FILE__)
+    
+    desc "Creates a sample configuration file in config/breadcrumbs.rb"
+    def create_config_file
+      copy_file "breadcrumbs.rb", "config/breadcrumbs.rb"
+    end
+
+    desc "Creates an initializer with trail secret"
+    def create_initializer
+      initializer "gretel.rb" do
+        %{Gretel::Trails::UrlStore.secret = '#{SecureRandom.hex(64)}'}
+      end
+    end
+  end
+end

data/lib/generators/gretel/templates/breadcrumbs.rb

@@ -0,0 +1,28 @@
+crumb :root do
+  link "Home", root_path
+end
+
+# crumb :projects do
+#   link "Projects", projects_path
+# end
+
+# crumb :project do |project|
+#   link project.name, project_path(project)
+#   parent :projects
+# end
+
+# crumb :project_issues do |project|
+#   link "Issues", project_issues_path(project)
+#   parent :project, project
+# end
+
+# crumb :issue do |issue|
+#   link issue.title, issue_path(issue)
+#   parent :project_issues, issue.project
+# end
+
+# If you want to split your breadcrumbs configuration over multiple files, you
+# can create a folder named `config/breadcrumbs` and put your configuration
+# files there. All *.rb files (e.g. `frontend.rb` or `products.rb`) in that
+# folder are loaded and reloaded automatically when you change them, just like
+# this file (`config/breadcrumbs.rb`).

data/lib/generators/gretel/templates/trail_migration.rb

@@ -0,0 +1,11 @@
+class CreateGretelTrails < ActiveRecord::Migration
+  def change
+    create_table :gretel_trails do |t|
+      t.string :key, limit: 40
+      t.text :value
+      t.datetime :expires_at
+    end
+    add_index :gretel_trails, :key, unique: true
+    add_index :gretel_trails, :expires_at
+  end
+end

data/lib/generators/gretel/trail/migration_generator.rb

@@ -0,0 +1,20 @@
+require 'rails/generators'
+
+module Gretel
+  module Trail
+    class MigrationGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('../../templates', __FILE__)
+      
+      def self.next_migration_number(path)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+      
+      desc "Creates a migration for a table to store trail data"
+      def create_migration
+        migration_template "trail_migration.rb", "db/migrate/create_gretel_trails.rb"
+      end
+    end
+  end
+end

data/lib/gretel/trails.rb

@@ -1,9 +1,18 @@
 require "gretel"
+require "gretel/trails/stores"
+require "gretel/trails/tasks"
+require "gretel/trails/patches"
 require "gretel/trails/version"
 require "gretel/trails/engine"
 
 module Gretel
   module Trails
+    STORES = {
+      url: UrlStore,
+      db: ActiveRecordStore,
+      redis: RedisStore
+    }
+
     class << self
       # Activated strategies
       def strategies
@@ -20,6 +29,76 @@ module Gretel
       end
 
       alias_method :strategy=, :strategies=
+
+      # Gets the store that is used to encode and decode trails.
+      # Default: +Gretel::Trails::UrlStore+
+      def store
+        @store ||= UrlStore
+      end
+
+      # Sets the store that is used to encode and decode trails.
+      # Can be a subclass of +Gretel::Trails::Store+, or a symbol: +:url+, +:db+, or +:redis+.
+      def store=(value)
+        if value.is_a?(Symbol)
+          klass = STORES[value]
+          raise ArgumentError, "Unknown Gretel::Trails.store #{value.inspect}. Use any of #{STORES.inspect}." unless klass
+          self.store = klass
+        else
+          @store = value
+        end
+      end
+
+      # Uses the store to encode an array of links to a unique key that can be used in URLs.
+      def encode(links)
+        store.encode(links)
+      end
+
+      # Uses the store to decode a unique key to an array of links.
+      def decode(key)
+        store.decode(key)
+      end
+
+      # Deletes expired keys from the store.
+      # Not all stores support expiring keys, and will raise an exception if they don't.
+      def delete_expired
+        store.delete_expired
+      end
+
+      # Returns the current number of trails in the store.
+      # Not all stores support counting keys, and will raise an exception if they don't.
+      def count
+        store.key_count
+      end
+
+      # Deletes all trails in the store.
+      # Not all stores support deleting trails, and will raise an exception if they don't.
+      def delete_all
+        store.delete_all_keys
+      end
+
+      # Name of trail param. Default: +:trail+.
+      def trail_param
+        @trail_param ||= :trail
+      end
+      
+      # Sets the trail param.
+      attr_writer :trail_param
+
+      # Yields +self+ for configuration.
+      # 
+      #   Gretel::Trails.configure do |config|
+      #     config.store = :db
+      #     config.strategy = :hidden
+      #   end
+      def configure
+        yield self
+      end
+
+      # Resets all changes made to +Gretel::Trail+. Used for testing.
+      def reset!
+        instance_variables.each { |var| remove_instance_variable var }
+        STORES.each_value(&:reset!)
+      end
     end
   end
 end

data/lib/gretel/trails/patches.rb

@@ -0,0 +1,3 @@
+require "gretel/trails/patches/gretel"
+require "gretel/trails/patches/renderer"
+require "gretel/trails/patches/view_helpers"

data/lib/gretel/trails/patches/gretel.rb

@@ -0,0 +1,11 @@
+Gretel.class_eval do
+  class << self
+    # Adds +Trails.reset!+ to +Gretel.reset!+.
+    def reset_with_trails!
+      reset_without_trails!
+      Gretel::Trails.reset!
+    end
+
+    alias_method_chain :reset!, :trails
+  end
+end

data/lib/gretel/trails/patches/renderer.rb

@@ -0,0 +1,17 @@
+Gretel::Renderer.class_eval do
+  # Loads parent links from trail if +params[:trail]+ is present.
+  def parent_links_for_with_trail(crumb)
+    if params[Gretel::Trails.trail_param].present?
+      Gretel::Trails.decode(params[Gretel::Trails.trail_param])
+    else
+      parent_links_for_without_trail(crumb)
+    end
+  end
+
+  alias_method_chain :parent_links_for, :trail
+
+  # Returns encoded trail for the breadcrumb.
+  def trail
+    @trail ||= Gretel::Trails.encode(links)
+  end
+end

data/lib/gretel/trails/patches/view_helpers.rb

@@ -0,0 +1,6 @@
+Gretel::ViewHelpers.class_eval do
+  # Encoded breadcrumb trail to be used in URLs.
+  def breadcrumb_trail
+    gretel_renderer.trail
+  end
+end

data/lib/gretel/trails/stores.rb

@@ -0,0 +1,4 @@
+require "gretel/trails/stores/store"
+require "gretel/trails/stores/url_store"
+require "gretel/trails/stores/active_record_store"
+require "gretel/trails/stores/redis_store"

data/lib/gretel/trails/stores/active_record_store.rb

@@ -0,0 +1,64 @@
+module Gretel
+  module Trails
+    class ActiveRecordStore < Store
+      class << self
+        # Number of seconds to keep the trails in the database.
+        # Default: +1.day+
+        def expires_in
+          @expires_in ||= 1.day
+        end
+
+        # Sets the number of seconds to keep the trails in the database.
+        attr_writer :expires_in
+
+        # Save array to database.
+        def save(array)
+          json = array.to_json
+          key = Digest::SHA1.hexdigest(json)
+          GretelTrail.set(key, array, expires_in.from_now)
+          key
+        end
+
+        # Retrieve array from database.
+        def retrieve(key)
+          GretelTrail.get(key)
+        end
+
+        # Delete expired keys.
+        def delete_expired
+          GretelTrail.delete_expired
+        end
+
+        # Gets the number of trails stored in the database.
+        def key_count
+          GretelTrail.count
+        end
+
+        # Deletes all trails stored in the database.
+        def delete_all_keys
+          GretelTrail.delete_all
+        end
+      end
+      
+      class GretelTrail < ActiveRecord::Base
+        serialize :value, Array
+
+        def self.get(key)
+          find_by_key(key).try(:value)
+        end
+
+        def self.set(key, value, expires_at)
+          find_or_initialize_by_key(key).tap do |rec|
+            rec.value = value
+            rec.expires_at = expires_at
+            rec.save
+          end
+        end
+
+        def self.delete_expired
+          delete_all(["expires_at < ?", Time.now])
+        end
+      end
+    end
+  end
+end

data/lib/gretel/trails/stores/redis_store.rb

@@ -0,0 +1,54 @@
+module Gretel
+  module Trails
+    class RedisStore < Store
+      class << self
+        # Options to connect to Redis.
+        def connect_options
+          @connect_options ||= {}
+        end
+
+        # Sets the Redis connect options.
+        attr_writer :connect_options
+
+        # Number of seconds to keep the trails in Redis.
+        # Default: +1.day+
+        def expires_in
+          @expires_in ||= 1.day
+        end
+
+        # Sets the number of seconds to keep the trails in Redis.
+        attr_writer :expires_in
+
+        # Save array to Redis.
+        def save(array)
+          json = array.to_json
+          key = Digest::SHA1.hexdigest(json)
+          redis.setex redis_key_for(key), expires_in, json
+          key
+        end
+
+        # Retrieve array from Redis.
+        def retrieve(key)
+          if json = redis.get(redis_key_for(key))
+            JSON.parse(json)
+          end
+        end
+
+        # Reference to the Redis connection.
+        def redis
+          @redis ||= begin
+            raise "Redis needs to be installed in order for #{name} to use it. Please add `gem \"redis\"` to your Gemfile." unless defined?(Redis)
+            Redis.new(connect_options)
+          end
+        end
+
+        private
+
+        # Key to be stored in Redis.
+        def redis_key_for(key)
+          "gretel:trail:#{key}"
+        end
+      end
+    end
+  end
+end

data/lib/gretel/trails/stores/store.rb

@@ -0,0 +1,54 @@
+module Gretel
+  module Trails
+    class Store
+      class << self
+        # Save an encoded array to the store. It must return the trail key that
+        # can later be used to retrieve the array from the store.
+        def save(array)
+          raise "#{name} must implement #save to be able to save trails."
+        end
+
+        # Retrieve an encoded array from the store based on the saved key.
+        # It must return either the array, or nil if the key was not found.
+        def retrieve(key)
+          raise "#{name} must implement #retrieve to be able to retrieve trails."
+        end
+
+        # Deletes expired keys from the store.
+        def delete_expired
+          raise "#{name} doesn't support deleting expired keys."
+        end
+
+        # Gets the number of stored trail keys.
+        def key_count
+          raise "#{name} doesn't support counting trail keys."
+        end
+
+        # Deletes all stored trail keys.
+        def delete_all_keys
+          raise "#{name} doesn't support deleting all trail keys."
+        end
+
+        # Encode array of +links+ to unique trail key.
+        def encode(links)
+          arr = links.map { |link| [link.key, link.text, (link.text.html_safe? ? 1 : 0), link.url] }
+          save(arr)
+        end
+
+        # Decode unique trail key to array of links.
+        def decode(key)
+          if arr = retrieve(key)
+            arr.map { |key, text, html_safe, url| Link.new(key.to_sym, (html_safe == 1 ? text.html_safe : text), url) }
+          else
+            []
+          end
+        end
+    
+        # Resets all changes made to the store. Used for testing.
+        def reset!
+          instance_variables.each { |var| remove_instance_variable var }
+        end
+      end
+    end
+  end
+end

data/lib/gretel/trails/stores/url_store.rb

@@ -0,0 +1,57 @@
+module Gretel
+  module Trails
+    class UrlStore < Store
+      class << self
+        # Secret used for crypting trail in URL that should be set to something
+        # unguessable. This is required when using trails, for the reason that
+        # unencrypted trails would be vulnerable to cross-site scripting attacks.
+        attr_accessor :secret
+
+        # Securely encodes encoded array to a trail string to be used in URL.
+        def save(array)
+          base64 = encode_base64(array)
+          hash = generate_hash(base64)
+
+          [hash, base64].join("_")
+        end
+
+        # Securely decodes a URL trail string to encoded array.
+        def retrieve(key)
+          hash, base64 = key.split("_", 2)
+
+          if base64.blank?
+            Rails.logger.info "[Gretel] Trail decode failed: No Base64 in trail"
+            []
+          elsif hash == generate_hash(base64)
+            decode_base64(base64)
+          else
+            Rails.logger.info "[Gretel] Trail decode failed: Invalid hash '#{hash}' in trail"
+            []
+          end
+        end
+
+        private
+
+        # Encodes links array to Base64, internally using JSON for serialization.
+        def encode_base64(array)
+          Base64.urlsafe_encode64(array.to_json)
+        end
+
+        # Decodes links array from Base64.
+        def decode_base64(base64)
+          json = Base64.urlsafe_decode64(base64)
+          JSON.parse(json)
+        rescue
+          Rails.logger.info "[Gretel] Trail decode failed: Invalid Base64 '#{base64}' in trail"
+          []
+        end
+
+        # Generates a salted hash of +base64+.
+        def generate_hash(base64)
+          raise "#{name}.secret is not set. Please set it to an unguessable string, e.g. from `rake secret`, or use `rails generate gretel:install` to generate and set it automatically." if secret.blank?
+          Digest::SHA1.hexdigest([base64, secret].join)
+        end
+      end
+    end
+  end
+end

data/lib/gretel/trails/strategies/hidden_strategy.rb

@@ -29,11 +29,11 @@ end
 
 Gretel::Renderer.class_eval do
   # Moves the trail from the querystring into a data attribute.
-  def link_to_with_hidden_trail(name, url, options = {})
-    if url.include?("#{Gretel.trail_param}=")
+  def breadcrumb_link_to_with_hidden_trail(name, url, options = {})
+    if url.include?("#{Gretel::Trails.trail_param}=")
       uri = URI.parse(url)
       query_hash = Hash[CGI.parse(uri.query.to_s).map { |k, v| [k, v.first] }]
-      trail = query_hash.delete(Gretel.trail_param.to_s)
+      trail = query_hash.delete(Gretel::Trails.trail_param.to_s)
 
       options = options.dup
       options[:data] ||= {}
@@ -42,16 +42,16 @@ Gretel::Renderer.class_eval do
       uri.query = query_hash.to_query.presence
       url = uri.to_s
     end
-    link_to_without_hidden_trail(name, url, options)
+    breadcrumb_link_to_without_hidden_trail(name, url, options)
   end
 
-  alias_method_chain :link_to, :hidden_trail
+  alias_method_chain :breadcrumb_link_to, :hidden_trail
 end
 
 ActionView::Base.class_eval do
-  # View helper proxy to the breadcrumb renderer's link_to that automatically
-  # removes trails from URLs and adds them as data attributes.
+  # View helper proxy to the breadcrumb renderer's breadcrumb_link_to that
+  # automatically removes trails from URLs and adds them as data attributes.
   def breadcrumb_link_to(name, url, options = {})
-    gretel_renderer.link_to(name, url, options)
+    gretel_renderer.breadcrumb_link_to(name, url, options)
   end unless method_defined?(:breadcrumb_link_to)
 end

data/lib/gretel/trails/tasks.rb

@@ -0,0 +1,5 @@
+require "rake"
+
+Rake::Task.define_task("gretel:trails:delete_expired" => :environment) do
+  Gretel::Trails.delete_expired
+end

data/lib/gretel/trails/version.rb

@@ -1,5 +1,5 @@
 module Gretel
   module Trails
-    VERSION = "0.0.1"
+    VERSION = "0.0.2"
   end
 end

data/test/dummy/config/breadcrumbs.rb

@@ -2,6 +2,10 @@ crumb :root do
   link "Home", root_path
 end
 
+crumb :about do
+  link "About", about_path
+end
+
 crumb :category do |category|
   link category.name, category
 end

data/test/dummy/config/initializers/gretel.rb

@@ -1,2 +1,2 @@
-Gretel.trail_store = :db
+Gretel::Trails.store = :db
 Gretel::Trails.strategy = :hidden

data/test/dummy/config/routes.rb

@@ -1,5 +1,7 @@
 Dummy::Application.routes.draw do
   root to: "home#index"
+  
+  get "about" => "home#about", as: :about
 
   resources :categories
   resources :products do

data/test/stores/active_record_store_test.rb

@@ -0,0 +1,53 @@
+require 'test_helper'
+
+class ActiveRecordStoreTest < ActiveSupport::TestCase
+  setup do
+    Gretel.reset!
+    Gretel::Trails.store = :db
+    Gretel::Trails.delete_all
+    
+    @links = [
+      [:root, "Home", "/"],
+      [:store, "Store <b>Test</b>".html_safe, "/store"],
+      [:search, "Search", "/store/search?q=test"]
+    ]
+  end
+
+  test "defaults" do
+    assert_equal 1.day, Gretel::Trails::ActiveRecordStore.expires_in
+  end
+
+  test "encoding" do
+    assert_equal "684c211441e72225cee89477a2d1f59e657c9e26",
+                 Gretel::Trails.encode(@links.map { |key, text, url| Gretel::Link.new(key, text, url) })
+  end
+
+  test "decoding" do
+    Gretel::Trails.encode(@links.map { |key, text, url| Gretel::Link.new(key, text, url) })
+    decoded = Gretel::Trails.decode("684c211441e72225cee89477a2d1f59e657c9e26")
+    assert_equal @links, decoded.map { |link| [link.key, link.text, link.url] }
+    assert_equal [false, true, false], decoded.map { |link| link.text.html_safe? }
+  end
+
+  test "invalid trail" do
+    assert_equal [], Gretel::Trails.decode("asdgasdg")
+  end
+
+  test "delete expired" do
+    10.times { Gretel::Trails.encode([Gretel::Link.new(:test, SecureRandom.hex(20), "/test")]) }
+    assert_equal 10, Gretel::Trails.count
+    
+    Gretel::Trails.delete_expired
+    assert_equal 10, Gretel::Trails.count
+
+    Timecop.travel(14.hours.from_now) do
+      5.times { Gretel::Trails.encode([Gretel::Link.new(:test, SecureRandom.hex(20), "/test")]) }
+      assert_equal 15, Gretel::Trails.count
+    end
+
+    Timecop.travel(25.hours.from_now) do
+      Gretel::Trails.delete_expired
+      assert_equal 5, Gretel::Trails.count
+    end
+  end
+end

data/test/stores/redis_store_test.rb

@@ -0,0 +1,35 @@
+require 'test_helper'
+require 'fakeredis'
+
+class RedisStoreTest < ActiveSupport::TestCase
+  setup do
+    Gretel.reset!
+    Gretel::Trails.store = :redis
+    
+    @links = [
+      [:root, "Home", "/"],
+      [:store, "Store <b>Test</b>".html_safe, "/store"],
+      [:search, "Search", "/store/search?q=test"]
+    ]
+  end
+
+  test "defaults" do
+    assert_equal 1.day, Gretel::Trails::RedisStore.expires_in
+  end
+
+  test "encoding" do
+    assert_equal "684c211441e72225cee89477a2d1f59e657c9e26",
+                 Gretel::Trails.encode(@links.map { |key, text, url| Gretel::Link.new(key, text, url) })
+  end
+
+  test "decoding" do
+    Gretel::Trails.encode(@links.map { |key, text, url| Gretel::Link.new(key, text, url) })
+    decoded = Gretel::Trails.decode("684c211441e72225cee89477a2d1f59e657c9e26")
+    assert_equal @links, decoded.map { |link| [link.key, link.text, link.url] }
+    assert_equal [false, true, false], decoded.map { |link| link.text.html_safe? }
+  end
+
+  test "invalid trail" do
+    assert_equal [], Gretel::Trails.decode("asdgasdg")
+  end
+end

data/test/stores/url_store_test.rb

@@ -0,0 +1,38 @@
+require 'test_helper'
+
+class UrlStoreTest < ActiveSupport::TestCase
+  setup do
+    Gretel.reset!
+    
+    Gretel::Trails.store = :url
+    Gretel::Trails::UrlStore.secret = "128107d341e912db791d98bbe874a8250f784b0a0b4dbc5d5032c0fc1ca7bda9c6ece667bd18d23736ee833ea79384176faeb54d2e0d21012898dde78631cdf1"
+    
+    @links = [
+      [:root, "Home", "/"],
+      [:store, "Store <b>Test</b>".html_safe, "/store"],
+      [:search, "Search", "/store/search?q=test"]
+    ]
+  end
+
+  test "encoding" do
+    assert_equal "5543214e6d7bbc3ba5209b2362cd7513d500f61b_W1sicm9vdCIsIkhvbWUiLDAsIi8iXSxbInN0b3JlIiwiU3RvcmUgPGI-VGVzdDwvYj4iLDEsIi9zdG9yZSJdLFsic2VhcmNoIiwiU2VhcmNoIiwwLCIvc3RvcmUvc2VhcmNoP3E9dGVzdCJdXQ==",
+                 Gretel::Trails.encode(@links.map { |key, text, url| Gretel::Link.new(key, text, url) })
+  end
+
+  test "decoding" do
+    decoded = Gretel::Trails.decode("5543214e6d7bbc3ba5209b2362cd7513d500f61b_W1sicm9vdCIsIkhvbWUiLDAsIi8iXSxbInN0b3JlIiwiU3RvcmUgPGI-VGVzdDwvYj4iLDEsIi9zdG9yZSJdLFsic2VhcmNoIiwiU2VhcmNoIiwwLCIvc3RvcmUvc2VhcmNoP3E9dGVzdCJdXQ==")
+    assert_equal @links, decoded.map { |link| [link.key, link.text, link.url] }
+    assert_equal [false, true, false], decoded.map { |link| link.text.html_safe? }
+  end
+
+  test "invalid trail" do
+    assert_equal [], Gretel::Trails.decode("28f104524f5eaf6b3bd035710432fd2b9cbfd62c_X1sicm9vdCIsIkhvbWUiLDAsIi8iXSxbInN0b3JlIiwiU3RvcmUiLDAsIi9zdG9yZSJdLFsic2VhcmNoIiwiU2VhcmNoIiwwLCIvc3RvcmUvc2VhcmNoP3E9dGVzdCJdXQ==")
+  end
+
+  test "raises error if no secret set" do
+    Gretel::Trails::UrlStore.secret = nil
+    assert_raises RuntimeError do
+      Gretel::Trails.encode(@links.map { |key, text, url| Gretel::Link.new(key, text, url) })
+    end
+  end
+end

data/test/test_helper.rb

@@ -11,6 +11,7 @@ Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |f| require f }
 
 require "capybara/rails"
 require "capybara-webkit"
+require "timecop"
 
 class ActionDispatch::IntegrationTest
   # Make the Capybara DSL available in all integration tests

data/test/trails_test.rb

@@ -0,0 +1,25 @@
+require 'test_helper'
+
+class TrailsTest < ActiveSupport::TestCase
+  setup do
+    Gretel.reset!
+  end
+
+  test "defaults" do
+    assert_equal :trail, Gretel::Trails.trail_param
+  end
+
+  test "configuration block" do
+    Gretel::Trails.configure do |config|
+      config.trail_param = :set_from_config
+    end
+
+    assert_equal :set_from_config, Gretel::Trails.trail_param
+  end
+
+  test "setting invalid store" do
+    assert_raises ArgumentError do
+      Gretel::Trails.store = :xx
+    end
+  end
+end

data/test/view_helpers_test.rb

@@ -0,0 +1,41 @@
+require 'test_helper'
+
+class ViewHelpersTest < ActionView::TestCase
+  include Gretel::ViewHelpers
+
+  setup do
+    Gretel.reset!
+    Gretel::Trails::UrlStore.secret = "84f3196275c50b6fee3053c7b609b2633143f33f3536cb74abdf2753cca5a3e24b9dd93e4d7c75747c2f111821c7feb0e51e13485e4d772c17f60c1f8d832b72"
+  end
+
+  test "trail helper" do
+    breadcrumb :about
+
+    assert_equal "aec19c5388f02dd60151589ad01b4f3ec074598e_W1siYWJvdXQiLCJBYm91dCIsMCwiL2Fib3V0Il1d", breadcrumb_trail
+  end
+
+  test "loading trail" do
+    params[:trail] = "aec19c5388f02dd60151589ad01b4f3ec074598e_W1siYWJvdXQiLCJBYm91dCIsMCwiL2Fib3V0Il1d"
+    breadcrumb :recent_products
+
+    assert_equal %{<div class="breadcrumbs"><a href="/">Home</a> &rsaquo; <a href="/about">About</a> &rsaquo; <span class="current">Recent products</span></div>},
+                 breadcrumbs
+  end
+
+  test "different trail param" do
+    Gretel::Trails.trail_param = :mytest
+    params[:mytest] = "aec19c5388f02dd60151589ad01b4f3ec074598e_W1siYWJvdXQiLCJBYm91dCIsMCwiL2Fib3V0Il1d"
+    breadcrumb :recent_products
+
+    assert_equal %{<div class="breadcrumbs"><a href="/">Home</a> &rsaquo; <a href="/about">About</a> &rsaquo; <span class="current">Recent products</span></div>},
+                 breadcrumbs
+  end
+
+  test "unknown trail" do
+    params[:trail] = "notfound"
+    breadcrumb :recent_products
+
+    assert_equal %{<div class="breadcrumbs"><a href="/">Home</a> &rsaquo; <span class="current">Recent products</span></div>},
+                 breadcrumbs
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gretel-trails
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Lasse Bunk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-17 00:00:00.000000000 Z
+date: 2013-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gretel
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
-        version: 3.0.0.beta4
+        version: 3.0.0.beta5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
-        version: 3.0.0.beta4
+        version: 3.0.0.beta5
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +94,34 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: fakeredis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.2
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.6.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.6.3
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
@@ -138,10 +166,25 @@ files:
 - gretel-trails.gemspec
 - lib/assets/javascripts/gretel.trails.hidden.js.coffee.erb
 - lib/assets/javascripts/gretel.trails.jsuri.js.coffee
+- lib/generators/gretel/USAGE
+- lib/generators/gretel/install_generator.rb
+- lib/generators/gretel/templates/breadcrumbs.rb
+- lib/generators/gretel/templates/trail_migration.rb
+- lib/generators/gretel/trail/migration_generator.rb
 - lib/gretel-trails.rb
 - lib/gretel/trails.rb
 - lib/gretel/trails/engine.rb
+- lib/gretel/trails/patches.rb
+- lib/gretel/trails/patches/gretel.rb
+- lib/gretel/trails/patches/renderer.rb
+- lib/gretel/trails/patches/view_helpers.rb
+- lib/gretel/trails/stores.rb
+- lib/gretel/trails/stores/active_record_store.rb
+- lib/gretel/trails/stores/redis_store.rb
+- lib/gretel/trails/stores/store.rb
+- lib/gretel/trails/stores/url_store.rb
 - lib/gretel/trails/strategies/hidden_strategy.rb
+- lib/gretel/trails/tasks.rb
 - lib/gretel/trails/version.rb
 - test/dummy/README.rdoc
 - test/dummy/Rakefile
@@ -193,7 +236,12 @@ files:
 - test/dummy/test/fixtures/categories.yml
 - test/dummy/test/fixtures/products.yml
 - test/gretel_trails_test.rb
+- test/stores/active_record_store_test.rb
+- test/stores/redis_store_test.rb
+- test/stores/url_store_test.rb
 - test/test_helper.rb
+- test/trails_test.rb
+- test/view_helpers_test.rb
 homepage: https://github.com/lassebunk/gretel-trails
 licenses:
 - MIT
@@ -269,4 +317,9 @@ test_files:
 - test/dummy/test/fixtures/categories.yml
 - test/dummy/test/fixtures/products.yml
 - test/gretel_trails_test.rb
+- test/stores/active_record_store_test.rb
+- test/stores/redis_store_test.rb
+- test/stores/url_store_test.rb
 - test/test_helper.rb
+- test/trails_test.rb
+- test/view_helpers_test.rb