gretel 2.1.0 → 2.2.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 20b6074d04a88e299ce92a69065f183ba6e299ca
-  data.tar.gz: 33fa2c8f9ff4cb909a430786d1e4b467ffec40f5
+  metadata.gz: 8655da4c27996c4a3cfa81b8e64b7096a9a8a59a
+  data.tar.gz: a108906eacb8b38d53fc748d55a57bab030d5dcd
 SHA512:
-  metadata.gz: 38c61ee418788d568672b173f8fb72e67d45b00c6022210c37009a0bb9a53b6885c71d286647a583ebf0390544ee495e094129945919147161e201a2d68164a9
-  data.tar.gz: af07be5e7434820b66b08f3e48959e8f123658ec5cd5f978264a80c2443480c70a46181f813ed38048d68fc2ff013490a3dfd03e067dca1e39f933be5084b104
+  metadata.gz: 2807debcf21aa80f5643bdef961003f299520469ad07e60e03ce9a0484b656e3b626edf56a957eec39126ef68dc43e7576a89b23d7f6192a1e199d910fad0f14
+  data.tar.gz: d69ab2b538e39e97de79ae712481f4bdd586062869ed552beb68af667f0ad4572c800baf01c550b9cc34af8c6416c8c96b9a3a892991ae1ba17a37c6fb0771c5

data/CHANGELOG.md

@@ -1,6 +1,12 @@
 Changelog
 =========
 
+Version 2.2
+-----------
+* Support for setting trails via the URL – `params[:trail]`. This makes it possible to link 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 linking from the review section, you want to link back to the reviews instead.
+  See the readme for more info.
+
 Version 2.1
 -----------
 * Breadcrumbs are now configured in `config/breadcrumbs.rb` and `config/breadcrumbs/**/*.rb` and reloaded when changed in the development environment instead of the initializer that required restart when configuration changed.

data/README.md

