activities 0.1.0

data/README.rdoc

@@ -0,0 +1,89 @@
+= Introduction
+
+Activities is a gem that enables social activities in ActiveRecord objects.
+
+= Install
+
+  sudo gem install activities
+
+You have to create a migration with the following code:
+
+  create_table :activities do |t|
+    t.references :tracker, :polymorphic => true, :null => false
+    t.references :trackable, :polymorphic => true, :null => false
+    t.string :action, :null => false
+    t.text :data, :null => true
+    t.timestamps
+  end
+
+  add_index :activities, [:tracker_id, :trackable_id]
+  add_index :activities, [:tracker_id, :trackable_id, :action]
+
+If you want the source go to http://github.com/fnando/activities
+
+= Usage
+
+Activities is plugged on associations. So, all you have to do is add something like this:
+
+  class User < ActiveRecord::Base
+    has_many :projects
+    activities_for :projects do
+      track :renamed, :if => proc {|r| !r.new_record? && r.name_changed? }, :on => :save
+      track :create
+      track :update
+      track :destroy
+    end
+  end
+
+This will add activities when you create, update, destroy a project or the change its name.
+
+To retrieve the activities, you can use the association +activities+.
+
+  @user.activities.all
+
+By default, all attributes are stored in a field called +data+. You should overwrite the method
++to_activity+ and return a hash with the attributes that you really want to be saved.
+
+  class Project < ActiveRecord::Base
+    belongs_to :user
+
+    def to_activity
+      { :name => name, :status => status }
+    end
+  end
+
+To display the activities, you should use the helper +render_activity+.
+
+  <% for activity in @activities %>
+    <%= render_activity @activity %>
+  <% end %>
+
+The +render_activity+ helper will render a partial as <tt>app/views/activities/TRACKABLE_TYPE/ACTION</tt>.
+So, if you want to render activities fro that project, you should create the following files:
+
+  app/views/activities/project/_renamed.html.erb
+  app/views/activities/project/_create.html.erb
+  app/views/activities/project/_update.html.erb
+  app/views/activities/project/_destroy.html.erb
+
+The activity object will be available and you can display something like this:
+
+  <p>
+    <%= tracker.name %> created the
+    repository <%= link_to data[:name], project_path(trackable) %>
+    <%= time_ago_in_words data[:created_at] %>
+  </p>
+
+= License
+
+(The MIT License)
+
+Copyright © 2010:
+
+* Nando Vieira - http://simplesideias.com.br
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,43 @@
+require "jeweler"
+require "rcov/rcovtask"
+require "rake/testtask"
+require "rake/rdoctask"
+require "lib/activities/version"
+
+Rcov::RcovTask.new do |t|
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.rcov_opts = ["--sort coverage", "--exclude .gem,.bundle,errors.rb"]
+
+  t.output_dir = "coverage"
+  t.libs << "test"
+  t.verbose = true
+end
+
+Rake::TestTask.new do |t|
+  t.libs << "lib"
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.main = "README.rdoc"
+  rdoc.rdoc_dir = "doc"
+  rdoc.title = "Actitivies API"
+  rdoc.options += %w[ --line-numbers --inline-source --charset utf-8 ]
+  rdoc.rdoc_files.include("README.rdoc")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+JEWEL = Jeweler::Tasks.new do |gem|
+  gem.name = "activities"
+  gem.email = "fnando.vieira@gmail.com"
+  gem.homepage = "http://github.com/fnando/activities"
+  gem.authors = ["Nando Vieira"]
+  gem.version = Activities::Version::STRING
+  gem.summary = "A framework for aggregating social activity."
+  gem.add_dependency "activerecord"
+  gem.files =  FileList["{README,CHANGELOG}.rdoc", "{lib,test}/**/*", "Rakefile"]
+end
+
+Jeweler::GemcutterTasks.new

data/lib/activities.rb

@@ -0,0 +1,14 @@
+require "active_record"
+require "activities/version"
+require "activities/helper"
+require "activities/active_record"
+require "activities/activity"
+require "activities/dsl"
+
+module Activities
+end
+
+ActiveRecord::Base.class_eval do
+  include Activities::ActiveRecord::InstanceMethods
+  extend Activities::ActiveRecord::ClassMethods
+end

