public_activity 0.3.4 → 0.4.0.rc1

data/lib/public_activity/destruction.rb

@@ -2,15 +2,14 @@ module PublicActivity
   # Handles creation of Activities upon destruction of tracked model.
   module Destruction
     extend ActiveSupport::Concern
-    
+
     included do
       before_destroy :activity_on_destroy
-    end   
+    end
     private
       # Records an activity upon destruction of the tracked model
       def activity_on_destroy
-        settings = prepare_settings
-        create_activity("activity."+self.class.name.parameterize('_')+".destroy", settings[:owner], settings[:parameters])
+        create_activity(:destroy)
       end
   end
 end

data/lib/public_activity/store_controller.rb

@@ -0,0 +1,36 @@
+module PublicActivity
+  # @private
+  @@controllers = Hash.new
+  Finalizer = lambda { |id|
+    @@controllers.delete id
+  }
+
+  class << self
+    # Setter for remembering controller instance
+    def set_controller(controller)
+      unless @@controllers.has_key?(Thread.current.object_id)
+        ObjectSpace.define_finalizer Thread.current, Finalizer
+      end if RUBY_VERSION != "1.9.3"
+      @@controllers[Thread.current.object_id] = controller
+    end
+
+    # Getter for accessing the controller instance
+    def get_controller
+      @@controllers[Thread.current.object_id]
+    end
+  end
+
+  # Module included in controllers to allow p_a access to controller instance
+  module StoreController
+    extend ActiveSupport::Concern
+
+    included do
+      before_filter :store_controller_for_public_activity
+    end
+
+    # Before filter executed to remember current controller
+    def store_controller_for_public_activity
+      PublicActivity.set_controller(self)
+    end
+  end
+end

data/lib/public_activity/tracked.rb

@@ -4,69 +4,133 @@ module PublicActivity
     extend ActiveSupport::Concern
 
     included do
-      class_attribute :activity_owner_global, :activity_params_global
-      self.activity_owner_global = nil
-      self.activity_params_global = {}
+      class_attribute :activity_owner_global, :activity_recipient_global,
+                      :activity_params_global, :activity_hooks
+      self.activity_owner_global     = nil
+      self.activity_recipient_global = nil
+      self.activity_params_global    = {}
+      self.activity_hooks            = {}
     end
+
+    # @!group Global options
+
+    # @!attribute activity_owner_global
+    #   Global version of activity owner
+    #   @see #activity_owner
+    #   @return [Model]
+
+    # @!attribute activity_recipient_global
+    #   Global version of activity recipient
+    #   @see #activity_recipient
+    #   @return [Model]
+
+    # @!attribute activity_params_global
+    #   Global version of activity parameters
+    #   @see #activity_params
+    #   @return [Hash<Symbol, Object>]
+
+    # @!attribute activity_hooks
+    #   @return [Hash<Symbol, Proc>]
+    #   Hooks/functions that will be used to decide *if* the activity should get
+    #   created.
+    #
+    #   The supported keys are:
+    #   * :create
+    #   * :update
+    #   * :destroy
+
+    # @!endgroup
+
+    # @!group Instance options
+
     # Set or get parameters that will be passed to {Activity} when saving
     #
     # == Usage:
-    # In model:
     #
-    #   class Article < ActiveRecord::Base
-    #     tracked
-    #   end
-    #
-    # In controller
-    #   @article = Article.new
     #   @article.activity_params = {:article_title => @article.title}
     #   @article.save
-    # This way you can pass strings that should remain constant, even when Article
-    # changes after creating this {Activity}.
+    #
+    # This way you can pass strings that should remain constant, even when model attributes
+    # change after creating this {Activity}.
+    # @return [Hash<Symbol, Object>]
     attr_accessor :activity_params
     @activity_params = {}
     # Set or get owner object responsible for the {Activity}.
     #
     # == Usage:
-    # In model:
     #
