diff options
Diffstat (limited to 'actionmailer')
| -rw-r--r-- | actionmailer/CHANGELOG.md | 10 | ||||
| -rw-r--r-- | actionmailer/README.rdoc | 6 | ||||
| -rw-r--r-- | actionmailer/lib/action_mailer/base.rb | 21 | ||||
| -rw-r--r-- | actionmailer/lib/action_mailer/delivery_job.rb | 4 | ||||
| -rw-r--r-- | actionmailer/lib/action_mailer/message_delivery.rb | 89 | ||||
| -rw-r--r-- | actionmailer/lib/action_mailer/test_helper.rb | 12 |
6 files changed, 101 insertions, 41 deletions
diff --git a/actionmailer/CHANGELOG.md b/actionmailer/CHANGELOG.md index a4923de045..1ff4db41a3 100644 --- a/actionmailer/CHANGELOG.md +++ b/actionmailer/CHANGELOG.md @@ -1,7 +1,9 @@ -* Added #deliver_later in addition to #deliver, which will enqueue a job to render and - deliver the mail instead of delivering it right at that moment. The job is enqueued - using the new Active Job framework in Rails, and will use whatever queue is configured for Rails. - +* Added #deliver_later, #deliver_now and deprecate #deliver in favour of + #deliver_now. #deliver_later will enqueue a job to render and deliver + the mail instead of delivering it right at that moment. The job is enqueued + using the new Active Job framework in Rails, and will use whatever queue is + configured for Rails. + *DHH/Abdelkader Boudih/Cristian Bica* * Make ActionMailer::Previews methods class methods. Previously they were diff --git a/actionmailer/README.rdoc b/actionmailer/README.rdoc index ceca912ada..3b8e3ed749 100644 --- a/actionmailer/README.rdoc +++ b/actionmailer/README.rdoc @@ -65,12 +65,12 @@ In order to send mails, you simply call the method and then call +deliver+ on th Calling the method returns a Mail Message object: - message = Notifier.welcome("david@loudthinking.com") # => Returns a Mail::Message object - message.deliver # => delivers the email + message = Notifier.welcome("david@loudthinking.com") # => Returns a Mail::Message object + message.deliver_now # => delivers the email Or you can just chain the methods together like: - Notifier.welcome("david@loudthinking.com").deliver # Creates the email and sends it immediately + Notifier.welcome("david@loudthinking.com").deliver_now # Creates the email and sends it immediately == Setting defaults diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb index 9aae14ec8c..fc2d0936f9 100644 --- a/actionmailer/lib/action_mailer/base.rb +++ b/actionmailer/lib/action_mailer/base.rb @@ -138,9 +138,20 @@ module ActionMailer # Once a mailer action and template are defined, you can deliver your message or create it and save it # for delivery later: # - # Notifier.welcome(david).deliver # sends the email - # mail = Notifier.welcome(david) # => a Mail::Message object - # mail.deliver # sends the email + # Notifier.welcome(david).deliver_now # sends the email + # mail = Notifier.welcome(david) # => an ActionMailer::MessageDeliver object + # mail.deliver_now # sends the email + # + # The <tt>ActionMailer::MessageDeliver</tt> class is a wrapper around a <tt>Mail::Message</tt> object. If + # you want direct access to the <tt>Mail::Message</tt> object you can call the <tt>message</tt> method on + # the <tt>ActionMailer::MessageDeliver</tt> object. + # + # Notifier.welcome(david).message # => a Mail::Message object + # + # ActionMailer is nicely integrated with ActiveJob so you can send emails in the background (example: outside + # of the request-response cycle, so the user doesn't have to wait on it): + # + # Notifier.welcome(david).deliver_later # enqueue the email sending to ActiveJob # # You never instantiate your mailer class. Rather, you just call the method you defined on the class itself. # @@ -322,8 +333,8 @@ module ActionMailer # end # # Methods must return a <tt>Mail::Message</tt> object which can be generated by calling the mailer - # method without the additional <tt>deliver</tt>. The location of the mailer previews - # directory can be configured using the <tt>preview_path</tt> option which has a default + # method without the additional <tt>deliver_now</tt> / <tt>deliver_later</tt>. The location of the + # mailer previews directory can be configured using the <tt>preview_path</tt> option which has a default # of <tt>test/mailers/previews</tt>: # # config.action_mailer.preview_path = "#{Rails.root}/lib/mailer_previews" diff --git a/actionmailer/lib/action_mailer/delivery_job.rb b/actionmailer/lib/action_mailer/delivery_job.rb index b2cfa245fd..622f202695 100644 --- a/actionmailer/lib/action_mailer/delivery_job.rb +++ b/actionmailer/lib/action_mailer/delivery_job.rb @@ -1,10 +1,10 @@ require 'active_job' module ActionMailer - class DeliveryJob < ActiveJob::Base + class DeliveryJob < ActiveJob::Base #:nodoc: queue_as :mailers - def perform(mailer, mail_method, delivery_method, *args) + def perform(mailer, mail_method, delivery_method, *args) #:nodoc# mailer.constantize.public_send(mail_method, *args).send(delivery_method) end end diff --git a/actionmailer/lib/action_mailer/message_delivery.rb b/actionmailer/lib/action_mailer/message_delivery.rb index 8136483725..e65e79e741 100644 --- a/actionmailer/lib/action_mailer/message_delivery.rb +++ b/actionmailer/lib/action_mailer/message_delivery.rb @@ -1,65 +1,112 @@ require 'delegate' module ActionMailer + + # The ActionMailer::MessageDeliver class is used by ActionMailer::Base when + # creating a new mailer. MessageDeliver is a wrapper (Delegator subclass) + # around a lazy created Mail::Message. You can get direct access to the + # Mail::Message, deliver the email or schedule the email to be sent through ActiveJob. + # + # Notifier.welcome(david) # an ActionMailer::MessageDeliver object + # Notifier.welcome(david).deliver_now # sends the email + # Notifier.welcome(david).deliver_later # enqueue the deliver email job to ActiveJob + # Notifier.welcome(david).message # a Mail::Message object class MessageDelivery < Delegator - def initialize(mailer, mail_method, *args) + def initialize(mailer, mail_method, *args) #:nodoc: @mailer = mailer @mail_method = mail_method @args = args end - def __getobj__ + def __getobj__ #:nodoc: @obj ||= @mailer.send(:new, @mail_method, *@args).message end - def __setobj__(obj) + def __setobj__(obj) #:nodoc: @obj = obj end - def message #:nodoc: + # Returns the Mail::Message object + def message __getobj__ end + # Enqueues the message to be delivered through ActiveJob. When the + # ActiveJob job runs it will send the email using #deliver_now!. That + # means that the message will be sent bypassing checking perform_deliveries + # and raise_delivery_errors, so use with caution. + # + # ==== Examples + # + # Notifier.welcome(david).deliver_later + # Notifier.welcome(david).deliver_later(in: 1.hour) + # Notifier.welcome(david).deliver_later(at: 10.hours.from_now) + # + # ==== Options + # * <tt>in</tt> - Enqueue the message to be delivered with a delay + # * <tt>at</tt> - Enqueue the message to be delivered at (after) a specific date / time def deliver_later!(options={}) enqueue_delivery :deliver_now!, options end + # Enqueues the message to be delivered through ActiveJob. When the + # ActiveJob job runs it will send the email using #deliver_now. + # + # ==== Examples + # + # Notifier.welcome(david).deliver_later + # Notifier.welcome(david).deliver_later(in: 1.hour) + # Notifier.welcome(david).deliver_later(at: 10.hours.from_now) + # + # ==== Options + # * <tt>in</tt> - Enqueue the message to be delivered with a delay + # * <tt>at</tt> - Enqueue the message to be delivered at (after) a specific date / time def deliver_later(options={}) enqueue_delivery :deliver_now, options end + # Delivers a message. The message will be sent bypassing checking perform_deliveries + # and raise_delivery_errors, so use with caution. + # + # Notifier.welcome(david).deliver_now! + # def deliver_now! message.deliver! end + # Delivers a message: + # + # Notifier.welcome(david).deliver_now + # def deliver_now message.deliver end - def deliver! - ActiveSupport::Deprecation.warn "#deliver! is deprecated and will be removed on Rails 5. " \ - "Use #deliver_now! to deliver immediately or #deliver_later! to deliver through ActiveJob" + def deliver! #:nodoc: + ActiveSupport::Deprecation.warn "#deliver! is deprecated and will be removed in Rails 5. " \ + "Use #deliver_now! to deliver immediately or #deliver_later! to deliver through ActiveJob." deliver_now! end - def deliver - ActiveSupport::Deprecation.warn "#deliver is deprecated and will be removed on Rails 5. " \ - "Use #deliver_now to deliver immediately or #deliver_later to deliver through ActiveJob" + def deliver #:nodoc: + ActiveSupport::Deprecation.warn "#deliver is deprecated and will be removed in Rails 5. " \ + "Use #deliver_now to deliver immediately or #deliver_later to deliver through ActiveJob." deliver_now end private - def enqueue_delivery(delivery_method, options={}) - args = @mailer.name, @mail_method.to_s, delivery_method.to_s, *@args - enqueue_method = :enqueue - if options[:at] - enqueue_method = :enqueue_at - args.unshift options[:at] - elsif options[:in] - enqueue_method = :enqueue_in - args.unshift options[:in] + + def enqueue_delivery(delivery_method, options={}) + args = @mailer.name, @mail_method.to_s, delivery_method.to_s, *@args + enqueue_method = :enqueue + if options[:at] + enqueue_method = :enqueue_at + args.unshift options[:at] + elsif options[:in] + enqueue_method = :enqueue_in + args.unshift options[:in] + end + ActionMailer::DeliveryJob.send enqueue_method, *args end - ActionMailer::DeliveryJob.send enqueue_method, *args - end end end diff --git a/actionmailer/lib/action_mailer/test_helper.rb b/actionmailer/lib/action_mailer/test_helper.rb index 06da0dd27e..6ddacf7b79 100644 --- a/actionmailer/lib/action_mailer/test_helper.rb +++ b/actionmailer/lib/action_mailer/test_helper.rb @@ -6,9 +6,9 @@ module ActionMailer # # def test_emails # assert_emails 0 - # ContactMailer.welcome.deliver + # ContactMailer.welcome.deliver_now # assert_emails 1 - # ContactMailer.welcome.deliver + # ContactMailer.welcome.deliver_now # assert_emails 2 # end # @@ -17,12 +17,12 @@ module ActionMailer # # def test_emails_again # assert_emails 1 do - # ContactMailer.welcome.deliver + # ContactMailer.welcome.deliver_now # end # # assert_emails 2 do - # ContactMailer.welcome.deliver - # ContactMailer.welcome.deliver + # ContactMailer.welcome.deliver_now + # ContactMailer.welcome.deliver_now # end # end def assert_emails(number) @@ -40,7 +40,7 @@ module ActionMailer # # def test_emails # assert_no_emails - # ContactMailer.welcome.deliver + # ContactMailer.welcome.deliver_now # assert_emails 1 # end # |