pluginaweek-has_messages 0.4.0

data/CHANGELOG.rdoc

@@ -0,0 +1,59 @@
+== master
+
+== 0.4.0 / 2009-04-19
+
+* Add dependency on Rails 2.3
+* Add dependency on plugin_test_helper 0.3.0
+* Add dependency on state_machine 0.7.0
+
+== 0.3.1 / 2009-01-11
+
+* Use a state machine for the hidden_at field on Message/MessageRecipient
+* Add dependency on state_machine 0.5.0
+
+== 0.3.0 / 2008-12-14
+
+* Remove the PluginAWeek namespace
+* Rename Message#hide!/unhide! to Message#hide/unhide and MessageRecipient#hide!/unhide! to MessageRecipient#hide/unhide
+
+== 0.2.0 / 2008-10-26
+
+* Add mass-assignment protection in the Message/MessageRecipient models
+* Change how the base module is included to prevent namespacing conflicts
+
+== 0.1.3 / 2008-09-07
+
+* Add dependency on state_machine 0.3.0
+
+== 0.1.2 / 2008-06-29
+
+* Add compatibility with state_machine 0.2.0
+
+== 0.1.1 / 2008-06-22
+
+* Remove log files from gems
+
+== 0.1.0 / 2008-05-05
+
+* Remove dependency on acts_as_list
+* Update to reflect changes from has_states to state_machine
+* Introduce an ActionMailer-type api for adding the various types of recipients
+* Update migrations to support Rails 2.0 syntax
+* Replace has_finder dependency with named_scope
+* Remove has_messages helper
+* Update documentation
+
+== 0.0.1 / 2007-09-26
+
+* Add state_changes fixtures for tests
+* Use has_finder for tracking the deletion status of Messages/MessageRecipients
+* Message#forward and Message#reply should create new instances of the current class, not always Message
+* Add type field to MessageRecipient table
+* Allow message senders to not be model recipients in third-party plugins
+* Remove old references to Message::StateExtension
+* Update with dependency on custom_callbacks
+* Add documentation
+* Convert dos newlines to unix newlines
+* Move ReceiverMessage state into the MessageRecipient class
+* Moved Build extensions out of the MessageRecipient class
+* Fix determining whether classes exist in has_messages

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2009 Aaron Pfeifer
+
+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/README.rdoc

@@ -0,0 +1,101 @@
+= has_messages
+
++has_messages+ demonstrates a reference implementation for sending messages between users.
+
+== Resources
+
+API
+
+* http://api.pluginaweek.org/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
+
+=== 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/Rakefile

@@ -0,0 +1,97 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+spec = Gem::Specification.new do |s|
+  s.name              = 'has_messages'
+  s.version           = '0.4.0'
+  s.platform          = Gem::Platform::RUBY
+  s.summary           = 'Demonstrates a reference implementation for sending messages between users in ActiveRecord'
+  s.description       = s.summary
+  
+  s.files             = FileList['{app,db,lib,test}/**/*'] + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc) - FileList['test/app_root/{log,log/*,script,script/*}']
+  s.require_path      = 'lib'
+  s.has_rdoc          = true
+  s.test_files        = Dir['test/**/*_test.rb']
+  s.add_dependency    'state_machine', '>= 0.7.0'
+  
+  s.author            = 'Aaron Pfeifer'
+  s.email             = 'aaron@pluginaweek.org'
+  s.homepage          = 'http://www.pluginaweek.org'
+  s.rubyforge_project = 'pluginaweek'
+end
+  
+desc 'Default: run all tests.'
+task :default => :test
+
+desc "Test the #{spec.name} plugin."
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.test_files = spec.test_files
+  t.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  namespace :test do
+    desc "Test the #{spec.name} plugin with Rcov."
+    Rcov::RcovTask.new(:rcov) do |t|
+      t.libs << 'lib'
+      t.test_files = spec.test_files
+      t.rcov_opts << '--exclude="^(?!lib/|app/)"'
+      t.verbose = true
+    end
+  end
+rescue LoadError
+end
+
+desc "Generate documentation for the #{spec.name} plugin."
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = spec.name
+  rdoc.template = '../rdoc_template.rb'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'LICENSE', 'lib/**/*.rb', 'app/**/*.rb')
+end
+
+desc 'Generate a gemspec file.'
+task :gemspec do
+  File.open("#{spec.name}.gemspec", 'w') do |f|
+    f.write spec.to_ruby
+  end
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+desc 'Publish the beta gem.'
+task :pgem => [:package] do
+  Rake::SshFilePublisher.new('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{spec.name}-#{spec.version}.gem").upload
+end
+
+desc 'Publish the API documentation.'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{spec.name}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+task :publish => [:pgem, :pdoc, :release]
+
+desc 'Publish the release files to RubyForge.'
+task :release => [:gem, :package] do
+  require 'rubyforge'
+  
+  ruby_forge = RubyForge.new.configure
+  ruby_forge.login
+  
+  %w(gem tgz zip).each do |ext|
+    file = "pkg/#{spec.name}-#{spec.version}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(spec.rubyforge_project, spec.name, spec.version, file)
+  end
+end

data/app/models/message.rb

@@ -0,0 +1,145 @@
+# 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
+  has_many    :recipients, :class_name => 'MessageRecipient', :order => 'kind DESC, position ASC', :dependent => :destroy
+  
+  validates_presence_of :state, :sender_id, :sender_type
+  
+  attr_accessible :subject, :body, :to, :cc, :bcc
+  
+  after_save :update_recipients
+  
+  named_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
+  
+  # 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)
+    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)
+    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/app/models/message_recipient.rb

@@ -0,0 +1,120 @@
+# 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
+  
+  named_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)
+    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 - [receiver] + [sender])
+    message.cc(cc - [receiver])
+    message.bcc(bcc - [receiver])
+    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