acts_as_readable 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 44f09001b617edaeaaeb303302ff7806c787574e
+  data.tar.gz: aed97cd3809d30621c534da9f3cbe31c40f92336
+SHA512:
+  metadata.gz: ca634e25c362eb653545e2ba6b2213ec636bd038946609e7de37331d67372addbe03c8261df81c88c979c9d17c50439d526b611fea61c739e7d222c95d14d8ca
+  data.tar.gz: b5ae7f2ad8c44ab52b340613efa8bd1c3d1fe9635e71b491e9c4904e6e2a59629ffb689f3caf2f821d0d6a30dad278264635335c81b2a4f9e880ad557d683892

data/README.rdoc

@@ -0,0 +1,35 @@
+== ActsAsReadable
+
+ActsAsReadable allows you to create a generic relationship of items which can
+be marked as 'read' by users. This is useful for forums or any other kind of
+situation where you might need to know whether or not a user has seen a particular
+model.
+
+=== Installation
+
+TODO...
+
+=== Example
+
+	class Post < ActiveRecord::Base
+	  acts_as_readable
+	end
+
+	bob = User.find_by_name("bob")
+
+	bob.readings                      # => []
+
+	Post.unread_by(bob)               # => [<Post 1>,<Post 2>,<Post 3>...]
+	Post.read_by(bob)                 # => []
+
+	Post.find(1).read_by?(bob)        # => false
+	Post.find(1).read_by!(bob)        # => <Reading 1>
+	Post.find(1).read_by?(bob)        # => true
+	Post.find(1).readers              # => [<User bob>]
+
+	Post.unread_by(bob)               # => [<Post 2>,<Post 3>...]
+	Post.read_by(bob)                 # => [<Post 1>]
+
+	bob.readings                      # => [<Reading 1>]
+
+Copyright (c) 2012 Culture Code Software Consulting. Released under the MIT license

data/generators/acts_as_readable_migration/acts_as_readable_migration_generator.rb

@@ -0,0 +1,11 @@
+class ActsAsReadableMigrationGenerator < Rails::Generator::Base 
+  def manifest 
+    record do |m| 
+      m.migration_template 'migration.rb', 'db/migrate' 
+    end 
+  end
+  
+  def file_name
+    "acts_as_readable_migration"
+  end
+end

data/generators/acts_as_readable_migration/templates/migration.rb

@@ -0,0 +1,17 @@
+class ActsAsReadableMigration < ActiveRecord::Migration
+  def self.up
+    create_table :readings do |t|
+      t.string :readable_type
+      t.integer :readable_id
+      t.integer :user_id
+      t.string :state, :null => false, :default => :read
+      t.timestamps
+    end
+    
+    add_index :readings, [:readable_id, :readable_type, :user_id], :unique => true
+  end
+  
+  def self.down
+    drop_table :readings
+  end
+end

data/lib/acts_as_readable.rb

@@ -0,0 +1,4 @@
+require 'acts_as_readable/acts_as_readable'
+require 'acts_as_readable/reading'
+
+ActiveRecord::Base.send :extend, ActsAsReadable::ActMethod

data/lib/acts_as_readable/acts_as_readable.rb