data/lib/activities/active_record.rb

@@ -0,0 +1,2 @@
+require "activities/active_record/instance_methods"
+require "activities/active_record/class_methods"

data/lib/activities/active_record/class_methods.rb

@@ -0,0 +1,93 @@
+module Activities
+  module ActiveRecord
+    module ClassMethods
+      # Add a new activity trigger.
+      #
+      #   class User < ActiveRecord::Base
+      #     has_many :tasks
+      #
+      #     activities_for :tasks do
+      #       track :create
+      #       track :update
+      #       track :destroy
+      #     end
+      #   end
+      #
+      # The above statement will create activities when
+      # a <tt>Thing</tt> instance is created, updated or removed.
+      #
+      # By default, the activity tracker stores all
+      # attributes. But you can specify which attributes you want to
+      # save. Just overwrite the method <tt>to_activity</tt> on your
+      # trackable model.
+      #
+      #   class Task < ActiveRecord::Base
+      #     belongs_to :project
+      #
+      #     def to_activity
+      #       { :project_name => project.name, :task_name => name }
+      #     end
+      #   end
+      #
+      # To track custom actions, you need to specify other options.
+      # Imagine you want to track when a task is marked as completed.
+      # You can add an activity to this action.
+      #
+      #   class User < ActiveRecord::Base
+      #     has_many :tasks
+      #
+      #     activities_for :tasks do
+      #        track :completed, :on => :update, :if => proc {|task| task.status_changed? && task.status == "completed" }
+      #     end
+      #   end
+      #
+      # You can also track when an attribute changes:
+      #
+      #   class User < ActiveRecord::Base
+      #     has_many :projects
+      #
+      #     activities_for :projects do
+      #       track :renamed, :on => :update, :if => :name_changed?
+      #     end
+      #   end
+      #
+      # There's also an <tt>:unless</tt> option. REMEMBER: you can't use the <tt>:unless</tt> and <tt>:if</tt>
+      # options at the same time.
+      #
+      def activities_for(reflection_name, &block)
+        reflection = self.reflections[reflection_name]
+        tracker_class = self
+
+        raise ArgumentError, "#{reflection_name.inspect} is not an existing association" unless reflection
+        raise ArgumentError, "no block given" unless block_given?
+
+        tracker_class.class_eval do
+          has_many :activities, :as => :tracker
+        end
+
+        model_class = reflection.class_name.constantize
+
+        model_class.class_eval do
+          unless self.respond_to?(:activity_trackers)
+            class << self
+              attr_accessor :activity_trackers
+            end
+
+            has_many :activities, :as => :trackable
+
+            self.activity_trackers = {}
+
+            after_create   :process_activities_on_create
+            before_save    :process_activities_on_update
+            before_destroy :process_activities_on_destroy
+          end
+        end
+
+        dsl = Activities::Dsl.new
+        dsl.trackable = model_class
+        dsl.reflection_name = reflection.primary_key_name.gsub(/_id$/, "")
+        dsl.instance_eval(&block)
+      end
+    end
+  end
+end

data/lib/activities/active_record/instance_methods.rb

@@ -0,0 +1,55 @@
+module Activities
+  module ActiveRecord
+    module InstanceMethods
+      def to_activity # :nodoc:
+        attributes
+      end
+
+      private
+      def process_activities(step)
+        [self.class.activity_trackers[step]].flatten.compact.each do |options|
+          next unless process_activity?(options)
+
+          ::Activity.create!({
+            :tracker => self.send(options[:reflection_name]),
+            :trackable => self,
+            :action => options[:action].to_s,
+            :data => to_activity.symbolize_keys
+          })
+        end
+      end
+
+      def process_activity?(options)
+        if options[:if]
+          check_against = true
+          callback = options[:if]
+        elsif options[:unless]
+          check_against = false
+          callback = options[:unless]
+        else
+          return true
+        end
+
+        if callback.respond_to?(:call)
+          result = callback[self]
+        elsif callback.kind_of?(Symbol)
+          result = send(callback)
+        end
+
+        !!result == check_against
+      end
+
+      def process_activities_on_create
+        process_activities(:create)
+      end
+
+      def process_activities_on_update
+        process_activities(:update) unless new_record?
+      end
+
+      def process_activities_on_destroy
+        process_activities(:destroy)
+      end
+    end
+  end
+end

