has_messages 0.1.0

data/CHANGELOG

@@ -0,0 +1,43 @@
+*SVN*
+
+*0.1.0* (May 5th, 2008)
+
+* 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* (September 26th, 2007)
+
+* 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/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2008 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

@@ -0,0 +1,97 @@
+= has_messages
+
++has_messages+ demonstrates a reference implementation for sending messages between users.
+
+== Resources
+
+Wiki
+
+* http://wiki.pluginaweek.org/Has_messages
+
+API
+
+* http://api.pluginaweek.org/has_messages
+
+Development
+
+* http://dev.pluginaweek.org/browser/trunk/has_messages
+
+Source
+
+* http://svn.pluginaweek.org/trunk/has_messages
+
+== 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 complete 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 specified needs, you can create the same associations manually
+that +has_messages+ builds.  See PluginAWeek::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 <tt>queue!</tt> event,
+rather than <tt>deliver!</tt>.  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://wiki.pluginaweek.org/Plugin_test_helper]
+
+== Dependencies
+
+* plugins_plus[http://wiki.pluginaweek.org/Plugins_plus]
+* state_machine[http://wiki.pluginaweek.org/State_machine]

data/Rakefile

@@ -0,0 +1,80 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+PKG_NAME           = 'has_messages'
+PKG_VERSION        = '0.1.0'
+PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
+RUBY_FORGE_PROJECT = 'pluginaweek'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the has_messages plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the has_messages plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'HasMessages'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s|
+  s.name            = PKG_NAME
+  s.version         = PKG_VERSION
+  s.platform        = Gem::Platform::RUBY
+  s.summary         = 'Demonstrates a reference implementation for sending messages between users.'
+  
+  s.files           = FileList['{app,db,lib,test}/**/*'].to_a + %w(CHANGELOG init.rb MIT-LICENSE Rakefile README)
+  s.require_path    = 'lib'
+  s.autorequire     = 'has_messages'
+  s.has_rdoc        = true
+  s.test_files      = Dir['test/**/*_test.rb']
+  s.add_dependency  'state_machine', '>= 0.1.0'
+  
+  s.author          = 'Aaron Pfeifer'
+  s.email           = 'aaron@pluginaweek.org'
+  s.homepage        = 'http://www.pluginaweek.org'
+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', "#{PKG_FILE_NAME}.gem").upload
+end
+
+desc 'Publish the API documentation'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{PKG_NAME}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+task :publish => [:pdoc, :release]
+
+desc 'Publish the release files to RubyForge.'
+task :release => [:gem, :package] do
+  require 'rubyforge'
+  
+  ruby_forge = RubyForge.new
+  ruby_forge.login
+  
+  %w( gem tgz zip ).each do |ext|
+    file = "pkg/#{PKG_FILE_NAME}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(RUBY_FORGE_PROJECT, PKG_NAME, PKG_VERSION, file)
+  end
+end

data/app/models/message.rb

@@ -0,0 +1,141 @@
+# 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
+# 
+# == Hiding messages
+# 
+# Although you can delete a message, it will also delete it from the inbox of all
+# the message's recipients.  Instead, you can hide messages from users with the
+# following actions:
+# * +hide!+ -Hides the message from the sender's inbox
+# * +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
+  
+  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 :to => 'queued', :from => 'unsent', :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 :to => 'sent', :from => %w(unsent queued), :if => :has_recipients?
+    end
+  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
+  def forward
+    message = self.class.new(:subject => subject, :body => body)
+    message.sender = sender
+    message
+  end
+  
+  # Replies to this message
+  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
+  def reply_to_all
+    message = reply
+    message.cc(cc)
+    message.bcc(bcc)
+    message
+  end
+  
+  # Hides the message from the sender's inbox
+  def hide!
+    update_attribute(:hidden_at, Time.now)
+  end
+  
+  # Makes the message visible in the sender's inbox
+  def unhide!
+    update_attribute(:hidden_at, nil)
+  end
+  
+  # Is this message still hidden from the sender's inbox?
+  def hidden?
+    hidden_at?
+  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 hide messages from users with the following actions:
+# * +hide!+ -Hides the message from the recipient's inbox
+# * +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
+  
+  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}
+  
+  state_machine :state, :initial => 'unread' do
+    # Indicates that the message has been viewed by the receiver
+    event :view do
+      transition :to => 'read', :from => 'unread', :if => :message_sent?
+    end
+  end
+  
+  # Forwards the message
+  def forward
+    message = self.message.class.new(:subject => subject, :body => body)
+    message.sender = receiver
+    message
+  end
+  
+  # Replies to the message
+  def reply
+    message = self.message.class.new(:subject => subject, :body => body)
+    message.sender = receiver
+    message.to(sender)
+    message
+  end
+  
+  # Replies to all recipients on the message, including the original sender
+  def reply_to_all
+    message = reply
+    message.to(to - [receiver] + [sender])
+    message.cc(cc - [receiver])
+    message.bcc(bcc - [receiver])
+    message
+  end
+  
+  # Hides the message from the recipient's inbox
+  def hide!
+    update_attribute(:hidden_at, Time.now)
+  end
+  
+  # Makes the message visible in the recipient's inbox
+  def unhide!
+    update_attribute(:hidden_at, nil)
+  end
+  
+  # Is this message still hidden from the recipient's inbox?
+  def hidden?
+    hidden_at?
+  end
+  
+  private
+    # Has the message this recipient is on been sent?
+    def message_sent?
+      message.state == '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