has_emails 0.1.2 → 0.1.3

data/CHANGELOG.rdoc

@@ -1,5 +1,9 @@
 == master
 
+== 0.1.3 / 2008-09-07
+
+* Add compatibility with state_machine 0.3.0
+
 == 0.1.2 / 2008-06-29
 
 * Add compatibility with has_messages 0.1.2

data/README.rdoc

@@ -91,6 +91,6 @@ To run against a specific version of Rails:
 == Dependencies
 
 * Rails 2.1 or later
-* plugins_plus[http://github.com/pluginaweek/plugins_plus]
 * has_messages[http://github.com/pluginaweek/has_messages]
 * state_machine[http://github.com/pluginaweek/state_machine]
+* plugins_plus[http://github.com/pluginaweek/plugins_plugins] (optional if app files are copied to your project tree)

data/Rakefile

@@ -5,15 +5,15 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'has_emails'
-  s.version           = '0.1.2'
+  s.version           = '0.1.3'
   s.platform          = Gem::Platform::RUBY
   s.summary           = 'Demonstrates a reference implementation for sending emails with logging and asynchronous support.'
   
-  s.files             = FileList['{app,db,lib,test}/**/*'].to_a - FileList['test/app_root/log/*'].to_a + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc)
+  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    'has_messages', '>= 0.1.2'
+  s.add_dependency    'has_messages', '>= 0.1.3'
   s.add_dependency    'validates_as_email_address', '>= 0.0.2'
   
   s.author            = 'Aaron Pfeifer'

data/app/models/email.rb

@@ -1,11 +1,13 @@
 # Represents an email which has been sent to one or more recipients.  This is
-# essentially the same as the Message class, but overrides how the it is
+# essentially the same as the Message class, but changes how the it is
 # delivered.
 class Email < Message
-  after_deliver :deliver_email
+  state_machine :state do
+    after_transition :on => 'deliver', :do => :deliver_email
+  end
   
   private
-    # Actually delivers the email to the recipients
+    # Actually delivers the email to the recipients using ActionMailer
     def deliver_email
       ActionMailer::Base.deliver_email(self)
     end

data/app/models/email_address.rb

@@ -1,4 +1,17 @@
-# Represents a valid RFC822 email address
+# Represents a valid RFC822 email address.  See http://www.w3.org/Protocols/rfc822/
+# for more information about the entire specification.
+# 
+# Email addresses are directly associated with emails and, therefore, should be
+# used for building and delivering new e-mails.
+# 
+# == Associations
+# 
+# Email addresses have the following associations defined as a result of using the
+# +has_emails+ macro:
+# * +emails+ - Emails that were composed and are visible to the owner.  Emails may have been sent or unsent.
+# * +received_emails+ - Emails that have been received from others and are visible.  Emails may have been read or unread.
+# * +unsent_emails+ - Emails that have not yet been delivered
+# * +sent_emails+ - Emails that have already been delivered
 class EmailAddress < ActiveRecord::Base
   has_emails
   
@@ -14,7 +27,10 @@ class EmailAddress < ActiveRecord::Base
       find_or_create_by_name_and_spec(name, spec)
     end
     
-    # Splits the given address into a name and spec
+    # Splits the given address into a name and spec. For example,
+    # 
+    #   EmailAddress.split_address("John Smith <john.smith@gmail.com")  # => ["John Smith", "john.smith@gmail.com"]
+    #   EmailAddress.split_address("john.smith@gmail.com")              # => [nil, "john.smith@gmail.com"]
     def split_address(address)
       if match = /^(\S.*)\s+<(.*)>$/.match(address)
         name = match[1]

data/lib/has_emails/extensions/action_mailer.rb

@@ -1,7 +1,21 @@
 module PluginAWeek #:nodoc:
   module HasEmails
     module Extensions #:nodoc:
+      # Adds support for queueing emails so that they can be procssed in the
+      # background.  Emails are stored in the database using the Email ActiveRecord
+      # model.
       # 
+      # == Queueing mail
+      # 
+      # Once a mailer action and template are defined, you can queue your message
+      # for background processing like so:
+      # 
+      #   Notifier.queue_signup_notification(john_smith) # Queues the email
+      # 
+      # If you were to deliver the mail immediately, the normal process would be
+      # used like so:
+      # 
+      #   Notifier.deliver_signup_notification(john_smith) # Delivers the email
       module ActionMailer
         def self.included(base) #:nodoc:
           base.class_eval do
@@ -9,7 +23,7 @@ module PluginAWeek #:nodoc:
             cattr_accessor :default_subject_prefix
             
             # Specify the prefix to use for the subject. This defaults to the
-            # +default_subject_prefix+ specified for ApplicationMailer.
+            # +default_subject_prefix+ specified for ActionMailer::Base.
             adv_attr_accessor :subject_prefix
             
             include PluginAWeek::HasEmails::Extensions::ActionMailer::InstanceMethods

data/lib/has_emails.rb

@@ -24,11 +24,9 @@ module PluginAWeek #:nodoc:
       #   email = user.emails.build
       #   email.subject = 'Hello'
       #   email.body = 'How are you?'
-      #   email.to User.EmailAddress(456)
+      #   email.to EmailAddress.find(456)
       #   email.save!
       #   email.deliver!
-      # 
-      # Alternatively, 
       def has_emails
         has_many  :emails,
                     :as => :sender,
@@ -47,12 +45,14 @@ module PluginAWeek #:nodoc:
     end
     
     module InstanceMethods
-      # Composed emails that have not yet been sent
+      # Composed emails that have not yet been sent.  These consists of all
+      # emails that are currently in the "unsent" state.
       def unsent_emails
         emails.with_state('unsent')
       end
       
-      # Composed emails that have already been sent
+      # Composed emails that have already been sent.  These consist of all emails
+      # that are currently in the "queued" or "sent states.
       def sent_emails
         emails.with_states(%w(queued sent))
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: has_emails
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors: 
 - Aaron Pfeifer
@@ -9,20 +9,22 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-06-29 00:00:00 -04:00
+date: 2008-09-07 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: has_messages
+  type: :runtime
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.1.2
+        version: 0.1.3
     version: 
 - !ruby/object:Gem::Dependency 
   name: validates_as_email_address
+  type: :runtime
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
@@ -58,7 +60,6 @@ files:
 - test/app_root/db/migrate
 - test/app_root/db/migrate/001_migrate_has_messages_to_version_2.rb
 - test/app_root/db/migrate/002_migrate_has_emails_to_version_1.rb
-- test/app_root/log
 - test/functional
 - test/functional/has_emails_test.rb
 - test/test_helper.rb
@@ -94,7 +95,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: pluginaweek
-rubygems_version: 1.1.1
+rubygems_version: 1.2.0
 signing_key: 
 specification_version: 2
 summary: Demonstrates a reference implementation for sending emails with logging and asynchronous support.