-    #   class Article < ActiveRecord::Base
-    #     tracked
-    #   end
-    # Controller:
-    #
-    #   @article = Article.new
-    #   @article.activity_owner = current_user # where current_user is an object of logged in user
-    #   @article.activity_owner = :author # OR: take @article.author attribute
-    #   @article.activity_owner = proc {|o| o.author } # OR: provide a Proc with custom code
+    #   # where current_user is an object of logged in user
+    #   @article.activity_owner = current_user
+    #   # OR: take @article.author association
+    #   @article.activity_owner = :author
+    #   # OR: provide a Proc with custom code
+    #   @article.activity_owner = proc {|controller, model| model.author }
     #   @article.save
     #   @article.activities.last.owner #=> Returns owner object
+    # @return [Model] Polymorphic model
+    # @see #activity_owner_global
     attr_accessor :activity_owner
     @activity_owner = nil
+
+    # Set or get recipient for activity.
+    #
+    # Association is polymorphic, thus allowing assignment of
+    # all types of models. This can be used for example in the case of sending
+    # private notifications for only a single user.
+    # @return (see #activity_owner)
+    attr_accessor :activity_recipient
+    @activity_recipient = nil
     # Set or get custom i18n key passed to {Activity}, later used in {Activity#text}
     #
     # == Usage:
-    # In model:
-    #
-    #   class Article < ActiveRecord::Base
-    #     tracked
-    #   end
-    #
-    # In controller:
     #
     #   @article = Article.new
-    #   @article.save
-    #   @article.activities.last.key #=> "activity.article.create"
-    # By default, key looks like "activity.class_name.create|update|destroy"
-    #
-    # You can customize it, by setting your own key:
-    #   @article = Article.new
     #   @article.activity_key = "my.custom.article.key"
     #   @article.save
     #   @article.activities.last.key #=> "my.custom.article.key"
+    #
+    # @return [String]
     attr_accessor :activity_key
     @activity_key = nil
 
+    # @!visibility private
+    @@activity_hooks = {}
+
+    # @!endgroup
+
+    # A shortcut method for setting custom key, owner and parameters of {Activity}
+    # in one line. Accepts a hash with 3 keys:
+    # :key, :owner, :params. You can specify all of them or just the ones you want to overwrite.
+    #
+    # == Options
+    #
+    # [:key]
+    #   See {#activity_key}
+    # [:owner]
+    #   See {#activity_owner}
+    # [:params]
+    #   See {#activity_params}
+    # [:recipient]
+    #   Set the recipient for this activity. Useful for private notifications, which should only be visible to a certain user. See {#activity_recipient}.
+    # @example
+    #
+    #   @article = Article.new
+    #   @article.title = "New article"
+    #   @article.activity :key => "my.custom.article.key", :owner => @article.author, :params => {:title => @article.title}
+    #   @article.save
+    #   @article.activities.last.key #=> "my.custom.article.key"
+    #   @article.activities.last.parameters #=> {:title => "New article"}
+    #
+    # @param options [Hash] instance options to set on the tracked model
+    # @return [nil]
+    def activity(options = {})
+      self.activity_key = options[:key] if options[:key]
+      self.activity_owner = options[:owner] if options[:owner]
+      self.activity_params = options[:params] if options[:params]
+      self.activity_recipient = options[:recipient] if options[:recipient]
+      nil
+    end
+
     # Module with basic +tracked+ method that enables tracking models.
     module ClassMethods
       # Adds required callbacks for creating and updating
@@ -78,28 +142,93 @@ module PublicActivity
       #   Specify the owner of the {Activity} (person responsible for the action).
       #   It can be a Proc, Symbol or an ActiveRecord object:
       #   == Examples:
