declarative-find 1.0 → 1.0.1

data/README.markdown

@@ -1,16 +1,16 @@
-Declarative Find for Rails
-=======================
+Declarative Find
+================
 
-This Rails plugin makes a `find` method available at the class level in `ApplicationController` which takes the name of an ActiveRecord model. Using this method creates a before filter which finds an ActiveRecord instance and assigns it to an appropriately named instance variable in the controller. The name of the model passed to `find` is used for both the key in `params` assumed to contain the ID of the record to find as well as the name of the instance variable to assign it to. An 404 HTTP code will be returned and the corresponding error page rendered for non-existent records via the [`http-error` gem](http://codyrobbins.com/software/http-error).
+This Rails plugin makes a `find` method available at the class level in `ApplicationController` which takes the name of an ActiveRecord model. Using this method creates a before filter which finds an ActiveRecord instance and assigns it to an appropriately named instance variable in the controller. The name of the model passed to `find` is used for both the key in `params` assumed to contain the ID of the record to find as well as the name of the instance variable to assign it to. This behavior can be customized any which way via options. An 404 HTTP code will be returned and the corresponding error page rendered for non-existent records via the [`http-error` gem](http://codyrobbins.com/software/http-error).
 
 Full documentation is at [RubyDoc.info](http://rubydoc.info/gems/declarative-find).
 
 Examples
 --------
 
-The following examples assume the request for the `delete` action has an `:id` or `:user` param passed to it with the ID of the user to delete.
+### Straight-forward
 
-### All actions
+The following example assumes the request for the `delete` action has an `:id` or `:user` param passed to it with the ID of the user to delete.
 
     class UserController < ApplicationController
       find(:user)
@@ -20,7 +20,45 @@ The following examples assume the request for the `delete` action has an `:id` o
       end
     end
 
-### Options
+### Different parameter name
+
+The following example assumes the request for the `delete` action has a `:user_id` param passed to it with the ID of the user to delete.
+
+    class UserController < ApplicationController
+      find(:user, :param => :user_id)
+
+      def delete
+        @user.destroy
+      end
+    end
+
+### Different instance variable name
+
+    class UserController < ApplicationController
+      find(:user, :variable => :user_to_delete)
+
+      def delete
+        @user_to_delete.destroy
+      end
+    end
+
+### Custom lookup
+
+    class UserController < ApplicationController
+      find(:user)
+
+      def delete
+        @user.destroy
+      end
+
+      protected
+
+      def find_user
+        User.find_by_email(params[:email])
+      end
+    end
+
+### Pass-through of options
 
 The find can be restricted to specific actions the same way a typical before filter can be—in fact, any options passed to `find` are simply passed through to `before_filter`.
 
@@ -39,6 +77,10 @@ The find can be restricted to specific actions the same way a typical before fil
 Colophon
 --------
 
+### See also
+
+If you like this gem, you may also want to check out [Create New](http://codyrobbins.com/software/create-new), [Save Changes To](http://codyrobbins.com/software/save-changes-to), or [HTTP Error](http://codyrobbins.com/software/http-error).
+
 ### Tested with
 
 * Rails 3.0.5 — 20 May 2011
@@ -55,4 +97,5 @@ To send patches, please fork on GitHub and submit a pull request.
 © 2011 [Cody Robbins](http://codyrobbins.com/). See LICENSE for details.
 
 * [Homepage](http://codyrobbins.com/software/declarative-find)
+* [My other gems](http://codyrobbins.com/software#gems)
 * [Follow me on Twitter](http://twitter.com/codyrobbins)

data/declarative-find.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name     = 'declarative-find'
-  s.version  = '1.0'
+  s.version  = '1.0.1'
   s.summary  = 'Find records for Rails controller actions declaratively.'
   s.homepage = 'http://codyrobbins.com/software/declarative-find'
   s.author   = 'Cody Robbins'
@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
 
   s.post_install_message = '
 -------------------------------------------------------------
-Follow me on Twitter: http://twitter.com/codyrobbins
+Follow me on Twitter! http://twitter.com/codyrobbins
 -------------------------------------------------------------
 
 '

data/lib/cody_robbins/declarative_find/class_methods.rb

@@ -6,15 +6,19 @@ module CodyRobbins
       # Creates a before filter on the controller that finds an ActiveRecord instance and assigns it to an instance variable.
       #
       # * You pass the name of the model to look up to the method.
-      # * The key in `params` assumed to contain the ID of the record to find is either `:id` or, if `:id` is not present, then extrapolated from the model name. For example, if the model is `User` then this key would be `:user`. Preference is given to `:id` to prevent conflicts in situations such as edit actions, where a record is looked up but new values for its attributes are passed via a key in `params` sharing the name of the model. For example, if the model is `User` then `params[:user]` would contain the attributes for the user from the form, and `:id` would have to be used to specify the ID of the user in question.
-      # * The instance variable that the record is assigned to will be named according to the model. For example, if the model is `User` then the instance variable will be `@user`.
+      # * By default the key in `params` assumed to contain the ID of the record to find is either `:id` or, if `:id` is not present, then extrapolated from the model name. For example, if the model is `User` then this key would be `:user`. Preference is given to `:id` to prevent conflicts in situations such as edit actions, where a record is looked up but new values for its attributes are passed via a key in `params` sharing the name of the model. For example, if the model is `User` then `params[:user]` would contain the attributes for the user from the form, and `:id` would have to be used to specify the ID of the user in question.
+      # * By default the instance variable that the record is assigned to will be named according to the model. For example, if the model is `User` then the instance variable will be `@user`.
+      # * This behavior can be customized any which way via different combinations of options.
       #
       # An 404 HTTP code will be returned and the corresponding error page rendered for non-existent records via the [`http-error` gem](http://codyrobbins.com/software/http-error).
       #
       # @param name [Symbol, String] The name of the model to look up.
-      # @param filter_options [Hash] Options to pass through to the underlying `before_filter`. For example, you could limit the lookup to a specific action by using the `:only` option.
+      # @param options [Hash] Any options not specifically used by the plugin method are simply passed through to the underlying `before_filter`. For example, you could limit the lookup to a specific action by including the `:only` option.
+      # @option options [String, Symbol] :param The key used to look up the record’s ID in the `params` hash. It defaults to the name of the model. For example, if the model is `User` then this option will default to `:user`.
+      # @option options [String, Symbol] :variable The name of the instance variable to assign the looked up object to. It defaults to the name of the model. For example, if the model is `User` then this option will default to `:user`.
+      # @option options [String, Symbol, Proc] :using If this option is string or symbol, it represents the name of a method on the controller that will be invoked in order to perform the look up. If it’s a `Proc`, then the proc is invoked to perform the look up. In either case, the return value should be the object to assign to the instance variable. This option can be used when custom logic needs to be provided to find a record beyond simply looking up by its ID. This option defaults to `:find_` prepended to the name of the model. For example, if the model is `User` then this option will default to `:find_user`.
       #
-      # @example The following examples assume the request for the `delete` action has an `:id` or `:user` param passed to it with the ID of the user to delete.
+      # @example Straight-forward lookup. This example assumes the request for the `delete` action has an `:id` or `:user` param passed to it containing the ID of the user to delete.
       #    class UserController < ApplicationController
       #      find(:user)
       #
@@ -22,7 +26,73 @@ module CodyRobbins
       #        @user.destroy
       #      end
       #    end
-      # @example Restricting the find to specific actions.
+      # @example Overriding the name of the parameter containing the ID of the model. This example assumes the request for the `delete` action has a `:user_id` param passed to it containing the ID of the user to delete.
+      #    class UserController < ApplicationController
+      #      find(:user, :param => :user_id)
+      #
+      #      def delete
+      #        @user.destroy
+      #      end
+      #    end
+      # @example Overriding the name of the instance variable used to store the record. This example assumes the request for the `delete` action has an `:id` or `:user` param passed to it containing the ID of the user to delete.
+      #    class UserController < ApplicationController
+      #      find(:user, :variable => :user_to_delete)
+      #
+      #      def delete
+      #        @user_to_delete.destroy
+      #      end
+      #    end
+      # @example Using a method to provide custom logic for the lookup of the model.
+      #    class UserController < ApplicationController
+      #      find(:user)
+      #
+      #      def delete
+      #        @user.destroy
+      #      end
+      #
+      #      protected
+      #
+      #      def find_user
+      #        User.find_by_email(params[:email])
+      #      end
+      #    end
+      # @example Using a custom-named method to provide the logic for the lookup of the model.
+      #    class UserController < ApplicationController
+      #      find(:user, :using => :find_user_by_email)
+      #
+      #      def delete
+      #        @user.destroy
+      #      end
+      #
+      #      protected
+      #
+      #      def find_user_by_email
+      #        User.find_by_email(params[:email])
+      #      end
+      #    end
+      # @example Using a `Proc` to provide custom logic for the lookup of the model.
+      #    class UserController < ApplicationController
+      #      find(:user, :using => proc { User.find_by_email(params[:email]) })
+      #
+      #      def delete
+      #        @user.destroy
+      #      end
+      #
+      #      protected
+      #
+      #      def find_user_by_email
+      #        User.find_by_email(params[:email])
+      #      end
+      #    end
+      # @example Using a block to provide custom logic for the lookup of the model.
+      #    class UserController < ApplicationController
+      #      find(:user) { User.find_by_email(params[:email]) }
+      #
+      #      def delete
+      #        @user.destroy
+      #      end
+      #    end
+      # @example Restricting the lookup to specific actions.
       #    class UserController < ApplicationController
       #      find(:user, :only => :delete)
       #
@@ -34,14 +104,30 @@ module CodyRobbins
       #        render(:text => 'Something else.')
       #      end
       #    end
-      def find(name, filter_options = {})
-        before_filter(filter_options) do
-          model = name.to_class
-          id = params[:id] || params[name]
-          object = model.find_by_id(id)
+      def find(name, options = {}, &block)
+        options.reverse_merge!(:param    => name,
+                               :variable => name,
+                               :using    => "find_#{name}")
+
+        model         = name.to_class
+        param_name    = options.delete(:param)
+        variable_name = options.delete(:variable)
+        lookup_method = options.delete(:using)
+
+        before_filter(options) do
+          object = if block_given?
+                     yield
+                   elsif lookup_method.is_a?(Proc)
+                     lookup_method.call
+                   elsif lookup_method.respond_to?(:to_s) && respond_to?(lookup_method.to_s)
+                     send(lookup_method.to_s)
+                   else
+                     id = params[:id] || params[param_name]
+                     model.find_by_id(id)
+                   end
 
           if object
-            set_instance_variable(name, object)
+            set_instance_variable(variable_name, object)
           else
             http_error(404)
           end

metadata

@@ -1,8 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: declarative-find
 version: !ruby/object:Gem::Version 
-  prerelease: 
-  version: "1.0"
+  hash: 21
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 1
+  version: 1.0.1
 platform: ruby
 authors: 
 - Cody Robbins
@@ -10,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-24 00:00:00 -04:00
+date: 2011-07-18 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -21,6 +26,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
   type: :runtime
   version_requirements: *id001
@@ -32,6 +40,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
   type: :runtime
   version_requirements: *id002
@@ -43,6 +54,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
   type: :runtime
   version_requirements: *id003
@@ -67,10 +81,12 @@ has_rdoc: true
 homepage: http://codyrobbins.com/software/declarative-find
 licenses: []
 
-post_install_message: "\n\
-  -------------------------------------------------------------\n\
-  Follow me on Twitter: http://twitter.com/codyrobbins\n\
-  -------------------------------------------------------------\n\n"
+post_install_message: |+
+  
+  -------------------------------------------------------------
+  Follow me on Twitter! http://twitter.com/codyrobbins
+  -------------------------------------------------------------
+  
 rdoc_options: []
 
 require_paths: 
@@ -80,17 +96,23 @@ required_ruby_version: !ruby/object:Gem::Requirement
   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.6.2
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Find records for Rails controller actions declaratively.