has_emails 0.0.1 → 0.1.0

data/CHANGELOG

@@ -1,5 +1,13 @@
 *SVN*
 
+*0.1.0* (May 5th, 2008)
+
+* Update to latest has_messages api
+
+* Simplify by removing support for models other than EmailAddresses in Emails
+
+* Updated documentation
+
 *0.0.1* (September 26th, 2007)
 
 * Refactor has_email_address/has_email_addresses so that new associations for unsent/sent emails isn't created for has_email_address

data/README

@@ -1,28 +1,25 @@
 = has_emails
 
-+has_emails+ adds support for emailing capabilities between ActiveRecord models.
++has_emails+ demonstrates a reference implementation for sending emails with
+logging and asynchronous support.
 
 == Resources
 
-API
-
-* http://api.pluginaweek.org/has_emails
-
 Wiki
 
 * http://wiki.pluginaweek.org/Has_emails
 
-Announcement
+API
 
-* http://www.pluginaweek.org
+* http://api.pluginaweek.org/has_emails
 
-Source
+Development
 
-* http://svn.pluginaweek.org/trunk/plugins/active_record/has/has_emails
+* http://dev.pluginaweek.org/browser/trunk/has_emails
 
-Development
+Source
 
-* http://dev.pluginaweek.org/browser/trunk/plugins/active_record/has/has_emails
+* http://svn.pluginaweek.org/trunk/has_emails
 
 == Description
 
@@ -33,43 +30,29 @@ web application to send notices and other notifications to users.
 
 Rails already provides ActionMailer as a way of sending emails.  However, the
 framework does not provide an easy way to persist emails, track their status, and
-process them asynchronously.  Designing and building this type of framework can
-become complex and cumbersome and takes away from the focus of the web application.
-This plugin helps ease that process by providing a complete implementation for
-sending and receiving emails to and between models in your application.
+process them asynchronously.  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 emailing support
-
-If you want to use the built-in support for email addresses (using the EmailAddress
-model), you can add emailing support for users like so:
-
-  class User < ActiveRecord::Base
-    has_email_address
-    # has_email_addresses if you want to support multiple addresses
-  end
+=== Creating new emails
 
-On the other hand, if you already have the email address for users stored as a
-column in your users table, you can add emailing support like so:
+Emails should usually still be created using ActionMailer.  However, instead of
+delivering the emails, you can queue the emails like so:
 
-  class User < ActiveRecord::Base
-    has_messages  :emails,
-                    :message_class => 'Email'
-  end
+  Notifier.deliver_signup_notification(david) # sends the email now
+  Notifier.queue_signup_notification(david) # sends the email later (has_emails kicks in)
 
-=== Creating new emails
+In addition to queueing emails, you can build them directly like so:
 
-  email = user.emails.build
-  email.to << [user1, email_address1, 'someone@somewhere.com']
+  email_address = EmailAddress.find(123)
+  email = email_address.emails.build
+  email.to EmailAddress.find(456)
   email.subject = 'Hey!'
   email.body = 'Does anyone want to go out tonight?'
   email.deliver!
 
-As can be seen in the above example, you can use Users, EmailAddresses, or even
-Strings as recipients in emails.  Each will be automatically converted to the
-EmailRecipient class so that it can be stored in the database.
-
 === Replying to emails
 
   reply = email.reply_to_all
@@ -82,49 +65,27 @@ EmailRecipient class so that it can be stored in the database.
   forward.body = 'Interested?'
   forward.deliver!
 
-=== External process messaging
+=== Processing email asynchronously
 
 In addition to delivering emails immediately, you can also *queue* emails so
-that an external application processes and delivers them.  This is especially
-useful when you want to asynchronously send e-mails so that it doesn't block the
-user interface on your web application.
-
-To queue emails for external processing, you can simply use the <tt>queue!</tt>
-event, rather than <tt>deliver!</tt>.  This will indicate to any external processes
-that the email is ready to be sent.  The external process can then invoke <tt>deliver!</tt>
-whenever it is ready to send the queued email.
+that an external application processes and delivers them (as mentioned above).
+This is especially useful when you want to asynchronously send e-mails so that
+it doesn't block the user interface on your web application.
 