-      #    @article.activity :owner => :author
-      #    @article.activity :owner => {|o| o.author}
-      #    @article.activity :owner => User.where(:login => 'piotrek').first
-      #   Keep in mind that owner relation is polymorphic, so you can't just provide id number of the owner object.
+      #
+      #    tracked :owner => :author
+      #    tracked :owner => {|o| o.author}
+      #
+      #   Keep in mind that owner relation is polymorphic, so you can't just
+      #   provide id number of the owner object.
+      # [:recipient]
+      #   Specify the recipient of the {Activity}
+      #   It can be a Proc, Symbol, or an ActiveRecord object
+      #   == Examples:
+      #
+      #    tracked :recipient => :author
+      #    tracked :recipient => {|o| o.author}
+      #
+      #   Keep in mind that recipient relation is polymorphic, so you can't just
+      #   provide id number of the owner object.
       # [:params]
       #   Accepts a Hash with custom parameters you want to pass to i18n.translate
       #   method. It is later used in {Activity#text} method.
       #   == Example:
-      #    @article.activity :parameters => {:title => @article.title, :short => truncate(@article.text, :length => 50)}
-      #   Everything specified here has a lower priority than parameters specified directly in {#activity} method.
-      #   So treat it as a place where you provide 'default' values.
-      #   For more dynamic settings refer to {Activity} model
-      #   documentation.
+      #    class Article < ActiveRecord::Base
+      #      include PublicActivity::Model
+      #      tracked :params => {
+      #          :title => :title,
+      #          :author_name => "Michael",
+      #          :category_name => proc {|controller, model_instance| model_instance.category.name},
+      #          :summary => proc {|controller, model_instance| truncate(model.text, :length => 30)}
+      #      }
+      #    end
+      #
+      #   Values in the :params hash can either be an *exact* *value*, a *Proc/Lambda* executed before saving the activity or a *Symbol*
+      #   which is a an attribute or a method name executed on the tracked model's instance.
+      #
+      #   Everything specified here has a lower priority than parameters
+      #   specified directly in {#activity} method.
+      #   So treat it as a place where you provide 'default' values or where you
+      #   specify what data should be gathered for every activity.
+      #   For more dynamic settings refer to {Activity} model documentation.
       # [:skip_defaults]
       #   Disables recording of activities on create/update/destroy leaving that to programmer's choice. Check {PublicActivity::Common#create_activity}
       #   for a guide on how to manually record activities.
+      # [:only]
+      #   Accepts array of symbols, of which correct is any combination of the three:
+      #   * _:create_
+      #   * _:update_
+      #   * _:destroy_
+      #   Selecting one or more of these will make PublicActivity create activities
+      #   automatically for the tracked model on selected actions.
+      #
+      #   Resulting activities will have have keys assigned to, respectively:
+      #   * _article.create_
+      #   * _article.update_
+      #   * _article.destroy_
+      #   Since only three options are valid in this array,
+      #   see _:except_ option for a shorter version
+      # [:except]
+      #   Accepts array of symbols with values like in _:only_, above.
+      #   Values provided will be subtracted from all default actions:
+      #   (create, update, destroy).
+      #
+      #   So, passing _create_ would track and automatically create
+      #   activities on _update_ and _destroy_ actions.
+      # [:on]
+      #   Accepts a Hash with key being the *action* on which to execute *value* (proc)
+      #   Currently supported only for CRUD actions which are enabled in _:only_
+      #   or _:except_ options on this method.
+      #
+      #   Key-value pairs in this option define callbacks that can decide
+      #   whether to create an activity or not. Procs have two attributes for
+      #   use: _model_ and _controller_. If the proc returns true, the activity
+      #   will be created, if not, then activity will not be saved.
+      #
+      #   == Example:
+      #     # app/models/article.rb
+      #     tracked :on => {:update => proc {|model, controller| model.published? }}
+      #
+      #   In the example above, given a model Article with boolean column _published_.
+      #   The activities with key _article.update_ will only be created
+      #   if the published status is set to true on that article.
+      # @param options [Hash] options
+      # @return [nil] options
       def tracked(options = {})
         include Common
 
         all_options = [:create, :update, :destroy]
 
