From 9e7f4a94caa9019b2ef0295ad242fbed0acf8bb6 Mon Sep 17 00:00:00 2001 From: Cristian Bica Date: Wed, 20 Aug 2014 15:34:37 +0300 Subject: Updated rdoc / guides / release notes related to ActiveJob / ActionMailer --- guides/source/4_2_release_notes.md | 3 +++ guides/source/action_mailer_basics.md | 32 ++++++++++++++++++++++++++++---- guides/source/active_job_basics.md | 6 +++--- guides/source/active_record_querying.md | 10 +++++----- guides/source/testing.md | 2 +- 5 files changed, 40 insertions(+), 13 deletions(-) (limited to 'guides') diff --git a/guides/source/4_2_release_notes.md b/guides/source/4_2_release_notes.md index aa056f5844..864026e9f2 100644 --- a/guides/source/4_2_release_notes.md +++ b/guides/source/4_2_release_notes.md @@ -311,6 +311,9 @@ Please refer to the [Changelog][action-mailer] for detailed changes. * Deprecated `*_path` helpers in mailers. Always use `*_url` helpers instead. ([Pull Request](https://github.com/rails/rails/pull/15840)) +* Deprecated `deliver` / `deliver!` in favour of `deliver_now` / `deliver_now!`. + ([Pull Request](https://github.com/rails/rails/pull/16582)) + ### Notable changes * Introduced `deliver_later` which enqueues a job on the application's queue diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md index 9ad9319255..6b6ce145e4 100644 --- a/guides/source/action_mailer_basics.md +++ b/guides/source/action_mailer_basics.md @@ -159,7 +159,10 @@ $ bin/rake db:migrate Now that we have a user model to play with, we will just edit the `app/controllers/users_controller.rb` make it instruct the `UserMailer` to deliver an email to the newly created user by editing the create action and inserting a -call to `UserMailer.welcome_email` right after the user is successfully saved: +call to `UserMailer.welcome_email` right after the user is successfully saved. + +Action Mailer is nicely integrated with Active Job so you can send emails outside +of the request-response cycle, so the user doesn't have to wait on it: ```ruby class UsersController < ApplicationController @@ -171,7 +174,7 @@ class UsersController < ApplicationController respond_to do |format| if @user.save # Tell the UserMailer to send a welcome email after save - UserMailer.welcome_email(@user).deliver + UserMailer.welcome_email(@user).deliver_later format.html { redirect_to(@user, notice: 'User was successfully created.') } format.json { render json: @user, status: :created, location: @user } @@ -184,8 +187,29 @@ class UsersController < ApplicationController end ``` -The method `welcome_email` returns a `Mail::Message` object which can then just -be told `deliver` to send itself out. +NOTE: By default Active Job is configured to execute the job `:inline`. So you can +use `deliver_later` now to send the emails and when you decide to start sending the +email from a background job you'll just have to setup Active Job to use a queueing +backend (Sidekiq, Resque, etc). + +If you want to send the emails right away (from a cronjob for example) just +call `deliver_now`: + +```ruby +class SendWeeklySummary + def run + User.find_each do |user| + UserMailer.weekly_summary(user).deliver_now + end + end +end +``` + +The method `welcome_email` returns a `ActionMailer::MessageDelivery` object which +can then just be told `deliver_now` or `deliver_later` to send itself out. The +`ActionMailer::MessageDelivery` object is just a wrapper around a `Mail::Message`. If +you want to inspect, alter or do anything else with the `Mail::Message` object you can +access it with the `message` method on the `ActionMailer::MessageDelivery` object. ### Auto encoding header values diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md index ae5d21d546..0df4320e36 100644 --- a/guides/source/active_job_basics.md +++ b/guides/source/active_job_basics.md @@ -196,10 +196,10 @@ of the request-response cycle, so the user doesn't have to wait on it. Active Jo is integrated with Action Mailer so you can easily send emails async: ```ruby -# Instead of the classic -UserMailer.welcome(@user).deliver +# If you want to send the email now use #deliver_now +UserMailer.welcome(@user).deliver_now -# use #deliver later to send the email async +# If you want to send the email through ActiveJob use #deliver_later UserMailer.welcome(@user).deliver_later ``` diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index f9b46286c1..cb243c95f5 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -276,7 +276,7 @@ This may appear straightforward: ```ruby # This is very inefficient when the users table has thousands of rows. User.all.each do |user| - NewsMailer.weekly(user).deliver + NewsMailer.weekly(user).deliver_now end ``` @@ -292,7 +292,7 @@ The `find_each` method retrieves a batch of records and then yields _each_ recor ```ruby User.find_each do |user| - NewsMailer.weekly(user).deliver + NewsMailer.weekly(user).deliver_now end ``` @@ -300,7 +300,7 @@ To add conditions to a `find_each` operation you can chain other Active Record m ```ruby User.where(weekly_subscriber: true).find_each do |user| - NewsMailer.weekly(user).deliver + NewsMailer.weekly(user).deliver_now end ``` @@ -316,7 +316,7 @@ The `:batch_size` option allows you to specify the number of records to be retri ```ruby User.find_each(batch_size: 5000) do |user| - NewsMailer.weekly(user).deliver + NewsMailer.weekly(user).deliver_now end ``` @@ -328,7 +328,7 @@ For example, to send newsletters only to users with the primary key starting fro ```ruby User.find_each(start: 2000, batch_size: 5000) do |user| - NewsMailer.weekly(user).deliver + NewsMailer.weekly(user).deliver_now end ``` diff --git a/guides/source/testing.md b/guides/source/testing.md index 2ecd560a87..d91f13699a 100644 --- a/guides/source/testing.md +++ b/guides/source/testing.md @@ -949,7 +949,7 @@ class UserMailerTest < ActionMailer::TestCase test "invite" do # Send the email, then test that it got queued email = UserMailer.create_invite('me@example.com', - 'friend@example.com', Time.now).deliver + 'friend@example.com', Time.now).deliver_now assert_not ActionMailer::Base.deliveries.empty? # Test the body of the sent email contains what we expect it to -- cgit v1.2.3