public_activity 0.5.4 → 1.0.0

data/lib/public_activity/config.rb

@@ -1,12 +1,58 @@
+require 'singleton'
+
 module PublicActivity
   # Class used to initialize configuration object.
   class Config
-    include Singleton
+    include ::Singleton
     attr_accessor :enabled
 
+    @@orm = :active_record
+
     def initialize
       # Indicates whether PublicActivity is enabled globally
-      @enabled         = true
+      @enabled  = true
+      load_orm
+    end
+
+    def self.set &block
+      b = Block.new
+      b.instance_eval &block
+      orm = b.instance_variable_get(:@orm)
+      @@orm = orm unless orm.nil?
+      enabled = b.instance_variable_get(:@en)
+      instance
+      instance.instance_variable_set(:@enabled, enabled) unless enabled.nil?
+    end
+
+    def self.orm(orm = nil)
+      @@orm = (orm ? orm.to_sym : false) || @@orm
+    end
+
+    def self.orm=(orm = nil)
+      orm(orm)
+    end
+
+    def orm(orm=nil)
+      self.class.orm(orm)
+    end
+
+    def load_orm
+      require "public_activity/orm/#{@@orm.to_s}"
+      m = "PublicActivity::ORM::#{@@orm.to_s.classify}".constantize
+      ::PublicActivity.const_set(:Activity,  m.const_get(:Activity))
+      ::PublicActivity.const_set(:Adapter,   m.const_get(:Adapter))
+      ::PublicActivity.const_set(:Activist,  m.const_get(:Activist))
+      ::PublicActivity.const_set(:Trackable, m.const_get(:Trackable))
+    end
+
+    class Block
+      def orm(orm = nil)
+        @orm = (orm ? orm.to_sym : false) || @orm
+      end
+
+      def enabled(en = nil)
+        @en = (en.nil? ? @en : en)
+      end
     end
   end
-end
+end

data/lib/public_activity/orm/active_record.rb

@@ -0,0 +1,5 @@
+require 'active_record'
+require_relative 'active_record/activity.rb'
+require_relative 'active_record/adapter.rb'
+require_relative 'active_record/activist.rb'
+require_relative 'active_record/trackable.rb'

data/lib/public_activity/orm/active_record/activist.rb

@@ -0,0 +1,42 @@
+module PublicActivity
+  module ORM
+    module ActiveRecord
+      # Module extending classes that serve as owners
+      module Activist
+        extend ActiveSupport::Concern
+
+        # Association of activities as their owner.
+        # @!method activities
+        # @return [Array<Activity>] Activities which self is the owner of.
+
+        # Association of activities as their recipient.
+        # @!method private_activities
+        # @return [Array<Activity>] Activities which self is the recipient of.
+
+        # Module extending classes that serve as owners
+        module ClassMethods
+          # Adds ActiveRecord associations to model to simplify fetching
+          # so you can list activities performed by the owner.
+          # It is completely optional. Any model can be an owner to an activity
+          # even without being an explicit activist.
+          #
+          # == Usage:
+          # In model:
+          #
+          #   class User < ActiveRecord::Base
+          #     include PublicActivity::Model
+          #     activist
+          #   end
+          #
+          # In controller:
+          #   User.first.activities
+          #
+          def activist
+            has_many :activities_as_owner, :class_name => "PublicActivity::Activity", :as => :owner
+            has_many :activities_as_recipient, :class_name => "PublicActivity::Activity", :as => :recipient
+          end
+        end
+      end
+    end
+  end
+end

data/lib/public_activity/orm/active_record/activity.rb

@@ -0,0 +1,23 @@
+module PublicActivity
+  module ORM
+    module ActiveRecord
+      # The ActiveRecord model containing
+      # details about recorded activity.
+      class Activity < ::ActiveRecord::Base
+        include Renderable
+
+        # Define polymorphic association to the parent
+        belongs_to :trackable, :polymorphic => true
+        # Define ownership to a resource responsible for this activity
+        belongs_to :owner, :polymorphic => true
+        # Define ownership to a resource targeted by this activity
+        belongs_to :recipient, :polymorphic => true
+        # Serialize parameters Hash
+        serialize :parameters, Hash
+
+        # should recipient and owner be accessible?
+        attr_accessible :key, :owner, :parameters, :recipient, :trackable
+      end
+    end
+  end
+end

