Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 612 lines (570 sloc) 26.393 kb
a9751a7 @josevalim Refactor ActionMailer layout and remove legacy one.
josevalim authored
1 require 'active_support/core_ext/class'
0ece244 Ensure implicit multipart templates with locale works as expected.
José Valim and Mikel Lindsaar authored
2 require 'active_support/core_ext/object/blank'
3 require 'active_support/core_ext/array/uniq_by'
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
4 require 'active_support/core_ext/module/delegation'
0ece244 Ensure implicit multipart templates with locale works as expected.
José Valim and Mikel Lindsaar authored
5 require 'active_support/core_ext/string/inflections'
616ebb8 @josevalim Remove unused code paths and require mail only when it's needed.
josevalim authored
6 require 'mail'
a288082 @mikel Adding :transfer_encoding -> :content_transfer_encoding as part of Tmail...
mikel authored
7 require 'action_mailer/tmail_compat'
c985a0e Add some tests to collector with templates and any.
José Valim and Mikel Lindsaar authored
8 require 'action_mailer/collector'
a63caa4 Get tests to run (with failures) without old base around
Yehuda Katz + Carl Lerche authored
9
c4590d5 @dhh Fixed docs
dhh authored
10 module ActionMailer #:nodoc:
98dc582 @lifo Merge docrails.
lifo authored
11 # Action Mailer allows you to send email from your application using a mailer model and views.
db045db @dhh Initial
dhh authored
12 #
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
13 # = Mailer Models
20bd4bd @dhh Updated docs and otherwise
dhh authored
14 #
98dc582 @lifo Merge docrails.
lifo authored
15 # To use Action Mailer, you need to create a mailer model.
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
16 #
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
17 # $ script/generate mailer Notifier
18 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
19 # The generated model inherits from ActionMailer::Base. Emails are defined by creating methods
20 # within the model which are then used to set variables to be used in the mail template, to
21 # change options on the mail, or to add attachments.
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
22 #
23 # Examples:
24 #
25 # class Notifier < ActionMailer::Base
ccea6ab @mikel Fixing up tests and docs to use defaults :from => 'name' instead of defa...
mikel authored
26 # defaults :from => 'no-reply@example.com',
27 # :return_path => 'system@example.com'
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
28 #
29 # def welcome(recipient)
30 # @account = recipient
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
31 # mail(:to => recipient.email_address_with_name,
32 # :bcc => ["bcc@example.com", "Order Watcher <watcher@example.com>"])
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
33 # end
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
34 # end
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
35 #
36 # Within the mailer method, you have access to the following methods:
37 #
38 # * <tt>attachments[]=</tt> - Allows you to add attachments to your email in an intuitive
39 # manner; <tt>attachments['filename.png'] = File.read('path/to/filename.png')</tt>
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
40 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
41 # * <tt>headers[]=</tt> - Allows you to specify non standard headers in your email such
42 # as <tt>headers['X-No-Spam'] = 'True'</tt>
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
43 #
9520166 @mikel Fixed up being able to pass random headers in with headers, or mail. Al...
mikel authored
44 # * <tt>headers(hash)</tt> - Allows you to specify multiple headers in your email such
45 # as <tt>headers({'X-No-Spam' => 'True', 'In-Reply-To' => '1234@message.id'})</tt>
46 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
47 # * <tt>mail</tt> - Allows you to specify your email to send.
48 #
9520166 @mikel Fixed up being able to pass random headers in with headers, or mail. Al...
mikel authored
49 # The hash passed to the mail method allows you to specify any header that a Mail::Message
50 # will accept (any valid Email header including optional fields). Obviously if you specify
51 # the same header in the headers method and then again in the mail method, the last one
52 # will over write the first, unless you are specifying a header field that can appear more
53 # than once per RFC, in which case, both will be inserted (X-value headers for example can
54 # appear multiple times.)
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
55 #
56 # The mail method, if not passed a block, will inspect your views and send all the views with
57 # the same name as the method, so the above action would send the +welcome.plain.erb+ view file
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
58 # as well as the +welcome.html.erb+ view file in a +multipart/alternative+ email.
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
59 #
60 # If you want to explicitly render only certain templates, pass a block:
61 #
62 # mail(:to => user.emai) do |format|
63 # format.text
64 # format.html
65 # end
20bd4bd @dhh Updated docs and otherwise
dhh authored
66 #
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
67 # The block syntax is useful if also need to specify information specific to a part:
68 #
69 # mail(:to => user.emai) do |format|
70 # format.text(:content_transfer_encoding => "base64")
71 # format.html
72 # end
73 #
74 # Or even to renderize a special view:
75 #
76 # mail(:to => user.emai) do |format|
77 # format.text
78 # format.html { render "some_other_template" }
79 # end
80 #
20bd4bd @dhh Updated docs and otherwise
dhh authored
81 # = Mailer views
82 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
83 # Like Action Controller, each mailer class has a corresponding view directory in which each
84 # method of the class looks for a template with its name.
85 #
86 # To define a template to be used with a mailing, create an <tt>.erb</tt> file with the same
87 # name as the method in your mailer model. For example, in the mailer defined above, the template at
88 # <tt>app/views/notifier/signup_notification.text.erb</tt> would be used to generate the email.
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
89 #
90 # Variables defined in the model are accessible as instance variables in the view.
91 #
92 # Emails by default are sent in plain text, so a sample view for our model example might look like this:
93 #
94 # Hi <%= @account.name %>,
95 # Thanks for joining our service! Please check back often.
96 #
20bd4bd @dhh Updated docs and otherwise
dhh authored
97 # You can even use Action Pack helpers in these views. For example:
98 #
99 # You got a new note!
ee70d1b @josevalim adv_attr_accessors in ActionMailer are not sent to the views, use the ma...
josevalim authored
100 # <%= truncate(@note.body, 25) %>
101 #
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
102 # If you need to access the subject, from or the recipients in the view, you can do that through message object:
ee70d1b @josevalim adv_attr_accessors in ActionMailer are not sent to the views, use the ma...
josevalim authored
103 #
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
104 # You got a new note from <%= message.from %>!
ee70d1b @josevalim adv_attr_accessors in ActionMailer are not sent to the views, use the ma...
josevalim authored
105 # <%= truncate(@note.body, 25) %>
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
106 #
20bd4bd @dhh Updated docs and otherwise
dhh authored
107 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
108 # = Generating URLs
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
109 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
110 # URLs can be generated in mailer views using <tt>url_for</tt> or named routes.
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
111 # Unlike controllers from Action Pack, the mailer instance doesn't have any context about the incoming request,
112 # so you'll need to provide all of the details needed to generate a URL.
20bd4bd @dhh Updated docs and otherwise
dhh authored
113 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
114 # When using <tt>url_for</tt> you'll need to provide the <tt>:host</tt>, <tt>:controller</tt>, and <tt>:action</tt>:
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
115 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
116 # <%= url_for(:host => "example.com", :controller => "welcome", :action => "greeting") %>
20bd4bd @dhh Updated docs and otherwise
dhh authored
117 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
118 # When using named routes you only need to supply the <tt>:host</tt>:
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
119 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
120 # <%= users_url(:host => "example.com") %>
121 #
122 # You will want to avoid using the <tt>name_of_route_path</tt> form of named routes because it doesn't make sense to
123 # generate relative URLs in email messages.
124 #
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
125 # It is also possible to set a default host that will be used in all mailers by setting the <tt>:host</tt> option in
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
126 # the <tt>ActionMailer::Base.default_url_options</tt> hash as follows:
127 #
128 # ActionMailer::Base.default_url_options[:host] = "example.com"
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
129 #
dc4eec1 @lifo Merge docrails:
lifo authored
130 # This can also be set as a configuration option in <tt>config/environment.rb</tt>:
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
131 #
132 # config.action_mailer.default_url_options = { :host => "example.com" }
20bd4bd @dhh Updated docs and otherwise
dhh authored
133 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
134 # If you do decide to set a default <tt>:host</tt> for your mailers you will want to use the
135 # <tt>:only_path => false</tt> option when using <tt>url_for</tt>. This will ensure that absolute URLs are generated because
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
136 # the <tt>url_for</tt> view helper will, by default, generate relative URLs when a <tt>:host</tt> option isn't
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
137 # explicitly provided.
20bd4bd @dhh Updated docs and otherwise
dhh authored
138 #
139 # = Sending mail
140 #
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
141 # Once a mailer action and template are defined, you can deliver your message or create it and save it
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
142 # for delivery later:
143 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
144 # Notifier.welcome(david).deliver # sends the email
145 # mail = Notifier.welcome(david) # => a Mail::Message object
146 # mail.deliver # sends the email
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
147 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
148 # You never instantiate your mailer class. Rather, you just call the method on the class itself.
20bd4bd @dhh Updated docs and otherwise
dhh authored
149 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
150 # = Multipart Emails
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
151 #
98dc582 @lifo Merge docrails.
lifo authored
152 # Multipart messages can also be used implicitly because Action Mailer will automatically
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
153 # detect and use multipart templates, where each template is named after the name of the action, followed
154 # by the content type. Each such detected template will be added as separate part to the message.
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
155 #
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
156 # For example, if the following templates existed:
21187c0 @dhh Apply the rest of Chads patch
dhh authored
157 # * signup_notification.text.plain.erb
158 # * signup_notification.text.html.erb
159 # * signup_notification.text.xml.builder
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
160 # * signup_notification.text.yaml.erb
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
161 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
162 # Each would be rendered and added as a separate part to the message, with the corresponding content
163 # type. The content type for the entire message is automatically set to <tt>multipart/alternative</tt>,
164 # which indicates that the email contains multiple different representations of the same email
165 # body. The same instance variables defined in the action are passed to all email templates.
359caef @jamis A very thorough refactoring, resulting in new mail property setters and ...
jamis authored
166 #
46f30f9 @lifo Merge documentation changes from docrails.
lifo authored
167 # Implicit template rendering is not performed if any attachments or parts have been added to the email.
168 # This means that you'll have to manually add each part to the email and set the content type of the email
169 # to <tt>multipart/alternative</tt>.
20bd4bd @dhh Updated docs and otherwise
dhh authored
170 #
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
171 # = Attachments
20bd4bd @dhh Updated docs and otherwise
dhh authored
172 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
173 # You can see above how to make a multipart HTML / Text email, to send attachments is just
174 # as easy:
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
175 #
176 # class ApplicationMailer < ActionMailer::Base
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
177 # def welcome(recipient)
178 # attachments['free_book.pdf'] = { :data => File.read('path/to/file.pdf') }
179 # mail(:to => recipient, :subject => "New account information")
db045db @dhh Initial
dhh authored
180 # end
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
181 # end
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
182 #
183 # Which will (if it had both a <tt>.text.erb</tt> and <tt>.html.erb</tt> tempalte in the view
184 # directory), send a complete <tt>multipart/mixed</tt> email with two parts, the first part being
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
185 # a <tt>multipart/alternative</tt> with the text and HTML email parts inside, and the second being
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
186 # a <tt>application/pdf</tt> with a Base64 encoded copy of the file.pdf book with the filename
187 # +free_book.pdf+.
c927aa0 @dhh Updated documentation
dhh authored
188 #
20bd4bd @dhh Updated docs and otherwise
dhh authored
189 #
c927aa0 @dhh Updated documentation
dhh authored
190 # = Configuration options
191 #
192 # These options are specified on the class level, like <tt>ActionMailer::Base.template_root = "/my/templates"</tt>
193 #
21dcc20 @mikel Fixed up documentation to reflect code change and cleaned up tests of sp...
mikel authored
194 # * <tt>defaults</tt> - This is a class wide hash of <tt>:key => value</tt> pairs containing
195 # default values for the specified header fields of the <tt>Mail::Message</tt>. You can
196 # specify a default for any valid header for <tt>Mail::Message</tt> and it will be used if
197 # you do not override it. The defaults set by Action Mailer are:
198 # * <tt>:mime_version => "1.0"</tt>
199 # * <tt>:charset => "utf-8",</tt>
200 # * <tt>:content_type => "text/plain",</tt>
201 # * <tt>:parts_order => [ "text/plain", "text/enriched", "text/html" ]</tt>
c927aa0 @dhh Updated documentation
dhh authored
202 #
203 # * <tt>logger</tt> - the logger is used for generating information on the mailing run if available.
204 # Can be set to nil for no logging. Compatible with both Ruby's own Logger and Log4r loggers.
205 #
64092de @fxn Improve documentation coverage and markup
fxn authored
206 # * <tt>smtp_settings</tt> - Allows detailed configuration for <tt>:smtp</tt> delivery method:
dc4eec1 @lifo Merge docrails:
lifo authored
207 # * <tt>:address</tt> - Allows you to use a remote mail server. Just change it from its default "localhost" setting.
208 # * <tt>:port</tt> - On the off chance that your mail server doesn't run on port 25, you can change it.
209 # * <tt>:domain</tt> - If you need to specify a HELO domain, you can do it here.
210 # * <tt>:user_name</tt> - If your mail server requires authentication, set the username in this setting.
211 # * <tt>:password</tt> - If your mail server requires authentication, set the password in this setting.
b2504f8 @josh Tidy up ActionMailer rendering logic to take advantage of view path cach...
josh authored
212 # * <tt>:authentication</tt> - If your mail server requires authentication, you need to specify the authentication type here.
46f30f9 @lifo Merge documentation changes from docrails.
lifo authored
213 # This is a symbol and one of <tt>:plain</tt>, <tt>:login</tt>, <tt>:cram_md5</tt>.
c2e7851 @josevalim Add ActionMailer::Base#enable_starttls_auto option for enabling/disablin...
josevalim authored
214 # * <tt>:enable_starttls_auto</tt> - When set to true, detects if STARTTLS is enabled in your SMTP server and starts to use it.
215 # It works only on Ruby >= 1.8.7 and Ruby >= 1.9. Default is true.
c927aa0 @dhh Updated documentation
dhh authored
216 #
46f30f9 @lifo Merge documentation changes from docrails.
lifo authored
217 # * <tt>sendmail_settings</tt> - Allows you to override options for the <tt>:sendmail</tt> delivery method.
218 # * <tt>:location</tt> - The location of the sendmail executable. Defaults to <tt>/usr/sbin/sendmail</tt>.
219 # * <tt>:arguments</tt> - The command line arguments. Defaults to <tt>-i -t</tt>.
dc4eec1 @lifo Merge docrails:
lifo authored
220 #
fbe6c3c @edavis10 Adds a :file delivery_method to save email to a file on disk
edavis10 authored
221 # * <tt>file_settings</tt> - Allows you to override options for the <tt>:file</tt> delivery method.
222 # * <tt>:location</tt> - The directory into which emails will be written. Defaults to the application <tt>tmp/mails</tt>.
223 #
dc4eec1 @lifo Merge docrails:
lifo authored
224 # * <tt>raise_delivery_errors</tt> - Whether or not errors should be raised if the email fails to be delivered.
c927aa0 @dhh Updated documentation
dhh authored
225 #
fbe6c3c @edavis10 Adds a :file delivery_method to save email to a file on disk
edavis10 authored
226 # * <tt>delivery_method</tt> - Defines a delivery method. Possible values are <tt>:smtp</tt> (default), <tt>:sendmail</tt>, <tt>:test</tt>,
f4f7677 @matthewrudy abstract all of the ActionMailer delivery methods into their own classes...
matthewrudy authored
227 # and <tt>:file</tt>. Or you may provide a custom delivery method object eg. MyOwnDeliveryMethodClass.new
c927aa0 @dhh Updated documentation
dhh authored
228 #
dc4eec1 @lifo Merge docrails:
lifo authored
229 # * <tt>perform_deliveries</tt> - Determines whether <tt>deliver_*</tt> methods are actually carried out. By default they are,
c927aa0 @dhh Updated documentation
dhh authored
230 # but this can be turned off to help functional testing.
231 #
64092de @fxn Improve documentation coverage and markup
fxn authored
232 # * <tt>deliveries</tt> - Keeps an array of all the emails sent out through the Action Mailer with <tt>delivery_method :test</tt>. Most useful
c927aa0 @dhh Updated documentation
dhh authored
233 # for unit and functional testing.
af56c80 @dhh Updated documentation
dhh authored
234 #
21dcc20 @mikel Fixed up documentation to reflect code change and cleaned up tests of sp...
mikel authored
235 # * <tt>default_charset</tt> - This is now deprecated, use the +defaults+ method above to
236 # set the default +:charset+.
c2e7851 @josevalim Add ActionMailer::Base#enable_starttls_auto option for enabling/disablin...
josevalim authored
237 #
21dcc20 @mikel Fixed up documentation to reflect code change and cleaned up tests of sp...
mikel authored
238 # * <tt>default_content_type</tt> - This is now deprecated, use the +defaults+ method above
239 # to set the default +:content_type+.
c2e7851 @josevalim Add ActionMailer::Base#enable_starttls_auto option for enabling/disablin...
josevalim authored
240 #
21dcc20 @mikel Fixed up documentation to reflect code change and cleaned up tests of sp...
mikel authored
241 # * <tt>default_mime_version</tt> - This is now deprecated, use the +defaults+ method above
242 # to set the default +:mime_version+.
c2e7851 @josevalim Add ActionMailer::Base#enable_starttls_auto option for enabling/disablin...
josevalim authored
243 #
21dcc20 @mikel Fixed up documentation to reflect code change and cleaned up tests of sp...
mikel authored
244 # * <tt>default_implicit_parts_order</tt> - This is now deprecated, use the +defaults+ method above
245 # to set the default +:parts_order+. Parts Order is used when a message is built implicitly
246 # (i.e. multiple parts are assembled from templates which specify the content type in their
247 # filenames) this variable controls how the parts are ordered.
4964d3b @josevalim Make ActionMailer::Base inherit from AbstractController::Base
josevalim authored
248 class Base < AbstractController::Base
0d931fe Finish cleaning up delivery methods implementation.
José Valim and Mikel Lindsaar authored
249 include DeliveryMethods, Quoting
f30d73b Add new class delivery method API.
José Valim and Mikel Lindsaar authored
250 abstract!
251
c03c40b @josevalim Expose a _render_partial hook as thhe _render_template one and make use ...
josevalim authored
252 include AbstractController::Logger
83f4d86 @dhh Rename the RenderingController module to just plain Rendering
dhh authored
253 include AbstractController::Rendering
976c264 @josevalim Extracted localized_cache.rb from ActionController, added it to Abstract...
josevalim authored
254 include AbstractController::LocalizedCache
a9751a7 @josevalim Refactor ActionMailer layout and remove legacy one.
josevalim authored
255 include AbstractController::Layouts
684c2dc @josevalim Remove ActionMailer helpers and rely on AbstractController one.
josevalim authored
256 include AbstractController::Helpers
f564f94 @josevalim Remove duplicated url_for code and move methods shared between ActionMai...
josevalim authored
257 include AbstractController::UrlFor
48a3985 @josevalim Also include translation in ActionMailer.
josevalim authored
258 include AbstractController::Translation
359caef @jamis A very thorough refactoring, resulting in new mail property setters and ...
jamis authored
259
ee70d1b @josevalim adv_attr_accessors in ActionMailer are not sent to the views, use the ma...
josevalim authored
260 helper ActionMailer::MailHelper
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
261
5dead5b Maintain old_api and deprecated_api in different files.
José Valim and Mikel Lindsaar authored
262 include ActionMailer::OldApi
f30d73b Add new class delivery method API.
José Valim and Mikel Lindsaar authored
263 include ActionMailer::DeprecatedApi
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
264
c927aa0 @dhh Updated documentation
dhh authored
265 private_class_method :new #:nodoc:
db045db @dhh Initial
dhh authored
266
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
267 extlib_inheritable_accessor :default_params
268 self.default_params = {
269 :mime_version => "1.0",
270 :charset => "utf-8",
271 :content_type => "text/plain",
272 :parts_order => [ "text/plain", "text/enriched", "text/html" ]
273 }
e1c1318 Added delivers_from.
José Valim and Mikel Lindsaar authored
274
eda1719 @jamis ActionMailer::Base.deliver(email) had been accidentally removed, but was...
jamis authored
275 class << self
0b05acd @mikel Implementing class level :defaults hash, instead of delivers_from et al
mikel authored
276
bd5ed65 @technoweenie Update ActionMailer so it treats ActionView the same way that ActionCont...
technoweenie authored
277 def mailer_name
278 @mailer_name ||= name.underscore
279 end
0750304 @mikel Migrated over to Mail doing delivery.
mikel authored
280 attr_writer :mailer_name
281 alias :controller_path :mailer_name
81c416b @josevalim More refactoring on ActionMailer::Base.
josevalim authored
282
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
283 def defaults(value=nil)
284 self.default_params.merge!(value) if value
285 self.default_params
286 end
287
59f1df1 @jamis Update/extend ActionMailer documentation (rdoc)
jamis authored
288 # Receives a raw email, parses it into an email object, decodes it,
289 # instantiates a new mailer, and passes the email object to the mailer
98dc582 @lifo Merge docrails.
lifo authored
290 # object's +receive+ method. If you want your mailer to be able to
291 # process incoming messages, you'll need to implement a +receive+
59f1df1 @jamis Update/extend ActionMailer documentation (rdoc)
jamis authored
292 # method that accepts the email object as a parameter:
293 #
294 # class MyMailer < ActionMailer::Base
295 # def receive(mail)
296 # ...
297 # end
298 # end
704daad @josevalim Ensure we just send Ruby Stdlib objects in ActionMailer notifications.
josevalim authored
299 def receive(raw_mail)
300 ActiveSupport::Notifications.instrument("action_mailer.receive") do |payload|
301 mail = Mail.new(raw_mail)
302 set_payload_for_mail(payload, mail)
2a6bc12 @josevalim Add subscriber to ActionMailer.
josevalim authored
303 new.receive(mail)
304 end
eda1719 @jamis ActionMailer::Base.deliver(email) had been accidentally removed, but was...
jamis authored
305 end
306
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
307 # Delivers a mail object. This is actually called by the <tt>Mail::Message</tt> object
308 # itself through a call back when you call <tt>:deliver</tt> on the Mail::Message,
309 # calling +deliver_mail+ directly and passing an Mail::Message will do nothing.
e4a989e Added delivery_handler method to mail and implemented in ActionMailer to...
José Valim and Mikel Lindsaar authored
310 def deliver_mail(mail) #:nodoc:
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
311 ActiveSupport::Notifications.instrument("action_mailer.deliver") do |payload|
258ca14 Delegated ActionMailer::Base.deliveries to Mail.deliveries, added callba...
José Valim and Mikel Lindsaar authored
312 self.set_payload_for_mail(payload, mail)
ace7497 Got AM working with Mail yield on delivery_handler and updated tests
José Valim and Mikel Lindsaar authored
313 yield # Let Mail do the delivery actions
258ca14 Delegated ActionMailer::Base.deliveries to Mail.deliveries, added callba...
José Valim and Mikel Lindsaar authored
314 end
315 end
316
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
317 def respond_to?(method, *args) #:nodoc:
318 super || action_methods.include?(method.to_s)
319 end
320
321 protected
322
704daad @josevalim Ensure we just send Ruby Stdlib objects in ActionMailer notifications.
josevalim authored
323 def set_payload_for_mail(payload, mail) #:nodoc:
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
324 payload[:mailer] = self.name
c905fce @josevalim Add message_id to AM payload and don't send bcc and cc if they were not ...
josevalim authored
325 payload[:message_id] = mail.message_id
326 payload[:subject] = mail.subject
327 payload[:to] = mail.to
328 payload[:from] = mail.from
329 payload[:bcc] = mail.bcc if mail.bcc.present?
330 payload[:cc] = mail.cc if mail.cc.present?
331 payload[:date] = mail.date
332 payload[:mail] = mail.encoded
704daad @josevalim Ensure we just send Ruby Stdlib objects in ActionMailer notifications.
josevalim authored
333 end
f30d73b Add new class delivery method API.
José Valim and Mikel Lindsaar authored
334
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
335 def method_missing(method, *args) #:nodoc:
f30d73b Add new class delivery method API.
José Valim and Mikel Lindsaar authored
336 if action_methods.include?(method.to_s)
337 new(method, *args).message
338 else
339 super
340 end
341 end
eda1719 @jamis ActionMailer::Base.deliver(email) had been accidentally removed, but was...
jamis authored
342 end
343
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
344 attr_internal :message
345
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
346 # Instantiate a new mailer object. If +method_name+ is not +nil+, the mailer
347 # will be initialized according to the named method. If not, the mailer will
348 # remain uninitialized (useful when you only need to invoke the "receive"
349 # method, for instance).
350 def initialize(method_name=nil, *args)
351 super()
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
352 @_message = Mail.new
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
353 process(method_name, *args) if method_name
354 end
355
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
356 # Allows you to pass random and unusual headers to the new +Mail::Message+ object
357 # which will add them to itself.
358 #
359 # headers['X-Special-Domain-Specific-Header'] = "SecretValue"
360 #
9520166 @mikel Fixed up being able to pass random headers in with headers, or mail. Al...
mikel authored
361 # You can also pass a hash into headers of header field names and values, which
362 # will then be set on the Mail::Message object:
363 #
05c4ad9 Tidy up tests and docs.
José Valim and Mikel Lindsaar authored
364 # headers 'X-Special-Domain-Specific-Header' => "SecretValue",
365 # 'In-Reply-To' => incoming.message_id
9520166 @mikel Fixed up being able to pass random headers in with headers, or mail. Al...
mikel authored
366 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
367 # The resulting Mail::Message will have the following in it's header:
368 #
369 # X-Special-Domain-Specific-Header: SecretValue
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
370 def headers(args=nil)
371 if args
9520166 @mikel Fixed up being able to pass random headers in with headers, or mail. Al...
mikel authored
372 @_message.headers(args)
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
373 else
374 @_message
375 end
376 end
c34cfcc @mikel Created mail method for new API
mikel authored
377
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
378 # Allows you to add attachments to an email, like so:
379 #
380 # mail.attachments['filename.jpg'] = File.read('/path/to/filename.jpg')
381 #
382 # If you do this, then Mail will take the file name and work out the mime type
383 # set the Content-Type, Content-Disposition, Content-Transfer-Encoding and
384 # base64 encode the contents of the attachment all for you.
385 #
386 # You can also specify overrides if you want by passing a hash instead of a string:
387 #
388 # mail.attachments['filename.jpg'] = {:mime_type => 'application/x-gzip',
389 # :content => File.read('/path/to/filename.jpg')}
390 #
391 # If you want to use a different encoding than Base64, you can pass an encoding in,
392 # but then it is up to you to pass in the content pre-encoded, and don't expect
393 # Mail to know how to decode this data:
394 #
395 # file_content = SpecialEncode(File.read('/path/to/filename.jpg'))
396 # mail.attachments['filename.jpg'] = {:mime_type => 'application/x-gzip',
397 # :encoding => 'SpecialEncoding',
398 # :content => file_content }
399 #
400 # You can also search for specific attachments:
401 #
402 # # By Filename
403 # mail.attachments['filename.jpg'] #=> Mail::Part object or nil
404 #
405 # # or by index
406 # mail.attachments[0] #=> Mail::Part (first attachment)
407 #
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
408 def attachments
409 @_message.attachments
410 end
dcb9253 Add basic template rendering to new DSL.
José Valim and Mikel Lindsaar authored
411
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
412 # The main method that creates the message and renders the email templates. There are
413 # two ways to call this method, with a block, or without a block.
414 #
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
415 # Both methods accept a headers hash. This hash allows you to specify the most used headers
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
416 # in an email message, these are:
417 #
418 # * <tt>:subject</tt> - The subject of the message, if this is omitted, ActionMailer will
419 # ask the Rails I18n class for a translated <tt>:subject</tt> in the scope of
420 # <tt>[:actionmailer, mailer_scope, action_name]</tt> or if this is missing, will translate the
421 # humanized version of the <tt>action_name</tt>
422 # * <tt>:to</tt> - Who the message is destined for, can be a string of addresses, or an array
423 # of addresses.
0b05acd @mikel Implementing class level :defaults hash, instead of delivers_from et al
mikel authored
424 # * <tt>:from</tt> - Who the message is from
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
425 # * <tt>:cc</tt> - Who you would like to Carbon-Copy on this email, can be a string of addresses,
426 # or an array of addresses.
427 # * <tt>:bcc</tt> - Who you would like to Blind-Carbon-Copy on this email, can be a string of
428 # addresses, or an array of addresses.
429 # * <tt>:reply_to</tt> - Who to set the Reply-To header of the email to.
430 # * <tt>:date</tt> - The date to say the email was sent on.
431 #
0b05acd @mikel Implementing class level :defaults hash, instead of delivers_from et al
mikel authored
432 # You can set default values for any of the above headers (except :date) by using the <tt>defaults</tt>
433 # class method:
434 #
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
435 # class Notifier < ActionMailer::Base
436 # self.defaults :from => 'no-reply@test.lindsaar.net',
437 # :bcc => 'email_logger@test.lindsaar.net',
438 # :reply_to => 'bounces@test.lindsaar.net'
0b05acd @mikel Implementing class level :defaults hash, instead of delivers_from et al
mikel authored
439 # end
440 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
441 # If you need other headers not listed above, use the <tt>headers['name'] = value</tt> method.
442 #
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
443 # When a <tt>:return_path</tt> is specified as header, that value will be used as the 'envelope from'
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
444 # address for the Mail message. Setting this is useful when you want delivery notifications
445 # sent to a different address than the one in <tt>:from</tt>. Mail will actually use the
446 # <tt>:return_path</tt> in preference to the <tt>:sender</tt> in preference to the <tt>:from</tt>
447 # field for the 'envelope from' value.
448 #
449 # If you do not pass a block to the +mail+ method, it will find all templates in the
450 # template path that match the method name that it is being called from, it will then
451 # create parts for each of these templates intelligently, making educated guesses
452 # on correct content type and sequence, and return a fully prepared Mail::Message
453 # ready to call <tt>:deliver</tt> on to send.
454 #
455 # If you do pass a block, you can render specific templates of your choice:
456 #
457 # mail(:to => 'mikel@test.lindsaar.net') do |format|
458 # format.text
459 # format.html
460 # end
461 #
462 # You can even render text directly without using a template:
463 #
464 # mail(:to => 'mikel@test.lindsaar.net') do |format|
465 # format.text { render :text => "Hello Mikel!" }
466 # format.html { render :text => "<h1>Hello Mikel!</h1>" }
467 # end
468 #
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
469 # Which will render a <tt>multipart/alternative</tt> email with <tt>text/plain</tt> and
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
470 # <tt>text/html</tt> parts.
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
471 #
472 # The block syntax also allows you to customize the part headers if desired:
473 #
474 # mail(:to => 'mikel@test.lindsaar.net') do |format|
475 # format.text(:content_transfer_encoding => "base64")
476 # format.html
477 # end
478 #
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
479 def mail(headers={}, &block)
480 # Guard flag to prevent both the old and the new API from firing
481 # Should be removed when old API is removed
482 @mail_was_called = true
483 m = @_message
258ca14 Delegated ActionMailer::Base.deliveries to Mail.deliveries, added callba...
José Valim and Mikel Lindsaar authored
484
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
485 # At the beginning, do not consider class default for parts order neither content_type
486 content_type = headers[:content_type]
487 parts_order = headers[:parts_order]
1cd5592 First work on implicit multipart.
José Valim and Mikel Lindsaar authored
488
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
489 # Merge defaults from class
490 headers = headers.reverse_merge(self.class.defaults)
491 charset = headers[:charset]
0b05acd @mikel Implementing class level :defaults hash, instead of delivers_from et al
mikel authored
492
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
493 # Quote fields
494 headers[:subject] ||= default_i18n_subject
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
495 quote_fields!(headers, charset)
951397b Get implicit multipart and attachments working together.
José Valim and Mikel Lindsaar authored
496
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
497 # Render the templates and blocks
39a1b06 Deprecate old defaults API.
José Valim and Mikel Lindsaar authored
498 responses, explicit_order = collect_responses_and_parts_order(headers, &block)
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
499 create_parts_from_responses(m, responses, charset)
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
500
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
501 # Finally setup content type and parts order
502 m.content_type = set_content_type(m, content_type, headers[:content_type])
951397b Get implicit multipart and attachments working together.
José Valim and Mikel Lindsaar authored
503 m.charset = charset
504
e7e4ed4 Set sort order for explicit parts from the collector's template sequence
José Valim and Mikel Lindsaar authored
505 if m.multipart?
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
506 parts_order ||= explicit_order || headers[:parts_order]
507 m.body.set_sort_order(parts_order)
951397b Get implicit multipart and attachments working together.
José Valim and Mikel Lindsaar authored
508 m.body.sort_parts!
509 end
bb9d71f Move class methods to deprecated stuff.
José Valim and Mikel Lindsaar authored
510
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
511 # Set configure delivery behavior
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
512 wrap_delivery_behavior!(headers[:delivery_method])
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
513
514 # Remove headers already treated and assign all others
515 headers.except!(:subject, :to, :from, :cc, :bcc, :reply_to)
516 headers.except!(:body, :parts_order, :content_type, :charset, :delivery_method)
517 headers.each { |k, v| m[k] = v }
518
c34cfcc @mikel Created mail method for new API
mikel authored
519 m
520 end
521
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
522 protected
523
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
524 def set_content_type(m, user_content_type, class_default)
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
525 params = m.content_type_parameters || {}
526 case
527 when user_content_type.present?
528 user_content_type
529 when m.has_attachments?
530 ["multipart", "mixed", params]
531 when m.multipart?
532 ["multipart", "alternative", params]
533 else
b6b3db6 @mikel Fixed bug on HTML only emails getting set to text/plain
mikel authored
534 m.content_type || class_default
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
535 end
536 end
537
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
538 def default_i18n_subject #:nodoc:
5c3ef8c Refactor subject with i18n.
José Valim and Mikel Lindsaar authored
539 mailer_scope = self.class.mailer_name.gsub('/', '.')
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
540 I18n.t(:subject, :scope => [:actionmailer, mailer_scope, action_name], :default => action_name.humanize)
5c3ef8c Refactor subject with i18n.
José Valim and Mikel Lindsaar authored
541 end
542
73a9000 Adding failing tests for calling just the action, instead of :create_act...
José Valim and Mikel Lindsaar authored
543 # TODO: Move this into Mail
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
544 def quote_fields!(headers, charset) #:nodoc:
545 m = @_message
546 m.subject ||= quote_if_necessary(headers[:subject], charset) if headers[:subject]
547 m.to ||= quote_address_if_necessary(headers[:to], charset) if headers[:to]
548 m.from ||= quote_address_if_necessary(headers[:from], charset) if headers[:from]
549 m.cc ||= quote_address_if_necessary(headers[:cc], charset) if headers[:cc]
550 m.bcc ||= quote_address_if_necessary(headers[:bcc], charset) if headers[:bcc]
551 m.reply_to ||= quote_address_if_necessary(headers[:reply_to], charset) if headers[:reply_to]
552 end
553
39a1b06 Deprecate old defaults API.
José Valim and Mikel Lindsaar authored
554 def collect_responses_and_parts_order(headers) #:nodoc:
555 responses, parts_order = [], nil
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
556
557 if block_given?
558 collector = ActionMailer::Collector.new(self) { render(action_name) }
559 yield(collector)
39a1b06 Deprecate old defaults API.
José Valim and Mikel Lindsaar authored
560 parts_order = collector.responses.map { |r| r[:content_type] }
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
561 responses = collector.responses
562 elsif headers[:body]
563 responses << {
564 :body => headers[:body],
39a1b06 Deprecate old defaults API.
José Valim and Mikel Lindsaar authored
565 :content_type => self.class.defaults[:content_type] || "text/plain"
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
566 }
567 else
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
568 each_template do |template|
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
569 responses << {
570 :body => render_to_body(:_template => template),
571 :content_type => template.mime_type.to_s
572 }
573 end
574 end
575
39a1b06 Deprecate old defaults API.
José Valim and Mikel Lindsaar authored
576 [responses, parts_order]
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
577 end
578
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
579 def each_template(&block) #:nodoc:
580 self.class.view_paths.each do |load_paths|
581 templates = load_paths.find_all(action_name, {}, self.class.mailer_name)
0ece244 Ensure implicit multipart templates with locale works as expected.
José Valim and Mikel Lindsaar authored
582 templates = templates.uniq_by { |t| t.details[:formats] }
583
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
584 unless templates.empty?
585 templates.each(&block)
586 return
587 end
588 end
589 end
590
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
591 def create_parts_from_responses(m, responses, charset) #:nodoc:
592 if responses.size == 1 && !m.has_attachments?
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
593 responses[0].each { |k,v| m[k] = v }
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
594 elsif responses.size > 1 && m.has_attachments?
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
595 container = Mail::Part.new
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
596 container.content_type = "multipart/alternative"
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
597 responses.each { |r| insert_part(container, r, charset) }
598 m.add_part(container)
599 else
600 responses.each { |r| insert_part(m, r, charset) }
601 end
359caef @jamis A very thorough refactoring, resulting in new mail property setters and ...
jamis authored
602 end
603
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
604 def insert_part(container, response, charset) #:nodoc:
605 response[:charset] ||= charset
606 part = Mail::Part.new(response)
607 container.add_part(part)
359caef @jamis A very thorough refactoring, resulting in new mail property setters and ...
jamis authored
608 end
3fad0cd @dhh Added support for charsets for both subject and body. The default charse...
dhh authored
609
db045db @dhh Initial
dhh authored
610 end
611 end
Something went wrong with that request. Please try again.