public_activity 0.3.4 → 0.4.0.rc1

data/Gemfile

@@ -2,12 +2,4 @@ source :rubygems
 
 gemspec
 
-gem 'rails'
-gem 'yard'
-gem 'pusher'
-
-group :development, :test do
-  gem 'rspec'
-  gem 'sqlite3'
-  gem 'rspec-rails'
-end
+gem 'yard'

data/README.md

@@ -5,53 +5,52 @@ Simply put: it records what has been changed or edited and gives you the ability
 
 ## Example
 
-A picture is worth a thousand words, so here is a visual representation of what this gem is about:
+Here is a simple example showing what this gem is about:
 
 ![Example usage](http://i.imgur.com/uGPSm.png)
 
-## Installation
+## Upgrading to 0.4
+
+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
+
+### Gem installation
+
+You can install `public_activity` as you would any other gem:
 
-You can install this gem as you would any other gem:
     gem install public_activity
+
 or in your Gemfile:
+
     gem 'public_activity'
 
-## Usage
+### Database setup
 
-Create migration for activities (in your Rails project):
+Create migration for activities and migrate the database (in your Rails project):
 
     rails g public_activity:migration
     rake db:migrate
 
-Add 'tracked' to the model you want to keep track of:
+### Model configuration
+
+Include `PublicActivity::Model` and add `tracked` to the model you want to keep track of:
 
 ```ruby
 class Article < ActiveRecord::Base
+  include PublicActivity::Model
   tracked
 end
 ```
 
-To default the owner to the current user (optional)
+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.
 
-```ruby
-#Aplication Controller
-before_filter :define_current_user
+### Displaying activities
 
-def define_current_user
-  User.current_user = current_user
-end
-
-#User.rb (model)
-class User < ActiveRecord::Base
-  cattr_accessor :current_user
-end
-```
-
-And now, by default create/update/destroy activities are recorded in activities table. 
-To display them you can do a simple query:
+To display them you simply query the `PublicActivity::Activity` ActiveRecord model:
 
 ```ruby
-# some_controller.rb
+# notifications_controller.rb
 def index
   @activities = PublicActivity::Activity.all
 end
@@ -60,12 +59,39 @@ end
 And in your views:
 
 ```erb
-<% for activity in @activities %>
-  <%= activity.text %><br/>
+<%= for activity in @activities %>
+  <%= 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.
+
+```erb
+<%= for activity in @activities %>
+  <%= render_activity(activity, :layout => :activity) %>
 <% end %>
 ```
 
-The only thing left is to add templates (config/pba.yml), for example:
+The activity will be wrapped with the `app/views/layouts/activity` layout, in the above example.
+
+### 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.
+
+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)`.
+
+*Hint*: the `"activity."` prefix in `:key` is completely optional and kept for backwards compatibility, you can skip it in new projects.
+
+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
+
+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 should be put in your locale `.yml` files. To render pure strings from I18n Example structure:
 
 ```yaml
 activity:
@@ -74,16 +100,37 @@ activity:
     update: 'Someone has edited the article'
     destroy: 'Some user removed an article!'
 ```
-Place this in a file and reference it in a Rails initializer.
 
-```ruby
-PublicActivity::Activity.template = YAML.load_file("#{Rails.root}/config/pba.yml")
-```
+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
+
+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:
+
+    ```ruby
+    class Article < ActiveRecord::Base
+      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:
+
+     ```bash
+     rails g public_activity:migration_upgrade
+     rake db:migrate
+     ```
 
-This is only a basic example, refer to documentation for more options and customization!
 ## Documentation
 
