has_messages_huacnlee 0.4.1

data/README.rdoc

@@ -0,0 +1,112 @@
+= has_messages
+
++has_messages+ demonstrates a reference implementation for sending messages between users.
+
+== Resources
+
+API
+
+* http://rdoc.info/projects/pluginaweek/has_messages
+
+Bugs
+
+* http://pluginaweek.lighthouseapp.com/projects/13274-has_messages
+
+Development
+
+* http://github.com/pluginaweek/has_messages
+
+Source
+
+* git://github.com/pluginaweek/has_messages.git
+
+== Description
+
+Messaging between users is fairly common in web applications, especially those
+that support social networking.  Messaging doesn't necessarily need to be
+between users, but can also act as a way for the web application to send notices
+and other notifications to users.
+
+Designing and building a framework that supports this can be complex and takes
+away from the business focus.  This plugin can help ease that process by
+demonstrating a reference implementation of these features.
+
+== Usage
+
+=== Installation
+
++has_messages+ requires additional database tables to work.  You can generate
+a migration for these tables like so:
+
+  rails g has_messages
+
+Then simply migrate your database:
+
+  rake db:migrate
+
+=== Adding message support
+
+  class User < ActiveRecord::Base
+    has_messages
+  end
+
+This will build the following associations:
+* +messages+
+* +unsent_messages+
+* +sent_messages+
+* +received_messages+
+
+If you have more specific needs, you can create the same associations manually
+that +has_messages+ builds.  See HasMessages::MacroMethods#has_messages
+for more information about the asssociations that are generated from this macro.
+
+=== Creating new messages
+
+  message = user.messages.build
+  message.to user1, user2
+  message.subject = 'Hey!'
+  message.body = 'Does anyone want to go out tonight?'
+  message.deliver
+
+=== Replying to messages
+
+  reply = message.reply_to_all
+  reply.body = "I'd love to go out!"
+  reply.deliver
+
+=== Forwarding messages
+
+  forward = message.forward
+  forward.body = 'Interested?'
+  forward.deliver
+
+=== Processing messages asynchronously
+
+In addition to delivering messages immediately, you can also *queue* messages so
+that an external application processes and delivers them.  This is especially
+useful for messages that need to be sent outside of the confines of the application.
+
+To queue messages for external processing, you can use the +queue+ event,
+rather than +deliver+.  This will indicate to any external processes that
+the message is ready to be sent.
+
+To process queued emails, you need an external cron job that checks and sends
+them like so:
+
+  Message.with_state('queued').each do |message|
+    message.deliver
+  end
+
+== Testing
+
+Before you can run any tests, the following gem must be installed:
+* plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]
+
+To run against a specific version of Rails:
+
+  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails
+
+== Dependencies
+
+* Rails 2.3 or later
+* state_machine[http://github.com/pluginaweek/state_machine]

data/init.rb

@@ -0,0 +1 @@
+require 'has_messages'

data/lib/generators/has_messages/USAGE

@@ -0,0 +1,5 @@
+Usage:
+
+  rails g has_messages
+
+This will create migrations that will add the proper tables to store messages.

data/lib/generators/has_messages/has_messages_generator.rb

@@ -0,0 +1,24 @@
+class HasMessagesGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+
+  def self.source_root
+    @source_root ||= File.expand_path('../templates', __FILE__)
+  end
+
+  # Implement the required interface for Rails::Generators::Migration.
+  # taken from http://github.com/rails/rails/blob/master/activerecord/lib/generators/active_record.rb
+  def self.next_migration_number(dirname)
+    if ActiveRecord::Base.timestamped_migrations
+      Time.now.utc.strftime("%Y%m%d%H%M%S")
+    else
+      "%.3d" % (current_migration_number(dirname) + 1)
+    end
+  end
+
+  def generate_migration
+    migration_template "001_create_messages.rb", "db/migrate/create_messages.rb"
+    sleep(1)
+    migration_template "002_create_message_recipients.rb", "db/migrate/create_message_recipients.rb"
+  end
+ 
+end

data/lib/generators/has_messages/templates/001_create_messages.rb

@@ -0,0 +1,17 @@
+class CreateMessages < ActiveRecord::Migration
+  def self.up
+    create_table :messages do |t|
+      t.references :sender, :polymorphic => true, :null => false
+      t.text :subject, :body
+      t.string :state, :null => false
+      t.datetime :hidden_at
+      t.string :type
+      t.belongs_to :original_message
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :messages
+  end
+end

data/lib/generators/has_messages/templates/002_create_message_recipients.rb

@@ -0,0 +1,17 @@
+class CreateMessageRecipients < ActiveRecord::Migration
+  def self.up
+    create_table :message_recipients do |t|
+      t.references :message, :null => false
+      t.references :receiver, :polymorphic => true, :null => false
+      t.string :kind, :null => false
+      t.integer :position
+      t.string :state, :null => false
+      t.datetime :hidden_at
+    end
+    add_index :message_recipients, [:message_id, :kind, :position], :unique => true
+  end
+  
+  def self.down
+    drop_table :message_recipients
+  end
+end

data/lib/has_messages/models/message.rb

@@ -0,0 +1,167 @@
+# Represents a message sent from one user to one or more others.
+# 
+# == States
+# 
+# Messages can be in 1 of 3 states:
+# * +unsent+ - The message has not yet been sent.  This is the *initial* state.
+# * +queued+ - The message has been queued for future delivery.
+# * +sent+ - The message has been sent.
+# 
+# == Interacting with the message
+# 
+# In order to perform actions on the message, such as queueing or delivering,
+# you should always use the associated event action:
+# * +queue+ - Queues the message so that you can send it in a separate process
+# * +deliver+ - Sends the message to all of the recipients
+# 
+# == Message visibility
+# 
+# Although you can delete a message, it will also delete it from the inbox of all
+# the message's recipients.  Instead, you can change the *visibility* of the
+# message.  Messages have 1 of 2 states that define its visibility:
+# * +visible+ - The message is visible to the sender
+# * +hidden+ - The message is hidden from the sender
+# 
+# The visibility of a message can be changed by running the associated action:
+# * +hide+ -Hides the message from the sender
+# * +unhide+ - Makes the message visible again
+class Message < ActiveRecord::Base
+  belongs_to  :sender, :polymorphic => true
+  belongs_to  :original_message, :class_name => 'Message'
+  has_many    :recipients, :class_name => 'MessageRecipient', :order => 'kind DESC', :dependent => :destroy
+  has_many    :follow_up_messages, :class_name => 'Message', :foreign_key => 'original_message_id'
+  
+  validates_presence_of :state, :sender_id, :sender_type
+  
+  attr_accessible :subject, :body, :to, :cc, :bcc
+  
+  after_save :update_recipients
+  
+  scope :visible, :conditions => {:hidden_at => nil}
+  
+  # Define actions for the message
+  state_machine :state, :initial => :unsent do
+    # Queues the message so that it's sent in a separate process
+    event :queue do
+      transition :unsent => :queued, :if => :has_recipients?
+    end
+    
+    # Sends the message to all of the recipients as long as at least one
+    # recipient has been added
+    event :deliver do
+      transition [:unsent, :queued] => :sent, :if => :has_recipients?
+    end
+  end
+  
+  # Defines actions for the visibility of the message
+  state_machine :hidden_at, :initial => :visible do
+    # Hides the message from the recipient's inbox
+    event :hide do
+      transition all => :hidden
+    end
+    
+    # Makes the message visible in the recipient's inbox
+    event :unhide do
+      transition all => :visible
+    end
+    
+    state :visible, :value => nil
+    state :hidden, :value => lambda {Time.now}, :if => lambda {|value| value}
+  end
+  
+  def thread
+    [self] + follow_up_messages
+  end
+  
+  def latest_message
+    follow_up_messages.last || self
+  end
+  
+  # Directly adds the receivers on the message (i.e. they are visible to all recipients)
+  def to(*receivers)
+    receivers(receivers, 'to')
+  end
+  alias_method :to=, :to
+  
+  # Carbon copies the receivers on the message
+  def cc(*receivers)
+    receivers(receivers, 'cc')
+  end
+  alias_method :cc=, :cc
+  
+  # Blind carbon copies the receivers on the message
+  def bcc(*receivers)
+    receivers(receivers, 'bcc')
+  end
+  alias_method :bcc=, :bcc
+  
+  # Forwards this message, including the original subject and body in the new
+  # message
+  def forward
+    message = self.class.new(:subject => subject, :body => body)
+    message.sender = sender
+    message
+  end
+  
+  # Replies to this message, including the original subject and body in the new
+  # message.  Only the original direct receivers are added to the reply.
+  def reply
+    message = self.class.new(:subject => subject, :body => body)
+    message.sender = sender
+    message.to(to)
+    # use the very first message to anchor all replies
+    if self.original_message
+      message.original_message = self.original_message
+    else
+      message.original_message = self
+    end
+    message
+  end
+  
+  # Replies to all recipients on this message, including the original subject
+  # and body in the new message.  All receivers (direct, cc, and bcc) are added
+  # to the reply.
+  def reply_to_all
+    message = reply
+    message.cc(cc)
+    message.bcc(bcc)
+    # use the very first message to anchor all replies
+    if self.original_message
+      message.original_message = self.original_message
+    else
+      message.original_message = self
+    end
+    message
+  end
+  
+  private
+    # Create/destroy any receivers that were added/removed
+    def update_recipients
+      if @receivers
+        @receivers.each do |kind, receivers|
+          kind_recipients = recipients.select {|recipient| recipient.kind == kind}
+          new_receivers = receivers - kind_recipients.map(&:receiver)
+          removed_recipients = kind_recipients.reject {|recipient| receivers.include?(recipient.receiver)}
+          
+          recipients.delete(*removed_recipients) if removed_recipients.any?
+          new_receivers.each {|receiver| self.recipients.create!(:receiver => receiver, :kind => kind)}
+        end
+        
+        @receivers = nil
+      end
+    end
+    
+    # Does this message have any recipients on it?
+    def has_recipients?
+      (to + cc + bcc).any?
+    end
+    
+    # Creates new receivers or gets the current receivers for the given kind (to, cc, or bcc)
+    def receivers(receivers, kind)
+      if receivers.any?
+        (@receivers ||= {})[kind] = receivers.flatten.compact
+      else
+        @receivers && @receivers[kind] || recipients.select {|recipient| recipient.kind == kind}.map(&:receiver)
+      end
+    end
+end

data/lib/has_messages/models/message_recipient.rb

@@ -0,0 +1,132 @@
+# Represents a recipient on a message.  The kind of recipient (to, cc, or bcc) is
+# determined by the +kind+ attribute.
+# 
+# == States
+#
+# Recipients can be in 1 of 2 states:
+# * +unread+ - The message has been sent, but not yet read by the recipient.  This is the *initial* state.
+# * +read+ - The message has been read by the recipient
+# 
+# == Interacting with the message
+# 
+# In order to perform actions on the message, such as viewing, you should always
+# use the associated event action:
+# * +view+ - Marks the message as read by the recipient
+# 
+# == Hiding messages
+# 
+# Although you can delete a recipient, it will also delete it from everyone else's
+# message, meaning that no one will know that person was ever a recipient of the
+# message.  Instead, you can change the *visibility* of the message.  Messages
+# have 1 of 2 states that define its visibility:
+# * +visible+ - The message is visible to the recipient
+# * +hidden+ - The message is hidden from the recipient
+# 
+# The visibility of a message can be changed by running the associated action:
+# * +hide+ -Hides the message from the recipient
+# * +unhide+ - Makes the message visible again
+class MessageRecipient < ActiveRecord::Base
+  belongs_to  :message
+  belongs_to  :receiver, :polymorphic => true
+  
+  validates_presence_of :message_id, :kind, :state, :receiver_id, :receiver_type
+  
+  attr_protected :state, :position, :hidden_at
+  
+  before_create :set_position
+  before_destroy :reorder_positions
+  
+  # Make this class look like the actual message
+  delegate  :sender, :subject, :body, :recipients, :to, :cc, :bcc, :created_at,
+              :to => :message
+  
+  scope :visible, :conditions => {:hidden_at => nil}
+  
+  # Defines actions for the recipient
+  state_machine :state, :initial => :unread do
+    # Indicates that the message has been viewed by the receiver
+    event :view do
+      transition :unread => :read, :if => :message_sent?
+    end
+  end
+  
+  # Defines actions for the visibility of the message to the recipient
+  state_machine :hidden_at, :initial => :visible do
+    # Hides the message from the recipient's inbox
+    event :hide do
+      transition all => :hidden
+    end
+    
+    # Makes the message visible in the recipient's inbox
+    event :unhide do
+      transition all => :visible
+    end
+    
+    state :visible, :value => nil
+    state :hidden, :value => lambda {Time.now}, :if => lambda {|value| value}
+  end
+  
+  # Forwards this message, including the original subject and body in the new
+  # message
+  def forward
+    message = self.message.class.new(:subject => subject, :body => body)
+    message.sender = receiver
+    message
+  end
+  
+  # Replies to this message, including the original subject and body in the new
+  # message.  Only the original direct receivers are added to the reply.
+  def reply
+    message = self.message.class.new(:subject => subject, :body => body)
+    message.sender = receiver
+    message.to(sender)
+    # use the very first message to anchor all replies
+    if self.message.original_message
+      message.original_message = self.message.original_message
+    else
+      message.original_message = self.message
+    end
+    message
+  end
+  
+  # Replies to all recipients on this message, including the original subject
+  # and body in the new message.  All receivers (sender, direct, cc, and bcc) are
+  # added to the reply.
+  def reply_to_all
+    message = reply
+    message.to(  (to + [sender]).uniq )
+    message.cc(cc - [receiver])
+    message.bcc(bcc - [receiver])
+    # use the very first message to anchor all replies
+    if self.message.original_message
+      message.original_message = self.message.original_message
+    else
+      message.original_message = self.message
+    end
+    message
+  end
+  
+  private
+    # Has the message this recipient is on been sent?
+    def message_sent?
+      message.sent?
+    end
+    
+    # Sets the position of the current recipient based on existing recipients
+    def set_position
+      if last_recipient = message.recipients.find(:first, :conditions => {:kind => kind}, :order => 'position DESC')
+        self.position = last_recipient.position + 1
+      else
+        self.position = 1
+      end
+    end
+    
+    # Reorders the positions of the message's recipients
+    def reorder_positions
+      if position
+        position = self.position
+        update_attribute(:position, nil)
+        self.class.update_all('position = (position - 1)', ['message_id = ? AND kind = ? AND position > ?', message_id, kind, position])
+      end
+    end
+end

data/lib/has_messages.rb

@@ -0,0 +1,103 @@
+require 'state_machine'
+
+# Adds a generic implementation for sending messages between users
+module HasMessages
+  module MacroMethods
+    # Creates the following message associations:
+    # * +messages+ - Messages that were composed and are visible to the owner.
+    #   Mesages may have been sent or unsent.
+    # * +received_messages - Messages that have been received from others and
+    #   are visible.  Messages may have been read or unread.
+    # 
+    # == Creating new messages
+    # 
+    # To create a new message, the +messages+ association should be used,
+    # for example:
+    # 
+    #   user = User.find(123)
+    #   message = user.messages.build
+    #   message.subject = 'Hello'
+    #   message.body = 'How are you?'
+    #   message.to User.find(456)
+    #   message.save
+    #   message.deliver
+    # 
+    # == Drafts
+    # 
+    # You can get the drafts for a particular user by using the +unsent_messages+
+    # helper method.  This will find all messages in the "unsent" state.  For example,
+    # 
+    #   user = User.find(123)
+    #   user.unsent_messages
+    # 
+    # You can also get at the messages that *have* been sent, using the +sent_messages+
+    # helper method.  For example,
+    # 
+    #  user = User.find(123)
+    #  user.sent_messages
+    def has_messages
+      has_many  :messages,
+                  :as => :sender,
+                  :class_name => 'Message',
+                  :conditions => {:hidden_at => nil},
+                  :order => 'messages.created_at DESC'
+      has_many  :received_messages,
+                  :as => :receiver,
+                  :class_name => 'MessageRecipient',
+                  :include => :message,
+                  :conditions => ['message_recipients.hidden_at IS NULL AND messages.state = ?', 'sent'],
+                  :order => 'messages.created_at DESC'
+#      has_many  :received_message_threads,
+#                  :as => :receiver,
+#                  :class_name => 'MessageRecipient',
+#                  :include => :message,
+#                  :conditions => ['message_recipients.hidden_at IS NULL AND messages.state = ? and messages.original_message_id IS NOT NULL', 'sent'],
+#                  :group => 'messages.original_message_id',
+#                  :order => 'messages.created_at DESC'
+
+      include HasMessages::InstanceMethods
+    end
+  end
+  
+  module InstanceMethods
+    # Composed messages that have not yet been sent.  These consists of all
+    # messages that are currently in the "unsent" state.
+    def unsent_messages
+      messages.with_state(:unsent)
+    end
+    
+    # Composed messages that have already been sent.  These consists of all
+    # messages that are currently in the "queued" or "sent" states.
+    def sent_messages
+      messages.with_states(:queued, :sent)
+    end
+
+    # Returns the most recent message of each thread
+    def last_received_message_per_thread
+      MessageRecipient.find_all_by_receiver_id(id, :order => 'id desc', :joins => :message, :conditions => 'message_recipients.hidden_at is null', :group => 'COALESCE(original_message_id,messages.id)')
+    end
+    
+    def conversations
+      (messages + received_messages.map(&:message)).compact.uniq
+    end
+
+    def original_conversations
+      conversations.select{ |message| message.original_message_id == nil }
+    end
+
+    def find_conversation_by_id(id)
+      conversations.select{ |message| message.id == id.to_i }.first
+    end
+
+    def unread_messages
+      received_messages.select(&:unread?).map(&:message)
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  extend HasMessages::MacroMethods
+end
+
+require 'has_messages/models/message.rb'
+require 'has_messages/models/message_recipient.rb'

data/test/app_root/app/models/user.rb

@@ -0,0 +1,3 @@
+class User < ActiveRecord::Base
+  has_messages
+end

data/test/app_root/config/environment.rb

@@ -0,0 +1,9 @@
+require 'config/boot'
+
+Rails::Initializer.run do |config|
+  config.plugin_paths << '..'
+  config.plugins = %w(state_machine has_messages)
+  config.cache_classes = false
+  config.whiny_nils = true
+  config.action_controller.session = {:key => 'rails_session', :secret => 'd229e4d22437432705ab3985d4d246'}
+end

data/test/app_root/db/migrate/001_create_users.rb

@@ -0,0 +1,11 @@
+class CreateUsers < ActiveRecord::Migration
+  def self.up
+    create_table :users do |t|
+      t.string :login, :null => false
+    end
+  end
+
+  def self.down
+    drop_table :users
+  end
+end

data/test/app_root/db/migrate/002_migrate_has_messages_to_version_2.rb

@@ -0,0 +1,13 @@
+class MigrateHasMessagesToVersion2 < ActiveRecord::Migration
+  def self.up
+    ActiveRecord::Migrator.new(:up, "#{Rails.root}/../../generators/has_messages/templates", 0).migrations.each do |migration|
+      migration.migrate(:up)
+    end
+  end
+  
+  def self.down
+    ActiveRecord::Migrator.new(:down, "#{Rails.root}/../../generators/has_messages/templates", 0).migrations.each do |migration|
+      migration.migrate(:down)
+    end
+  end
+end

data/test/factory.rb

@@ -0,0 +1,58 @@
+module Factory
+  # Build actions for the model
+  def self.build(model, &block)
+    name = model.to_s.underscore
+    
+    define_method("#{name}_attributes", block)
+    define_method("valid_#{name}_attributes") {|*args| valid_attributes_for(model, *args)}
+    define_method("new_#{name}")              {|*args| new_record(model, *args)}
+    define_method("create_#{name}")           {|*args| create_record(model, *args)}
+  end
+  
+  # Get valid attributes for the model
+  def valid_attributes_for(model, attributes = {})
+    name = model.to_s.underscore
+    send("#{name}_attributes", attributes)
+    attributes.stringify_keys!
+    attributes
+  end
+  
+  # Build an unsaved record
+  def new_record(model, *args)
+    attributes = valid_attributes_for(model, *args)
+    record = model.new(attributes)
+    attributes.each {|attr, value| record.send("#{attr}=", value) if model.accessible_attributes && !model.accessible_attributes.include?(attr) || model.protected_attributes && model.protected_attributes.include?(attr)}
+    record
+  end
+  
+  # Build and save/reload a record
+  def create_record(model, *args)
+    record = new_record(model, *args)
+    record.save!
+    record.reload
+    record
+  end
+  
+  build Message do |attributes|
+    attributes[:sender] = create_user unless attributes.include?(:sender)
+    attributes.reverse_merge!(
+      :subject => 'New features',
+      :body => 'Lots of new things to talk about... come to the meeting tonight to find out!',
+      :created_at => Time.current + Message.count
+    )
+  end
+  
+  build MessageRecipient do |attributes|
+    attributes[:message] = create_message unless attributes.include?(:message)
+    attributes[:receiver] = create_user(:login => 'me') unless attributes.include?(:receiver)
+    attributes.reverse_merge!(
+      :kind => 'to'
+    )
+  end
+  
+  build User do |attributes|
+    attributes.reverse_merge!(
+      :login => 'admin'
+    )
+  end
+end