@@ -1,33 +1,19 @@
 [![Build Status](https://secure.travis-ci.org/lassebunk/gretel.png)](http://travis-ci.org/lassebunk/gretel)
 
 Gretel is a [Ruby on Rails](http://rubyonrails.org) plugin that makes it easy yet flexible to create breadcrumbs.
+It is based around the idea that breadcrumbs are a separate concern, and therefore should be defined in their own place.
+You define a set of breadcrumbs in the config folder and specify in the view which breadcrumb to use.
+Gretel also supports [semantic breadcrumbs](http://support.google.com/webmasters/bin/answer.py?hl=en&answer=185417) (those used in Google results).
 
-New in version 2.1
-------------------
-Instead of using the initializer that in Gretel version 2.0 and below required restarting the application after breadcrumb configuration changes, the configuration of the breadcrumbs is now loaded from `config/breadcrumbs.rb` (and `config/breadcrumbs/*.rb` if you want to split your breadcrumbs configuration across multiple files).
-In the Rails development environment, these files are automatically reloaded when changed.
-
-Using the initializer (e.g. `config/initializers/breadcrumbs.rb`) is deprecated but still supported until Gretel version 3.0.
-
-To update, use `bundle update gretel`. Then remove the `Gretel::Crumbs.layout do ... end` block, so instead of:
-
-```ruby
-Gretel::Crumbs.layout do
-  crumb :root do
-    link "Home", root_path
-  end
-end
-```
+Have fun! And please do write, if you (dis)like it – [lassebunk@gmail.com](mailto:lassebunk@gmail.com).
 
-in the initializer, you write:
+New in version 2.2
+------------------
 
-```ruby
-crumb :root do
-  link "Home", root_path
-end
-```
+Gretel now supports setting trails via the URL – `params[:trail]`. This makes it possible to link 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 linking from the review section, you want to link back to the reviews instead.
 
-in `config/breadcrumbs.rb`.
+See below for more info or the [changelog](https://github.com/lassebunk/gretel/blob/master/CHANGELOG.md) for more changes.
 
 Installation
 ------------
@@ -219,12 +205,58 @@ If you supply a block to the `breadcrumbs` method, it will yield an array with t
 <% end %>
 ```
 
+Setting custom breadcrumb trails
+--------------------------------
+
+You can set a custom breadcrumb trail via `params[:trail]`. This makes it possible to link to a different breadcrumb trail than the one specified in your breadcrumb.
+
+An example is if you have a store with products that have a default parent to their category, but when linking from the review section, you want to link back to the reviews instead.
+
+### Initial setup
+
+To use breadcrumb trails, you must set a secret to be used when encoding the trails.
+
+You can generate it using the installer:
+
+```bash
+$ rails generate gretel:install
+```
+
+This will create an initializer in *config/initializers/gretel.rb* that will contain a random secret key.
+
+If you want to do it manually, you can put the following in *config/initializers/gretel.rb*:
+
+```
+Gretel::Trail.secret = 'your_key_here' # Must be changed to something else to be secure
+```
+
+You can generate a key using `SecureRandom.hex(64)`.
+
+### Example
+
+This example shows how to link to the trail in the view.
+Gretel has a built-in view helper method named `breadcrumb_trail` that contains the current breadcrumb trail ready for use in a URL.
+
+```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.
+
+### Note
+
+Please use the trail functionality with care; the trails can get very long.
+
 Nice to know
 ------------
 
 ### Access to view helpers
 
-When inside `Gretel::Crumbs.layout do .. end`, you have access to all view helpers of the current view where the breadcrumbs are inserted.
+When configuring breadcrumbs, you have access to all view helpers of the view where the breadcrumbs are inserted.
 
 ### Using multiple breadcrumb configuration files
 
@@ -235,6 +267,34 @@ The format is the same as `config/breadcrumbs.rb` which is also loaded.
 
 Since Gretel version 2.1.0, the breadcrumb configuration files are now reloaded in the Rails development environment if they change. In other environments, like production, the files are loaded once, when first needed.
 
+Upgrading from version 2.0 or below
+-----------------------------------
+Instead of using the initializer that in Gretel version 2.0 and below required restarting the application after breadcrumb configuration changes, the configuration of the breadcrumbs is now loaded from `config/breadcrumbs.rb` (and `config/breadcrumbs/*.rb` if you want to split your breadcrumbs configuration across multiple files).
+In the Rails development environment, these files are automatically reloaded when changed.
+
+Using the initializer (e.g. `config/initializers/breadcrumbs.rb`) is deprecated but still supported until Gretel version 3.0.
+If you want to silence the deprecation warning until you upgrade, you can set `Gretel.suppress_deprecation_warnings = true` before the layout block in your initializer.
+
+To update to the latest version of Gretel, use `bundle update gretel`. Then remove the `Gretel::Crumbs.layout do ... end` block, so instead of:
+
+```ruby
+Gretel::Crumbs.layout do
+  crumb :root do
+    link "Home", root_path
+  end
+end
+```
+
+in the initializer, you write:
+
+```ruby
+crumb :root do
+  link "Home", root_path
+end
+```
+
+in `config/breadcrumbs.rb`.
+
 Documentation
 -------------
 

data/lib/generators/gretel/install_generator.rb

@@ -8,5 +8,12 @@ module Gretel
     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::Trail.secret = '#{SecureRandom.hex(64)}'}
+      end
+    end
   end
 end

data/lib/gretel.rb

@@ -2,6 +2,7 @@ require 'gretel/version'
 require 'gretel/crumbs'
 require 'gretel/crumb'
 require 'gretel/link'
+require 'gretel/trail'
 require 'gretel/view_helpers'
 require 'gretel/deprecated'
 
@@ -42,10 +43,11 @@ module Gretel
     # Sets the Rails environment names with automatic configuration reload. Default is +["development"]+.
     attr_writer :reload_environments
 
-    # Resets all changes made to +Gretel+ and +Gretel::Crumbs+. Used for testing.
+    # Resets all changes made to +Gretel+, +Gretel::Crumbs+, and +Gretel::Trail+. Used for testing.
     def reset!
       instance_variables.each { |var| remove_instance_variable var }
       Crumbs.reset!
+      Trail.reset!
     end
   end
 end

data/lib/gretel/crumb.rb

@@ -12,6 +12,9 @@ module Gretel
 
     # Sets link of the breadcrumb.
     def link(text, url = nil)
+      # Transform objects to real paths.
+      url = url_for(url) if url
+      
       links << Gretel::Link.new(key, text, url)
     end
 

data/lib/gretel/trail.rb

@@ -0,0 +1,73 @@
+module Gretel
+  module Trail
+    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 array of links to a trail string to be used in URL.
+      def encode(links)
+        ensure_secret!
+
+        base64 = encode_base64(links)
+        hash = base64.crypt(secret)
+
+        [hash, base64].join("_")
+      end
+
+      # Securely decodes a URL trail string to array of links.
+      def decode(trail)
+        ensure_secret!
+
+        hash, base64 = trail.split("_", 2)
+
+        if base64.blank?
+          Rails.logger.info "[Gretel] Trail decode failed: No Base64 in trail"
+          []
+        elsif hash == base64.crypt(secret)
+          decode_base64(base64)
+        else
+          Rails.logger.info "[Gretel] Trail decode failed: Invalid hash '#{hash}' in trail"
+          []
+        end
+      end
+
+      # Name of trail param. Default: +:trail+.
+      def trail_param
+        @trail_param ||= :trail
+      end
+      
+      attr_writer :trail_param
+
+      # Resets all changes made to +Gretel::Trail+. Used for testing.
+      def reset!
+        instance_variables.each { |var| remove_instance_variable var }
+      end
+
+    private
+
+      # Encodes links array to Base64, internally using YAML for serialization.
+      def encode_base64(links)
+        arr = links.map { |link| [link.key, link.text, link.url] }
+        Base64.urlsafe_encode64(arr.to_yaml)
+      end
+
+      # Decodes links array from Base64.
+      def decode_base64(base64)
+        yaml = Base64.urlsafe_decode64(base64)
+        arr = YAML.load(yaml)
+        arr.map { |key, text, url| Link.new(key, text, url) }
+      rescue
+        Rails.logger.info "[Gretel] Trail decode failed: Invalid Base64 '#{base64}' in trail"
+        []
+      end
+
+      # Ensures that a secret has been set, and raises an exception if this is not the case.
+      def ensure_secret!
+        raise "Gretel::Trail.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?
+      end
+
+    end
+  end
+end

data/lib/gretel/version.rb

@@ -1,3 +1,3 @@
 module Gretel
-  VERSION = "2.1.0"
+  VERSION = "2.2.0.rc1"
 end

data/lib/gretel/view_helpers.rb

@@ -10,6 +10,8 @@ module Gretel
       if args.any?
         @_breadcrumb_key = args.shift
         @_breadcrumb_args = args
+        @_breadcrumb_links = nil
+        @_breadcrumb_trail = nil
       else
         breadcrumbs(options)
       end
@@ -28,10 +30,8 @@ module Gretel
     #     <% end %>
     #   <% end %>
     def breadcrumbs(options = {})
-      Gretel::Crumbs.reload_if_needed
-      
       options = default_breadcrumb_options.merge(options)
-      links = get_breadcrumb_links(options)
+      links = breadcrumb_links_for_render(options)
       if block_given?
         yield links
       else
@@ -39,20 +39,21 @@ module Gretel
       end
     end
 
-    # Returns an array of links for the path of the breadcrumb set by +breadcrumb+.
-    def get_breadcrumb_links(options = {})
-      return [] if @_breadcrumb_key.blank?
+    def breadcrumb_trail
+      @_breadcrumb_trail ||= Gretel::Trail.encode(breadcrumb_links)
+    end
 
-      # Get breadcrumb set by the `breadcrumb` method
-      crumb = Gretel::Crumb.new(self, @_breadcrumb_key, *@_breadcrumb_args)
+    private
 
-      # Links of first crumb
-      links = crumb.links.dup
-
-      # Build parents
-      while crumb = crumb.parent
-        links.unshift *crumb.links
+    def breadcrumb_links
+      @_breadcrumb_links ||= begin
+        Gretel::Crumbs.reload_if_needed
+        get_breadcrumb_links
       end
+    end
+
+    def breadcrumb_links_for_render(options = {})
+      links = breadcrumb_links.dup
 
       # Handle autoroot
       if options[:autoroot] && links.map(&:key).exclude?(:root) && Gretel::Crumbs.crumb_defined?(:root)
@@ -67,6 +68,33 @@ module Gretel
       links
     end
 
+    # Returns an array of links for the path of the breadcrumb set by +breadcrumb+.
+    def get_breadcrumb_links
+      return [] if @_breadcrumb_key.blank?
+
+      # Get breadcrumb set by the `breadcrumb` method
+      crumb = Gretel::Crumb.new(self, @_breadcrumb_key, *@_breadcrumb_args)
+
+      # Links of first crumb
+      links = crumb.links.dup
+      
+      links.last.tap do |last|
+        last.url = request.try(:fullpath) || last.url
+      end
+
+      if params[Gretel::Trail.trail_param].present?
+        # Decode trail from URL
+        links.unshift *Gretel::Trail.decode(params[Gretel::Trail.trail_param])
+      else
+        # Build parents
+        while crumb = crumb.parent
+          links.unshift *crumb.links
+        end
+      end
+
+      links
+    end
+
     # Renders breadcrumbs HTML.
     def render_breadcrumbs(links, options)
       return "" if links.empty?

data/test/helper_methods_test.rb

@@ -7,6 +7,7 @@ class HelperMethodsTest < ActionView::TestCase
 
   setup do
     Gretel.reset!
+    Gretel::Trail.secret = "128107d341e912db791d98bbe874a8250f784b0a0b4dbc5d5032c0fc1ca7bda9c6ece667bd18d23736ee833ea79384176faeb54d2e0d21012898dde78631cdf1"
   end
 
   test "shows basic breadcrumb" do
@@ -177,6 +178,29 @@ class HelperMethodsTest < ActionView::TestCase
     end
   end
 
+  test "trail helper" do
+    breadcrumb :basic
+
+    assert_equal "12hY7tdmRCBzQ_LS0tCi0gLSA6YmFzaWMKICAtIEFib3V0CiAgLSAvYWJvdXQK", breadcrumb_trail
+  end
+
+  test "loading trail" do
+    params[:trail] = "12hY7tdmRCBzQ_LS0tCi0gLSA6YmFzaWMKICAtIEFib3V0CiAgLSAvYWJvdXQK"
+    breadcrumb :multiple_links
+
+    assert_equal %{<div class="breadcrumbs"><a href="/">Home</a> &gt; <a href="/about">About</a> &gt; <a href="/about/contact">Contact</a> &gt; <span class="current">Contact form</span></div>},
+                 breadcrumbs
+  end
+
+  test "different trail param" do
+    Gretel::Trail.trail_param = :mytest
+    params[:mytest] = "12hY7tdmRCBzQ_LS0tCi0gLSA6YmFzaWMKICAtIEFib3V0CiAgLSAvYWJvdXQK"
+    breadcrumb :multiple_links
+
+    assert_equal %{<div class="breadcrumbs"><a href="/">Home</a> &gt; <a href="/about">About</a> &gt; <a href="/about/contact">Contact</a> &gt; <span class="current">Contact form</span></div>},
+                 breadcrumbs
+  end
+
   test "reload configuration when file is changed" do
     path = setup_loading_from_tmp_folder
     Gretel.reload_environments << "test"

data/test/trail_test.rb

@@ -0,0 +1,30 @@
+require 'test_helper'
+
+class TrailTest < ActiveSupport::TestCase
+  setup do
+    Gretel::Trail.secret = "128107d341e912db791d98bbe874a8250f784b0a0b4dbc5d5032c0fc1ca7bda9c6ece667bd18d23736ee833ea79384176faeb54d2e0d21012898dde78631cdf1"
+    @links = [
+      ["root", "Home", "/"],
+      ["store", "Store", "/store"],
+      ["search", "Search", "/store/search?q=test"]
+    ]
+  end
+
+  test "defaults" do
+    assert_equal :trail, Gretel::Trail.trail_param
+  end
+
+  test "encoding" do
+    assert_equal "12hY7tdmRCBzQ_LS0tCi0gLSByb290CiAgLSBIb21lCiAgLSAvCi0gLSBzdG9yZQogIC0gU3RvcmUKICAtIC9zdG9yZQotIC0gc2VhcmNoCiAgLSBTZWFyY2gKICAtIC9zdG9yZS9zZWFyY2g_cT10ZXN0Cg==",
+                 Gretel::Trail.encode(@links.map { |key, text, url| Gretel::Link.new(key, text, url) })
+  end
+
+  test "decoding" do
+    assert_equal @links,
+                 Gretel::Trail.decode("12hY7tdmRCBzQ_LS0tCi0gLSByb290CiAgLSBIb21lCiAgLSAvCi0gLSBzdG9yZQogIC0gU3RvcmUKICAtIC9zdG9yZQotIC0gc2VhcmNoCiAgLSBTZWFyY2gKICAtIC9zdG9yZS9zZWFyY2g_cT10ZXN0Cg==").map { |link| [link.key, link.text, link.url] }
+  end
+
+  test "invalid trail" do
+    assert_equal [], Gretel::Trail.decode("12hY7tdmRCBzZ_LS0tCi0gLSByb290CiAgLSBIb21lCiAgLSAvCi0gLSBzdG9yZQogIC0gU3RvcmUKICAtIC9zdG9yZQotIC0gc2VhcmNoCiAgLSBTZWFyY2gKICAtIC9zdG9yZS9zZWFyY2g_cT10ZXN0Cc==")
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gretel
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0.rc1
 platform: ruby
 authors:
 - Lasse Bunk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-23 00:00:00.000000000 Z
+date: 2013-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -62,6 +62,7 @@ files:
 - lib/gretel/crumbs.rb
 - lib/gretel/deprecated.rb
 - lib/gretel/link.rb
+- lib/gretel/trail.rb
 - lib/gretel/version.rb
 - lib/gretel/view_helpers.rb
 - test/deprecated_test.rb
@@ -107,6 +108,7 @@ files:
 - test/gretel_test.rb
 - test/helper_methods_test.rb
 - test/test_helper.rb
+- test/trail_test.rb
 homepage: http://github.com/lassebunk/gretel
 licenses:
 - MIT
@@ -122,9 +124,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.0.3
@@ -175,3 +177,4 @@ test_files:
 - test/gretel_test.rb
 - test/helper_methods_test.rb
 - test/test_helper.rb
+- test/trail_test.rb