data/lib/public_activity/orm/active_record/adapter.rb

@@ -0,0 +1,14 @@
+module PublicActivity
+  module ORM
+    module ActiveRecord
+      module Adapter
+        class << self
+          # Creates the activity on `trackable` with `options`
+          def create_activity(trackable, options)
+            trackable.activities.create options
+          end
+        end
+      end
+    end
+  end
+end

data/lib/public_activity/orm/active_record/trackable.rb

@@ -0,0 +1,11 @@
+module PublicActivity
+  module ORM
+    module ActiveRecord
+      module Trackable
+        def self.included(base)
+          base.has_many :activities, :class_name => "::PublicActivity::Activity", :as => :trackable
+        end
+      end
+    end
+  end
+end

data/lib/public_activity/orm/mongoid.rb

@@ -0,0 +1,4 @@
+require_relative "mongoid/activity.rb"
+require_relative "mongoid/adapter.rb"
+require_relative "mongoid/activist.rb"
+require_relative "mongoid/trackable.rb"

data/lib/public_activity/orm/mongoid/activist.rb

@@ -0,0 +1,42 @@
+module PublicActivity
+  module ORM
+    module Mongoid
+      # Module extending classes that serve as owners
+      module Activist
+        extend ActiveSupport::Concern
+
+        # Association of activities as their owner.
+        # @!method activities
+        # @return [Array<Activity>] Activities which self is the owner of.
+
+        # Association of activities as their recipient.
+        # @!method private_activities
+        # @return [Array<Activity>] Activities which self is the recipient of.
+
+        # Module extending classes that serve as owners
+        module ClassMethods
+          # Adds ActiveRecord associations to model to simplify fetching
+          # so you can list activities performed by the owner.
+          # It is completely optional. Any model can be an owner to an activity
+          # even without being an explicit activist.
+          #
+          # == Usage:
+          # In model:
+          #
+          #   class User < ActiveRecord::Base
+          #     include PublicActivity::Model
+          #     activist
+          #   end
+          #
+          # In controller:
+          #   User.first.activities
+          #
+          def activist
+            has_many :activities_as_owner,      :class_name => "PublicActivity::Activity", :inverse_of => :owner
+            has_many :activities_as_recipient,  :class_name => "PublicActivity::Activity", :inverse_of => :recipient
+          end
+        end
+      end
+    end
+  end
+end

data/lib/public_activity/orm/mongoid/activity.rb

@@ -0,0 +1,25 @@
+require 'mongoid'
+
+module PublicActivity
+  module ORM
+    module Mongoid
+      # The ActiveRecord model containing
+      # details about recorded activity.
+      class Activity
+        include ::Mongoid::Document
+        include ::Mongoid::Timestamps
+        include Renderable
+
+        # Define polymorphic association to the parent
+        belongs_to :trackable,  polymorphic: true
+        # Define ownership to a resource responsible for this activity
+        belongs_to :owner,      polymorphic: true
+        # Define ownership to a resource targeted by this activity
+        belongs_to :recipient,  polymorphic: true
+
+        field :key,         type: String
+        field :parameters,  type: Hash
+      end
+    end
+  end
+end

data/lib/public_activity/orm/mongoid/adapter.rb

@@ -0,0 +1,14 @@
+module PublicActivity
+  module ORM
+    module Mongoid
+      module Adapter
+        class << self
+          # Creates the activity on `trackable` with `options`
+          def create_activity(trackable, options)
+            trackable.activities.create options
+          end
+        end
+      end
+    end
+  end
+end

data/lib/public_activity/orm/mongoid/trackable.rb

@@ -0,0 +1,11 @@
+module PublicActivity
+  module ORM
+    module Mongoid
+      module Trackable
+        def self.included(base)
+          base.has_many :activities, :class_name => "::PublicActivity::Activity", :as => :trackable
+        end
+      end
+    end
+  end
+end

data/lib/public_activity/{activity.rb → renderable.rb}

@@ -1,46 +1,7 @@
 module PublicActivity
