redirectr 0.0.4

data/README

@@ -0,0 +1,50 @@
+Redirectr
+=========
+
+In many web applications, the user triggers actions that result in simple or complex workflows that should, after that workflow is finished, result in the user being redirected to the page where he initially started it. Another example would be a "back"-Link on any page.
+A simple but completely Un-RESTful way would be to store the "current" page in a cookie each time the user calls an action and redirect to the url stored there if needed.
+
+A much better (and potentially even cacheable) way is to encode the "backlink" URL in an URL parameter or form field and pass it along with every workflow step until the last (or only) action uses it to redirect the user back to where he initially came from.
+
+Redirectr really does nothing more than provide a simple API for exactly that.
+
+Redirectr provides a few Controller and Helper methods that will be included in your ApplicationController and ApplicationHelper, respectively.
+
+Installation
+============
+
+With Rails 3, just at the following to your Gemfile
+
+    gem 'redirectr', :git => 'https://github.com/wvk/redirectr.git'
+
+and then call
+
+    bundle install
+
+Example
+=======
+
+Suppose you have an application with a contact form that can be reached via a footer link on every page. After submitting the form, the user should be redirected to the page he was before clicking on the "contact form" link.
+
+for the footer link to the contact form:
+
+    <%= link_to 'Contact us!', new_contact_path(referrer_param => current_path) %>
+
+In the 'new contact' view:
+
+    <%= form for ... do |f| %>
+      <%= hidden_referrer_input_tag %>
+      <!-- ... -->
+    <% end %>
+
+and finally, in the 'create' action of your ContactsController:
+
+    def create
+      # ...
+      redirect_to back_or_default
+    end
+
+for more detailled examples, see the Rdoc documentation.
+
+
+Copyright (c) 2010 Willem van Kerkhof <wvk@consolving.de>, released under the MIT license

data/lib/redirectr.rb

@@ -0,0 +1,135 @@
+module Redirectr
+  REFERRER_PARAM_NAME = :referrer
+
+  module ControllerMethods
+    def self.included(base)
+      base.send :include, InstanceMethods
+      base.send :extend, ClassMethods
+
+      base.send :helper_method,
+        :current_path,
+        :referrer_or_current_path,
+        :back_or_default,
+        :referrer_path,
+        :referrer_param
+    end
+
+    module ClassMethods
+      # Used to set a different param name where the referrer path should be stored.
+      # Default is :referrer, a sensible alternative would be :r or so.
+      # Example:
+      #
+      #   class MyController
+      #     use_referrer_param_name :r
+      #     # ...
+      #   end
+      #
+      def use_referrer_param_name(new_name)
+        const_set Redirectr::REFERRER_PARAM_NAME, new_name.to_sym
+      end
+    end
+
+    module InstanceMethods
+
+      # Return the name of the parameter used to pass the referrer path.
+      # Use this instead of the real param name in creating your own links
+      # to allow easily changing the name later
+      # Example:
+      #
+      #  <%= link_to my_messages_path :filter_by => 'date', referrer_param => current_path %>
+      #
+      def referrer_param
+        Redirectr::REFERRER_PARAM_NAME
+      end
+
+      # Return the path of the current request.
+      # note that this path does NOT include any query parameters nor the hostname,
+      # thus allowing you to navigate within the application only. This may be changed
+      # in the future. If you need a different behaviour now, just overwrite this method
+      # in your controller.
+      # Example:
+      #
+      #  <%= link_to my_messages_path referrer_param => current_path %>
+      #
+      def current_path
+        # maybe we want to use request.env['REQUEST_URI'] in the future...?
+        request.env['PATH_INFO']
+      end
+
+      # Return the referrer or the current path, it the former is not set.
+      # Useful in cases where there might be a redirect path that has to be
+      # taken note of but in case it is not present, the current path will be
+      # redirected back to.
+      # Example:
+      #
+      #  <%= link_to my_messages_path referrer_param => referrer_or_current_path %>
+      #
+      def referrer_or_current_path
+        referrer_path.blank? ? current_path : referrer_path
+      end
+
+      # Used in back links, referrer based redirection after actions etc.
+      # Accepts a default redirect path in case no param[referrer_param]
+      # is set, default being root_path.
+      # Can and should be overwritten in namespace specific controllers
+      # to set a sensible default if no referrer is given.
+      # Example:
+      #
+      #   class MyController
+      #     def create
+      #       @my = My.create(...)
+      #       redirect_to back_or_default(my_path)
+      #     end
+      #   end
+      #
+      # The above example will redirect to the referrer_path if it is defined, otherwise
+      # it will redirect to the my_path
+      #
+      # Example:
+      #
+      #   class MyController
+      #     def create
+      #       @my = My.create(...)
+      #       redirect_to back_or_default
+      #     end
+      #   end
+      #
+      # The above example will redirect to the referrer_path if it is defined, otherwise
+      # it will redirect to the root_path of the application.
+      def back_or_default(default = nil)
+        unless referrer_path.blank?
+          referrer_path
+        else
+          root_path
+        end
+      end
+
+      # Convenience method for params[referrer_param]
+      def referrer_path
+        params[referrer_param]
+      end
+    end
+
+  end
+
+  module Helpers
+    # Create a link back to the path specified in the referrer-param.
+    # title can be either a text string or anything else like an image.
+    # Remember to call #html_safe on the title argument if it contains
+    # HTML and you are using Rails 3.
+    def link_to_back(title, options = {})
+      link_to title, back_or_default, options
+    end
+
+    # Create a hidden input field containing the referrer or current path.
+    # Handy for use in forms that are called with a referrer param which
+    # has to be passed on and respected by the form processing action.
+    def hidden_referrer_input_tag
+      hidden_field_tag :referrer, referrer_or_current_path
+    end
+
+  end # module Helpers
+end # module Redirectr
+
+ActionController::Base.send :include, Redirectr::ControllerMethods
+ActionView::Helpers.send :include, Redirectr::Helpers

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: redirectr
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 4
+  version: 0.0.4
+platform: ruby
+authors: 
+- Willem van Kerkhof
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-16 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: Provides Rails-helper methods for referrer-style backlinks and setting redirect URLs after form submussion
+email: wvk@consolving.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README
+- init.rb
+- lib/redirectr.rb
+has_rdoc: true
+homepage: http://github.com/wvk/redirectr
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Provides Rails-helper methods for referrer-style backlinks
+test_files: []
+