diff options
Diffstat (limited to 'actionmailer/lib/action_mailer/base.rb')
| -rw-r--r-- | actionmailer/lib/action_mailer/base.rb | 185 |
1 files changed, 125 insertions, 60 deletions
diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb index ff74185e37..275f657f8a 100644 --- a/actionmailer/lib/action_mailer/base.rb +++ b/actionmailer/lib/action_mailer/base.rb @@ -3,6 +3,7 @@ require 'action_mailer/collector' require 'active_support/core_ext/string/inflections' require 'active_support/core_ext/hash/except' require 'active_support/core_ext/module/anonymous' + require 'action_mailer/log_subscriber' module ActionMailer @@ -49,7 +50,7 @@ module ActionMailer # # * <tt>mail</tt> - Allows you to specify email to be sent. # - # The hash passed to the mail method allows you to specify any header that a Mail::Message + # The hash passed to the mail method allows you to specify any header that a <tt>Mail::Message</tt> # will accept (any valid Email header including optional fields). # # The mail method, if not passed a block, will inspect your views and send all the views with @@ -151,9 +152,9 @@ module ActionMailer # # For example, if the following templates exist: # * signup_notification.text.erb - # * signup_notification.text.html.erb - # * signup_notification.text.xml.builder - # * signup_notification.text.yaml.erb + # * signup_notification.html.erb + # * signup_notification.xml.builder + # * signup_notification.yaml.erb # # Each would be rendered and added as a separate part to the message, with the corresponding content # type. The content type for the entire message is automatically set to <tt>multipart/alternative</tt>, @@ -175,7 +176,7 @@ module ActionMailer # end # end # - # Which will (if it had both a <tt>welcome.text.erb</tt> and <tt>welcome.text.html.erb</tt> + # Which will (if it had both a <tt>welcome.text.erb</tt> and <tt>welcome.html.erb</tt> # template in the view directory), send a complete <tt>multipart/mixed</tt> email with two parts, # the first part being a <tt>multipart/alternative</tt> with the text and HTML email parts inside, # and the second being a <tt>application/pdf</tt> with a Base64 encoded copy of the file.pdf book @@ -228,7 +229,7 @@ module ActionMailer # An interceptor class must implement the <tt>:delivering_email(message)</tt> method which will be # called before the email is sent, allowing you to make modifications to the email before it hits # the delivery agents. Your class should make any needed modifications directly to the passed - # in Mail::Message instance. + # in <tt>Mail::Message</tt> instance. # # = Default Hash # @@ -307,6 +308,28 @@ module ActionMailer # Note that unless you have a specific reason to do so, you should prefer using before_action # rather than after_action in your ActionMailer classes so that headers are parsed properly. # + # = Previewing emails + # + # You can preview your email templates visually by adding a mailer preview file to the + # <tt>ActionMailer::Base.preview_path</tt>. Since most emails do something interesting + # with database data, you'll need to write some scenarios to load messages with fake data: + # + # class NotifierPreview < ActionMailer::Preview + # def welcome + # Notifier.welcome(User.first) + # end + # 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 + # of <tt>test/mailers/previews</tt>: + # + # config.action_mailer.preview_path = "#{Rails.root}/lib/mailer_previews" + # + # An overview of all previews is accessible at <tt>http://localhost:3000/rails/mailers</tt> + # on a running development server instance. + # # = Configuration options # # These options are specified on the class level, like @@ -316,7 +339,7 @@ module ActionMailer # per the above section. # # * <tt>logger</tt> - the logger is used for generating information on the mailing run if available. - # Can be set to nil for no logging. Compatible with both Ruby's own Logger and Log4r loggers. + # Can be set to +nil+ for no logging. Compatible with both Ruby's own +Logger+ and Log4r loggers. # # * <tt>smtp_settings</tt> - Allows detailed configuration for <tt>:smtp</tt> delivery method: # * <tt>:address</tt> - Allows you to use a remote mail server. Just change it from its default @@ -334,8 +357,9 @@ module ActionMailer # and starts to use it. # * <tt>:openssl_verify_mode</tt> - When using TLS, you can set how OpenSSL checks the certificate. This is # really useful if you need to validate a self-signed and/or a wildcard certificate. You can use the name - # of an OpenSSL verify constant ('none', 'peer', 'client_once','fail_if_no_peer_cert') or directly the - # constant (OpenSSL::SSL::VERIFY_NONE, OpenSSL::SSL::VERIFY_PEER,...). + # of an OpenSSL verify constant (<tt>'none'</tt>, <tt>'peer'</tt>, <tt>'client_once'</tt>, + # <tt>'fail_if_no_peer_cert'</tt>) or directly the constant (<tt>OpenSSL::SSL::VERIFY_NONE</tt>, + # <tt>OpenSSL::SSL::VERIFY_PEER</tt>, ...). # # * <tt>sendmail_settings</tt> - Allows you to override options for the <tt>:sendmail</tt> delivery method. # * <tt>:location</tt> - The location of the sendmail executable. Defaults to <tt>/usr/sbin/sendmail</tt>. @@ -350,7 +374,7 @@ module ActionMailer # # * <tt>delivery_method</tt> - Defines a delivery method. Possible values are <tt>:smtp</tt> (default), # <tt>:sendmail</tt>, <tt>:test</tt>, and <tt>:file</tt>. Or you may provide a custom delivery method - # object e.g. MyOwnDeliveryMethodClass. See the Mail gem documentation on the interface you need to + # object e.g. +MyOwnDeliveryMethodClass+. See the Mail gem documentation on the interface you need to # implement for a custom delivery agent. # # * <tt>perform_deliveries</tt> - Determines whether emails are actually sent from Action Mailer when you @@ -361,17 +385,25 @@ module ActionMailer # <tt>delivery_method :test</tt>. Most useful for unit and functional testing. class Base < AbstractController::Base include DeliveryMethods + include Previews + abstract! - include AbstractController::Logger include AbstractController::Rendering - include AbstractController::Layouts + + include AbstractController::Logger include AbstractController::Helpers include AbstractController::Translation include AbstractController::AssetPaths include AbstractController::Callbacks - self.protected_instance_variables = [:@_action_has_layout] + include ActionView::Layouts + + PROTECTED_IVARS = AbstractController::Rendering::DEFAULT_PROTECTED_INSTANCE_VARIABLES + [:@_action_has_layout] + + def _protected_ivars # :nodoc: + PROTECTED_IVARS + end helper ActionMailer::MailHelper @@ -412,12 +444,20 @@ module ActionMailer Mail.register_interceptor(delivery_interceptor) end + # Returns the name of current mailer. This method is also being used as a path for a view lookup. + # If this is an anonymous mailer, this method will return +anonymous+ instead. def mailer_name @mailer_name ||= anonymous? ? "anonymous" : name.underscore end + # Allows to set the name of current mailer. attr_writer :mailer_name alias :controller_path :mailer_name + # Sets the defaults through app configuration: + # + # config.action_mailer.default { from: "no-reply@example.org" } + # + # Aliased by ::default_options= def default(value = nil) self.default_params = default_params.merge(value).freeze if value default_params @@ -429,13 +469,15 @@ module ActionMailer # Receives a raw email, parses it into an email object, decodes it, # instantiates a new mailer, and passes the email object to the mailer - # object's +receive+ method. If you want your mailer to be able to - # process incoming messages, you'll need to implement a +receive+ - # method that accepts the raw email string as a parameter: + # object's +receive+ method. + # + # If you want your mailer to be able to process incoming messages, you'll + # need to implement a +receive+ method that accepts the raw email string + # as a parameter: # # class MyMailer < ActionMailer::Base # def receive(mail) - # ... + # # ... # end # end def receive(raw_mail) @@ -446,10 +488,12 @@ module ActionMailer end end - # Wraps an email delivery inside of Active Support Notifications instrumentation. This - # method is actually called by the <tt>Mail::Message</tt> object itself through a callback - # when you call <tt>:deliver</tt> on the Mail::Message, calling +deliver_mail+ directly - # and passing a Mail::Message will do nothing except tell the logger you sent the email. + # Wraps an email delivery inside of <tt>ActiveSupport::Notifications</tt> instrumentation. + # + # This method is actually called by the <tt>Mail::Message</tt> object itself + # through a callback when you call <tt>:deliver</tt> on the <tt>Mail::Message</tt>, + # calling +deliver_mail+ directly and passing a <tt>Mail::Message</tt> will do + # nothing except tell the logger you sent the email. def deliver_mail(mail) #:nodoc: ActiveSupport::Notifications.instrument("deliver.action_mailer") do |payload| set_payload_for_mail(payload, mail) @@ -475,7 +519,7 @@ module ActionMailer payload[:mail] = mail.encoded end - def method_missing(method_name, *args) + def method_missing(method_name, *args) # :nodoc: if respond_to?(method_name) new(method_name, *args).message else @@ -497,11 +541,18 @@ module ActionMailer process(method_name, *args) if method_name end - def process(*args) #:nodoc: - lookup_context.skip_default_locale! + def process(method_name, *args) #:nodoc: + payload = { + mailer: self.class.name, + action: method_name + } + + ActiveSupport::Notifications.instrument("process.action_mailer", payload) do + lookup_context.skip_default_locale! - super - @_message = NullMail.new unless @_mail_was_called + super + @_message = NullMail.new unless @_mail_was_called + end end class NullMail #:nodoc: @@ -512,22 +563,23 @@ module ActionMailer end end + # Returns the name of the mailer object. def mailer_name self.class.mailer_name end - # Allows you to pass random and unusual headers to the new <tt>Mail::Message</tt> object - # which will add them to itself. + # Allows you to pass random and unusual headers to the new <tt>Mail::Message</tt> + # object which will add them to itself. # # headers['X-Special-Domain-Specific-Header'] = "SecretValue" # - # You can also pass a hash into headers of header field names and values, which - # will then be set on the Mail::Message object: + # You can also pass a hash into headers of header field names and values, + # which will then be set on the <tt>Mail::Message</tt> object: # # headers 'X-Special-Domain-Specific-Header' => "SecretValue", # 'In-Reply-To' => incoming.message_id # - # The resulting Mail::Message will have the following in its header: + # The resulting <tt>Mail::Message</tt> will have the following in its header: # # X-Special-Domain-Specific-Header: SecretValue def headers(args = nil) @@ -578,44 +630,46 @@ module ActionMailer # Both methods accept a headers hash. This hash allows you to specify the most used headers # in an email message, these are: # - # * <tt>:subject</tt> - The subject of the message, if this is omitted, Action Mailer will - # ask the Rails I18n class for a translated <tt>:subject</tt> in the scope of + # * +:subject+ - The subject of the message, if this is omitted, Action Mailer will + # ask the Rails I18n class for a translated +:subject+ in the scope of # <tt>[mailer_scope, action_name]</tt> or if this is missing, will translate the - # humanized version of the <tt>action_name</tt> - # * <tt>:to</tt> - Who the message is destined for, can be a string of addresses, or an array + # humanized version of the +action_name+ + # * +:to+ - Who the message is destined for, can be a string of addresses, or an array # of addresses. - # * <tt>:from</tt> - Who the message is from - # * <tt>:cc</tt> - Who you would like to Carbon-Copy on this email, can be a string of addresses, + # * +:from+ - Who the message is from + # * +:cc+ - Who you would like to Carbon-Copy on this email, can be a string of addresses, # or an array of addresses. - # * <tt>:bcc</tt> - Who you would like to Blind-Carbon-Copy on this email, can be a string of + # * +:bcc+ - Who you would like to Blind-Carbon-Copy on this email, can be a string of # addresses, or an array of addresses. - # * <tt>:reply_to</tt> - Who to set the Reply-To header of the email to. - # * <tt>:date</tt> - The date to say the email was sent on. + # * +:reply_to+ - Who to set the Reply-To header of the email to. + # * +:date+ - The date to say the email was sent on. # - # You can set default values for any of the above headers (except :date) by using the <tt>default</tt> - # class method: + # You can set default values for any of the above headers (except +:date+) + # by using the ::default class method: # # class Notifier < ActionMailer::Base - # self.default from: 'no-reply@test.lindsaar.net', - # bcc: 'email_logger@test.lindsaar.net', - # reply_to: 'bounces@test.lindsaar.net' + # default from: 'no-reply@test.lindsaar.net', + # bcc: 'email_logger@test.lindsaar.net', + # reply_to: 'bounces@test.lindsaar.net' # end # # If you need other headers not listed above, you can either pass them in # as part of the headers hash or use the <tt>headers['name'] = value</tt> # method. # - # When a <tt>:return_path</tt> is specified as header, that value will be used as the 'envelope from' - # address for the Mail message. Setting this is useful when you want delivery notifications - # sent to a different address than the one in <tt>:from</tt>. Mail will actually use the - # <tt>:return_path</tt> in preference to the <tt>:sender</tt> in preference to the <tt>:from</tt> - # field for the 'envelope from' value. + # When a +:return_path+ is specified as header, that value will be used as + # the 'envelope from' address for the Mail message. Setting this is useful + # when you want delivery notifications sent to a different address than the + # one in +:from+. Mail will actually use the +:return_path+ in preference + # to the +:sender+ in preference to the +:from+ field for the 'envelope + # from' value. # - # If you do not pass a block to the +mail+ method, it will find all templates in the - # view paths using by default the mailer name and the method name that it is being - # called from, it will then create parts for each of these templates intelligently, - # making educated guesses on correct content type and sequence, and return a fully - # prepared Mail::Message ready to call <tt>:deliver</tt> on to send. + # If you do not pass a block to the +mail+ method, it will find all + # templates in the view paths using by default the mailer name and the + # method name that it is being called from, it will then create parts for + # each of these templates intelligently, making educated guesses on correct + # content type and sequence, and return a fully prepared <tt>Mail::Message</tt> + # ready to call <tt>:deliver</tt> on to send. # # For example: # @@ -650,8 +704,8 @@ module ActionMailer # format.html { render text: "<h1>Hello Mikel!</h1>" } # end # - # Which will render a <tt>multipart/alternative</tt> email with <tt>text/plain</tt> and - # <tt>text/html</tt> parts. + # Which will render a +multipart/alternative+ email with +text/plain+ and + # +text/html+ parts. # # The block syntax also allows you to customize the part headers if desired: # @@ -661,6 +715,8 @@ module ActionMailer # end # def mail(headers = {}, &block) + return @_message if @_mail_was_called && headers.blank? && !block + @_mail_was_called = true m = @_message @@ -668,9 +724,9 @@ module ActionMailer content_type = headers[:content_type] # Call all the procs (if any) - class_default = self.class.default - default_values = class_default.merge(class_default) do |k,v| - v.respond_to?(:to_proc) ? instance_eval(&v) : v + default_values = {} + self.class.default.each do |k,v| + default_values[k] = v.is_a?(Proc) ? instance_eval(&v) : v end # Handle defaults @@ -705,6 +761,15 @@ module ActionMailer protected + # Used by #mail to set the content type of the message. + # + # It will use the given +user_content_type+, or multipart if the mail + # message has any attachments. If the attachments are inline, the content + # type will be "multipart/related", otherwise "multipart/mixed". + # + # If there is no content type passed in via headers, and there are no + # attachments, or the message is multipart, then the default content type is + # used. def set_content_type(m, user_content_type, class_default) params = m.content_type_parameters || {} case |