grosser-userstamp 2.0.0

data/CHANGELOG

@@ -0,0 +1,26 @@
+2.0 (2-17-2008)
+    * [Ben  Wyrosdick] - Added a migration helper that gives migration scripts a <tt>userstamps</tt>
+                         method.
+    * [Marshall Roch]  - Stamping can be temporarily turned off using the 'without_stamps' class
+                         method. 
+      Example:
+        Post.without_stamps do
+          post = Post.find(params[:id])
+          post.update_attributes(params[:post])
+          post.save
+        end
+
+    * Models that should receive updates made by 'stampers' now use the acts_as_stampable class
+      method. This sets up the belongs_to relationships and also injects private methods for use by
+      the individual callback filter methods.
+
+    * Models that are responsible for updating now use the acts_as_stamper class method. This
+      injects the stamper= and stamper methods that are thread safe and should be updated per
+      request by a controller.
+
+    * The Userstamp module is now meant to be included with one of your project's controllers (the
+      Application Controller is recommended). It creates a before filter called 'set_stampers' that
+      is responsible for setting all the current Stampers.
+
+1.0 (01-18-2006)
+    * Initial Release

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2008 DeLynn Berry
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,179 @@
+= Userstamp Plugin (v 2.0)
+
+== Overview
+
+The Userstamp Plugin extends ActiveRecord::Base[http://api.rubyonrails.com/classes/ActiveRecord/Base.html] to add automatic updating of 'creator',
+'updater', and 'deleter' attributes. It is based loosely on the ActiveRecord::Timestamp[http://api.rubyonrails.com/classes/ActiveRecord/Timestamp.html] module.
+
+Two class methods (<tt>model_stamper</tt> and <tt>stampable</tt>) are implemented in this plugin.
+The <tt>model_stamper</tt> method is used in models that are responsible for creating, updating, or
+deleting other objects. The <tt>stampable</tt> method is used in models that are subject to being
+created, updated, or deleted by 'stampers'.
+
+
+== Installation
+Installation of the plugin can be done using the built in Rails plugin script. Issue the following
+command from the root of your application:
+
+  script/plugin install git://github.com/delynn/userstamp.git
+
+Once installed you will need to restart your application for the plugin to be loaded into the Rails
+environment.
+
+You might also be interested in using Piston[http://piston.rubyforge.org/index.html] to manage the
+importing and future updating of this plugin.
+
+== Usage
+In this new version of the Userstamp plug-in, the assumption is that you have two different
+categories of objects; those that mani˝pulate, and those that are manipulated. For those objects
+that are being manipulated there's the Stampable module and for the manipulators there's the
+Stamper module. There's also the actual Userstamp module for your controllers that assists in
+setting up your environment on a per request basis.
+
+To better understand how all this works, I think an example is in order. For this example we will
+assume that a weblog application is comprised of User and Post objects. The first thing we need to
+do is create the migrations for these objects, and the plug-in gives you a <tt>userstamps</tt>
+method for very easily doing this:
+
+  class CreateUsers < ActiveRecord::Migration
+    def self.up
+      create_table :users, :force => true do |t|
+        t.timestamps
+        t.userstamps
+        t.name
+      end
+    end
+    
+    def self.down
+      drop_table :users
+    end
+  end
+  
+  class CreatePosts < ActiveRecord::Migration
+    def self.up
+      create_table :posts, :force => true do |t|
+        t.timestamps
+        t.userstamps
+        t.title
+      end
+    end
+    
+    def self.down
+      drop_table :posts
+    end
+  end
+
+Second, since Users are going to manipulate other objects in our project, we'll use the
+<tt>model_stamper</tt> method in our User class:
+
+  class User < ActiveRecord::Base
+    model_stamper
+  end
+
+Finally, we need to setup a controller to set the current user of the application. It's
+recommended that you do this in your ApplicationController:
+
+  class ApplicationController < ActionController::Base
+    include Userstamp
+  end
+
+If all you are interested in is making sure all tables that have the proper columns are stamped
+by the currently logged in user you can stop right here. More than likely you want all your
+associations setup on your stamped objects, and that's where the <tt>stampable</tt> class method
+comes in. So in our example we'll want to use this method in both our User and Post classes:
+
+  class User < ActiveRecord::Base
+    model_stamper
+    stampable
+  end
+  
+  class Post < ActiveRecord::Base
+    stampable
+  end
+
+Okay, so what all have we done? The <tt>model_stamper</tt> class method injects two methods into the
+User class. They are #stamper= and #stamper and look like this:
+
+  def stamper=(object)
+    object_stamper = if object.is_a?(ActiveRecord::Base)
+      object.send("#{object.class.primary_key}".to_sym)
+    else
+      object
+    end
+    
+    Thread.current["#{self.to_s.downcase}_#{self.object_id}_stamper"] = object_stamper
+  end
+
+  def stamper
+    Thread.current["#{self.to_s.downcase}_#{self.object_id}_stamper"]
+  end
+
+The big change with this new version is that we are now using Thread.current to save the current
+stamper so as to avoid conflict with concurrent requests.
+
+The <tt>stampable</tt> method allows you to customize what columns will get stamped, and also
+creates the +creator+, +updater+, and +deleter+ associations.
+
+The Userstamp module that we included into our ApplicationController uses the setter method to
+set which user is currently making the request. By default the 'set_stampers' method works perfectly
+with the RestfulAuthentication[http://svn.techno-weenie.net/projects/plugins/restful_authentication] plug-in:
+
+  def set_stampers
+    User.stamper = self.current_user
+  end
+
+If you aren't using ActsAsAuthenticated, then you need to create your own version of the
+<tt>set_stampers</tt> method in the controller where you've included the Userstamp module.
+
+Now, let's get back to the Stampable module (since it really is the interesting one). The Stampable
+module sets up before_* filters that are responsible for setting those attributes at the appropriate
+times. It also creates the belongs_to relationships for you.
+
+If you need to customize the columns that are stamped, the <tt>stampable</tt> method can be
+completely customized. Here's an quick example:
+
+  class Post < ActiveRecord::Base
+    acts_as_stampable :stamper_class_name => :person,
+                      :creator_attribute  => :create_user,
+                      :updater_attribute  => :update_user,
+                      :deleter_attribute  => :delete_user
+  end
+
+If you are upgrading your application from the old version of Userstamp, there is a compatibility
+mode to have the plug-in use the old "_by" columns by default. To enable this mode, add the
+following line to the RAILS_ROOT/config/environment.rb file:
+
+  Ddb::Userstamp.compatibility_mode = true
+  
+If you are having a difficult time getting the Userstamp plug-in to work, I recommend you checkout
+the sample application that I created. You can find this application on GitHub[http://github.com/delynn/userstamp_sample]
+
+== Uninstall
+Uninstalling the plugin can be done using the built in Rails plugin script. Issue the following
+command from the root of your application:
+
+  script/plugin remove userstamp
+
+
+== Documentation
+RDoc has been run on the plugin directory and is available in the doc directory.
+
+
+== Running Unit Tests
+There are extensive unit tests in the "test" directory of the plugin. These test can be run
+individually by executing the following command from the userstamp directory:
+
+ ruby test/compatibility_stamping_test.rb
+ ruby test/stamping_test.rb
+ ruby test/userstamp_controller_test.rb
+
+
+== Bugs & Feedback
+Bug reports and feedback are welcome via my delynn+userstamp@gmail.com email address. I also
+encouraged everyone to clone the git repository and make modifications--I'll be more than happy
+to merge any changes from other people's branches that would be beneficial to the whole project.
+
+
+== Credits and Special Thanks
+The original idea for this plugin came from the Rails Wiki article entitled
+{Extending ActiveRecord}[http://wiki.rubyonrails.com/rails/pages/ExtendingActiveRecordExample].

data/Rakefile

@@ -0,0 +1,36 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the userstamp plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the userstamp plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Userstamp'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README', 'CHANGELOG', 'LICENSE')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'echoe'
+# update:
+# rake build_gemspec
+# rake install (always test that it builds, before uploading to github)
+Echoe.new('userstamp', '2.0.0') do |p|
+  p.description    = "This Rails plugin extends ActiveRecord::Base to add automatic updating of created_by and updated_by attributes of your models in much the same way that the ActiveRecord::Timestamp module updates created_(at/on) and updated_(at/on) attributes."
+  p.url            = "http://github.com/delynn/userstamp"
+  p.author         = "DeLynn Berry"
+  p.email          = "delynn@gmail.com"
+  p.ignore_pattern = ["tmp/*", "script/*", "nbproject/*", "rdoc/*"]
+  p.dependencies   = ['actionpack','activerecord','activesupport']
+  p.development_dependencies = ['echoe','activerecord','activesupport','actionpack']
+end

data/init.rb

@@ -0,0 +1 @@
+require 'userstamp'

data/lib/ddb/userstamp.rb

@@ -0,0 +1,44 @@
+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.send           :include, InstanceMethods
+        base.before_filter  :set_stamper
+        base.after_filter   :reset_stamper
+      end
+
+      module InstanceMethods
+        private
+          # 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
+
+          # 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
+      end
+    end
+  end
+end
+
+ActionController::Base.send(:include, Ddb::Controller) if defined?(ActionController)

data/lib/ddb/userstamp/migration_helper.rb

@@ -0,0 +1,19 @@
+module Ddb
+  module Userstamp
+    module MigrationHelper
+      def self.included(base) # :nodoc:
+        base.send(:include, InstanceMethods)
+      end
+
+      module InstanceMethods
+        def userstamps(include_deleted_by = false)
+          column(Ddb::Userstamp.compatibility_mode ? :created_by : :creator_id, :integer)
+          column(Ddb::Userstamp.compatibility_mode ? :updated_by : :updater_id, :integer)
+          column(Ddb::Userstamp.compatibility_mode ? :deleted_by : :deleter_id, :integer) if include_deleted_by
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::ConnectionAdapters::TableDefinition.send(:include, Ddb::Userstamp::MigrationHelper)

data/lib/ddb/userstamp/stampable.rb

@@ -0,0 +1,151 @@
+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:
+        super
+
+        base.extend(ClassMethods)
+        base.class_eval do
+          include InstanceMethods
+
+          # 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,
+                        :creator_attribute  => Ddb::Userstamp.compatibility_mode ? :created_by : :creator_id,
+                        :updater_attribute  => Ddb::Userstamp.compatibility_mode ? :updated_by : :updater_id,
+                        :deleter_attribute  => Ddb::Userstamp.compatibility_mode ? :deleted_by : :deleter_id
+                      }.merge(options)
+
+          self.stamper_class_name = defaults[:stamper_class_name].to_sym
+          self.creator_attribute  = defaults[:creator_attribute].to_sym
+          self.updater_attribute  = defaults[:updater_attribute].to_sym
+          self.deleter_attribute  = defaults[:deleter_attribute].to_sym
+
+          class_eval do
+            belongs_to :creator, :class_name => self.stamper_class_name.to_s.singularize.camelize,
+                                 :foreign_key => self.creator_attribute
+                                 
+            belongs_to :updater, :class_name => self.stamper_class_name.to_s.singularize.camelize,
+                                 :foreign_key => self.updater_attribute
+                                 
+            before_save     :set_updater_attribute
+            before_create   :set_creator_attribute
+                                 
+            if defined?(Caboose::Acts::Paranoid)
+              belongs_to :deleter, :class_name => self.stamper_class_name.to_s.singularize.camelize,
+                                   :foreign_key => self.deleter_attribute
+              before_destroy  :set_deleter_attribute
+            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 #:nodoc:
+          stamper_class_name.to_s.capitalize.constantize rescue nil
+        end
+      end
+
+      module InstanceMethods #:nodoc:
+        private
+          def has_stamper?
+            !self.class.stamper_class.nil? && !self.class.stamper_class.stamper.nil? rescue false
+          end
+
+          def set_creator_attribute
+            return unless self.record_userstamp
+            if respond_to?(self.creator_attribute.to_sym) && has_stamper?
+              self.send("#{self.creator_attribute}=".to_sym, 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?
+              self.send("#{self.updater_attribute}=".to_sym, 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?
+              self.send("#{self.deleter_attribute}=".to_sym, self.class.stamper_class.stamper)
+              save
+            end
+          end
+        #end private
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send(:include, Ddb::Userstamp::Stampable) if defined?(ActiveRecord)