public_activity 1.1.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8fd39acfbf854c069a2b94620e3053830683b8fb
-  data.tar.gz: d8c98bb1597029b47b4926aa98afd16a5afaf7ce
+  metadata.gz: 86fca5f56a3715cdc7aa50a5429478d3da652e2a
+  data.tar.gz: 6873ddaac083d14044c4e9eb7f4137b257d7bfec
 SHA512:
-  metadata.gz: b21e5ce84fd4c69efb5c0a8ea47ad594c46d2405340ee51930ce7d05f9249adc173a25f2120bb404d475339a7c95716ee23053b1c8dcd1dab5b544a9e6bda888
-  data.tar.gz: e41642ab559c0616592d20e59ccbbec11e0bd3183855b493fe819bddb60bc04d9a5cd820086afc97c77eb055faa06daa44a726b569b7ec21ececb3748c54fcc5
+  metadata.gz: 8b432bcada38def3820e0a72b49d233e14bd1c87ceb6fdca7263e5b442a1c4d888cf88cc106a3df66febf6b5a6785b1a92a15b148c5410a72b8608596732a540
+  data.tar.gz: 8ace1656f39368a932ff0e5883d710a59a546ce269f25608bfaa9e08e6fde99881681e8eade10461f0d8142e3a72751545016a0a9eda3aae5f3c319332cb731c

data/Gemfile

@@ -1,22 +1,2 @@
-ENV['PA_ORM'] ||= 'active_record'
-
 source "https://rubygems.org"
-
-
-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', '< 5.0.0'
-  gem 'redcarpet'
-  gem 'yard', '~> 0.8'
-end
-
 gemspec

data/README.md

@@ -1,7 +1,7 @@
 # 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
