acts_as_feedable 1.0.0

data/README.rdoc

@@ -0,0 +1,56 @@
+This +acts_as+ extension allows objects to create feeds which describe them. 
+These feeds can then be used in a "Facebook-style" News Feed.
+
+example:
+
+  class ItemUserTag < ActiveRecord::Base
+    acts_as_feedable :feed_name => 'Tag'
+  end
+
+Feeds are created using the _with_feed wrappers around the save methods.
+
+example:
+
+  annotation = Annotation.new
+  annotation.save_with_feed(current_user)
+
+OR
+
+  annotation = annotation.find(params[:id])
+  annotation.update_attributes_with_feed(params[:annotation])
+
+== Delegated Feeds
+
+Sometimes a object that is created isn't the focus of the feed that represents it's creation. A
+good example is a membership. When a membership is created we don't care about the membership itself
+but about the user. When a membership is destroyed, we still want to reference the user in the feed about its creation.
+This is solved by using the :delegate option to instead create a 'joined' feed with a User feedable in place of a 'created'
+feed with a Membership feedable.
+
+== Aggregate Feeds
+
+Some things happen too frequently to list every occurance. Adding 50 items to a project shouldn't generate 50 feeds.
+Passing :aggregate => true will instead create a single feed per person per day which counts the number of feedables created, updated, and destroyed.
+Each feedable creation will also generate an aggregated_component, a link to the object which is aggregated into the feed. This allows feeds
+to show each individual object which was added or destroyed upon request.
+
+== Deleting a Feedable
+
+When a feedable is deleted, one of three things happen: 
+* If the feedable is being aggregated, we can add an aggregated component which represents the destruction of the feedable.
+
+If the feedable is not being aggregated, there are two options:
+* We simply delete all related feeds to avoid problems that would occur because feed permissions are proxies of the destroyed object.
+* If the +keep_feeds_when_destroyed+ flag is set, we can add a destruction feed and inherit permissions from the feed's scoping object instead.
+
+== Assumptions
+
+* The acts_as_permissable plugin is being used by the application.
+* Feedables being aggregated all have the same permissions.
+* Feedables being aggregated are all public or permissable_proxies of the object they reference
+
+== License
+
+ActsAsFeeable is released under the MIT license:
+
+* http://www.opensource.org/licenses/MIT

data/app/models/feed.rb

@@ -0,0 +1,20 @@
+class Feed < ActiveRecord::Base
+  belongs_to :initiator, :class_name => 'User'
+  
+  belongs_to :feedable, :polymorphic => true
+  belongs_to :scoping_object, :polymorphic => true
+  
+  has_many :feed_aggregated_components, :dependent => :destroy, :order => 'feed_aggregated_components.updated_at DESC'
+  
+  default_scope order('feeds.updated_at DESC')
+
+  # Used to group feeds by the day they occurred
+  def date
+    updated_at.to_date.to_formatted_s(:long_ordinal)
+  end
+
+  # Is this an aggregate feed
+  def aggregate?
+    added_count > 0 || updated_count > 0 || removed_count > 0
+  end
+end

data/app/models/feed_aggregated_component.rb

@@ -0,0 +1,32 @@
+class FeedAggregatedComponent < ActiveRecord::Base
+  belongs_to :feed
+  belongs_to :reference, :polymorphic => true
+  belongs_to :secondary_reference, :polymorphic => true
+
+  def self.created_today(feed, reference, secondary_reference = nil)
+    time_scope('created', Date.today, feed, reference, secondary_reference)
+  end
+  
+  def self.created_recently(feed, reference, secondary_reference = nil)
+    time_scope('created', Time.now - 5.minutes, feed, reference, secondary_reference)
+  end
+
+  def self.updated_today(feed, reference, secondary_reference = nil)
+    time_scope('updated', Date.today, feed, reference, secondary_reference)
+  end
+
+  def self.destroyed_today(feed, reference, secondary_reference = nil)
+    time_scope('destroyed', Date.today, feed, reference, secondary_reference)
+  end
+  
+  def self.time_scope(action, time, feed, reference, secondary_reference)
+    scope = where(:action => action, :feed_id => feed.id, :reference_type => reference.class.to_s, :reference_id => reference.id)
+    scope = scope.where("created_at > ?", time)
+    
+    if secondary_reference.present?
+      scope = scope.where(:secondary_reference_type => secondary_reference.class.to_s, :secondary_reference_id => secondary_reference.id)
+    end
+    
+    return scope.first
+  end
+end