data/lib/activities/activity.rb

@@ -0,0 +1,5 @@
+class Activity < ::ActiveRecord::Base
+  belongs_to :tracker, :polymorphic => true
+  belongs_to :trackable, :polymorphic => true
+  serialize :data, Hash
+end

data/lib/activities/dsl.rb

@@ -0,0 +1,24 @@
+module Activities
+  class Dsl
+    attr_accessor :trackable
+    attr_accessor :reflection_name
+
+    def track(action, options = {})
+      options = prepare_options(action, options)
+      check_validity!(options)
+      on = options.delete(:on)
+      trackable.activity_trackers[on] ||= []
+      trackable.activity_trackers[on] << options.merge(:action => action, :reflection_name => reflection_name)
+    end
+
+    protected
+    def prepare_options(action, options = {}) # :nodoc:
+      options[:on] ||= action if [:create, :update, :destroy].include?(action)
+      options
+    end
+
+    def check_validity!(options) # :nodoc:
+      raise ArgumentError, "the track method expects :on to be set" unless [:create, :update, :destroy].include?(options[:on])
+    end
+  end
+end

data/lib/activities/helper.rb

@@ -0,0 +1,14 @@
+module Activities
+  module Helper
+    def render_activity(activity)
+      path = "activities/#{activity.trackable_type.underscore}/#{activity.action}"
+      locals = {
+        :activity => activity,
+        :tracker => activity.tracker,
+        :trackable => activity.trackable,
+        :data => activity.data
+      }
+      render :partial => path, :locals => locals
+    end
+  end
+end

data/lib/activities/version.rb

@@ -0,0 +1,8 @@
+module Activities
+  module Version
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+    STRING = "#{MAJOR}.#{MINOR}.#{PATCH}"
+  end
+end

data/test/activities/active_record_test.rb

