lifestreamable 0.0.1 → 0.0.2

data/README.rdoc

@@ -11,11 +11,13 @@ This is a port to a gem of the lifestream libraries that have been designed for
 == FEATURES/PROBLEMS:
 
 TODO:
-add support for pagination.
-add support for delayed jobs.
-port to rails 3.0
-write the tests
-complete the doc on which options are available for lifestreamable and lifestreamed
+* add support for pagination.
+* add support for delayed jobs.
+* add support for memcached
+* port to rails 3.0
+* write the tests
+* complete the doc on which options are available for lifestreamable and lifestreamed
+* make sure that syntax like user.posts << Post.create(...) triggers the observers correctly.
 
 == SYNOPSIS:
 
@@ -27,7 +29,7 @@ for example, a user can write posts and comments, we want to report in the user'
 
 defining the owner class
     class User < ActiveRecord::Base
-        lifestreamed 
+        lifestreamed :order=>'id asc'     # <= overrides the normal order which is 'id desc'
     end
 
 defining the event classes
@@ -57,26 +59,26 @@ defining the event classes
                 }
     end
 
-get the lifestream from the owner
+Whenever a new post is created, it will create a new entry in the lifestream model. To get the lifestream from the owner:
     user=User.first
 
     # get the lifestream for the user
-    lifestream = user.lifestream  #=> returns an array of Lifestreamable::Lifesteam instances
+    lifestream = user.lifestream  #=> returns an array of Lifestreamable::Lifesteam model instances
     
     #get the data that was stored 
     data = lifestream.first.object_data
     
-    
+see the module Lifestreamable for all the details.  
 
 == REQUIREMENTS:
 
+* ActiveRecord
 * YAML
 
 == INSTALL:
 
 * sudo gem install lifestreamable
 
-
 == LICENSE:
 
 (The MIT License)

data/lib/lifestreamable.rb

@@ -1,6 +1,8 @@
 $:.unshift(File.dirname(__FILE__)) unless
 $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
+require 'active_record'
+
 require File.join(File.dirname(__FILE__),'lifestreamable/lifestreamable')
 require File.join(File.dirname(__FILE__),'lifestreamable/lifestreamed')
 

data/lib/lifestreamable/create_observer.rb

@@ -2,7 +2,7 @@ module Lifestreamable
   class CreateObserver < Lifestreamable::Observer
     observe :"lifestreamable/dummy"
     def after_create(model)
-      if model.lifestreamable?
+      if model.lifestreamable?(:create)
         Lifestreamable::Lifestreamer.push model.get_action_instead_of(:create), model.get_payload
       end
     end

data/lib/lifestreamable/destroy_observer.rb

@@ -2,7 +2,7 @@ module Lifestreamable
   class DestroyObserver < Lifestreamable::Observer
     observe :"lifestreamable/dummy"
     def before_destroy(model)
-      if model.lifestreamable?
+      if model.lifestreamable?(:destroy)
         Lifestreamable::Lifestreamer.push model.get_action_instead_of(:destroy), model.get_payload
       end
     end

data/lib/lifestreamable/lifestream.rb

@@ -18,6 +18,7 @@ module Lifestreamable
       #
       def process(action, struct)
         # put explicitly the actions accepted
+        puts "calling process #{action} #{struct.inspect}"
         case action
           when :create
             create get_payload(struct)

data/lib/lifestreamable/lifestreamable.rb

