public_activity 0.5.4 → 1.0.0

data/Gemfile

@@ -1,5 +1,22 @@
+ENV['PA_ORM'] ||= 'active_record'
+
 source :rubygems
 
-gemspec
 
-gem 'yard'
+case ENV['PA_ORM']
+when 'active_record'
+  gem 'activerecord', '~> 3.0'
+when 'mongoid'
+  gem 'mongoid', '~> 3.0'
+end
+
+group :development, :test do
+  gem 'sqlite3', '~> 1.3.7' if ENV['PA_ORM'] == 'active_record'
+  gem 'mocha', '~> 0.13.0', require: false
+  gem 'simplecov', '~> 0.7.0'
+  gem 'minitest', '>= 4.3.0'
+  gem 'redcarpet'
+  gem 'yard', '~> 0.8'
+end
+
+gemspec

data/README.md

@@ -1,7 +1,24 @@
-# PublicActivity [![Build Status](https://secure.travis-ci.org/pokonski/public_activity.png)](http://travis-ci.org/pokonski/public_activity)
-
-public_activity provides smooth activity tracking for your ActiveRecord models in Rails 3.
-Simply put: it records what has been changed or edited and gives you the ability to present those recorded activities to users - in a similar way Github does it.
+# PublicActivity [![Build Status](https://secure.travis-ci.org/pokonski/public_activity.png)](http://travis-ci.org/pokonski/public_activity) [![Dependency Status](https://gemnasium.com/pokonski/public_activity.png)](https://gemnasium.com/pokonski/public_activity)
+
+_public_activity_ provides smooth activity tracking for your **ActiveRecord** and **Mongoid 3** models in Rails 3.
+Simply put: it records what has been changed or created and gives you the ability to present those
+recorded activities to users - in a similar way to how GitHub does it.
+
+## Table of contents
+
+1. [Example](#example)
+  * [Demo](#online-demo)
+3. **[Upgrading](#upgrading)**
+4. [Setup](#setup)
+  1. [Gem installation](#gem-installation)
+  2. [Database setup](#database-setup)
+  3. [Model configuration](#model-configuration)
+  4. [Custom activities](#custom-activities)
+  5. [Displaying activities](#displaying-activities)
+    1. [Activity views](#activity-views)
+    2. [i18n](#i18n)
+5. [Documentation](#documentation)
+6. **[Help](#help)**
 
 ## Example
 
@@ -14,11 +31,12 @@ Here is a simple example showing what this gem is about:
 You can see an actual application using this gem here: http://public-activity-example.herokuapp.com/feed
 
 The source code of the demo is hosted here: https://github.com/pokonski/activity_blog
-## Upgrading to 0.4
+
+## Upgrading from pre-0.4.0
 
 If you are using versions earlier than 0.4.0 please click [here](#upgrading) or scroll to the "Upgrading" section at the bottom of this README.
 
-## First time setup
+## Setup
 
 ### Gem installation
 
@@ -34,7 +52,17 @@ gem 'public_activity'
 
 ### Database setup
 
-Create migration for activities and migrate the database (in your Rails project):
+By default _public_activity_ uses Active Record. If you want to use Mongoid as your backend, create
+an initializer file in your Rails application with this code inside:
+
+```ruby
+# config/initializers/public_activity.rb
+PublicActivity::Config.set do
+  orm :mongoid
+end
+```
+
+**(ActiveRecord only)** Create migration for activities and migrate the database (in your Rails project):
 
     rails g public_activity:migration
     rake db:migrate
@@ -43,6 +71,8 @@ Create migration for activities and migrate the database (in your Rails project)
 
 Include `PublicActivity::Model` and add `tracked` to the model you want to keep track of:
 
+For _ActiveRecord:_
+
 ```ruby
 class Article < ActiveRecord::Base
   include PublicActivity::Model
@@ -50,11 +80,36 @@ class Article < ActiveRecord::Base
 end
 ```
 
-And now, by default create/update/destroy activities are recorded in activities table. This is all you need to start recording activities for basic CRUD actions.
+For _Mongoid:_
+
+```ruby
+class Article
+  include Mongoid::Document
+  include PublicActivity::Model
+  tracked
+end
+```
+
+And now, by default create/update/destroy activities are recorded in activities table.
+This is all you need to start recording activities for basic CRUD actions.
+
+_Optional_: If you don't need `#tracked` but still want the comfort of `#create_activity`,
+you can include only the lightweight `Common` module instead of `Model`.
+
+#### Custom activities
+
+You can trigger custom activities by setting all your required parameters and triggering `create_activity`
+on the tracked model, like this:
+
+```ruby
+@article.create_activity key: 'article.commented_on', owner: current_user
+```
+
+See this entry http://rubydoc.info/gems/public_activity/PublicActivity/Common:create_activity for more details.
 
 ### Displaying activities
 
-To display them you simply query the `PublicActivity::Activity` ActiveRecord model:
+To display them you simply query the `PublicActivity::Activity` model:
 
 ```ruby
 # notifications_controller.rb
@@ -66,25 +121,31 @@ end
 And in your views:
 
 ```erb
-<% for activity in @activities %>
+<% @activities.each do |activity| %>
   <%= render_activity(activity) %>
 <% end %>
 ```
 
 *Note*: `render_activity` is a helper for use in view templates. `render_activity(activity)` can be written as `activity.render(self)` and it will have the same meaning.
 
-You can also pass options to both `activity#render` and `#render_activity` methods, which are passed deeper to the `render_partial` method.
-A useful example would be to render activities wrapped in layout, which shares common elements of an activity, like a timestamp, owner's avatar etc.
+#### Layouts
+
+You can also pass options to both `activity#render` and `#render_activity` methods, which are passed deeper
+to the internally used `render_partial` method.
+A useful example would be to render activities wrapped in layout, which shares common elements of an activity,
+like a timestamp, owner's avatar etc:
 
 ```erb
-<% for activity in @activities %>
+<% @activities.each do |activity| %>
   <%= render_activity(activity, :layout => :activity) %>
 <% end %>
 ```
 
-The activity will be wrapped with the `app/views/layouts/activity` layout, in the above example.
+The activity will be wrapped with the `app/views/layouts/_activity.erb` layout, in the above example.
+
+**Important**: please note that layouts for activities are also partials. Hence the `_` prefix.
 
-### Activity views
+#### Activity views
 
 Since version `0.4.0` you can use views to render activities. `public_activity` looks for views in `app/views/public_activity`, and this is now the *default* behaviour.
 
@@ -94,7 +155,7 @@ For example, if you have an activity with `:key` set to `"activity.user.changed_
 
 If a view file does not exist, then p_a falls back to the old behaviour and tries to translate the activity `:key` using `I18n#translate` method (see the section below).
 
-### i18n
+#### i18n
 
 Translations are used by the `#text` method, to which you can pass additional options in form of a hash. `#render` method uses translations when view templates have not been provided.
 
@@ -112,10 +173,14 @@ This structure is valid for activities with keys `"activity.article.create"` or
 
 ## Upgrading
 
+**Read this if you have been using versions older than 0.4.**
+
 There are a couple of major differences between 0.3 and 0.4 version. To upgrade, follow these steps:
 
 1.  Add `include PublicActivity::Model` above `tracked` method call in your tracked models, like this:
 
+    _ActiveRecord:_
+
     ```ruby
     class Article < ActiveRecord::Base
       include PublicActivity::Model
@@ -123,12 +188,22 @@ There are a couple of major differences between 0.3 and 0.4 version. To upgrade,
     end
     ```
 
-2.   public_activity's config YAML file is no longer used (by default in `config/pba.yml`). Move your YAML contents to your `config/locales/*.yml` files.
+    _Mongoid:_
+
+    ```ruby
+    class Article
+      include Mongoid::Document
+      include PublicActivity::Model
+      tracked
+    end
+    ```
+
+2.   _public_activity_'s config YAML file is no longer used (by default in `config/pba.yml`). Move your YAML contents to your `config/locales/*.yml` files.
 
      <br/>**IMPORTANT**: Locales are no longer rendered with ERB, this has been removed in favor of real view partials like in actual Rails apps.
      Read [Activity views](#activity-views) section above to learn how to use those templates.<br/>
 
-3.   Generate and run migration which adds new column to `activities` table:
+3.   **(ActiveRecord only)** Generate and run migration which adds new column to `activities` table:
 
      ```bash
      rails g public_activity:migration_upgrade
@@ -143,6 +218,15 @@ For more customization go [here](http://rubydoc.info/gems/public_activity/index)
 
 * [[How to] Set the Activity's owner to current_user by default](https://github.com/pokonski/public_activity/wiki/%5BHow-to%5D-Set-the-Activity's-owner-to-current_user-by-default)
 * [[How to] Disable tracking for a class or globally](https://github.com/pokonski/public_activity/wiki/%5BHow-to%5D-Disable-tracking-for-a-class-or-globally)
+* [[How to] Create custom activities](https://github.com/pokonski/public_activity/wiki/%5BHow-to%5D-Create-custom-activities)
+
+## Help
+
+If you need help with using public_activity please visit our discussion group and ask a question there:
+
+https://groups.google.com/forum/?fromgroups#!forum/public-activity
+
+Please do not ask general questions in the Github Issues.
 
 ## License
-Copyright (c) 2012 Piotrek Okoński, released under the MIT license
+Copyright (c) 2012 Piotrek Okoński, released under the MIT license

data/UPGRADING

@@ -1,17 +1,8 @@
-################################################
-#          RUBY 1.8.7 IS NOW DEPRECATED        #
-################################################
-
-The 0.5 version of public_activity will be the
-last to support versions older than 1.9.2. Please
-update your Ruby if you wish to continue using
-this gem.
-
---------------------------------------------------
-|  NOTE FOR UPGRADING FROM PRE-0.4.0 VERSION     |
---------------------------------------------------
+##################################################
+#  NOTE FOR UPGRADING FROM PRE-0.4.0 VERSION     #
+##################################################
 
 public_activity 0.4.0 brings major changes compared to 0.3.X versions,
-please read https://github.com/pokonski/public_activity#upgrading
+please read https://github.com/pokonski/public_activity#upgrading 
 to learn about all the changes you need to apply to properly
 upgrade your applications.

data/lib/generators/public_activity/migration/templates/migration.rb

@@ -11,6 +11,10 @@ class CreateActivities < ActiveRecord::Migration
 
       t.timestamps
     end
+
+    add_index :activities, [:trackable_id, :trackable_type]
+    add_index :activities, [:owner_id, :owner_type]
+    add_index :activities, [:recipient_id, :recipient_type]
   end
   # Drop table
   def self.down

data/lib/public_activity.rb

@@ -1,7 +1,5 @@
 require 'active_support'
 require 'action_view'
-require 'active_record'
-
 # +public_activity+ keeps track of changes made to models
 # and allows you to display them to the users.
 #
@@ -10,15 +8,15 @@ require 'active_record'
 module PublicActivity
   extend ActiveSupport::Concern
   extend ActiveSupport::Autoload
-  autoload :Activist
-  autoload :Activity
   autoload :Config
-  autoload :Tracked
-  autoload :Creation
-  autoload :Update
-  autoload :Destruction
+  autoload :Tracked,      'public_activity/roles/tracked.rb'
+  autoload :Deactivatable,'public_activity/roles/deactivatable.rb'
+  autoload :Creation,     'public_activity/actions/creation.rb'
+  autoload :Update,       'public_activity/actions/update.rb'
+  autoload :Destruction,  'public_activity/actions/destruction.rb'
   autoload :VERSION
   autoload :Common
+  autoload :Renderable
 
   # Switches PublicActivity on or off.
   # @param value [Boolean]
@@ -45,11 +43,17 @@ module PublicActivity
   module Model
     extend ActiveSupport::Concern
     included do
+      include Common
+      include Deactivatable
       include Tracked
-      include Activist
+      include Activist  # optional associations by recipient|owner
     end
   end
 end
 
-require 'public_activity/store_controller'
-require 'public_activity/view_helpers'
+# Force Active Record ORM to load
+# makes initializer optional for default config
+PublicActivity.config if defined? ActiveRecord
+
+require 'public_activity/utility/store_controller'
+require 'public_activity/utility/view_helpers'

data/lib/public_activity/common.rb

@@ -20,6 +20,174 @@ module PublicActivity
   # Common methods shared across the gem.
   module Common
     extend ActiveSupport::Concern
+
+    included do
+      ::PublicActivity.config # it's the first module to be loaded into models
+                              # we need to have pieces provided by orm loaded
+      include Trackable
+      class_attribute :activity_owner_global, :activity_recipient_global,
+                      :activity_params_global, :activity_hooks, :activity_custom_fields_global
+      set_public_activity_class_defaults
+    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:
+    #
+    #   @article.activity_params = {:article_title => @article.title}
+    #   @article.save
+    #
+    # 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:
+    #
+    #   # 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:
+    #
+    #   @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
+
+    # Set or get custom fields for later processing
+    #
+    # @return [Hash]
+    attr_accessor :activity_custom_fields
+    @activity_custom_fields = {}
+
+    # @!visibility private
+    @@activity_hooks = {}
+
+    # @!endgroup
+    module ClassMethods
+      #
+      # @since 1.0.0
+      # @api private
+      def set_public_activity_class_defaults
+        self.activity_owner_global             = nil
+        self.activity_recipient_global         = nil
+        self.activity_params_global            = {}
+        self.activity_hooks                    = {}
+        self.activity_custom_fields_global     = {}
+      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
+    #
+    # Returns true if PublicActivity is enabled
+    # globally and for this class.
+    # @return [Boolean]
+    # @api private
+    # @since 0.5.0
+    def public_activity_enabled?
+      PublicActivity.enabled?
+    end
+    #
+    # 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
+
     # Directly creates activity record in the database, based on supplied options.
     #
     # It's meant for creating custom activities while *preserving* *all*
@@ -82,14 +250,11 @@ module PublicActivity
       options = prepare_settings(*args)
 
       if call_hook_safe(options[:key].split('.').last)
-        self.activities.create(
-          :key        => options[:key],
-          :owner      => options[:owner],
-          :recipient  => options[:recipient],
-          :parameters => options[:params]
-        )
         reset_activity_instance_options
+        PublicActivity::Adapter.create_activity(self, options)
       end
+
+      return nil
     end
 
     # Prepares settings used during creation of Activity record.
@@ -105,39 +270,50 @@ module PublicActivity
     #   @see #create_activity
     def prepare_settings(*args)
       # key
-      options = args.extract_options!
+      all_options = args.extract_options!
+      options = {
+        key: all_options.delete(:key),
+        owner: all_options.delete(:key),
+        action: all_options.delete(:action),
+        recipient: all_options.delete(:recipient),
+        parameters: all_options.delete(:parameters) || all_options.delete(:params)
+      }
       action = (args.first || options[:action]).try(:to_s)
 
-      key = extract_key(action, options)
+      options[:key] = extract_key(action, options)
 
-      raise NoKeyProvided, "No key provided for #{self.class.name}" unless key
+      raise NoKeyProvided, "No key provided for #{self.class.name}" unless options[:key]
+
+      options.delete(:action)
 
       # user responsible for the activity
-      owner = PublicActivity.resolve_value(self,
+      options[:owner] = PublicActivity.resolve_value(self,
         options[:owner] ||
         self.activity_owner ||
         self.class.activity_owner_global
       )
 
       # recipient of the activity
-      recipient = PublicActivity.resolve_value(self,
+      options[:recipient] = PublicActivity.resolve_value(self,
         options[:recipient] ||
         self.activity_recipient ||
         self.class.activity_recipient_global
       )
 
       #customizable parameters
-      params = options[:params] || {}
+      params = options[:params] || options[:parameters] || {}
       params.merge!(self.class.activity_params_global)
       params.merge!(self.activity_params) if self.activity_params
       params.each { |k, v| params[k] = PublicActivity.resolve_value(self, v) }
+      options[:parameters] = params
+      options.delete(:params)
 
-      {
-        :key        => key,
-        :owner      => owner,
-        :recipient  => recipient,
-        :params     => params
-      }
+      customs = self.class.activity_custom_fields_global
+      customs.merge!(self.activity_custom_fields) if self.activity_custom_fields
+      customs.merge!(all_options)
+      customs.each do  |k, v|
+        customs[k] = PublicActivity.resolve_value(self, v)
+      end.merge options
     end
 
     # Helper method to serialize class name into relevant key
@@ -159,6 +335,7 @@ module PublicActivity
       @activity_key = nil
       @activity_owner = nil
       @activity_recipient = nil
+      @activity_custom_fields = {}
     end
   end
 end