-=== Running migrations
+To process queued emails, you need an external cron job that checks and sends
+them like so:
 
-To migrate the tables required for this plugin, you can either run the
-migration from the command line like so:
-
-  rake db:migrate:plugins PLUGIN=has_emails
-
-or (more ideally) generate a migration file that will integrate into your main
-application's migration path:
-
-  ruby script/generate plugin_migration has_emails
+  Email.with_state('queued').each do |email|
+    email.deliver!
+  end
 
 == Testing
 
-Before you can run any tests, the following gems must be installed:
+Before you can run any tests, the following gem must be installed:
 * plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper]
-* dry_validity_assertions[http://wiki.pluginaweek.org/Dry_validity_assertions]
 
 == Dependencies
 
-This plugin depends on the presence of the following plugins:
+* plugins_plus[http://wiki.pluginaweek.org/Plugins_plus]
 * has_messages[http://wiki.pluginaweek.org/Has_messages]
-
-This plugin is also a plugin+.  That means that it contains a slice of an
-application, such as models and migrations.  To test or use a plugin+, you
-must have the following plugins/gems installed:
-* plugin_dependencies[http://wiki.pluginaweek.org/Plugin_dependencies]
-* loaded_plugins[http://wiki.pluginaweek.org/Loaded_plugins]
-* appable_plugins[http://wiki.pluginaweek.org/Appable_plugins]
-* plugin_migrations[http://wiki.pluginaweek.org/Plugin_migrations]
-
-Instead of installing each individual plugin+ feature, you can install them all
-at once using the plugins+[http://wiki.pluginaweek.org/Plugins_plus] meta package,
-which contains all additional features.
+* state_machine[http://wiki.pluginaweek.org/State_machine]

data/Rakefile

@@ -4,7 +4,7 @@ require 'rake/gempackagetask'
 require 'rake/contrib/sshpublisher'
 
 PKG_NAME           = 'has_emails'
-PKG_VERSION        = '0.0.1'
+PKG_VERSION        = '0.1.0'
 PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
 RUBY_FORGE_PROJECT = 'pluginaweek'
 
@@ -31,18 +31,18 @@ spec = Gem::Specification.new do |s|
   s.name            = PKG_NAME
   s.version         = PKG_VERSION
   s.platform        = Gem::Platform::RUBY
-  s.summary         = 'Adds support for emailing capabilities between ActiveRecord models.'
+  s.summary         = 'Demonstrates a reference implementation for sending emails with logging and asynchronous support.'
   
   s.files           = FileList['{app,db,lib,test}/**/*'].to_a + %w(CHANGELOG init.rb MIT-LICENSE Rakefile README)
   s.require_path    = 'lib'
   s.autorequire     = 'has_emails'
   s.has_rdoc        = true
   s.test_files      = Dir['test/**/*_test.rb']
-  s.add_dependency  'has_messages', '>= 0.0.1'
-  s.add_dependency  'validates_as_email_address', '>= 0.0.1'
+  s.add_dependency  'has_messages', '>= 0.1.0'
+  s.add_dependency  'validates_as_email_address', '>= 0.0.2'
   
-  s.author          = 'Aaron Pfeifer, Neil Abraham'
-  s.email           = 'info@pluginaweek.org'
+  s.author          = 'Aaron Pfeifer'
+  s.email           = 'aaron@pluginaweek.org'
   s.homepage        = 'http://www.pluginaweek.org'
 end
   
@@ -54,12 +54,12 @@ end
 
 desc 'Publish the beta gem'
 task :pgem => [:package] do
-  Rake::SshFilePublisher.new('pluginaweek@pluginaweek.org', '/home/pluginaweek/gems.pluginaweek.org/gems', 'pkg', "#{PKG_FILE_NAME}.gem").upload
+  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('pluginaweek@pluginaweek.org', "/home/pluginaweek/api.pluginaweek.org/#{PKG_NAME}", 'rdoc').upload
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{PKG_NAME}", 'rdoc').upload
 end
 
 desc 'Publish the API docs and gem'

data/app/models/email.rb

@@ -1,84 +1,12 @@
 # Represents an email which has been sent to one or more recipients.  This is
-# essentially the same as the Message class, but overrides the +to+, +cc+, and +bcc+
-# associations to that proper instances of the MessageRecipient class are created.
+# essentially the same as the Message class, but overrides how the it is
+# delivered.
 class Email < Message
-  validates_presence_of       :sender_spec
-  validates_as_email_address  :sender_spec,
-                                :allow_nil => true
-  
-  with_options(
-    :class_name => 'EmailRecipient',
-    :foreign_key => 'message_id',
-    :order => 'position ASC',
-    :dependent => true
-  ) do |e|
-    e.has_many  :to,
-                  :conditions => ['kind = ?', 'to'],
-                  :extend => [MessageRecipientToBuildExtension, EmailRecipientBuildExtension]
-    e.has_many  :cc,
-                  :conditions => ['kind = ?', 'cc'],
-                  :extend => [MessageRecipientCcBuildExtension, EmailRecipientBuildExtension]
-    e.has_many  :bcc,
-                  :conditions => ['kind = ?', 'bcc'],
-                  :extend => [MessageRecipientBccBuildExtension, EmailRecipientBuildExtension]
-  end
-  
-  # Returns the sender of the message.  This can be a string if being sent
-  # from an arbitrary e-mail address.
-  def sender_with_spec
-    sender_without_spec || sender_spec
-  end
-  alias_method_chain :sender, :spec
-  
-  # If sender is a string, then sets the spec, otherwise uses the original
-  # sender setter
-  def sender_with_spec=(value)
-    self.sender_spec = EmailAddress.convert_from(value).spec
-    self.sender_without_spec = value if !value.is_a?(String)
-  end
-  alias_method_chain :sender=, :spec
-  
-  # Converts the sender into an Email Address, whether it be a string,
-  # EmailAddress, or other model type
-  def sender_email_address
-    EmailAddress.convert_from(sender_spec)
-  end
-  
-  # The name of the person whose sending the email
-  def sender_name
-    sender_without_spec ? EmailAddress.convert_from(sender_without_spec).name : sender_email_address.name
-  end
-  
-  # Returns a string version of the email address plus any name like
-  # "John Doe <john.doe@gmail.com>"..
-  def sender_with_name
-    address = self.email_address
-    address.name = self.name
-    address.with_name
-  end
-  
-  # Actually delivers the email to the recipients
-  def deliver
-    ApplicationMailer.deliver_email(self)
-  end
-  
-  # Saves the +sender_spec+ in the forwarded message
-  def forward
-    message = super
-    message.sender_spec = sender_spec
-    message
-  end
-  
-  # Saves the +sender_spec+ in the replied message
-  def reply
-    message = super
-    message.sender_spec = sender_spec
-    message
-  end
+  after_deliver :deliver_email
   
   private
-  # Strings are allowed to participate in messaging
-  def model_participant?
-    sender_id && sender_type || sender_spec.nil?
-  end
+    # Actually delivers the email to the recipients
+    def deliver_email
+      ActionMailer::Base.deliver_email(self)
+    end
 end

data/app/models/email_address.rb

@@ -1,123 +1,45 @@
 # Represents a valid RFC822 email address
 class EmailAddress < ActiveRecord::Base
+  has_emails
+  
+  validates_presence_of       :spec
+  validates_as_email_address  :spec
+  validates_uniqueness_of     :spec,
+                                :scope => 'name'
+  
   class << self
-    # Converts the specified record to an EmailAddress.  It will convert the
-    # following types:
-    # 1. String
-    # 2. A record with an +email_address+ String attribute
-    # 3. A record with an +email_address+ association
-    # 4. A record with an +email_addresses+ association (first record will be chosen)
-    # 
-    # If an EmailAddress is specified, the same model will be returned.  An
-    # ArgumentError is raised if it doesn't match any of the above criteria.
-    def convert_from(record)
-      if record
-        if EmailAddress === record
-          record
-        elsif String === record
-          EmailAddress.new(:spec => record)
-        elsif record.respond_to?(:email_address)
-          if record.email_address.is_a?(String)
-            address = EmailAddress.new(:spec => record.email_address)
-            address.name = record.name if record.respond_to?(:name)
-            address
-          else
-            record.email_address
-          end
-        elsif record.respond_to?(:email_addresses)
-          record.email_addresses.first
-        else
-          raise ArgumentError, "Cannot convert #{record.class} to an EmailAddress"
-        end
-      end
+    # Finds or create an email address based on the given value
+    def find_or_create_by_address(address)
+      name, spec = split_address(address)
+      find_or_create_by_name_and_spec(name, spec)
     end
     
-    # Determines if the given spec is a valid address using the RFC822 spec
-    def valid?(spec)
-      !RFC822::EmailAddress.match(spec).nil?
+    # Splits the given address into a name and spec
+    def split_address(address)
+      if match = /^(\S.*)\s+<(.*)>$/.match(address)
+        name = match[1]
+        spec = match[2]
+      else
+        spec = address
+      end
+      
+      return name, spec
     end
   end
   
-  acts_as_tokenized :token_field => 'verification_code', :token_length => 32
-  
-  # Support e-mail address verification
-  has_states    :initial => :unverified
-  
-  # Add messaging capabilities.  This will give us an email_box.
-  has_messages  :emails,
-                  :message_class => 'Email'
-  belongs_to    :emailable,
-                  :polymorphic => true
-  
-  validates_presence_of       :spec
-  
-  with_options(:allow_nil => true) do |klass|
-    klass.validates_uniqueness_of     :spec
-    klass.validates_as_email_address  :spec
-  end
-  
-  # The name of the person who owns this email address
-  attr_accessor :name
-  
-  # Ensure that the e-mail address has a verification code that can be sent
-  # to the user
-  before_create :set_code_expiry
-  
-  state :unverified, :verified
-  
-  # Verifies that the email address is valid
-  event :verify do
-    transition_to :verified, :from => :unverified
-  end
-  
-  # Sets the full address
-  def spec=(new_spec)
-    @local_name = @domain = nil
-    write_attribute(:spec, new_spec)
-  end
-  
-  # The part of the e-mail address before the @
-  def local_name
-    parse_spec if !@local_name
-    @local_name
-  end
-  
-  # The part of the e-mail address after the @
-  def domain
-    parse_spec if !@domain
-    @domain
-  end
-  
-  # Gets the name of the person whose email address this is.  Default is an
-  # empty string.  Override this if you want it to appear in with_name
-  def name
-    @name || ''
+  # Sets the value to be used for this email address.  This can come in two formats:
+  # * With name - John Doe <john.doe@gmail.com>
+  # * Without name - john.doe@gmail.com
+  def address=(address)
+    self.name, self.spec = self.class.split_address(address)
   end
   
-  # Returns a string version of the email address plus any name like
-  # "John Doe <john.doe@gmail.com>".  In order to have a valid name within the
-  # string, you must override +name+.
+  # Generates the value for the email address, including the name associated with
+  # it (if provided).  For example,
+  # 
+  #   e = EmailAddress.new(:name => 'John Doe', :spec => 'john.doe@gmail.com')
+  #   e.with_name # => "John Doe <john.doe@gmail.com>"
   def with_name
-    name.blank? ? to_s : "#{name} <#{to_s}>"
-  end
-  
-  # Returns the full email address (without the name)
-  def to_s #:nodoc
-    spec
-  end
-  
-  private
-  # Sets the time at which the verification code will expire
-  def set_code_expiry
-    self.code_expiry = 48.hour.from_now
-  end
-  
-  # Parses the current spec and sets +@local_name+ and +@domain+ based on the
-  # matching groups within the regular expression
-  def parse_spec
-    if !@local_name && !@domain && match = RFC822::EmailAddress.match(spec)
-      @local_name = match.captures[0]
-      @domain = match.captures[1]
-    end
+    name.blank? ? spec : "#{name} <#{spec}>"
   end
 end

data/db/migrate/001_create_email_addresses.rb

@@ -1,23 +1,14 @@
 class CreateEmailAddresses < ActiveRecord::Migration
   def self.up
     create_table :email_addresses do |t|
-      t.column :emailable_id, :integer, :null => false, :references => nil
-      t.column :emailable_type, :string, :null => false
-      t.column :spec, :string, :null => false, :limit => 382
-      t.column :verification_code, :string, :limit => 40
-      t.column :code_expiry, :datetime
-      t.column :created_at, :timestamp, :null => false
-      t.column :updated_at, :datetime, :null => false
+      t.string :spec, :null => false, :limit => 382
+      t.string :name
+      t.timestamps
     end
-    add_index :email_addresses, :spec, :unique => true
-    add_index :email_addresses, :verification_code, :unique => true
-    
-    PluginAWeek::Has::States.migrate_up(:email_addresses)
+    add_index :email_addresses, [:spec, :name], :unique => true
   end
   
   def self.down
-    PluginAWeek::Has::States.migrate_down(:email_addresses)
-    
     drop_table :email_addresses
   end
 end

data/lib/has_emails/extensions/action_mailer.rb

@@ -0,0 +1,106 @@
+module PluginAWeek #:nodoc:
+  module HasEmails
+    module Extensions #:nodoc:
+      # 
+      module ActionMailer
+        def self.included(base) #:nodoc:
+          base.class_eval do
+            @@default_subject_prefix = "[#{File.basename(File.expand_path(Rails.root)).camelize}] "
+            cattr_accessor :default_subject_prefix
+            
+            # Specify the prefix to use for the subject. This defaults to the
+            # +default_subject_prefix+ specified for ApplicationMailer.
+            adv_attr_accessor :subject_prefix
+            
+            include PluginAWeek::HasEmails::Extensions::ActionMailer::InstanceMethods
+            extend PluginAWeek::HasEmails::Extensions::ActionMailer::ClassMethods
+          end
+        end
+        
+        module ClassMethods
+          def self.extended(base) #:nodoc:
+            class << base
+              alias_method_chain :method_missing, :has_emails
+            end
+          end
+          
+          # Handles calls to queue_*
+          def method_missing_with_has_emails(method_symbol, *parameters)
+            case method_symbol.id2name
+              when /^queue_([_a-z]\w*)/
+                # Queues the mail so that it's processed in the background
+                new($1, *parameters).queue
+              else
+                # Handle the mail delivery as normal
+                method_missing_without_has_emails(method_symbol, *parameters)
+            end
+          end
+        end
+        
+        module InstanceMethods
+          def self.included(base) #:nodoc:
+            base.class_eval do
+              alias_method_chain :initialize_defaults, :subject_prefix
+              alias_method_chain :subject, :prefix
+              alias_method :subject=, :subject_with_prefix
+            end
+          end
+          
+          # Sets or gets the subject of the email.  All subjects are prefixed with a
+          # value indicating the application it is coming from.
+          def subject_with_prefix(*parameters)
+            if parameters.empty?
+              subject_without_prefix
+            else
+              subject_without_prefix(subject_prefix + subject_without_prefix(*parameters))
+            end
+          end
+          
+          # Sets the default subject prefix
+          def initialize_defaults_with_subject_prefix(method_name) #:nodoc
+            initialize_defaults_without_subject_prefix(method_name)
+            @subject_prefix ||= ::ActionMailer::Base.default_subject_prefix.dup
+          end
+          
+          # Delivers an email based on the content in the specified email
+          def email(email)
+            @from       = email.sender.with_name
+            @recipients = email.to.map(&:with_name)
+            @cc         = email.cc.map(&:with_name)
+            @bcc        = email.bcc.map(&:with_name)
+            @subject    = email.subject || ''
+            @body       = email.body || ''
+            @sent_on    = email.updated_at
+          end
+          
+          # Queues the current e-mail that has been constructed
+          def queue
+            Email.transaction do
+              # Create the main email
+              email = Email.new(
+                :sender => EmailAddress.find_or_create_by_address(from),
+                :subject => subject,
+                :body => body,
+                :to => email_addresses_for(:recipients),
+                :cc => email_addresses_for(:cc),
+                :bcc => email_addresses_for(:bcc)
+              )
+              email.queue!
+            end
+          end
+          
+          private
+            # Finds or creates all of the email addresses for the given type of
+            # recipient (can be :recipients, :cc, or :bcc)
+            def email_addresses_for(kind)
+              [send(kind)].flatten.collect {|address| EmailAddress.find_or_create_by_address(address)}
+            end
+        end
+      end
+    end
+  end
+end
+
+ActionMailer::Base.class_eval do
+  include PluginAWeek::HasEmails::Extensions::ActionMailer
+end