-        if !options[:skip_defaults] && !options[:only] && !options[:except]
+        if !options.has_key?(:skip_defaults) && !options[:only] && !options[:except]
           include Creation
           include Destruction
           include Update
@@ -124,57 +253,65 @@ module PublicActivity
         if options[:owner]
           self.activity_owner_global = options[:owner]
         end
+        if options[:recipient]
+          self.activity_recipient_global = options[:recipient]
+        end
         if options[:params]
           self.activity_params_global = options[:params]
         end
+        if options.has_key?(:on) and options[:on].is_a? Hash
+          self.activity_hooks = options[:on].delete_if {|_, v| !v.is_a? Proc}.symbolize_keys if RUBY_VERSION == "1.8.7"
+          self.activity_hooks = options[:on].select {|_, v| v.is_a? Proc}.symbolize_keys if RUBY_VERSION != "1.8.7"
+        end
         has_many :activities, :class_name => "PublicActivity::Activity", :as => :trackable
 
         nil
       end
+
+      # Extracts a hook from the _:on_ option provided in
+      # {Tracked::ClassMethods#tracked}. Returns nil when no hook exists for
+      # given action
+      # {Tracked#get_hook}
+      #
+      # @see Tracked#get_hook
+      # @param key [String, Symbol] action to retrieve a hook for
+      # @return [Proc, nil] callable hook or nil
+      # @since 0.4.0
+      # @api private
+      def get_hook(key)
+        key = key.to_sym
+        if self.activity_hooks.has_key?(key) and self.activity_hooks[key].is_a? Proc
+          self.activity_hooks[key]
+        else
+          nil
+        end
+      end
     end
 
-    # A shortcut method for setting custom key, owner and parameters of {Activity}
-    # in one line. Accepts a hash with 3 keys:
-    # :key, :owner, :params. You can specify all of them or just the ones you want to overwrite.
-    #
-    # === Options
-    #
-    # [:key]
-    #   Accepts a string that will be used as a i18n key for {Activity#text} method.
-    # [:owner]
-    #   Specify the owner of the {Activity} (person responsible for the action).
-    #   It can be a Proc, Symbol or an ActiveRecord object:
-    #   == Examples:
-    #    @article.activity :owner => :author
-    #    @article.activity :owner => {|o| o.author}
-    #    @article.activity :owner => User.where(:login => 'piotrek').first
-    #   Keep in mind that owner relation is polymorphic, so you can't just provide id number of the owner object.
-    # [:params]
-    #   Accepts a Hash with custom parameters you want to pass to i18n.translate
-    #   method. It is later used in {Activity#text} method.
-    #   == Example:
-    #    @article.activity :parameters => {:title => @article.title, :short => truncate(@article.text, :length => 50)}
-    #
-    # == Usage:
-    # In model:
-    #
-    #   class Article < ActiveRecord::Base
-    #     tracked
-    #   end
-    #
-    # In controller:
-    #
-    #   @article = Article.new
-    #   @article.title = "New article"
-    #   @article.activity :key => "my.custom.article.key", :owner => @article.author, :params => {:title => @article.title}
-    #   @article.save
-    #   @article.activities.last.key #=> "my.custom.article.key"
-    #   @article.activities.last.parameters #=> {:title => "New article"}
-    def activity(options = {})
-      self.activity_key = options[:key] if options[:key]
-      self.activity_owner = options[:owner] if options[:owner]
-      self.activity_params = options[:params] if options[:params]
+    # Shortcut for {Tracked::ClassMethods#get_hook}
+    # @param (see Tracked::ClassMethods#get_hook)
+    # @return (see Tracked::ClassMethods#get_hook)
+    # @since (see Tracked::ClassMethods#get_hook)
+    # @api (see Tracked::ClassMethods#get_hook)
+    def get_hook(key)
+      self.class.get_hook(key)
     end
 