-  # The ActiveRecord model containing
-  # details about recorded activity.
-  class Activity < ActiveRecord::Base
-    # Define polymorphic association to the parent
-    belongs_to :trackable, :polymorphic => true
-    # Define ownership to a resource responsible for this activity
-    belongs_to :owner, :polymorphic => true
-    # Define ownership to a resource targeted by this activity
-    belongs_to :recipient, :polymorphic => true
-    # Serialize parameters Hash
-    serialize :parameters, Hash
-
-    class_attribute :template
-
-    # should recipient and owner be accessible?
-    attr_accessible :key, :owner, :parameters, :recipient, :trackable
+  module Renderable
     # Virtual attribute returning text description of the activity
-    # using basic ERB templating
-    #
-    # == Example:
-    #
-    # Let's say you want to show article's title inside Activity message.
-    #
-    #   #config/pba.yml
-    #   activity:
-    #     article:
-    #       create: "New <%= trackable.name %> article has been created"
-    #       update: 'Someone modified the article'
-    #       destroy: 'Someone deleted the article!'
-    #
-    # And in controller:
-    #
-    #   def create
-    #     @article = Article.new
-    #     @article.title = "Rails 3.0.5 released!"
-    #     @article.activity_params = {:title => @article.title}
-    #     @article.save
-    #   end
-    #
-    # Now when you list articles, you should see:
-    #   @article.activities.last.text #=> "Someone has created an article 'Rails 3.0.5 released!'"
-    # @see #render Advanced rendering
+    # using the activity's key to translate using i18n.
     def text(params = {})
       # TODO: some helper for key transformation for two supported formats
       k = key.split('.')
@@ -75,6 +36,21 @@ module PublicActivity
     #     <% end %>
     #   </ul>
     #
+    # = Layouts
+    # You can supply a layout that will be used for activity partials
+    # with :layout param.
+    # Keep in mind that layouts for partials are also partials.
+    # @example Supply a layout
+    #   # in views:
+    #   #   All examples look for a layout in app/views/layouts/_activity.erb
+    #    render_activity @activity, :layout => "activity"
+    #    render_activity @activity, :layout => "layouts/activity"
+    #    render_activity @activity, :layout => :activity
+    #
+    #   # app/views/layouts/_activity.erb
+    #   <p><%= a.created_at %></p>
+    #   <%= yield %>
+    #
     # = Creating a template
     # To use templates for formatting how the activity should render,
     # create a template based on activity key, for example:
@@ -84,7 +60,7 @@ module PublicActivity
     #
     # Note that if a key consists of more than three parts splitted by commas, your
     # directory structure will have to be deeper, for example:
-    #   activity.article.comments.destroy => /app/views/public_activity/articles/comments/_destroy.html.erb
+    #   activity.article.comments.destroy => app/views/public_activity/articles/comments/_destroy.html.erb
     #
     # == Variables in templates
     # From within a template there are two variables at your disposal:
@@ -98,21 +74,29 @@ module PublicActivity
     #     <%= distance_of_time_in_words_to_now(a.created_at) %>
     #   </p>
     def render(context, params = {})
-      begin
-        params_indifferent = self.parameters.with_indifferent_access
-        params_indifferent.merge!(params)
-        controller = PublicActivity.get_controller
-        context.render :partial => self.template_path(self.key),
-          :layout => params_indifferent.delete(:layout),
-          :locals =>
-            {:a => self, :activity => self,
-             :controller => controller,
-             :current_user => controller.respond_to?(:current_user) ?
-                  controller.current_user : nil ,
-             :p => params_indifferent, :params => params_indifferent}
-      rescue ActionView::MissingTemplate
-        context.render :text => self.text(params)
+      partial_path = nil
+      if params.has_key? :display
+        # if i18n has been requested, let it render and bail
+        return context.render :text => self.text(params) if params[:display].to_sym == :"i18n"
+        partial_path = 'public_activity/'+params[:display].to_s
+      end
+      # if we're going to render a partial, let it throw when none can be found
+      params_indifferent = self.parameters.with_indifferent_access
+      params_indifferent.merge!(params)
+      controller = PublicActivity.get_controller
+      layout = params_indifferent.delete(:layout)
+      if layout
+        layout = layout.to_s
+        layout = layout[0,8] == "layouts/" ? layout : "layouts/#{layout}"
       end
