Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Updating documentation.

  • Loading branch information...
commit 48334f21e5c128250e538fed809a1a22fee2286c 1 parent 326ff65
@delynn delynn authored
Showing with 94 additions and 18 deletions.
  1. +66 −13 lib/stampable.rb
  2. +5 −1 lib/stamper.rb
  3. +23 −4 lib/userstamp.rb
View
79 lib/stampable.rb
@@ -1,24 +1,70 @@
module Ddb #:nodoc:
module Userstamp
+ # Determines what default columns to use for recording the current stamper.
+ # By default this is set to false, so the plug-in will use columns named
+ # <tt>creator_id</tt>, <tt>updater_id</tt>, and <tt>deleter_id</tt>.
+ #
+ # To turn compatibility mode on, place the following line in your environment.rb
+ # file:
+ #
+ # Ddb::Userstamp.compatibility_mode = true
+ #
+ # This will cause the plug-in to use columns named <tt>created_by</tt>,
+ # <tt>updated_by</tt>, and <tt>deleted_by</tt>.
mattr_accessor :compatibility_mode
@@compatibility_mode = false
-
+
+ # Extends the stamping functionality of ActiveRecord by automatically recording the model
+ # responsible for creating, updating, and deleting the current object. See the Stamper
+ # and Userstamp modules for further documentation on how the entire process works.
module Stampable
- def self.included(base) # :nodoc:
+ def self.included(base) #:nodoc:
super
-
+
base.extend(ClassMethods)
base.class_eval do
include InstanceMethods
-
- class_inheritable_accessor :record_userstamp, :stamper_class_name, :creator_attribute,
- :updater_attribute, :deleter_attribute
+
+ # Should ActiveRecord record userstamps? Defaults to true.
+ class_inheritable_accessor :record_userstamp
self.record_userstamp = true
+
+ # Which class is responsible for stamping? Defaults to :user.
+ class_inheritable_accessor :stamper_class_name
+
+ # What column should be used for the creator stamp?
+ # Defaults to :creator_id when compatibility mode is off
+ # Defaults to :created_by when compatibility mode is on
+ class_inheritable_accessor :creator_attribute
+
+ # What column should be used for the updater stamp?
+ # Defaults to :updater_id when compatibility mode is off
+ # Defaults to :updated_by when compatibility mode is on
+ class_inheritable_accessor :updater_attribute
+
+ # What column should be used for the deleter stamp?
+ # Defaults to :deleter_id when compatibility mode is off
+ # Defaults to :deleted_by when compatibility mode is on
+ class_inheritable_accessor :deleter_attribute
+
self.stampable
end
end
module ClassMethods
+ # This method is automatically called on for all classes that inherit from
+ # ActiveRecord, but if you need to customize how the plug-in functions, this is the
+ # method to use. Here's an example:
+ #
+ # class Post < ActiveRecord::Base
+ # stampable :stamper_class_name => :person,
+ # :creator_attribute => :create_user,
+ # :updater_attribute => :update_user,
+ # :deleter_attribute => :delete_user
+ # end
+ #
+ # The method will automatically setup all the associations, and create <tt>before_save</tt>
+ # and <tt>before_create</tt> filters for doing the stamping.
def stampable(options = {})
defaults = {
:stamper_class_name => :user,
@@ -49,20 +95,27 @@ def stampable(options = {})
end
end
end
-
+
+ # Temporarily allows you to turn stamping off. For example:
+ #
+ # Post.without_stamps do
+ # post = Post.find(params[:id])
+ # post.update_attributes(params[:post])
+ # post.save
+ # end
def without_stamps
original_value = self.record_userstamp
self.record_userstamp = false
yield
self.record_userstamp = original_value
end
-
- def stamper_class
+
+ def stamper_class #:nodoc:
stamper_class_name.to_s.capitalize.constantize rescue nil
end
end
- module InstanceMethods
+ module InstanceMethods #:nodoc:
private
def has_stamper?
!self.class.stamper_class.nil? && !self.class.stamper_class.stamper.nil?
@@ -71,21 +124,21 @@ def has_stamper?
def set_creator_attribute
return unless self.record_userstamp
if respond_to?(self.creator_attribute.to_sym) && has_stamper?
- write_attribute(self.creator_attribute, self.class.stamper_class.stamper)
+ self.creator = self.class.stamper_class.stamper
end
end
def set_updater_attribute
return unless self.record_userstamp
if respond_to?(self.updater_attribute.to_sym) && has_stamper?
- write_attribute(self.updater_attribute, self.class.stamper_class.stamper)
+ self.updater = self.class.stamper_class.stamper
end
end
def set_deleter_attribute
return unless self.record_userstamp
if respond_to?(self.deleter_attribute.to_sym) && has_stamper?
- write_attribute(self.deleter_attribute, self.class.stamper_class.stamper)
+ self.deleter = self.class.stamper_class.stamper
save
end
end
View
6 lib/stamper.rb
@@ -14,6 +14,8 @@ def model_stamper
end
module InstanceMethods
+ # Used to set the stamper for a particular request. See the Userstamp module for more
+ # details on how to use this method.
def stamper=(object)
object_stamper = if object.is_a?(ActiveRecord::Base)
object.send("#{object.class.primary_key}".to_sym)
@@ -24,10 +26,12 @@ def stamper=(object)
Thread.current["#{self.to_s.downcase}_#{self.object_id}_stamper"] = object_stamper
end
+ # Retrieves the existing stamper for the current request.
def stamper
- Thread.current["#{self.to_s.downcase}_#{self.object_id}_stamper"]
+ find(Thread.current["#{self.to_s.downcase}_#{self.object_id}_stamper"])
end
+ # Sets the stamper back to +nil+ to prepare for the next request.
def reset_stamper
Thread.current["#{self.to_s.downcase}_#{self.object_id}_stamper"] = nil
end
View
27 lib/userstamp.rb
@@ -1,19 +1,38 @@
module Ddb
module Controller
+ # The Userstamp module, when included into a controller, adds a before filter
+ # (named <tt>set_stamper</tt>) and an after filter (name <tt>reset_stamper</tt>).
+ # These methods assume a couple of things, but can be re-implemented in your
+ # controller to better suite your application.
+ #
+ # See the documentation for <tt>set_stamper</tt> and <tt>reset_stamper</tt> for
+ # specific implementation details.
module Userstamp
def self.included(base) # :nodoc:
- base.before_filter :set_stampers
- base.after_filter :reset_stampers
base.send :include, InstanceMethods
+ base.before_filter :set_stamper
+ base.after_filter :reset_stamper
end
module InstanceMethods
private
- def set_stampers
+ # The <tt>set_stamper</tt> method as implemented here assumes a couple
+ # of things. First, that you are using a +User+ model as the stamper
+ # and second that your controller has a <tt>current_user</tt> method
+ # that contains the currently logged in stamper. If either of these
+ # are not the case in your application you will want to manually add
+ # your own implementation of this method to the private section of
+ # the controller where you are including the Userstamp module.
+ def set_stamper
User.stamper = self.current_user
end
- def reset_stampers
+ # The <tt>reset_stamper</tt> method as implemented here assumes that a
+ # +User+ model is being used as the stamper. If this is not the case then
+ # you will need to manually add your own implementation of this method to
+ # the private section of the controller where you are including the
+ # Userstamp module.
+ def reset_stamper
User.reset_stamper
end
#end private
Please sign in to comment.
Something went wrong with that request. Please try again.