@@ -0,0 +1,124 @@
+module ActsAsReadable
+  module ActMethod  
+    # OPTIONS
+    # :cache  => the name under which to cache timestamps for a "mark all as read" action to avoid the need to actually create readings for each record marked as read
+    def acts_as_readable(options = {})
+      class_attribute :acts_as_readable_options
+      self.acts_as_readable_options = options
+
+      has_many :readings, :as => :readable
+      has_many :readers, :through => :readings, :source => :user, :conditions => {:readings => {:state => 'read'}}
+
+      scope :read_by, lambda {|user| ActsAsReadable::HelperMethods.outer_join_readings(self, user).where(ActsAsReadable::HelperMethods.read_conditions(self, user))}
+      scope :unread_by, lambda {|user| ActsAsReadable::HelperMethods.outer_join_readings(self, user).where(ActsAsReadable::HelperMethods.unread_conditions(self, user))}
+
+      extend ActsAsReadable::ClassMethods
+      include ActsAsReadable::InstanceMethods
+    end
+  end
+
+  module HelperMethods
+    def self.read_conditions(readable_class, user)
+      ["(readable_type IS NULL AND COALESCE(#{readable_class.table_name}.updated_at < ?, TRUE)) OR (readable_type IS NOT NULL AND COALESCE(readings.updated_at < ?, TRUE)) OR (readings.state = 'read')", all_read_at(readable_class, user), all_read_at(readable_class, user)]
+    end
+
+    def self.unread_conditions(readable_class, user)
+      # IF there is no reading and it has been updated since we last read all OR there is an unreading and we haven't read all since then
+      ["(readable_type IS NULL AND COALESCE(#{readable_class.table_name}.updated_at > ?, TRUE)) OR (readings.state = 'unread' AND COALESCE(readings.updated_at > ?, TRUE))", all_read_at(readable_class, user), all_read_at(readable_class, user)]
+    end
+
+    def self.all_read_at(readable_class, user)
+      user[readable_class.acts_as_readable_options[:cache]] if readable_class.acts_as_readable_options[:cache]
+    end
+
+    def self.outer_join_readings(readable_class, user)
+      Reading.joins("LEFT OUTER JOIN readings ON readings.readable_type = '#{readable_class.name}' AND readings.readable_id = #{readable_class.table_name}.id AND readings.user_id = #{user.id}")
+    end        
+  end
+
+  module ClassMethods
+    # Find all the readings of the readables by the user in a single SQL query and cache them in the readables for use in the view.
+    def cache_readings_for(readables, user)
+      readings = []
+      Reading.where(:readable_type => name, :readable_id => readables.collect(&:id), :user_id => user.id).each do |reading|
+        readings[reading.readable_id] = reading
+      end
+
+      for readable in readables
+        readable.cached_reading = readings[readable.id] || false
+      end
+
+      return readables
+    end
+
+    # Mark all records as read by the user
+    # If a :cache option has been set in acts_as_readable, a timestamp will be updated on the user instead of creating individual readings for each record
+    def read_by!(user)
+      if user.has_attribute?(acts_as_readable_options[:cache])
+        Reading.delete_all(:user_id => user.id, :readable_type => name)
+        user.update_column(acts_as_readable_options[:cache], Time.now)
+      else
+        unread_by(user).find_each do |record|
+          record.read_by!(user)
+        end
+      end
+    end
+  end
+
+  module InstanceMethods
+    attr_accessor :cached_reading
+
+    def acts_like_readable?
+      true
+    end
+
+    def read_by!(user)
+      # Find an existing reading and update the record so we can know when the thing was first read, and the last time we read it
+      reading = Reading.find_or_initialize_by_user_id_and_readable_id_and_readable_type(user.id, self.id, self.class.name)
+      reading.updated_at = Time.now # Explicitly set the read time to now in order to force a save in case we haven't changed anything else about the reading
+      reading.state = :read
+      reading.save!
+    rescue ActiveRecord::RecordNotUnique
+      # Database-level uniqueness constraint failed.
+      return self
+    end
+
+    def unread_by!(user)
+      reading = Reading.find_or_initialize_by_user_id_and_readable_id_and_readable_type(user.id, self.id, self.class.name)
+      reading.state = :unread
+      reading.save!
+    end
+
+    def read_by?(user)
+      if cached_reading
+        cached_reading.read?
+      elsif cached_reading == false
+        user[acts_as_readable_options[:cache]].to_f > self.updated_at.to_f
+      elsif readers.loaded?
+        readers.include?(user)
+      elsif reading = readings.find_by_user_id(user.id)
+        reading.read?
+      else
+        user[acts_as_readable_options[:cache]].to_f > self.updated_at.to_f
+      end
+    end
+
+    # Returns true if the user has read this at least once, but it has been updated since the last reading
+    def updated?(user)
+      read_by?(user) && !latest_update_read_by?(user)
+    end
+
+    def latest_update_read_by?(user)
+      if cached_reading
+        cached_reading.updated_at > self.updated_at
+      elsif cached_reading == false
+        user[acts_as_readable_options[:cache]].to_f > self.updated_at.to_f
+      elsif reading = readings.where(:user_id => user.id, :state => :read).first
+        reading.updated_at > self.updated_at
+      else
+        user[acts_as_readable_options[:cache]].to_f > self.updated_at.to_f
+      end
+    end
+  end
+end
+

data/lib/acts_as_readable/reading.rb

@@ -0,0 +1,15 @@
+class Reading < ActiveRecord::Base
+  belongs_to :user
+  belongs_to :readable, :polymorphic => true
+  
+  validates_presence_of :user_id, :readable_id, :readable_type
+  validates_inclusion_of :state, :in => [:read, :unread, 'read', 'unread']
+  
+  def read?
+    self.state == 'read'
+  end
+  
+  def unread?
+    self.state == 'unread'
+  end
+end

data/spec/acts_as_readable_spec.rb