+_public_activity_ provides easy activity tracking for your **ActiveRecord**, **Mongoid 3** and **MongoMapper** 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
@@ -9,8 +9,8 @@ recorded activities to users - in a similar way to how GitHub does it.
 1. [Example](#example)
   * [Demo](#online-demo)
   * [Screencast](#screencast)
-3. **[Upgrading](#upgrading)**
-4. [Setup](#setup)
+  * **[Common examples](#common-examples)**
+2. [Setup](#setup)
   1. [Gem installation](#gem-installation)
   2. [Database setup](#database-setup)
   3. [Model configuration](#model-configuration)
@@ -18,8 +18,9 @@ recorded activities to users - in a similar way to how GitHub does it.
   5. [Displaying activities](#displaying-activities)
     1. [Activity views](#activity-views)
     2. [i18n](#i18n)
-5. [Documentation](#documentation)
-6. **[Help](#help)**
+3. [Documentation](#documentation)
+4. **[Help](#help)**
+5. [Upgrading](https://github.com/pokonski/public_activity/wiki/Upgrading-from-pre-0.4.0-versions)
 
 ## Example
 
@@ -37,10 +38,6 @@ The source code of the demo is hosted here: https://github.com/pokonski/activity
 
 Ryan Bates made a [great screencast](http://railscasts.com/episodes/406-public-activity) describing how to integrate Public Activity in your Rails Application.
 
-## 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.
-
 ## Setup
 
 ### Gem installation
@@ -57,8 +54,10 @@ gem 'public_activity'
 
 ### Database setup
 
-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:
+By default _public_activity_ uses Active Record. If you want to use Mongoid or MongoMapper as your backend, create
+an initializer file in your Rails application with the corresponding code inside:
+
+For _Mongoid:_
 
 ```ruby
 # config/initializers/public_activity.rb
@@ -67,6 +66,15 @@ PublicActivity::Config.set do
 end
 ```
 
+For _MongoMapper:_
+
+```ruby
+# config/initializers/public_activity.rb
+PublicActivity::Config.set do
+  orm :mongo_mapper
+end
+```
+
 **(ActiveRecord only)** Create migration for activities and migrate the database (in your Rails project):
 
     rails g public_activity:migration
@@ -95,6 +103,16 @@ class Article
 end
 ```
 
+For _MongoMapper:_
+
+```ruby
+class Article
+  include MongoMapper::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.
 
@@ -126,13 +144,13 @@ end
 And in your views:
 
 ```erb
-<% @activities.each do |activity| %>
-  <%= render_activity(activity) %>
-<% end %>
+<%= render_activities(@activities) %>
 ```
 
 *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.
 
+*Note*: `render_activities` is an alias for `render_activity` and does the same.
+
 #### Layouts
 
 You can also pass options to both `activity#render` and `#render_activity` methods, which are passed deeper
@@ -141,18 +159,26 @@ A useful example would be to render activities wrapped in layout, which shares c
 like a timestamp, owner's avatar etc:
 
 ```erb
-<% @activities.each do |activity| %>
-  <%= render_activity(activity, :layout => :activity) %>
-<% end %>
+<%= render_activities(@activities, layout: :activity) %>
 ```
 
 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.
 
+#### Locals
+
+Sometimes, it's desirable to pass additional local variables to partials. It can be done this way:
+
+```erb
+<%= render_activity(@activity, locals: {friends: current_user.friends} %>
+```
+
+*Note*: Before 1.4.0, one could pass variables directly to the options hash for `#render_activity` and access it from activity parameters. This functionality is retained in 1.4.0 and later, but the `:locals` method is **preferred**, since it prevents bugs from shadowing variables from activity parameters in the database.
+
 #### 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.
+`public_activity` looks for views in `app/views/public_activity`.
 
 For example, if you have an activity with `:key` set to `"activity.user.changed_avatar"`, the gem will look for a partial in `app/views/public_activity/user/_changed_avatar.(erb|haml|slim|something_else)`.
 
@@ -162,7 +188,7 @@ If a view file does not exist, then p_a falls back to the old behaviour and trie
 
 #### 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.
+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. You can render pure i18n strings by passing `{display: :i18n}` to `#render_activity` or `#render`.
 
 Translations should be put in your locale `.yml` files. To render pure strings from I18n Example structure:
 
@@ -176,54 +202,16 @@ activity:
 
 This structure is valid for activities with keys `"activity.article.create"` or `"article.create"`. As mentioned before, `"activity."` part of the key is optional.
 
-## 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
-      tracked
-    end
-    ```
-
-    _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.   **(ActiveRecord only)** Generate and run migration which adds new column to `activities` table:
-
-     ```bash
-     rails g public_activity:migration_upgrade
-     rake db:migrate
-     ```
-
 ## Documentation
 
-For more customization go [here](http://rubydoc.info/gems/public_activity/index)
+For more documentation go [here](http://rubydoc.info/gems/public_activity/index)
 
-## Useful examples
+## Common examples
 
 * [[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)
+* [[How to] Use custom fields on Activity](https://github.com/pokonski/public_activity/wiki/%5BHow-to%5D-Use-custom-fields-on-Activity)
 
 ## Help
 
@@ -234,4 +222,4 @@ 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) 2011-2013 Piotrek Okoński, released under the MIT license

data/lib/public_activity/activity.rb

@@ -1,4 +1,6 @@
 module PublicActivity
+  # Main model, stores all information about what happened,
+  # who caused it, when and anything else.
   class Activity < inherit_orm("Activity")
   end
 end

data/lib/public_activity/common.rb

@@ -96,7 +96,7 @@ module PublicActivity
     # @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}
+    # Set or get custom i18n key passed to {Activity}, later used in {Renderable#text}
     #
     # == Usage:
     #
@@ -119,6 +119,8 @@ module PublicActivity
     @@activity_hooks = {}
 
     # @!endgroup
+
+    # Provides some global methods for every model class.
     module ClassMethods
       #
       # @since 1.0.0
@@ -134,7 +136,7 @@ module PublicActivity
       # Extracts a hook from the _:on_ option provided in
       # {Tracked::ClassMethods#tracked}. Returns nil when no hook exists for
       # given action
-      # {Tracked#get_hook}
+      # {Common#get_hook}
       #
       # @see Tracked#get_hook
       # @param key [String, Symbol] action to retrieve a hook for
@@ -160,11 +162,11 @@ module PublicActivity
       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)
+    # Shortcut for {ClassMethods#get_hook}
+    # @param (see ClassMethods#get_hook)
+    # @return (see ClassMethods#get_hook)
+    # @since (see ClassMethods#get_hook)
+    # @api (see ClassMethods#get_hook)
     def get_hook(key)
       self.class.get_hook(key)
     end

data/lib/public_activity/config.rb

@@ -13,6 +13,12 @@ module PublicActivity
       @enabled  = true
     end
 
+    # Evaluates given block to provide DSL configuration.
+    # @example Initializer for Rails
+    #   PublicActivity::Config.set do
+    #     orm :mongo_mapper
+    #     enabled false
+    #   end
     def self.set &block
       b = Block.new
       b.instance_eval &block
@@ -23,23 +29,32 @@ module PublicActivity
       instance.instance_variable_set(:@enabled, enabled) unless enabled.nil?
     end
 
+    # Set the ORM for use by PublicActivity.
     def self.orm(orm = nil)
       @@orm = (orm ? orm.to_sym : false) || @@orm
     end
 
+    # alias for {#orm}
+    # @see #orm
     def self.orm=(orm = nil)
       orm(orm)
     end
 
+    # instance version of {Config#orm}
+    # @see Config#orm
     def orm(orm=nil)
       self.class.orm(orm)
     end
 
+    # Provides simple DSL for the config block.
     class Block
+      # @see Config#orm
       def orm(orm = nil)
         @orm = (orm ? orm.to_sym : false) || @orm
       end
 
+      # Decides whether to enable PublicActivity.
+      # @param en [Boolean] Enabled?
       def enabled(en = nil)
         @en = (en.nil? ? @en : en)
       end

data/lib/public_activity/models/activist.rb

@@ -1,5 +1,7 @@
 module PublicActivity
+  # Provides helper methods for selecting activities from a user.
   module Activist
+    # Delegates to configured ORM.
     def self.included(base)
       base.extend PublicActivity::inherit_orm("Activist")
     end

data/lib/public_activity/models/adapter.rb

@@ -1,4 +1,5 @@
 module PublicActivity
+  # Loads database-specific routines for use by PublicActivity.
   class Adapter < inherit_orm("Adapter")
   end
 end

data/lib/public_activity/models/trackable.rb

@@ -1,5 +1,7 @@
 module PublicActivity
+  # Provides association for activities bound to this object by *trackable*.
   module Trackable
+    # Delegates to ORM.
     def self.included(base)
       base.extend PublicActivity::inherit_orm("Trackable")
     end

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

@@ -5,16 +5,12 @@ module PublicActivity
       module Activist
         extend ActiveSupport::Concern
 
+        # Loads the {ClassMethods#activist} method for declaring the class
+        # as an activist.
         def self.extended(base)
           base.extend(ClassMethods)
         end
-        # 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
@@ -35,7 +31,14 @@ module PublicActivity
           #   User.first.activities
           #
           def activist
+            # Association of activities as their owner.
+            # @!method activities_as_owner
+            # @return [Array<Activity>] Activities which self is the owner of.
             has_many :activities_as_owner, :class_name => "::PublicActivity::Activity", :as => :owner
+
+            # Association of activities as their recipient.
+            # @!method activities_as_recipient
+            # @return [Array<Activity>] Activities which self is the recipient of.
             has_many :activities_as_recipient, :class_name => "::PublicActivity::Activity", :as => :recipient
           end
         end

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

@@ -15,9 +15,10 @@ module PublicActivity
         # Serialize parameters Hash
         serialize :parameters, Hash
 
-        # should recipient and owner be accessible?
-        attr_accessible :key, :owner, :parameters, :recipient, :trackable
+        if ::ActiveRecord::VERSION::MAJOR < 4
+          attr_accessible :key, :owner, :parameters, :recipient, :trackable
+        end
       end
     end
   end
-end
+end

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

@@ -1,6 +1,10 @@
 module PublicActivity
   module ORM
+    # Support for ActiveRecord for PublicActivity. Used by default and supported
+    # officialy.
     module ActiveRecord
+      # Provides ActiveRecord specific, database-related routines for use by
+      # PublicActivity.
       class Adapter
         # Creates the activity on `trackable` with `options`
         def self.create_activity(trackable, options)

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

@@ -1,7 +1,11 @@
 module PublicActivity
   module ORM
     module ActiveRecord
+      # Implements {PublicActivity::Trackable} for ActiveRecord
+      # @see PublicActivity::Trackable
       module Trackable
+        # Creates an association for activities where self is the *trackable*
+        # object.
         def self.extended(base)
           base.has_many :activities, :class_name => "::PublicActivity::Activity", :as => :trackable
         end

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

@@ -0,0 +1,46 @@
+module PublicActivity
+  module ORM
+    module MongoMapper
+      # Module extending classes that serve as owners
+      module Activist
+        extend ActiveSupport::Concern
+
+        def self.extended(base)
+          base.extend(ClassMethods)
+        end
+        # 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 MongoMapper 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
+          #     include MongoMapper::Document
+          #     include PublicActivity::Model
+          #     activist
+          #   end
+          #
+          # In controller:
+          #   User.first.activities
+          #
+          def activist
+            many :activities_as_owner,      :class_name => "::PublicActivity::Activity", :as => :owner
+            many :activities_as_recipient,  :class_name => "::PublicActivity::Activity", :as => :recipient
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+require 'mongo_mapper'
+require 'active_support/core_ext'
+
+module PublicActivity
+  module ORM
+    module MongoMapper
+      # The MongoMapper document containing
+      # details about recorded activity.
+      class Activity
+        include ::MongoMapper::Document
+        include Renderable
+
+        class SymbolHash < Hash
+          def self.from_mongo(value)
+            value.symbolize_keys unless value.nil?
+          end
+        end
+
+        # 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
+
+        key :key,         String
+        key :parameters,  SymbolHash
+
+        timestamps!
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,11 @@
+module PublicActivity
+  module ORM
+    module MongoMapper
+      module Trackable
+        def self.extended(base)
+          base.many :activities, :class_name => "::PublicActivity::Activity", order: :created_at.asc, :as => :trackable
+        end
+      end
+    end
+  end
+end

data/lib/public_activity/orm/mongo_mapper.rb

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

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

@@ -8,6 +8,7 @@ module PublicActivity
       class Activity
         include ::Mongoid::Document
         include ::Mongoid::Timestamps
+        include ::Mongoid::Attributes::Dynamic if (::Mongoid::VERSION =~ /^4/) == 0
         include Renderable
 
         # Define polymorphic association to the parent

data/lib/public_activity/renderable.rb

@@ -1,4 +1,6 @@
 module PublicActivity
+  # Provides logic for rendering activities. Handles both i18n strings
+  # support and smart partials rendering (different templates per activity key).
   module Renderable
     # Virtual attribute returning text description of the activity
     # using the activity's key to translate using i18n.
@@ -80,23 +82,25 @@ module PublicActivity
         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
+      if layout = params.delete(:layout)
         layout = layout.to_s
         layout = layout[0,8] == "layouts/" ? layout : "layouts/#{layout}"
       end
+
+      locals = params.delete(:locals) || Hash.new
+
+      params_indifferent = self.parameters.with_indifferent_access
+      params_indifferent.merge!(params)
+
       context.render :partial => (partial_path || self.template_path(self.key)),
         :layout => layout,
-        :locals =>
-          {:a => self, :activity => self,
+        :locals => locals.merge(:a => self, :activity => self,
            :controller => controller,
            :current_user => controller.respond_to?(:current_user) ?
                 controller.current_user : nil ,
-           :p => params_indifferent, :params => params_indifferent}
+           :p => params_indifferent, :params => params_indifferent)
     end
 
     protected

data/lib/public_activity/roles/deactivatable.rb

@@ -1,4 +1,5 @@
 module PublicActivity
+  # Enables per-class disabling of PublicActivity functionality.
   module Deactivatable
     extend ActiveSupport::Concern
 
@@ -17,6 +18,8 @@ module PublicActivity
       PublicActivity.enabled? && self.class.public_activity_enabled_for_model
     end
 
+    # Provides global methods to disable or enable PublicActivity on a per-class
+    # basis.
     module ClassMethods
       # Switches public_activity off for this class
       def public_activity_off

data/lib/public_activity/roles/tracked.rb

@@ -9,13 +9,13 @@ module PublicActivity
     # == Options
     #
     # [:key]
-    #   See {#activity_key}
+    #   See {Common#activity_key}
     # [:owner]
-    #   See {#activity_owner}
+    #   See {Common#activity_owner}
     # [:params]
-    #   See {#activity_params}
+    #   See {Common#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}.
+    #   Set the recipient for this activity. Useful for private notifications, which should only be visible to a certain user. See {Common#activity_recipient}.
     # @example
     #
     #   @article = Article.new
@@ -66,7 +66,7 @@ module PublicActivity
       #   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.
+      #   method. It is later used in {Renderable#text} method.
       #   == Example:
       #    class Article < ActiveRecord::Base
       #      include PublicActivity::Model
@@ -128,7 +128,7 @@ module PublicActivity
       #   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
+      # @param opts [Hash] options
       # @return [nil] options
       def tracked(opts = {})
         options = opts.clone