-You can find documentation [here](http://rubydoc.info/gems/public_activity/)
+For more customization go [here](http://rubydoc.info/gems/public_activity/index)
 
 ## License
-Copyright (c) 2012 Piotrek Okoński, released under the MIT license
+Copyright (c) 2012 Piotrek Okoński, released under the MIT license

data/Rakefile

@@ -2,15 +2,17 @@ require "bundler/gem_tasks"
 require 'rake'
 require 'yard'
 require 'yard/rake/yardoc_task'
-require 'rspec/core/rake_task'
+require 'rake/testtask'
 
-task :default => :spec
-
-RSpec::Core::RakeTask.new(:spec) do |t|
-  t.pattern = "./spec/*_spec.rb"
-end
+task :default => :test
 
 desc 'Generate documentation for the public_activity plugin.'
 YARD::Rake::YardocTask.new do |doc|
   doc.files = ['lib/**/*.rb']
 end
+
+Rake::TestTask.new do |t|
+	t.libs << "test"
+	t.test_files = FileList['test/test*.rb']
+end
+

data/lib/generators/public_activity/activity/activity_generator.rb

@@ -0,0 +1,17 @@
+require 'generators/public_activity'
+require 'rails/generators/active_record'
+
+module PublicActivity
+  module Generators
+    # Activity generator that creates activity model file from template
+    class ActivityGenerator < ActiveRecord::Generators::Base
+      extend Base
+
+      argument :name, :type => :string, :default => 'activity'
+      # Create model in project's folder
+      def generate_files
+        copy_file 'activity.rb', "app/models/#{name}.rb"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+# Activity model for customisation & custom methods
+class Activity < PublicActivity::Activity
+end

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

@@ -7,6 +7,7 @@ class CreateActivities < ActiveRecord::Migration
       t.belongs_to :owner, :polymorphic => true
       t.string  :key
       t.text    :parameters
+      t.belongs_to :recipient, :polymorphic => true
 
       t.timestamps
     end

data/lib/generators/public_activity/migration_upgrade/migration_upgrade_generator.rb

@@ -0,0 +1,17 @@
+require 'generators/public_activity'
+require 'rails/generators/active_record'
+
+module PublicActivity
+  module Generators
+    # Migration generator that creates migration file from template
+    class MigrationUpgradeGenerator < ActiveRecord::Generators::Base
+      extend Base
+
+      argument :name, :type => :string, :default => 'upgrade_activities'
+      # Create migration in project's folder
+      def generate_files
+        migration_template 'upgrade.rb', "db/migrate/#{name}"
+      end
+    end
+  end
+end

data/lib/generators/public_activity/migration_upgrade/templates/upgrade.rb

@@ -0,0 +1,9 @@
+# Migration responsible for creating a table with activities
+class UpgradeActivities < ActiveRecord::Migration
+  # Create table
+  def self.change
+    change_table :activities do |t|
+      t.belongs_to :recipient, :polymorphic => true
+    end
+  end
+end

data/lib/public_activity/activist.rb

@@ -2,25 +2,35 @@ module PublicActivity
   # 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 has_many :activities association to model
       # so you can list activities performed by the owner.
       # It is completely optional, but simplifies your work.
-      # 
+      #
       # == Usage:
       # In model:
       #
       #   class User < ActiveRecord::Base
       #     activist
-      #   end 
+      #   end
       #
       # In controller:
       #   User.first.activities
       #
       def activist
         has_many :activities, :class_name => "PublicActivity::Activity", :as => :owner
-      end    
+        has_many :private_activities, :class_name => "PublicActivity::Activity", :as => :recipient
+      end
     end
   end
 end

data/lib/public_activity/activity.rb

@@ -1,19 +1,20 @@
-require 'active_record'
-
 module PublicActivity
-  # The ActiveRecord model containing 
+  # 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
 
-    attr_accessible :key, :owner, :parameters
+    # should recipient and owner be accessible?
+    attr_accessible :key, :owner, :parameters, :recipient
     # Virtual attribute returning text description of the activity
     # using basic ERB templating
     #
@@ -22,11 +23,11 @@ module PublicActivity
     # 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!'
+    #   activity:
+    #     article:
+    #       create: "New <%= trackable.name %> article has been created"
+    #       update: 'Someone modified the article'
+    #       destroy: 'Someone deleted the article!'
     #
     # And in controller:
     #
@@ -39,30 +40,91 @@ module PublicActivity
     #
     # 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
     def text(params = {})
+      # TODO: some helper for key transformation for two supported formats
+      k = key.split('.')
+      k.unshift('activity') if k.first != 'activity'
+      k = k.join('.')
+
+      I18n.t(k, parameters.merge(params) || {})
+    end
+
+    # Renders activity from views.
+    #
+    # @param [ActionView::Base] context
+    # @return [nil] nil
+    #
+    # Renders activity to the given ActionView context with included
+    # AV::Helpers::RenderingHelper (most commonly just ActionView::Base)
+    #
+    # The *preferred* *way* of rendering activities is
+    # to provide a template specifying how the rendering should be happening.
+    # However, one may choose using _I18n_ based approach when developing
+    # an application that supports plenty of languages.
+    #
+    # If partial view exists that matches the *key* attribute
+    # renders that partial with local variables set to contain both
+    # Activity and activity_parameters (hash with indifferent access)
+    #
+    # Otherwise, it outputs the I18n translation to the context
+    # @example Render a list of all activities from a view (erb)
+    #   <ul>
+    #     <% for activity in PublicActivity::Activity.all %>
+    #      <li><%= render_activity(activity) %></li>
+    #     <% end %>
+    #   </ul>
+    #
+    # = Creating a template
+    # To use templates for formatting how the activity should render,
+    # create a template based on activity key, for example:
+    #
+    # Given a key _activity.article.create_, create directory tree
+    # _app/views/public_activity/article/_ and create the _create_ partial there
+    #
+    # 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
+    #
+    # == Variables in templates
+    # From within a template there are two variables at your disposal:
+    # * activity (aliased as *a* for a shortcut)
+    # * params   (aliased as *p*) [converted into a {HashWithIndifferentAccess}]
+    #
+    # @example Template for key: _activity.article.create_ (erb)
+    #   <p>
+    #     Article <strong><%= p[:name] %></strong>
+    #     was written by <em><%= p["author"] %></em>
+    #     <%= distance_of_time_in_words_to_now(a.created_at) %>
+    #   </p>
+    def render(context, params = {})
       begin
-        erb_template = resolveTemplate(key)
-        if erb_template
-          parameters.merge! params
-          renderer = ERB.new(erb_template)
-          renderer.result(binding)
-        else
-          "Template not defined"
-        end
-      rescue
-        "Template not defined"
+        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)
       end
     end
-    
-    private
-    def resolveTemplate(key)
-      res = nil
-      if self.template
-        key.split(".").each do |k|
-          res = (res ? res[k] : self.template[k])
-        end
-      end
-      res
+
+    protected
+    # Builds the path to template based on activity key
+    # TODO: verify that attribute `key` is splitted by commas
+    #       and that the word before first comma is equal to
+    #       "activity"
+    def template_path(key)
+      path = key.split(".")
+      path.delete_at(0) if path[0] == "activity"
+      path.unshift "public_activity"
+      path.join("/")
     end
-  end  
+  end
 end

data/lib/public_activity/common.rb

@@ -1,56 +1,143 @@
 module PublicActivity
+  # Happens when creating custom activities without either action or a key.
+  class NoKeyProvided < Exception; end
+
+  # Used to smartly transform value from metadata to data.
+  # Accepts Symbols, which it will send against context.
+  # Accepts Procs, which it will execute with controller and context.
+  # @since 0.4.0
+  def self.resolve_value(context, thing)
+    case thing
+    when Symbol
+      context.__send__(thing)
+    when Proc
+      thing.call(PublicActivity.get_controller, context)
+    else
+      thing
+    end
+  end
+
   # Common methods shared across the gem.
   module Common
     extend ActiveSupport::Concern
-    # Directly creates activity record in the database, based on supplied arguments.
-    # Only first argument - key - is required.
+    # Directly creates activity record in the database, based on supplied options.
     #
-    # == Usage:
+    # It's meant for creating custom activities while *preserving* *all*
+    # *configuration* defined before. If you fire up the simplest of options:
     #
-    #   current_user.create_activity("activity.user.avatar_changed") if @user.avatar_file_name_changed?
+    #   current_user.create_activity(:avatar_changed)
     #
-    # == Parameters:
-    # [key]
-    #   Custom key that will be used as a i18n translation key - *required*
-    # [owner]
-    #   Polymorphic relation specifying the owner of this activity (for example, a User who performed this task) - *optional*
-    # [params]
-    #  Hash with parameters passed directly into i18n.translate method - *optional*
+    # It will still gather data from any procs or symbols you passed as params
+    # to {Tracked::ClassMethods#tracked}. It will ask the hooks you defined
+    # whether to really save this activity.
     #
-    def create_activity(key, owner = nil, params = {})
-
-      if owner.nil? && ((defined? User) != nil) && User.respond_to?(:current_user)
-        owner = User.current_user
-      end
+    # But you can also overwrite instance and global settings with your options:
+    #
+    #   @article.activity :owner => proc {|controller| controller.current_user }
+    #   @article.create_activity(:commented_on, :owner => @user)
+    #
+    # And it's smart! It won't execute your proc, since you've chosen to
+    # overwrite instance parameter _:owner_ with @user.
+    #
+    # [:key]
+    #   The key will be generated from either:
+    #   * the first parameter you pass that is not a hash (*action*)
+    #   * the _:action_ option in the options hash (*action*)
+    #   * the _:key_ option in the options hash (it has to be a full key,
+    #     including model name)
+    #   When you pass an *action* (first two options above), they will be
+    #   added to parameterized model name:
+    #
+    #   Given Article model and instance: @article,
+    #
+    #     @article.create_activity :commented_on
+    #     @article.activities.last.key # => "article.commented_on"
+    #
+    # For other parameters, see {Tracked#activity}, and "Instance options"
+    # accessors at {Tracked}, information on hooks is available at
+    # {Tracked::ClassMethods#tracked}.
+    # @see #prepare_settings
+    # @return [Model, nil] If created successfully, new activity
+    # @since 0.4.0
+    # @api public
+    # @overload create_activity(action, options = {})
+    #   @param [Symbol,String] action Name of the action
+    #   @param [Hash] options Options with quality higher than instance options
+    #     set in {Tracked#activity}
+    #   @option options [Activist] :owner Owner
+    #   @option options [Activist] :recipient Recipient
+    #   @option options [Hash] :params Parameters, see
+    #     {PublicActivity.resolve_value}
+    # @overload create_activity(options = {})
+    #   @param [Hash] options Options with quality higher than instance options
+    #     set in {Tracked#activity}
+    #   @option options [Symbol,String] :action Name of the action
+    #   @option options [String] :key Full key
+    #   @option options [Activist] :owner Owner
+    #   @option options [Activist] :recipient Recipient
+    #   @option options [Hash] :params Parameters, see
+    #     {PublicActivity.resolve_value}
+    def create_activity(*args)
+      options = prepare_settings(*args)
 
-      activity = self.activities.create(:key => key, :owner => owner, :parameters => params)
-      if !Pusher.app_id.nil? && !Pusher.key.nil? && !Pusher.secret.nil?
-        Pusher['activity-channel'].trigger('activity-create', {:key => key, :owner => owner, :parameters => params, :text => activity.text, :object => self})
+      if call_hook_safe(options[:key].split('.').last)
+        self.activities.create(
+          :key        => options[:key],
+          :owner      => options[:owner],
+          :recipient  => options[:recipient],
+          :parameters => options[:params]
+        )
       end
     end
 
-    private
-      # Prepares settings used during creation of Activity record.
-      # params passed directly to tracked model have priority over
-      # settings specified in tracked() method
-      def prepare_settings
-        # user responsible for the activity
-        if self.activity_owner
-          owner = self.activity_owner
-        else
-          owner = self.class.activity_owner_global
-        end
-
-        case owner
-          when Symbol
-            owner = self.__send__(owner)
-          when Proc
-            owner = owner.call(self)
-        end
-        #customizable parameters
-        parameters = self.class.activity_params_global
-        parameters.merge! self.activity_params if self.activity_params
-        return {:key => self.activity_key,:owner => owner, :parameters => parameters}
+    # Prepares settings used during creation of Activity record.
+    # params passed directly to tracked model have priority over
+    # settings specified in tracked() method
+    #
+    # @see #create_activity
+    # @return [Hash] Settings with preserved options that were passed
+    # @api private
+    # @overload prepare_settings(action, options = {})
+    #   @see #create_activity
+    # @overload prepare_settings(options = {})
+    #   @see #create_activity
+    def prepare_settings(*args)
+      # key
+      options = args.extract_options!
+      action = (args.first || options[:action]).try(:to_s)
+      if action.nil? and !options.has_key?(:key)
+        raise NoKeyProvided, "No key provided for #{self.class.name}"
       end
+      key = (options[:key] ||
+            self.activity_key ||
+            (self.class.name.parameterize('_') + "." + action.to_s)).to_s
+
+      # user responsible for the activity
+      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] ||
+        self.activity_recipient ||
+        self.class.activity_recipient_global
+      )
+
+      #customizable parameters
+      params = options[:params] || {}
+      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) }
+
+      {
+        :key        => key,
+        :owner      => owner,
+        :recipient  => recipient,
+        :params     => params
+      }
+    end
   end
 end

data/lib/public_activity/creation.rb

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