data/lib/acts_as_feedable.rb

@@ -0,0 +1,18 @@
+require 'feedable/acts_as_feedable'
+
+module ActsAsFeedable
+  class Engine < Rails::Engine
+    initializer "acts_as_feedable.init" do
+      ActiveRecord::Base.send :extend, Feedable::ActsAsFeedable::ActMethod
+    end
+
+    config.to_prepare do
+      if defined?(ActsAsJoinable::Engine)
+        require 'feedable/joinable_extensions'
+        JoinableExtensions.add
+      else
+        puts "[ActsAsFeedable] ActsAsJoinable not loaded. Skipping extensions."
+      end
+    end
+  end
+end

data/lib/feedable/acts_as_feedable.rb

@@ -0,0 +1,376 @@
+module Feedable #:nodoc:
+  module ActsAsFeedable #:nodoc:
+    module ActMethod
+      # Configuration options are:
+      #
+      # * +keep_feeds_when_destroyed+ - specifies whether to keep the feeds when a feedable is destroyed. This should only be done if the feedable is public or is scoped to another feedable.
+      # * +target_name+ - specifies how to get the name of the target (used by the view to store the name of the primary object the feed links to). (default is nil)
+      # * +scoping_object?+ - Boolean - If true, this object will become the scoping object for all feedables descending from it. eg. a Project is a scoping object for all discussions, comments, and writeboards within the project.
+      # * +parent+ - Specifies the code to execute to traverse up the feedable chain in search of any scoping objects
+      #
+      # === Delegate Options
+      #
+      # * +actions+ - overrides the :created, :updated, and :destroyed actions with custom actions (must be set if the +delegate+ option is used)
+      # * +references+ - provides feeds with a surrogate feedable when the object itself isn't the focus of the feed. (must be set if the +delegate+ option is used)
+      #
+      # === Aggregate Options
+      #
+      # * +action+ - specifies the action group the aggregate feed should belong to (must be set if the +aggregate+ option is used)
+      # * +references+ - provides aggregate feeds with a feedable by which to group this object's feeds. (must be set if the +aggregate+ option is used)
+      # * +component_reference+ - specifies the object that is referenced by the aggregated feed component. This needs to be the object that the feed "happens to" (e.g. a label is applied to an item). We use this when determining how to handle subsequent update and destroy actions. (aggregated feed components are used to store each action that is referenced by an aggregate feed) (default is self)
+      # * +component_secondary_reference+ - specifies an optional secondary object that is referenced by an aggregated feed component. For example, the item that a label is being applied to (default is nil)
+      # * +component_reference_name+ - specifies how to get the name of the reference (used when a component is destroyed). (default is component_reference.name)
+      # * +component_secondary_reference_name+ - specifies how to get the name of the secondary_reference (used when the secondary_reference is destroyed). (default is component_secondary_reference.name)
+      def acts_as_feedable(options = {})
+        extend ClassMethods unless (class << self; included_modules; end).include?(ClassMethods)
+        include InstanceMethods unless included_modules.include?(InstanceMethods)
+        
+        # Sanity Check
+        options.assert_valid_keys(:scoping_object?, :parent, :keep_feeds_when_destroyed, :target_name, :delegate, :aggregate)
+        
+        raise 'target_name option must be set if the keep_feeds_when_destroyed option is used' if options.key?(:keep_feeds_when_destroyed) && !options.key?(:target_name)
+        
+        options[:delegate].assert_valid_keys(:actions, :references) if options[:delegate].present?
+        raise 'actions option must be set if the delegate option is used' if options[:delegate].is_a?(Hash) && options[:delegate][:actions].blank?
+        raise 'references option must be set if the delegate option is used' if options[:delegate].is_a?(Hash) && options[:delegate][:references].blank?
+        
+        options[:aggregate].assert_valid_keys(:action, :references, :component_reference, :component_secondary_reference, :component_reference_name, :component_secondary_reference_name) if options[:aggregate].present?
+        raise 'action option must be set if the aggregate option is used' if options[:aggregate].is_a?(Hash) && options[:aggregate][:action].blank?
+        raise 'references option must be set if the aggregate option is used' if options[:aggregate].is_a?(Hash) && options[:aggregate][:references].blank?
+        
+        options.reverse_merge!(:keep_feeds_when_destroyed => false, :delegate => {}, :aggregate => {})
+        
+        self.feed_options = options
+        
+        class_eval <<-EOV
+        
+          def keep_feeds_when_destroyed?
+            #{options[:keep_feeds_when_destroyed]}
+          end
+          
+          def feedable
+            if delegating?
+              #{options[:delegate][:references]}
+            elsif aggregating?
+              #{options[:aggregate][:references]}
+            else
+              self
+            end
+          end
+          
+          def target_name
+            #{options[:target_name] || 'nil'}
+          end
+
+          def parent_feedable
+            #{options[:parent] || 'nil'}
+          end
+          
+          # Aggregate Feed Methods
+          
+          def component_reference
+            #{options[:aggregate][:component_reference] || 'self'}
+          end
+          
+          def component_reference_name
+            #{options[:aggregate][:component_reference_name] || 'component_reference.name'}
+          end
+          
+          def component_secondary_reference
+            #{options[:aggregate][:component_secondary_reference] || 'nil'}
+          end
+          
+          def component_secondary_reference_name
+            #{options[:aggregate][:component_secondary_reference_name] || 'component_secondary_reference.try(:name)'}
+          end
+          # END Aggregate Feed Methods
+        EOV
+        
+      end
+    end
+    
+    module ClassMethods
+      def self.extended(base)
+        base.after_create :add_created_feed
+        base.after_update :add_updated_feed
+        base.before_destroy :setup_destroyed_feed_if_keeping_feeds
+        base.after_destroy :add_destroyed_feed, :destroy_scoped_feeds
+        
+        base.cattr_accessor :feed_options
+        base.has_many :feeds, :as => :feedable
+      end
+      
+      def create_with_feed(user, *args)
+        options = args.extract_options!
+        options.merge!(:feed_initiator_id => user.id)
+        return create(options)
+      end      
+    end
+    
+    module InstanceMethods
+      attr_accessor :feed_initiator_id
+
+      def acts_like_feedable?
+        true
+      end
+
+      # Returns the scoping object for this object
+      def scoping_object
+        scoping_ancestor || parent_feedable
+      end
+      
+      # Returns true if this object is a scoping object
+      def scoping_object?
+        self.feed_options[:scoping_object?] == true
+      end
+            
+      def delegating?
+        self.feed_options[:delegate][:actions].present? && self.feed_options[:delegate][:references].present?
+      end
+      
+      def delegate_action_for(action)
+        self.feed_options[:delegate][:actions][action.to_sym] || action.to_s
+      end
+      
+      def aggregating?
+        self.feed_options[:aggregate][:action].present? && self.feed_options[:aggregate][:references].present?
+      end
+      
+      def aggregate_action
+        self.feed_options[:aggregate][:action]
+      end
+      # ActiveRecord Wrappers with initiators
+              
+      def save_with_feed(user, *args)
+        self.feed_initiator_id = user.id
+        return save(*args)
+      end
+      
+      def save_with_feed!(user, *args)
+        self.feed_initiator_id = user.id
+        return save!(*args)
+      end
+      
+      def update_attributes_with_feed(user, *args)
+        self.feed_initiator_id = user.id
+        return update_attributes(*args)
+      end
+      
+      def update_attributes_with_feed!(user, *args)
+        self.feed_initiator_id = user.id
+        return update_attributes(*args)
+      end
+      
+      def destroy_with_feed(user, *args)
+        self.feed_initiator_id = user.id
+        return destroy(*args)
+      end
+      
+      def with_feed(user)
+        self.feed_initiator_id = user.id
+        return self
+      end
+      
+      # END ActiveRecord Wrappers with initiators
+    
+      # Adds a custom feed for this object with the given +action+ and +initiator+
+      def add_custom_feed(action, initiator, options = {})          
+        feed = Feed.new(:initiator => initiator, :action => action, :scoping_object => scoping_object, :feedable => self, :target_name => target_name)
+
+        feed.initial_instance_level_permission_map = options[:map] if options[:map]
+        
+        feed.save!
+      end
+      
+      private
+
+      # Searches up the chain of parent_feedables until it hits a scoping object and returns it
+      # If none is found, returns nil
+      def scoping_ancestor
+        if parent_feedable && parent_feedable.acts_like?(:feedable)
+          if parent_feedable.scoping_object?
+            parent_feedable
+          else
+            parent_feedable.send(:scoping_ancestor)
+          end
+        end                
+      end
+                  
+      # Creates a feed about the creation of the feedable  
+      def add_created_feed
+        return unless feed_initiator_id
+        
+        if aggregating?
+          update_aggregate_feed(:added)
+        elsif delegating?
+          create_feed_with_defaults(:action => delegate_action_for('created'))
+        else
+          create_feed_with_defaults(:action => 'created')
+        end
+        clear_initiator
+      end
+      
+      # Creates a feed about the update of the feedable  
+      def add_updated_feed
+        return unless feed_initiator_id
+                  
+        if aggregating?
+          update_aggregate_feed(:updated)
+        elsif delegating?
+          create_feed_with_defaults(:action => delegate_action_for('updated'))
+        else
+          create_feed_with_defaults(:action => 'updated')
+        end
+        clear_initiator
+      end
+      
+      # Creates a feed about the deletion of the feedable. 
+      # If the feed isn't aggregated then it deletes all existing feeds related to that object.
+      def add_destroyed_feed                  
+        if aggregating?
+          update_aggregate_feed(:removed) if feed_initiator_id
+        elsif delegating?
+          create_feed_with_defaults(:action => delegate_action_for('destroyed')) if feed_initiator_id
+        elsif !keep_feeds_when_destroyed?
+          Feed.destroy_all(:feedable_type => self.class.to_s, :feedable_id => id)
+        end
+        clear_initiator
+      end
+      
+      # Create the destroyed feed before the feedable is destroyed so it gets the correct permission mappings
+      def setup_destroyed_feed_if_keeping_feeds
+        if keep_feeds_when_destroyed? && feed_initiator_id  
+          create_feed_with_defaults(:action => 'destroyed')
+        end
+      end
+      
+      # Destroy all feeds which are scoped to the feedable.
+      # This will prevent feeds from not rendering because the feedable has been destroyed.
+      def destroy_scoped_feeds
+        unless aggregating?
+          Feed.destroy_all(:scoping_object_type => self.class.to_s, :scoping_object_id => id)
+        end
+      end
+      
+      def create_feed_with_defaults(options)
+        Feed.create(options.merge(:initiator_id => feed_initiator_id, :scoping_object => scoping_object, :feedable => feedable, :target_name => target_name))
+      end
+      
+      # Called when the feedable generates aggregate feeds.
+      #
+      # Increments one of the counts depending on whether the feedable is created or destroyed
+      # and creates an FeedAggregatedComponent to represent the feedable.
+      #
+      # eg. When a label is created update the count in the project_label_created feed and create a FeedAggregatedComponent which
+      # points to the label.
+      def update_aggregate_feed(direction)
+        feed = find_existing_aggregate_feed || create_aggregate_feed
+      
+        if direction.eql?(:added)
+          aggregated_component_addition(feed)
+        elsif direction.eql?(:updated)
+          aggregated_component_update(feed)
+        else
+          aggregated_component_removal(feed)
+        end
+      end
+
+      def aggregated_component_addition(feed)
+        # If the aggregated component was already removed today, just remove the destroyed
+        # components to zero out the feed.
+        #
+        # Else add a created FeedAggregatedComponent instead
+        if remove_todays_destroyed_feed(feed, component_reference)
+          # Get rid of the feed completely if there are no more FeedAggregatedComponents
+          feed.destroy if feed.added_count == 0 && feed.updated_count == 0 && feed.removed_count == 0
+        else          
+          feed.increment!(:added_count)
+          create_component(feed, 'created')
+        end
+      end
+
+      def aggregated_component_update(feed)
+        # Only add an 'updated' FeedAggregatedComponent if a matching FeedAggregatedComponent wasn't created lately or updated today.
+        unless FeedAggregatedComponent.created_recently(feed, component_reference, component_secondary_reference) || FeedAggregatedComponent.updated_today(feed, component_reference, component_secondary_reference)
+          feed.increment!(:updated_count)
+          create_component(feed, 'updated')
+        end
+      end
+
+      def aggregated_component_removal(feed)
+        # If the aggregated component was already created today, just remove the created
+        # and updated components to zero out the feed.
+        #
+        # Else get rid of any updated FeedAggregatedComponents from today and add a destroyed
+        # FeedAggregatedComponent instead
+        remove_todays_updated_feed(feed, component_reference)
+        if remove_todays_created_feed(feed, component_reference)
+          # Get rid of the feed completely if there are no more FeedAggregatedComponents
+          feed.destroy if feed.added_count == 0 && feed.updated_count == 0 && feed.removed_count == 0
+        else
+          feed.increment!(:removed_count)
+          create_component(feed, 'destroyed')
+        end
+      end
+
+      # Remove a 'created' FeedAggregatedComponent that was created today for the provided
+      # *component_reference* and return true if it was removed
+      def remove_todays_created_feed(feed, component_reference)
+        if feedable_aggregated_component = FeedAggregatedComponent.created_today(feed, component_reference, component_secondary_reference)
+          feed.decrement!(:added_count)
+          feedable_aggregated_component.destroy
+          
+          return true
+        end
+      end
+
+      # Remove an 'updated' FeedAggregatedComponent that was created today for the provided
+      # *component_reference* and return true if it was removed
+      def remove_todays_updated_feed(feed, component_reference)
+        if feedable_aggregated_component = FeedAggregatedComponent.updated_today(feed, component_reference, component_secondary_reference)
+          feed.decrement!(:updated_count)
+          feedable_aggregated_component.destroy
+
+          return true
+        end
+      end
+
+      # Remove a 'destroyed' FeedAggregatedComponent that was created today for the provided
+      # *component_reference* and return true if it was removed
+      def remove_todays_destroyed_feed(feed, component_reference)
+        if feedable_aggregated_component = FeedAggregatedComponent.destroyed_today(feed, component_reference, component_secondary_reference)
+          feed.decrement!(:removed_count)
+          feedable_aggregated_component.destroy
+
+          return true
+        end
+      end
+      
+      # Find an existing aggregate feed which was created on *date*
+      def find_existing_aggregate_feed(date = Date.today)
+        Feed.where("initiator_id = ? AND feedable_type = ? AND feedable_id = ? AND action = ? AND created_at > ? AND created_at < ?", feed_initiator_id, feedable.class.to_s, feedable.id, aggregate_action, date, date + 1.day).first
+      end
+      
+      def create_aggregate_feed
+        aggregate_feed = Feed.new(:initiator_id => feed_initiator_id, :scoping_object => scoping_object, :feedable => feedable, :target_name => target_name, :action => aggregate_action)
+
+        # Change permission mapping to respect permissions of object being aggregated.
+        aggregate_feed.view_permission = self.view_permission if acts_like?(:joinable_component)
+      
+        aggregate_feed.save!
+      
+        return aggregate_feed
+      end
+      
+      # Creates a component to reflect the *action* of the feedable.
+      def create_component(feed, action)
+        FeedAggregatedComponent.create(:action => action, :feed => feed, :reference => component_reference, :reference_name => component_reference_name, :secondary_reference => component_secondary_reference, :secondary_reference_name => component_secondary_reference_name)
+      end
+
+      # Clears the initiator id from the feedable
+      def clear_initiator
+        self.feed_initiator_id = nil
+      end
+    end
+  end
+end