@@ -0,0 +1,244 @@
+require "test_helper"
+
+class Activities::ActiveRecordTest < Test::Unit::TestCase
+  def setup
+    %w[User Task Milestone Project].each do |name|
+      Object.send(:remove_const, name) rescue nil
+    end
+    load "resources/models.rb"
+
+    User.delete_all
+    Project.delete_all
+    Task.delete_all
+    Milestone.delete_all
+    Activity.delete_all
+
+    @user = User.create(:login => "johndoe")
+  end
+
+  def test_models_should_respond_to_activities_for
+    assert User.respond_to?(:activities_for)
+  end
+
+  def test_activities_for_expects_an_association
+    assert_raise ArgumentError do
+      User.activities_for
+    end
+  end
+
+  def test_activities_for_expects_a_valid_association
+    assert_raise ArgumentError do
+      User.activities_for :invalid do
+        track :create
+      end
+    end
+  end
+
+  def test_activities_for_expects_a_block
+    assert_raise ArgumentError do
+      User.activities_for :projects
+    end
+  end
+
+  def test_setup_trackable_class
+    User.activities_for(:tasks) do
+      track :create
+      track :update
+      track :destroy
+      track :renamed, :on => :update, :if => :name_changed?
+    end
+
+    expected = {
+      :create => [{:reflection_name => "user", :action => :create}],
+      :update => [
+        {:reflection_name => "user", :action => :update},
+        {:reflection_name => "user", :action => :renamed, :if => :name_changed?}
+      ],
+      :destroy => [{:reflection_name => "user", :action => :destroy}]
+    }
+    assert_equal(expected, Task.activity_trackers)
+  end
+
+  def test_add_multiple_trackers
+    User.activities_for(:tasks) { track :create }
+    Project.activities_for(:tasks) { track :create }
+
+    expected = {
+      :create => [
+        { :reflection_name => "user", :action => :create },
+        { :reflection_name => "project", :action => :create }
+      ]
+    }
+    assert_equal(expected, Task.activity_trackers)
+  end
+
+  def test_add_multiple_activities
+    User.activities_for(:tasks) { track :create }
+    Project.activities_for(:tasks) { track :create }
+
+    @project = Project.create(:user => @user)
+    @task = @project.tasks.create(:user => @user, :name => "New task")
+
+    assert_equal 1, @user.activities.count(:conditions => {:action => "create"})
+    assert_equal 1, @project.activities.count(:conditions => {:action => "create"})
+  end
+
+  def test_store_attributes_for_activity
+    User.activities_for(:tasks) do
+      track :create
+    end
+
+    @task = @user.tasks.create(:name => "New task")
+    @activity = @user.activities.first
+
+    assert_equal @task.attributes.symbolize_keys, @activity.data
+  end
+
+  def test_activity_for_create
+    User.activities_for(:tasks) do
+      track :create
+    end
+
+    @task = @user.tasks.create(:name => "New task")
+    @task.update_attribute :name, "Updated task"
+    @task.destroy
+
+    assert_equal 1, @user.activities.count(:conditions => {:action => "create"})
+    assert_equal 1, @user.activities.count
+  end
+
+  def test_activity_for_destroy
+    User.activities_for(:tasks) do
+      track :destroy
+    end
+
+    @task = @user.tasks.create(:name => "New task")
+    @task.update_attribute :name, "Updated task"
+    @task.destroy
+
+    assert_equal 1, @user.activities.count(:conditions => {:action => "destroy"})
+    assert_equal 1, @user.activities.count
+  end
+
+  def test_activity_for_update
+    User.activities_for(:tasks) do
+      track :update
+    end
+
+    @task = @user.tasks.create(:name => "New task")
+    @task.update_attribute :name, "Updated task"
+    @task.destroy
+
+    assert_equal 1, @user.activities.count(:conditions => {:action => "update"})
+    assert_equal 1, @user.activities.count
+  end
+
+  def test_create_activities_for_all_actions
+    User.activities_for(:tasks) do
+      track :create
+      track :update
+      track :destroy
+    end
+
+    @task = @user.tasks.create(:name => "New task")
+    assert_equal 1, @user.activities.count(:conditions => {:action => "create"})
+
+    @task.update_attribute :name, "Updated task"
+    assert_equal 1, @user.activities.count(:conditions => {:action => "update"})
+
+    @task.destroy
+    assert_equal 1, @user.activities.count(:conditions => {:action => "destroy"})
+
+    assert_equal 3, @user.activities.count
+  end
+
+  def test_create_activity_respecting_the_if_option_using_symbol
+    User.activities_for(:projects) do
+      track :renamed, :on => :update, :if => :name_changed?
+    end
+
+    @project = @user.projects.create(:name => "New project", :status => "opened")
+    @project.update_attribute :name, "Updated project"
+
+    assert_equal 1, @user.activities.count(:conditions => {:action => "renamed"})
+    assert_equal 1, @user.activities.count
+  end
+
+  def test_dont_create_activity_when_if_evaluation_returns_false_symbol
+    User.activities_for(:projects) do
+      track :renamed, :on => :update, :if => :name_changed?
+    end
+
+    @project = @user.projects.create(:name => "New project", :status => "opened")
+    assert_equal 0, Activity.count
+
+    @project.update_attribute :status, "archived"
+    assert_equal 0, Activity.count
+  end
+
+  def test_create_activity_respecting_the_if_option_using_block
+    User.activities_for(:projects) do
+      track :renamed, :on => :update, :if => proc {|r| r.name_changed?}
+    end
+
+    @project = @user.projects.create(:name => "New project", :status => "opened")
+    @project.update_attribute :name, "Updated project"
+
+    assert_equal 1, @user.activities.count(:conditions => {:action => "renamed"})
+    assert_equal 1, @user.activities.count
+  end
+
+  def test_dont_create_activity_when_if_evaluation_returns_false_block
+    User.activities_for(:projects) do
+      track :renamed, :on => :update, :if => proc {|r| r.name_changed?}
+    end
+
+    @project = @user.projects.create(:name => "New project", :status => "opened")
+    assert_equal 0, Activity.count
+
+    @project.update_attribute :status, "archived"
+    assert_equal 0, Activity.count
+  end
+
+  def test_create_activity_respecting_the_unless_option_using_symbol
+    User.activities_for(:projects) do
+      track :renamed, :on => :update, :unless => :status_changed?
+    end
+
+    @project = @user.projects.create(:name => "New project", :status => "opened")
+    @project.update_attribute :name, "Updated project"
+    assert_equal 1, @user.activities.count(:conditions => {:action => "renamed"})
+    assert_equal 1, @user.activities.count
+  end
+
+  def test_create_activity_respecting_the_unless_option_using_block
+    User.activities_for(:projects) do
+      track :renamed, :on => :update, :unless => proc {|r| r.status_changed?}
+    end
+
+    @project = @user.projects.create(:name => "New project", :status => "opened")
+    @project.update_attribute :name, "Updated project"
+    assert_equal 1, @user.activities.count(:conditions => {:action => "renamed"})
+    assert_equal 1, @user.activities.count
+  end
+
+  def test_dont_create_activity_when_unless_evaluation_returns_false_block
+    User.activities_for(:projects) do
+      track :renamed, :on => :update, :unless => proc {|r| r.status_changed?}
+    end
+
+    @project = @user.projects.create(:name => "New project", :status => "opened")
+    @project.update_attributes :status => "archived", :name => "Updated project"
+    assert_equal 0, Activity.count
+  end
+
+  def test_dont_create_activity_when_unless_evaluation_returns_false_symbol
+    User.activities_for(:projects) do
+      track :renamed, :on => :update, :unless => :status_changed?
+    end
+
+    @project = @user.projects.create(:name => "New project", :status => "opened")
+    @project.update_attributes :status => "archived", :name => "Updated project"
+    assert_equal 0, Activity.count
+  end
+end