+    # Calls hook safely.
+    # If a hook for given action exists, calls it with model (self) and
+    # controller (if available, see {StoreController})
+    # @param key (see #get_hook)
+    # @return [Boolean] if hook exists, it's decision, if there's no hook, true
+    # @since 0.4.0
+    # @api private
+    def call_hook_safe(key)
+      hook = self.get_hook(key)
+      if hook
+        # provides hook with model and controller
+        hook.call(self, PublicActivity.get_controller)
+      else
+        true
+      end
+    end
   end
 end

data/lib/public_activity/update.rb

@@ -5,12 +5,11 @@ module PublicActivity
 
     included do
       after_update :activity_on_update
-    end   
+    end
     private
       # Creates activity upon modification of the tracked model
       def activity_on_update
-        settings = prepare_settings
-        create_activity(settings[:key] || "activity."+self.class.name.parameterize('_')+".update", settings[:owner], settings[:parameters])
+        create_activity(:update)
       end
   end
 end

data/lib/public_activity/version.rb

@@ -1,4 +1,4 @@
 module PublicActivity
   # A constant with gem's version
-  VERSION = '0.3.4'
+  VERSION = '0.4.0.rc1'
 end

data/lib/public_activity/view_helpers.rb

@@ -0,0 +1,12 @@
+# Provides a shortcut from views to the rendering method.
+module PublicActivity
+  # Module extending ActionView::Base and adding `render_activity` helper.
+  module ViewHelpers
+    # View helper for rendering an activity, calls {PublicActivity::Activity#render} internally.
+    def render_activity activity, options = {}
+      activity.render self, options
+    end
+  end
+
+  ActionView::Base.class_eval { include ViewHelpers }
+end

data/lib/public_activity.rb

@@ -1,56 +1,33 @@
-require 'active_support/concern'
-require 'active_support/dependencies'
+require 'active_support'
+require 'action_view'
 require 'active_record'
-require 'pusher'
+
 # +public_activity+ keeps track of changes made to models
-# and allows for easy displaying of them.
-#
-# Basic usage requires adding one line to your models:
-#
-#   class Article < ActiveRecord::Base
-#     tracked
-#   end
-# 
-# And creating a table for activities, by doing this:
-#   rails generate public_activity:migration
-#   rake db:migrate
-#
-# Now when saved, public_activity will create 
-# an Activity record containing information about that changed/created
-# model.
-# == Displaying Activities:
+# and allows you to display them to the users.
 #
-# Minimal example would be:
-#
-#   <% for activity in PublicActivity::Activity.all %>
-#   <%= activity.text %><br/>
-#   <% end %>
-# Now you will need to add translations in your locale .yml, for the example
-# provided above that would be:
-#   en:
-#     activity:
-#       create: 'New article has been created'
-#       update: 'Someone modified the article'
-#       destroy: 'Someone deleted the article!'
-#
-# Check {PublicActivity::ClassMethods#tracked} for more details about customizing and specifing
+# Check {PublicActivity::Tracked::ClassMethods#tracked} for more details about customizing and specifying
 # ownership to users.
 module PublicActivity
   extend ActiveSupport::Concern
   extend ActiveSupport::Autoload
   autoload :Activist
   autoload :Activity
+  autoload :StoreController
   autoload :Tracked
   autoload :Creation
-  autoload :Update  
+  autoload :Update
   autoload :Destruction
   autoload :VERSION
   autoload :Common
-  
-  included do
-    include Tracked
-    include Activist 
-  end  
+
+  # Module to be included in ActiveRecord models. Adds required functionality.
+  module Model
+    extend ActiveSupport::Concern
+    included do
+      include Tracked
+      include Activist
+    end
+  end
 end
 
-ActiveRecord::Base.send :include, PublicActivity
+require 'public_activity/view_helpers'