magiclabs-userstamp 2.0.2

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/Gemfile

@@ -0,0 +1,11 @@
+source :rubygems
+
+group :dev do
+  gem 'rake'
+  gem 'redgreen'
+  gem 'jeweler'
+  gem 'activerecord', :require => 'active_record'
+  gem 'activesupport', :require => 'active_support'
+  gem 'actionpack', :require => 'action_pack'
+  gem 'sqlite3-ruby', :require => 'sqlite3'
+end

data/Gemfile.lock

@@ -0,0 +1,55 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    abstract (1.0.0)
+    actionpack (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.4)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.13)
+      rack-test (~> 0.5.6)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activerecord (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      arel (~> 2.0.2)
+      tzinfo (~> 0.3.23)
+    activesupport (3.0.3)
+    arel (2.0.6)
+    builder (2.1.2)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    git (1.2.5)
+    i18n (0.5.0)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rack (1.2.1)
+    rack-mount (0.6.13)
+      rack (>= 1.0.0)
+    rack-test (0.5.7)
+      rack (>= 1.0)
+    rake (0.8.7)
+    redgreen (1.2.2)
+    sqlite3-ruby (1.3.2)
+    tzinfo (0.3.23)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  actionpack
+  activerecord
+  activesupport
+  jeweler
+  rake
+  redgreen
+  sqlite3-ruby

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/Rakefile

@@ -0,0 +1,38 @@
+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.rdoc', 'CHANGELOG', 'LICENSE')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  project_name = 'magiclabs-userstamp'
+  Jeweler::Tasks.new do |gem|
+    gem.name = project_name
+    gem.summary = "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."
+    gem.email = "delynn@gmail.com"
+    gem.homepage = "https://github.com/magiclabs/userstamp"
+    gem.authors = ["DeLynn Berry"]
+  end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler, or one of its dependencies, is not available. Install it with: gem install jeweler"
+end

data/Readme.rdoc

@@ -0,0 +1,163 @@
+== Userstamp
+
+
+== Fork Details
+
+This is a fork of the grosser fork [https://github.com/grosser/userstamp] of the original userstamp plugin created by delynn [https://github.com/delynn/userstamp]. 
+
+This fork has been created to combine the grosser changes that enable use of the plugin within applications that perform soft deletes but are not using the acts_as_paranoid plugin/gem (for example this fork can now be used in conjunction with the rails3_acts_as_paranoid plugin/gem [https://github.com/goncalossilva/rails3_acts_as_paranoid]).
+
+This fork also includes changes to perform the model stamping before validation is performed so that the model can enforce the presence of stamp attribute values eg.
+
+  validates :created_by, :presence => true
+  validates :updated_by, :presence => true
+	
+	
+== Using the Fork
+
+To use this fork add the following to your application gemfile:
+
+  gem 'userstamp', :git => "git://github.com/insphire/userstamp.git"
+	
+
+== Overview
+
+Userstamp 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'.
+
+
+== Usage
+The assumption is that you have two different
+categories of objects; those that manipulate, 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.
+
+=== Example
+Assume a weblog application has User and Post objects.
+# 1: Create the migrations for these objects
+
+  class CreateUsers < ActiveRecord::Migration
+    def self.up
+      create_table :users, :force => true do |t|
+        ...
+        t.userstamps # use t.userstamps(true) if you also want 'deleter_id'
+      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.userstamps # use t.userstamps(true) if you also want 'deleter_id'
+      end
+    end
+
+    def self.down
+      drop_table :posts
+    end
+  end
+
+# 2: Users are going to manipulate Post's, use the <tt>model_stamper</tt>:
+
+  class User < ActiveRecord::Base
+    model_stamper
+  end
+
+# 3: Set the current user in the 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 <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
+    stampable :stamper_class_name => :person,
+              :creator_attribute  => :create_user,
+              :updater_attribute  => :update_user,
+              :deleter_attribute  => :delete_user,
+			  :deleter => true
+  end
+
+== Upgrade from 1.x
+ # config/environment.rb
+ Ddb::Userstamp.compatibility_mode = true
+  
+{Example userstamp application}[http://github.com/delynn/userstamp_sample]
+
+== Running Unit Tests
+
+ All: rake
+ One: ruby test/compatibility_stamping_test.rb
+
+== Author
+{DeLynn Berry}[http://delynnberry.com/]
+
+The original idea for this plugin came from the Rails Wiki article entitled
+{Extending ActiveRecord}[http://wiki.rubyonrails.com/rails/pages/ExtendingActiveRecordExample].
+
+== Contributors / maintenance / enhancement
+- {Michael Grosser}[http://pragmatig.com]
+- {John Dell}[http://blog.spovich.com/]
+- Chris Hilton

data/VERSION

@@ -0,0 +1 @@
+2.0.2

data/init.rb

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

data/lib/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/stampable.rb

@@ -0,0 +1,154 @@
+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_attribute  :record_userstamp
+          self.record_userstamp = true
+
+          # Which class is responsible for stamping? Defaults to :user.
+          class_attribute  :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_attribute  :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_attribute  :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_attribute  :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
+        #               :deleter            => true
+        #   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.
+        # By default, the deleter association and before filter are not defined unless you are using
+        # acts_as_paranoid or you set the :deleter_attribute or set the :deleter option to true.
+        def stampable(options = {})
+          compatability = Ddb::Userstamp.compatibility_mode
+          defaults  = {
+            :stamper_class_name => :user,
+            :creator_attribute  => (compatability ? :created_by : :creator_id),
+            :updater_attribute  => (compatability ? :updated_by : :updater_id),
+            :deleter_attribute  => (compatability ? :deleted_by : :deleter_id),
+            :deleter            => !!(options.has_key?(:deleter_attribute) or defined?(Caboose::Acts::Paranoid))
+          }.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
+            klass = "::#{stamper_class_name.to_s.singularize.camelize}"
+            belongs_to :creator, :class_name => klass, :foreign_key => creator_attribute
+            belongs_to :updater, :class_name => klass, :foreign_key => updater_attribute
+
+            before_validation :set_updater_attribute
+            before_validation :set_creator_attribute, :on => :create
+
+            if defaults[:deleter]
+              belongs_to :deleter, :class_name => klass, :foreign_key => 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
+        ensure
+          self.record_userstamp = original_value
+        end
+
+        def stamper_class #:nodoc:
+          stamper_class_name.to_s.camelize.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)