data/lib/feedable/joinable_extensions.rb

@@ -0,0 +1,80 @@
+module Joinable::ActsAsJoinable::ClassMethods
+  class << self
+    alias_method :extended_without_feedable, :extended
+
+    def extended(base)
+      extended_without_feedable(base)
+      base.before_validation :dont_create_membership_invitation_feeds, :on => :create
+    end
+  end
+end
+
+module Joinable::ActsAsJoinable::InstanceMethods
+  # Don't create feeds for membership invitations when the joinable itself is being created
+  def dont_create_membership_invitation_feeds
+    membership_invitations.each { |invitation| invitation.no_default_feed = true }
+  end
+end
+
+module JoinableExtensions
+  def self.add
+    extend_membership
+    extend_membership_invitation
+    extend_membership_request
+  end
+
+  def self.extend_membership
+    Membership.class_eval do
+      acts_as_feedable :parent => 'joinable', :delegate => {:references => 'user', :actions => {:created => 'joined', :destroyed => 'left'}}
+
+      private
+
+      before_destroy :ensure_feed_creation
+
+      def ensure_feed_creation
+        with_feed(initiator) if initiator.present?
+      end
+    end
+  end
+
+  def self.extend_membership_invitation
+    MembershipInvitation.class_eval do
+      acts_as_feedable :parent => 'joinable', :delegate => {:references => 'user', :actions => {:created => 'invited', :destroyed => 'cancelled_invite'}}
+
+      attr_accessor :no_default_feed
+
+      private
+
+      def create_associated_membership_on_accept(current_user)
+        self.no_default_feed = true # Default feed has incorrect initiator. We're about to create a feed with the correct initiator.
+        Membership.create_with_feed(user, :joinable => joinable, :user => user, :permissions => permissions)
+      end
+      
+      def destroy_self_on_decline(current_user)
+        self.no_default_feed = true # Default feed has incorrect initiator. We're about to create a feed with the correct initiator.
+        destroy_with_feed(user)
+      end
+
+      before_create :ensure_feed_creation
+      before_destroy :ensure_feed_creation
+
+      # Don't create a destroyed feed if the user is accepting a membership invitation or a membership request exists for this User.
+      # In that case, a membership was created, and this invitation should be 'invisible' to the Users and the UI. Thus no feeds should be created.
+      def ensure_feed_creation
+        with_feed(initiator) unless no_default_feed || joinable.membership_for?(user) || joinable.membership_request_for?(user)
+      end
+    end
+  end
+
+  def self.extend_membership_request
+    MembershipRequest.class_eval do
+      acts_as_feedable :parent => 'joinable', :delegate => {:references => 'user', :actions => {:created => 'requested', :destroyed => 'cancelled_request'}}
+      
+      private
+
+      def create_associated_membership_on_grant(current_user, permissions)
+        Membership.create_with_feed(current_user, :joinable => joinable, :user => user, :permissions => permissions)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: acts_as_feedable
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Ryan Wallace
+- Nicholas Jakobsen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-30 00:00:00.000000000 Z
+dependencies: []
+description: Allows objects to create feeds which describe them. These feeds can then
+  be used in a "Facebook-style" News Feed.
+email: technical@rrnpilot.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- app/models/feed.rb
+- app/models/feed_aggregated_component.rb
+- lib/acts_as_feedable.rb
+- lib/feedable/acts_as_feedable.rb
+- lib/feedable/joinable_extensions.rb
+- README.rdoc
+homepage: http://github.com/rrn/acts_as_feedable
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Allows objects to create feeds which describe them
+test_files: []