@@ -0,0 +1,81 @@
+`createdb acts_as_readable_test`
+require 'spec_helper'
+
+describe 'acts_as_readable' do
+  before(:each) do
+    @comment = Comment.create
+    @user = User.create
+  end
+
+  describe "the unread scope" do
+    it "should return records without readings if the user hasn't 'read all'" do
+      Comment.unread_by(@user).exists?(@comment).should be_true
+    end
+
+    it "should return records explicitly marked as unread if the user hasn't 'read all'" do
+      @comment.unread_by! @user
+      Comment.unread_by(@user).exists?(@comment).should be_true
+    end
+
+    it "should return records explicitly marked as unread if the user has 'read all' before the record was marked unread" do
+      Comment.read_by! @user
+      @comment.unread_by! @user
+      Comment.unread_by(@user).exists?(@comment).should be_true
+    end
+
+    it "should not return records explicitly marked as unread if the user has 'read all' after the record was marked unread" do
+      @comment.unread_by! @user
+      Comment.read_by! @user
+      Comment.unread_by(@user).exists?(@comment).should be_false
+    end
+  end
+
+  describe "the read scope" do
+    it "should return records without readings if the user has 'read all' since the last time the record was updated" do
+      Comment.read_by! @user
+      Comment.read_by(@user).exists?(@comment).should be_true
+    end
+
+    it "should return records explicitly marked as read if the user hasn't 'read all'" do
+      @comment.read_by! @user
+      Comment.read_by(@user).exists?(@comment).should be_true
+    end
+
+    it "should return records explicitly marked as read if the user has 'read all' before the record was marked unread" do
+      Comment.read_by! @user
+      @comment.read_by! @user
+      Comment.read_by(@user).exists?(@comment).should be_true
+    end
+
+    it "should return records explicitly marked as unread if the user has 'read all' after the record was marked unread" do
+      @comment.unread_by! @user
+      Comment.read_by! @user
+      Comment.read_by(@user).exists?(@comment).should be_true
+    end
+  end
+
+  describe "when checking a specific record" do
+    it "should return true if the record hasn't explicitly been read, but the user has 'read all' since the last time the record was updated" do
+      Comment.read_by! @user
+      @comment.read_by?(@user).should be_true
+    end
+
+    it "should return true if the record has been explicitly marked as read and the user hasn't 'read all'" do
+      @comment.read_by! @user
+      @comment.read_by?(@user).should be_true
+    end
+
+    it "should return false if the user 'read all' before and then marked the record as unread" do
+      Comment.read_by! @user
+      @comment.unread_by! @user
+      @comment.read_by?(@user).should be_false
+    end
+
+    it "should return true if the user has explicitly marked it as unread and then 'reads all'" do
+      @comment.unread_by! @user
+      Comment.read_by! @user
+      @comment.read_by?(@user).should be_true
+    end
+  end  
+end
+`dropdb acts_as_readable_test`

data/spec/spec_helper.rb

@@ -0,0 +1,29 @@
+$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+require 'active_record'
+require 'acts_as_readable'
+
+ActiveRecord::Base.establish_connection(:adapter => "postgresql", :database => "acts_as_readable_test")
+
+ActiveRecord::Schema.define(:version => 0) do
+  create_table :users, :force => true do |t|
+    t.datetime :comments_read_at
+  end
+
+  create_table :comments, :force => true do |t|
+    t.timestamps
+  end
+
+  create_table :readings, :force => true do |t|
+    t.belongs_to :readable, :polymorphic => true
+    t.belongs_to :user
+    t.string :state, :null => false, :default => 'read'
+    t.timestamps
+  end
+end
+
+class User < ActiveRecord::Base
+end
+
+class Comment < ActiveRecord::Base
+  acts_as_readable :cache => :comments_read_at
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: acts_as_readable
+version: !ruby/object:Gem::Version
+  version: 2.0.0
+platform: ruby
+authors:
+- Nicholas Jakobsen
+- Ryan Wallace
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-28 00:00:00.000000000 Z
+dependencies: []
+description: 
+email: contact@culturecode.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.rdoc
+- generators/acts_as_readable_migration/acts_as_readable_migration_generator.rb
+- generators/acts_as_readable_migration/templates/migration.rb
+- lib/acts_as_readable.rb
+- lib/acts_as_readable/acts_as_readable.rb
+- lib/acts_as_readable/reading.rb
+- spec/acts_as_readable_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/culturecode/acts_as_readable
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.1
+signing_key: 
+specification_version: 4
+summary: Allows records to be marked as readable. Optimized for bulk, 'mark all as
+  read' operations
+test_files: []