+      context.render :partial => (partial_path || self.template_path(self.key)),
+        :layout => layout,
+        :locals =>
+          {:a => self, :activity => self,
+           :controller => controller,
+           :current_user => controller.respond_to?(:current_user) ?
+                controller.current_user : nil ,
+           :p => params_indifferent, :params => params_indifferent}
     end
 
     protected

data/lib/public_activity/roles/deactivatable.rb

@@ -0,0 +1,39 @@
+module PublicActivity
+  module Deactivatable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :public_activity_enabled_for_model
+      set_public_activity_class_defaults
+    end
+
+    # Returns true if PublicActivity is enabled
+    # globally and for this class.
+    # @return [Boolean]
+    # @api private
+    # @since 0.5.0
+    # overrides the method from Common
+    def public_activity_enabled?
+      PublicActivity.enabled? && self.class.public_activity_enabled_for_model
+    end
+
+    module ClassMethods
+      # Switches public_activity off for this class
+      def public_activity_off
+        self.public_activity_enabled_for_model = false
+      end
+
+      # Switches public_activity on for this class
+      def public_activity_on
+        self.public_activity_enabled_for_model = true
+      end
+
+      # @since 1.0.0
+      # @api private
+      def set_public_activity_class_defaults
+        super
+        self.public_activity_enabled_for_model = true
+      end
+    end
+  end
+end

data/lib/public_activity/roles/tracked.rb

@@ -0,0 +1,183 @@
+module PublicActivity
+  # Main module extending classes we want to keep track of.
+  module Tracked
+    extend ActiveSupport::Concern
+    # 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 = {})
+      rest = options.clone
+      self.activity_key = rest.delete(:key) if rest[:key]
+      self.activity_owner = rest.delete(:owner) if rest[:owner]
+      self.activity_params = rest.delete(:params) if rest[:params]
+      self.activity_recipient = rest.delete(:recipient) if rest[:recipient]
+      self.activity_custom_fields = rest if rest.count > 0
+      nil
+    end
+
+    # Module with basic +tracked+ method that enables tracking models.
+    module ClassMethods
+      # Adds required callbacks for creating and updating
+      # tracked models and adds +activities+ relation for listing
+      # associated activities.
+      #
+      # == Parameters:
+      # [:owner]
+      #   Specify the owner of the {Activity} (person responsible for the action).
+      #   It can be a Proc, Symbol or an ActiveRecord object:
+      #   == Examples:
+      #
+      #    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:
+      #    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 a symbol or an array of symbols, of which any combination of the three is accepted:
+      #   * _: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,
+      #   see _:except_ option for a shorter version
+      # [:except]
+      #   Accepts a symbol or an 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,
+      #   but not on the _create_ action.
+      # [: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(opts = {})
+        options = opts.clone
+
+        all_options = [:create, :update, :destroy]
+
+        if !options.has_key?(:skip_defaults) && !options[:only] && !options[:except]
+          include Creation
+          include Destruction
+          include Update
+        end
+        options.delete(:skip_defaults)
+
+        if options[:except]
+          options[:only] = all_options - Array(options.delete(:except))
+        end
+
+        if options[:only]
+          Array(options[:only]).each do |opt|
+            if opt.eql?(:create)
+              include Creation
+            elsif opt.eql?(:destroy)
+              include Destruction
+            elsif opt.eql?(:update)
+              include Update
+            end
+          end
+          options.delete(:only)
+        end
+
+        if options[:owner]
+          self.activity_owner_global = options.delete(:owner)
+        end
+        if options[:recipient]
+          self.activity_recipient_global = options.delete(:recipient)
+        end
+        if options[:params]
+          self.activity_params_global = options.delete(:params)
+        end
+        if options.has_key?(:on) and options[:on].is_a? Hash
+          self.activity_hooks = options.delete(:on).select {|_, v| v.is_a? Proc}.symbolize_keys
+        end
+
+        options.each do |k, v|
+          self.activity_custom_fields_global[k] = v
+        end
+
+        nil
+      end
+    end
+  end
+end