data/test/resources/models.rb

@@ -0,0 +1,21 @@
+class Task < ActiveRecord::Base
+  belongs_to :user
+  belongs_to :project
+end
+
+class Project < ActiveRecord::Base
+  belongs_to :user
+  has_many :milestones
+  has_many :tasks
+end
+
+class Milestone < ActiveRecord::Base
+  belongs_to :user
+  belongs_to :project
+end
+
+class User < ActiveRecord::Base
+  has_many :milestones
+  has_many :tasks
+  has_many :projects
+end

data/test/schema.rb

@@ -0,0 +1,28 @@
+ActiveRecord::Schema.define(:version => 0) do
+  create_table :users do |t|
+    t.string    :login
+  end
+
+  create_table :tasks do |t|
+    t.string :name
+    t.references :user, :project
+  end
+
+  create_table :milestones do |t|
+    t.string :name
+    t.references :user, :project
+  end
+
+  create_table :projects do |t|
+    t.string :name, :status
+    t.references :user
+  end
+
+  create_table :activities do |t|
+    t.references :tracker, :polymorphic => true, :null => false
+    t.references :trackable, :polymorphic => true, :null => false
+    t.string :action, :null => false
+    t.text :data, :null => true
+    t.timestamps
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,11 @@
+require "rubygems"
+gem "test-unit"
+require "test/unit"
+require "active_record"
+require "mocha"
+
+ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => ":memory:")
+load "schema.rb"
+
+require "activities"
+require "resources/models"

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification 
+name: activities
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Nando Vieira
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-13 00:00:00 -03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: 
+email: fnando.vieira@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- lib/activities.rb
+- lib/activities/active_record.rb
+- lib/activities/active_record/class_methods.rb
+- lib/activities/active_record/instance_methods.rb
+- lib/activities/activity.rb
+- lib/activities/dsl.rb
+- lib/activities/helper.rb
+- lib/activities/version.rb
+- test/activities/active_record_test.rb
+- test/resources/models.rb
+- test/schema.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/fnando/activities
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A framework for aggregating social activity.
+test_files: 
+- test/activities/active_record_test.rb
+- test/resources/models.rb
+- test/schema.rb
+- test/test_helper.rb