@@ -1,15 +1,85 @@
-# Pour le lifestream, on ajoute une methode a ActiveRecord::Base
-# pour savoir si on doit effacer une entree du lifestream a la
-# place de faire un update.
-# comme dans le cas de detail.youtube_username, si on efface
-# la valeur, on veut effacer l'entree dans le lifestream.
-# Meme chose pour l'insert, si on change le youtube user name,
-# on veut que ca insere une nouvelle rangee dans le lifestream.
+# :title: module Lifestreamable
+# module for models that trigger lifestream events.
+#
+# Usage:
+#   class Post < ActiveRecord::Base
+#     belongs_to :user
+#     lifestreamable :on=>[:create, :update, :destroy], :data=>:get_data, :owner=>:user
+#
+#     def get_data  # we gather the data here, while we have all this data loaded to avoid having to fetch the models when we'll display the lifestream
+#       {:post => {:title => this.title}, :user => {:first_name => self.user.firstname, :last_name => self.user.last_name}}
+#     end
+#   end
+#
+# Options
+# Note, when using Proc for the options, the model that triggers the event is always passed to the Proc.
+# ex. Proc.new {|model| ... }
+# 
+# *  :data => Required,  Proc or function name to call to get the data that needs to be lifestreamed, the data should be in a type that is serializable by YAML (Hash, Array and Struct are good)
+# *  :on => Required, Array of events that trigger the insertion into the lifestream, acceptable values are: :create, :update, :destroy 
+# *  :owner => Required, a String, Symbol, Proc or function name that returns the name of the owner of this event, i.e. the user that triggered the event.
+# *  :type => An identifier that represent the type of lifestream that is generated. this is useful when displaying the lifestream to select the view that will be used to display the lifestream event. Can be a String, Symbol, Proc or function name.
+# *  :when => An identifier that specifies if the event should be logged. Can be true, false, a Proc or a function name. A method receives the action that triggers the event. the Proc receives the model and the event. Useful in combination with the :on=>[:update] option, we will want to update the lifestream if only a specific field is modified, but not the others.
+#         :when=>Proc.new {|model, action| if action == :update ...  }
+#         :when=>:when_function
+#         def when_function(action)
+#           ...
+#         end
+# *  :filter => A STATIC function that will specify how to filter the data at display time, it may be necessary to remove some data when displaying the lifestream, for example 1- Bob is now friend with Bill and 2- Bill is now friend with Bob, we may want to remove one of the two events. A Proc or function name.
+# *  :destroy_instead_of_update => Specifies if the last entry should be destroyed in the lifestream when an :update event is triggered. can be true, false, a Proc or a function name.
+# *  :create_instead_of_update => Specifies if a new entry should be created in the lifestream when an :update event is triggered. can be true, false, a Proc or a function name.
+# *  :create_instead_of_destroy => Specifies if a new entry should be created in the lifestream when a :destroy event is triggered. can be true, false, a Proc or a function name.
+# *  :update_instead_of_destroy => Specifies if a the last entry should be updated in the lifestream when a :destroy event is triggered. can be true, false, a Proc or a function name.
+#
+#
+# Usage with all options
+#   class Post < ActiveRecord::Base
+#     belongs_to :user
+#     lifestreamable :on=>[:create, :update, :destroy], 
+#                    :data => :get_data, 
+#                    :owner => :user,
+#                    :type => 'Post',
+#                    :when => lambda {|model, action|   # when something else than updated_at changes
+#                        if action==:update 
+#                          (model.changed-['updated_at']).size > 0 
+#                        else
+#                          true
+#                        end
+#                      },   
+#                    :filter => :lifestream_filter,
+#                    :destroy_instead_of_update => Proc.new { |model| model.changed.include?('title') },
+#                    :create_instead_of_update => lambda { |model| model.changed.include?('body') },
+#                    :create_instead_of_destroy => false,
+#                    :update_instead_of_destroy => :false  # this is good also, and so is 'false'
+#
+#     def get_data     # => we gather the data here, while we have all this data loaded to avoid having to fetch the models when we'll display the lifestream
+#       {:post => {:title => this.title}, :user => {:first_name => self.user.firstname, :last_name => self.user.last_name}}
+#     end
+#
+#     def self.lifestream_filter(lifestream)     # <= Note this is a static function
+#       #remove all similar events
+#        types={}
+#        lifestream = lifestream.collect do |l|
+#          unless types[l.stream_type]
+#            types[l.stream_type]=true
+#            l
+#          else
+#            nil
+#          end
+#        end
+#        lifestream.compact
+#     end
+#
+#   end
+#
+# WARNING, the insertion into the lifestream is done as an after filter in the controller. when debigging in the console, you may want to generate the lifestream, in this case, call Lifestreamable::Lifestreamer.generate_lifestream
 
 module Lifestreamable
   Struct.new('LifestreamData', :reference_type, :reference_id, :owner_type, :owner_id, :stream_type, :object_data_hash)
   TRUE_REGEX = /^[tT][rR][uU][eE]$/
   FALSE_REGEX =  /^[fF][aA][lL][sS][eE]$/
+  ACCEPTABLE_OPTIONS = [:data, :on, :owner, :type, :when, :filter, :destroy_instead_of_update, :create_instead_of_update, :create_instead_of_destroy, :update_instead_of_destroy]
+  REQUIRED_OPTIONS = [:data, :on, :owner]
   
   def self.included(base)
     base.extend LifestreamableClassMethods
@@ -24,9 +94,19 @@ module Lifestreamable
     
     def lifestreamable(options)
       include LifestreamableInstanceMethods
-
       options.to_options
-      options[:on].each do |option_on|
+
+      unknown_keys = options.keys - ACCEPTABLE_OPTIONS
+      unless unknown_keys.blank?
+        raise LifestreamableException.new("Unknown keys for lifestreamable #{unknown_keys.inspect}") 
+      end
+
+      required_keys = REQUIRED_OPTIONS - options.keys
+      unless required_keys.blank?
+        raise LifestreamableException.new("Some requires option for lifestreamable are missing #{required_keys.inspect}") 
+      end
+
+      options[:on].to_a.each do |option_on|
         case option_on
           when :update
             Lifestreamable::UpdateObserver.instance.add_class_observer self.class_name.constantize
@@ -35,16 +115,14 @@ module Lifestreamable
           when :destroy
             Lifestreamable::DestroyObserver.instance.add_class_observer self.class_name.constantize
           else
-            raise Exception.new("option \"#{option_on}\" is not supported for Lifestreamable")
+            raise LifestreamableException.new("option \"#{option_on}\" is not supported for Lifestreamable")
         end
       end
-      @@lifestream_options = {:data=>options[:data], :on=>options[:on], :type=>options[:type], :owner=>options[:owner], :when=>options[:when], :filter=>options[:filter],
-        :destroy_instead_of_update=>options[:destroy_instead_of_update], :create_instead_of_update=>options[:create_instead_of_update],
-        :create_instead_of_destroy=>options[:create_instead_of_destroy], :update_instead_of_destroy=>options[:update_instead_of_destroy]}
+      ACCEPTABLE_OPTIONS.each {|k| @@lifestream_options[k]=options[k] } 
+
     end
     
     def filter(lifestream)
-      puts "in lifestreamable.filter"
       option = self.lifestream_options[:filter]
       lifestream = case option
         when Proc
@@ -64,16 +142,16 @@ module Lifestreamable
       self.class.lifestream_options
     end
 
-    def lifestreamable?
+    def lifestreamable?(action)
       case self.lifestream_options[:when]
         when NilClass, TrueClass, :true, TRUE_REGEX
           true
         when FalseClass, :false, FALSE_REGEX
           false
         when Proc
-          self.lifestream_options[:when].call(self)
+          self.lifestream_options[:when].call(self, action)
         when String, Symbol
-          send(self.lifestream_options[:when].to_s)
+          send(self.lifestream_options[:when].to_s, action)
       end 
     end
     
@@ -188,7 +266,11 @@ private
   end
 end
 
+class LifestreamableException < Exception
+end
+
 ActiveRecord::Base.observers << :"lifestreamable/update_observer"
 ActiveRecord::Base.observers << :"lifestreamable/create_observer"
 ActiveRecord::Base.observers << :"lifestreamable/destroy_observer"
-ActiveRecord::Base.send(:include, Lifestreamable)
+ActiveRecord::Base.send(:include, Lifestreamable)
+

data/lib/lifestreamable/lifestreamed.rb

@@ -47,7 +47,6 @@ module Lifestreamable
       end
 
       def get_filter_option(option)
-        puts "getting filter option"
         case option
           when NilClass, FalseClass, :false, Lifestreamable::FALSE_REGEX
             false

data/lib/lifestreamable/lifestreamer.rb

@@ -1,4 +1,10 @@
 module Lifestreamable
+  # :title: module Lifestreamable::Lifestreamer
+  # Module that generates the lifestream. this is done as an after_filter that is added to ActionController::Base.
+  # Hence any action that is called in the controller will call this function afterwards. 
+  # The Lifestreamable::Lifestreamer.generate_lifestream has a very small footprint when it has nothign to do. 
+  #
+  # TODO, include support for delayed_jobs to do it asynchronously
   module Lifestreamer
     @@stack=[]
     def self.push(action, lifestream_struct)

data/lib/lifestreamable/observer.rb

@@ -15,6 +15,3 @@ module Lifestreamable
   end
   
 end
-
-class LifestreamableException < Exception 
-end

data/lib/lifestreamable/update_observer.rb

@@ -2,7 +2,7 @@ module Lifestreamable
   class UpdateObserver < Lifestreamable::Observer
     observe :"lifestreamable/dummy"
     def after_update(model)
-      if model.lifestreamable?
+      if model.lifestreamable?(:update)
         Lifestreamable::Lifestreamer.push model.get_action_instead_of(:update), model.get_payload
       end
     end

data/lifestreamable.gemspec

@@ -2,12 +2,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{lifestreamable}
-  s.version = "0.0.1"
+  s.version = "0.0.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Benoit Goyette"]
-  s.date = %q{2010-05-19}
-  s.description = %q{library to perform social network like lifetstream functions, this is the code used on the social network http://legrandclub.rds.ca}
+  s.date = %q{2010-08-04}
+  s.description = %q{library to perform social network like lifestream functions, this is the code used on the social network http://legrandclub.rds.ca}
   s.email = %q{benoit.goyette@gmail.com}
   s.files = ["History.txt",
     "Manifest.txt",

data/script/console

@@ -6,5 +6,4 @@ libs =  " -r irb/completion"
 # Perhaps use a console_lib to store any extra methods I may want available in the cosole
 # libs << " -r #{File.dirname(__FILE__) + '/../lib/console_lib/console_logger.rb'}"
 libs <<  " -r #{File.dirname(__FILE__) + '/../lib/lifestreamable.rb'}"
-puts "Loading lifestreamable gem"
 exec "#{irb} #{libs} --simple-prompt"

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Benoit Goyette
@@ -14,11 +14,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-19 00:00:00 -04:00
+date: 2010-08-04 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
-description: library to perform social network like lifetstream functions, this is the code used on the social network http://legrandclub.rds.ca
+description: library to perform social network like lifestream functions, this is the code used on the social network http://legrandclub.rds.ca
 email: benoit.goyette@gmail.com
 executables: []