actionmailer-rack-upgrade-2 2.3.15

Sign up to get free protection for your applications and to get access to all the features.
Files changed (148) hide show
  1. data/CHANGELOG +387 -0
  2. data/MIT-LICENSE +21 -0
  3. data/README +149 -0
  4. data/Rakefile +97 -0
  5. data/install.rb +30 -0
  6. data/lib/action_mailer/adv_attr_accessor.rb +30 -0
  7. data/lib/action_mailer/base.rb +739 -0
  8. data/lib/action_mailer/helpers.rb +113 -0
  9. data/lib/action_mailer/mail_helper.rb +17 -0
  10. data/lib/action_mailer/part.rb +107 -0
  11. data/lib/action_mailer/part_container.rb +55 -0
  12. data/lib/action_mailer/quoting.rb +62 -0
  13. data/lib/action_mailer/test_case.rb +64 -0
  14. data/lib/action_mailer/test_helper.rb +68 -0
  15. data/lib/action_mailer/utils.rb +7 -0
  16. data/lib/action_mailer/vendor/text-format-0.6.3/text/format.rb +1466 -0
  17. data/lib/action_mailer/vendor/text_format.rb +10 -0
  18. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/Makefile +18 -0
  19. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/address.rb +392 -0
  20. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/attachments.rb +65 -0
  21. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/base64.rb +46 -0
  22. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/compat.rb +41 -0
  23. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/config.rb +67 -0
  24. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/core_extensions.rb +63 -0
  25. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/encode.rb +590 -0
  26. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/header.rb +962 -0
  27. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/index.rb +9 -0
  28. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb +1162 -0
  29. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/loader.rb +3 -0
  30. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb +578 -0
  31. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/mailbox.rb +496 -0
  32. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/main.rb +6 -0
  33. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/mbox.rb +3 -0
  34. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/net.rb +250 -0
  35. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/obsolete.rb +132 -0
  36. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/parser.rb +1060 -0
  37. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/parser.y +416 -0
  38. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/port.rb +379 -0
  39. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/quoting.rb +164 -0
  40. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/require_arch.rb +58 -0
  41. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/scanner.rb +49 -0
  42. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/scanner_r.rb +262 -0
  43. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/stringio.rb +280 -0
  44. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/utils.rb +362 -0
  45. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/COPYING +504 -0
  46. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/README +12 -0
  47. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/big5freq.rb +927 -0
  48. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/big5prober.rb +42 -0
  49. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/chardistribution.rb +238 -0
  50. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/charsetgroupprober.rb +112 -0
  51. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/charsetprober.rb +75 -0
  52. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/codingstatemachine.rb +64 -0
  53. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/constants.rb +42 -0
  54. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/escprober.rb +89 -0
  55. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/escsm.rb +244 -0
  56. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/eucjpprober.rb +88 -0
  57. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/euckrfreq.rb +596 -0
  58. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/euckrprober.rb +42 -0
  59. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/euctwfreq.rb +430 -0
  60. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/euctwprober.rb +42 -0
  61. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/gb2312freq.rb +474 -0
  62. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/gb2312prober.rb +42 -0
  63. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/hebrewprober.rb +289 -0
  64. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/jisfreq.rb +570 -0
  65. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/jpcntx.rb +229 -0
  66. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/langbulgarianmodel.rb +229 -0
  67. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/langcyrillicmodel.rb +330 -0
  68. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/langgreekmodel.rb +227 -0
  69. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/langhebrewmodel.rb +202 -0
  70. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/langhungarianmodel.rb +226 -0
  71. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/langthaimodel.rb +201 -0
  72. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/latin1prober.rb +147 -0
  73. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/mbcharsetprober.rb +89 -0
  74. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/mbcsgroupprober.rb +45 -0
  75. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/mbcssm.rb +542 -0
  76. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/sbcharsetprober.rb +124 -0
  77. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/sbcsgroupprober.rb +56 -0
  78. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/sjisprober.rb +88 -0
  79. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/universaldetector.rb +168 -0
  80. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet/utf8prober.rb +87 -0
  81. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/vendor/rchardet-1.3/lib/rchardet.rb +67 -0
  82. data/lib/action_mailer/vendor/tmail-1.2.7/tmail/version.rb +39 -0
  83. data/lib/action_mailer/vendor/tmail-1.2.7/tmail.rb +6 -0
  84. data/lib/action_mailer/vendor/tmail.rb +17 -0
  85. data/lib/action_mailer/version.rb +9 -0
  86. data/lib/action_mailer.rb +62 -0
  87. data/lib/actionmailer.rb +2 -0
  88. data/test/abstract_unit.rb +62 -0
  89. data/test/asset_host_test.rb +54 -0
  90. data/test/delivery_method_test.rb +51 -0
  91. data/test/fixtures/asset_host_mailer/email_with_asset.html.erb +1 -0
  92. data/test/fixtures/auto_layout_mailer/hello.html.erb +1 -0
  93. data/test/fixtures/auto_layout_mailer/multipart.text.html.erb +1 -0
  94. data/test/fixtures/auto_layout_mailer/multipart.text.plain.erb +1 -0
  95. data/test/fixtures/explicit_layout_mailer/logout.html.erb +1 -0
  96. data/test/fixtures/explicit_layout_mailer/signup.html.erb +1 -0
  97. data/test/fixtures/first_mailer/share.erb +1 -0
  98. data/test/fixtures/helper_mailer/use_example_helper.erb +1 -0
  99. data/test/fixtures/helper_mailer/use_helper.erb +1 -0
  100. data/test/fixtures/helper_mailer/use_helper_method.erb +1 -0
  101. data/test/fixtures/helper_mailer/use_mail_helper.erb +5 -0
  102. data/test/fixtures/helpers/example_helper.rb +5 -0
  103. data/test/fixtures/layouts/auto_layout_mailer.html.erb +1 -0
  104. data/test/fixtures/layouts/auto_layout_mailer.text.erb +1 -0
  105. data/test/fixtures/layouts/spam.html.erb +1 -0
  106. data/test/fixtures/path.with.dots/funky_path_mailer/multipart_with_template_path_with_dots.erb +1 -0
  107. data/test/fixtures/raw_email +14 -0
  108. data/test/fixtures/raw_email10 +20 -0
  109. data/test/fixtures/raw_email12 +32 -0
  110. data/test/fixtures/raw_email13 +29 -0
  111. data/test/fixtures/raw_email2 +114 -0
  112. data/test/fixtures/raw_email3 +70 -0
  113. data/test/fixtures/raw_email4 +59 -0
  114. data/test/fixtures/raw_email5 +19 -0
  115. data/test/fixtures/raw_email6 +20 -0
  116. data/test/fixtures/raw_email7 +66 -0
  117. data/test/fixtures/raw_email8 +47 -0
  118. data/test/fixtures/raw_email9 +28 -0
  119. data/test/fixtures/raw_email_quoted_with_0d0a +14 -0
  120. data/test/fixtures/raw_email_with_invalid_characters_in_content_type +104 -0
  121. data/test/fixtures/raw_email_with_nested_attachment +100 -0
  122. data/test/fixtures/raw_email_with_partially_quoted_subject +14 -0
  123. data/test/fixtures/second_mailer/share.erb +1 -0
  124. data/test/fixtures/templates/signed_up.erb +3 -0
  125. data/test/fixtures/test_mailer/_subtemplate.text.plain.erb +1 -0
  126. data/test/fixtures/test_mailer/body_ivar.erb +2 -0
  127. data/test/fixtures/test_mailer/custom_templating_extension.text.html.haml +6 -0
  128. data/test/fixtures/test_mailer/custom_templating_extension.text.plain.haml +6 -0
  129. data/test/fixtures/test_mailer/implicitly_multipart_example.ignored.erb +1 -0
  130. data/test/fixtures/test_mailer/implicitly_multipart_example.rhtml.bak +1 -0
  131. data/test/fixtures/test_mailer/implicitly_multipart_example.text.html.erb +10 -0
  132. data/test/fixtures/test_mailer/implicitly_multipart_example.text.html.erb~ +10 -0
  133. data/test/fixtures/test_mailer/implicitly_multipart_example.text.plain.erb +2 -0
  134. data/test/fixtures/test_mailer/implicitly_multipart_example.text.yaml.erb +1 -0
  135. data/test/fixtures/test_mailer/included_subtemplate.text.plain.erb +1 -0
  136. data/test/fixtures/test_mailer/rxml_template.builder +2 -0
  137. data/test/fixtures/test_mailer/rxml_template.rxml +2 -0
  138. data/test/fixtures/test_mailer/signed_up.html.erb +3 -0
  139. data/test/fixtures/test_mailer/signed_up_with_url.erb +5 -0
  140. data/test/mail_helper_test.rb +95 -0
  141. data/test/mail_layout_test.rb +123 -0
  142. data/test/mail_render_test.rb +116 -0
  143. data/test/mail_service_test.rb +1145 -0
  144. data/test/quoting_test.rb +105 -0
  145. data/test/test_helper_test.rb +129 -0
  146. data/test/tmail_test.rb +22 -0
  147. data/test/url_test.rb +76 -0
  148. metadata +209 -0
@@ -0,0 +1,739 @@
1
+ module ActionMailer #:nodoc:
2
+ # Action Mailer allows you to send email from your application using a mailer model and views.
3
+ #
4
+ #
5
+ # = Mailer Models
6
+ #
7
+ # To use Action Mailer, you need to create a mailer model.
8
+ #
9
+ # $ script/generate mailer Notifier
10
+ #
11
+ # The generated model inherits from ActionMailer::Base. Emails are defined by creating methods within the model which are then
12
+ # used to set variables to be used in the mail template, to change options on the mail, or
13
+ # to add attachments.
14
+ #
15
+ # Examples:
16
+ #
17
+ # class Notifier < ActionMailer::Base
18
+ # def signup_notification(recipient)
19
+ # recipients recipient.email_address_with_name
20
+ # bcc ["bcc@example.com", "Order Watcher <watcher@example.com>"]
21
+ # from "system@example.com"
22
+ # subject "New account information"
23
+ # body :account => recipient
24
+ # end
25
+ # end
26
+ #
27
+ # Mailer methods have the following configuration methods available.
28
+ #
29
+ # * <tt>recipients</tt> - Takes one or more email addresses. These addresses are where your email will be delivered to. Sets the <tt>To:</tt> header.
30
+ # * <tt>subject</tt> - The subject of your email. Sets the <tt>Subject:</tt> header.
31
+ # * <tt>from</tt> - Who the email you are sending is from. Sets the <tt>From:</tt> header.
32
+ # * <tt>cc</tt> - Takes one or more email addresses. These addresses will receive a carbon copy of your email. Sets the <tt>Cc:</tt> header.
33
+ # * <tt>bcc</tt> - Takes one or more email addresses. These addresses will receive a blind carbon copy of your email. Sets the <tt>Bcc:</tt> header.
34
+ # * <tt>reply_to</tt> - Takes one or more email addresses. These addresses will be listed as the default recipients when replying to your email. Sets the <tt>Reply-To:</tt> header.
35
+ # * <tt>sent_on</tt> - The date on which the message was sent. If not set, the header wil be set by the delivery agent.
36
+ # * <tt>content_type</tt> - Specify the content type of the message. Defaults to <tt>text/plain</tt>.
37
+ # * <tt>headers</tt> - Specify additional headers to be set for the message, e.g. <tt>headers 'X-Mail-Count' => 107370</tt>.
38
+ #
39
+ # When a <tt>headers 'return-path'</tt> is specified, that value will be used as the 'envelope from'
40
+ # address. Setting this is useful when you want delivery notifications sent to a different address than
41
+ # the one in <tt>from</tt>.
42
+ #
43
+ # The <tt>body</tt> method has special behavior. It takes a hash which generates an instance variable
44
+ # named after each key in the hash containing the value that that key points to.
45
+ #
46
+ # So, for example, <tt>body :account => recipient</tt> would result
47
+ # in an instance variable <tt>@account</tt> with the value of <tt>recipient</tt> being accessible in the
48
+ # view.
49
+ #
50
+ #
51
+ # = Mailer views
52
+ #
53
+ # Like Action Controller, each mailer class has a corresponding view directory
54
+ # in which each method of the class looks for a template with its name.
55
+ # To define a template to be used with a mailing, create an <tt>.erb</tt> file with the same name as the method
56
+ # in your mailer model. For example, in the mailer defined above, the template at
57
+ # <tt>app/views/notifier/signup_notification.erb</tt> would be used to generate the email.
58
+ #
59
+ # Variables defined in the model are accessible as instance variables in the view.
60
+ #
61
+ # Emails by default are sent in plain text, so a sample view for our model example might look like this:
62
+ #
63
+ # Hi <%= @account.name %>,
64
+ # Thanks for joining our service! Please check back often.
65
+ #
66
+ # You can even use Action Pack helpers in these views. For example:
67
+ #
68
+ # You got a new note!
69
+ # <%= truncate(note.body, 25) %>
70
+ #
71
+ #
72
+ # = Generating URLs
73
+ #
74
+ # URLs can be generated in mailer views using <tt>url_for</tt> or named routes.
75
+ # Unlike controllers from Action Pack, the mailer instance doesn't have any context about the incoming request,
76
+ # so you'll need to provide all of the details needed to generate a URL.
77
+ #
78
+ # When using <tt>url_for</tt> you'll need to provide the <tt>:host</tt>, <tt>:controller</tt>, and <tt>:action</tt>:
79
+ #
80
+ # <%= url_for(:host => "example.com", :controller => "welcome", :action => "greeting") %>
81
+ #
82
+ # When using named routes you only need to supply the <tt>:host</tt>:
83
+ #
84
+ # <%= users_url(:host => "example.com") %>
85
+ #
86
+ # You will want to avoid using the <tt>name_of_route_path</tt> form of named routes because it doesn't make sense to
87
+ # generate relative URLs in email messages.
88
+ #
89
+ # It is also possible to set a default host that will be used in all mailers by setting the <tt>:host</tt> option in
90
+ # the <tt>ActionMailer::Base.default_url_options</tt> hash as follows:
91
+ #
92
+ # ActionMailer::Base.default_url_options[:host] = "example.com"
93
+ #
94
+ # This can also be set as a configuration option in <tt>config/environment.rb</tt>:
95
+ #
96
+ # config.action_mailer.default_url_options = { :host => "example.com" }
97
+ #
98
+ # If you do decide to set a default <tt>:host</tt> for your mailers you will want to use the
99
+ # <tt>:only_path => false</tt> option when using <tt>url_for</tt>. This will ensure that absolute URLs are generated because
100
+ # the <tt>url_for</tt> view helper will, by default, generate relative URLs when a <tt>:host</tt> option isn't
101
+ # explicitly provided.
102
+ #
103
+ # = Sending mail
104
+ #
105
+ # Once a mailer action and template are defined, you can deliver your message or create it and save it
106
+ # for delivery later:
107
+ #
108
+ # Notifier.deliver_signup_notification(david) # sends the email
109
+ # mail = Notifier.create_signup_notification(david) # => a tmail object
110
+ # Notifier.deliver(mail)
111
+ #
112
+ # You never instantiate your mailer class. Rather, your delivery instance
113
+ # methods are automatically wrapped in class methods that start with the word
114
+ # <tt>deliver_</tt> followed by the name of the mailer method that you would
115
+ # like to deliver. The <tt>signup_notification</tt> method defined above is
116
+ # delivered by invoking <tt>Notifier.deliver_signup_notification</tt>.
117
+ #
118
+ #
119
+ # = HTML email
120
+ #
121
+ # To send mail as HTML, make sure your view (the <tt>.erb</tt> file) generates HTML and
122
+ # set the content type to html.
123
+ #
124
+ # class MyMailer < ActionMailer::Base
125
+ # def signup_notification(recipient)
126
+ # recipients recipient.email_address_with_name
127
+ # subject "New account information"
128
+ # from "system@example.com"
129
+ # body :account => recipient
130
+ # content_type "text/html"
131
+ # end
132
+ # end
133
+ #
134
+ #
135
+ # = Multipart email
136
+ #
137
+ # You can explicitly specify multipart messages:
138
+ #
139
+ # class ApplicationMailer < ActionMailer::Base
140
+ # def signup_notification(recipient)
141
+ # recipients recipient.email_address_with_name
142
+ # subject "New account information"
143
+ # from "system@example.com"
144
+ # content_type "multipart/alternative"
145
+ #
146
+ # part :content_type => "text/html",
147
+ # :body => render_message("signup-as-html", :account => recipient)
148
+ #
149
+ # part "text/plain" do |p|
150
+ # p.body = render_message("signup-as-plain", :account => recipient)
151
+ # p.transfer_encoding = "base64"
152
+ # end
153
+ # end
154
+ # end
155
+ #
156
+ # Multipart messages can also be used implicitly because Action Mailer will automatically
157
+ # detect and use multipart templates, where each template is named after the name of the action, followed
158
+ # by the content type. Each such detected template will be added as separate part to the message.
159
+ #
160
+ # For example, if the following templates existed:
161
+ # * signup_notification.text.plain.erb
162
+ # * signup_notification.text.html.erb
163
+ # * signup_notification.text.xml.builder
164
+ # * signup_notification.text.x-yaml.erb
165
+ #
166
+ # Each would be rendered and added as a separate part to the message,
167
+ # with the corresponding content type. The content type for the entire
168
+ # message is automatically set to <tt>multipart/alternative</tt>, which indicates
169
+ # that the email contains multiple different representations of the same email
170
+ # body. The same body hash is passed to each template.
171
+ #
172
+ # Implicit template rendering is not performed if any attachments or parts have been added to the email.
173
+ # This means that you'll have to manually add each part to the email and set the content type of the email
174
+ # to <tt>multipart/alternative</tt>.
175
+ #
176
+ # = Attachments
177
+ #
178
+ # Attachments can be added by using the +attachment+ method.
179
+ #
180
+ # Example:
181
+ #
182
+ # class ApplicationMailer < ActionMailer::Base
183
+ # # attachments
184
+ # def signup_notification(recipient)
185
+ # recipients recipient.email_address_with_name
186
+ # subject "New account information"
187
+ # from "system@example.com"
188
+ #
189
+ # attachment :content_type => "image/jpeg",
190
+ # :body => File.read("an-image.jpg")
191
+ #
192
+ # attachment "application/pdf" do |a|
193
+ # a.body = generate_your_pdf_here()
194
+ # end
195
+ # end
196
+ # end
197
+ #
198
+ # = Multipart Emails with Attachments
199
+ #
200
+ # Multipart emails that also have attachments can be created by nesting a "multipart/alternative" part
201
+ # within an email that has its content type set to "multipart/mixed". This would also need two templates
202
+ # in place within +app/views/mailer+ called "welcome_email.text.html.erb" and "welcome_email.text.plain.erb"
203
+ #
204
+ # class ApplicationMailer < ActionMailer::Base
205
+ # def signup_notification(recipient)
206
+ # recipients recipient.email_address_with_name
207
+ # subject "New account information"
208
+ # from "system@example.com"
209
+ # content_type "multipart/mixed"
210
+ #
211
+ # part "multipart/alternative" do |alternative|
212
+ #
213
+ # alternative.part "text/html" do |html|
214
+ # html.body = render_message("welcome_email.text.html", :message => "<h1>HTML content</h1>")
215
+ # end
216
+ #
217
+ # alternative.part "text/plain" do |plain|
218
+ # plain.body = render_message("welcome_email.text.plain", :message => "text content")
219
+ # end
220
+ #
221
+ # end
222
+ #
223
+ # attachment :content_type => "image/png",
224
+ # :body => File.read(File.join(RAILS_ROOT, 'public/images/rails.png'))
225
+ #
226
+ # attachment "application/pdf" do |a|
227
+ # a.body = File.read('/Users/mikel/Code/mail/spec/fixtures/attachments/test.pdf')
228
+ # end
229
+ # end
230
+ # end
231
+ #
232
+ # = Configuration options
233
+ #
234
+ # These options are specified on the class level, like <tt>ActionMailer::Base.template_root = "/my/templates"</tt>
235
+ #
236
+ # * <tt>template_root</tt> - Determines the base from which template references will be made.
237
+ #
238
+ # * <tt>logger</tt> - the logger is used for generating information on the mailing run if available.
239
+ # Can be set to nil for no logging. Compatible with both Ruby's own Logger and Log4r loggers.
240
+ #
241
+ # * <tt>smtp_settings</tt> - Allows detailed configuration for <tt>:smtp</tt> delivery method:
242
+ # * <tt>:address</tt> - Allows you to use a remote mail server. Just change it from its default "localhost" setting.
243
+ # * <tt>:port</tt> - On the off chance that your mail server doesn't run on port 25, you can change it.
244
+ # * <tt>:domain</tt> - If you need to specify a HELO domain, you can do it here.
245
+ # * <tt>:user_name</tt> - If your mail server requires authentication, set the username in this setting.
246
+ # * <tt>:password</tt> - If your mail server requires authentication, set the password in this setting.
247
+ # * <tt>:authentication</tt> - If your mail server requires authentication, you need to specify the authentication type here.
248
+ # This is a symbol and one of <tt>:plain</tt>, <tt>:login</tt>, <tt>:cram_md5</tt>.
249
+ # * <tt>:enable_starttls_auto</tt> - When set to true, detects if STARTTLS is enabled in your SMTP server and starts to use it.
250
+ # It works only on Ruby >= 1.8.7 and Ruby >= 1.9. Default is true.
251
+ #
252
+ # * <tt>sendmail_settings</tt> - Allows you to override options for the <tt>:sendmail</tt> delivery method.
253
+ # * <tt>:location</tt> - The location of the sendmail executable. Defaults to <tt>/usr/sbin/sendmail</tt>.
254
+ # * <tt>:arguments</tt> - The command line arguments. Defaults to <tt>-i -t</tt>.
255
+ #
256
+ # * <tt>raise_delivery_errors</tt> - Whether or not errors should be raised if the email fails to be delivered.
257
+ #
258
+ # * <tt>delivery_method</tt> - Defines a delivery method. Possible values are <tt>:smtp</tt> (default), <tt>:sendmail</tt>, and <tt>:test</tt>.
259
+ #
260
+ # * <tt>perform_deliveries</tt> - Determines whether <tt>deliver_*</tt> methods are actually carried out. By default they are,
261
+ # but this can be turned off to help functional testing.
262
+ #
263
+ # * <tt>deliveries</tt> - Keeps an array of all the emails sent out through the Action Mailer with <tt>delivery_method :test</tt>. Most useful
264
+ # for unit and functional testing.
265
+ #
266
+ # * <tt>default_charset</tt> - The default charset used for the body and to encode the subject. Defaults to UTF-8. You can also
267
+ # pick a different charset from inside a method with +charset+.
268
+ #
269
+ # * <tt>default_content_type</tt> - The default content type used for the main part of the message. Defaults to "text/plain". You
270
+ # can also pick a different content type from inside a method with +content_type+.
271
+ #
272
+ # * <tt>default_mime_version</tt> - The default mime version used for the message. Defaults to <tt>1.0</tt>. You
273
+ # can also pick a different value from inside a method with +mime_version+.
274
+ #
275
+ # * <tt>default_implicit_parts_order</tt> - When a message is built implicitly (i.e. multiple parts are assembled from templates
276
+ # which specify the content type in their filenames) this variable controls how the parts are ordered. Defaults to
277
+ # <tt>["text/html", "text/enriched", "text/plain"]</tt>. Items that appear first in the array have higher priority in the mail client
278
+ # and appear last in the mime encoded message. You can also pick a different order from inside a method with
279
+ # +implicit_parts_order+.
280
+ class Base
281
+ include AdvAttrAccessor, PartContainer, Quoting, Utils
282
+ if Object.const_defined?(:ActionController)
283
+ include ActionController::UrlWriter
284
+ include ActionController::Layout
285
+ end
286
+
287
+ private_class_method :new #:nodoc:
288
+
289
+ class_inheritable_accessor :view_paths
290
+ self.view_paths = []
291
+
292
+ cattr_accessor :logger
293
+
294
+ @@smtp_settings = {
295
+ :address => "localhost",
296
+ :port => 25,
297
+ :domain => 'localhost.localdomain',
298
+ :user_name => nil,
299
+ :password => nil,
300
+ :authentication => nil,
301
+ :enable_starttls_auto => true,
302
+ }
303
+ cattr_accessor :smtp_settings
304
+
305
+ @@sendmail_settings = {
306
+ :location => '/usr/sbin/sendmail',
307
+ :arguments => '-i -t'
308
+ }
309
+ cattr_accessor :sendmail_settings
310
+
311
+ @@raise_delivery_errors = true
312
+ cattr_accessor :raise_delivery_errors
313
+
314
+ class_attribute :delivery_method
315
+ self.delivery_method = :smtp
316
+
317
+ @@perform_deliveries = true
318
+ cattr_accessor :perform_deliveries
319
+
320
+ @@deliveries = []
321
+ cattr_accessor :deliveries
322
+
323
+ @@default_charset = "utf-8"
324
+ cattr_accessor :default_charset
325
+
326
+ @@default_content_type = "text/plain"
327
+ cattr_accessor :default_content_type
328
+
329
+ @@default_mime_version = "1.0"
330
+ cattr_accessor :default_mime_version
331
+
332
+ @@default_implicit_parts_order = [ "text/html", "text/enriched", "text/plain" ]
333
+ cattr_accessor :default_implicit_parts_order
334
+
335
+ cattr_reader :protected_instance_variables
336
+ @@protected_instance_variables = %w(@body)
337
+
338
+ # Specify the BCC addresses for the message
339
+ adv_attr_accessor :bcc
340
+
341
+ # Define the body of the message. This is either a Hash (in which case it
342
+ # specifies the variables to pass to the template when it is rendered),
343
+ # or a string, in which case it specifies the actual text of the message.
344
+ adv_attr_accessor :body
345
+
346
+ # Specify the CC addresses for the message.
347
+ adv_attr_accessor :cc
348
+
349
+ # Specify the charset to use for the message. This defaults to the
350
+ # +default_charset+ specified for ActionMailer::Base.
351
+ adv_attr_accessor :charset
352
+
353
+ # Specify the content type for the message. This defaults to <tt>text/plain</tt>
354
+ # in most cases, but can be automatically set in some situations.
355
+ adv_attr_accessor :content_type
356
+
357
+ # Specify the from address for the message.
358
+ adv_attr_accessor :from
359
+
360
+ # Specify the address (if different than the "from" address) to direct
361
+ # replies to this message.
362
+ adv_attr_accessor :reply_to
363
+
364
+ # Specify additional headers to be added to the message.
365
+ adv_attr_accessor :headers
366
+
367
+ # Specify the order in which parts should be sorted, based on content-type.
368
+ # This defaults to the value for the +default_implicit_parts_order+.
369
+ adv_attr_accessor :implicit_parts_order
370
+
371
+ # Defaults to "1.0", but may be explicitly given if needed.
372
+ adv_attr_accessor :mime_version
373
+
374
+ # The recipient addresses for the message, either as a string (for a single
375
+ # address) or an array (for multiple addresses).
376
+ adv_attr_accessor :recipients
377
+
378
+ # The date on which the message was sent. If not set (the default), the
379
+ # header will be set by the delivery agent.
380
+ adv_attr_accessor :sent_on
381
+
382
+ # Specify the subject of the message.
383
+ adv_attr_accessor :subject
384
+
385
+ # Specify the template name to use for current message. This is the "base"
386
+ # template name, without the extension or directory, and may be used to
387
+ # have multiple mailer methods share the same template.
388
+ adv_attr_accessor :template
389
+
390
+ # Override the mailer name, which defaults to an inflected version of the
391
+ # mailer's class name. If you want to use a template in a non-standard
392
+ # location, you can use this to specify that location.
393
+ def mailer_name(value = nil)
394
+ if value
395
+ self.mailer_name = value
396
+ else
397
+ self.class.mailer_name
398
+ end
399
+ end
400
+
401
+ def mailer_name=(value)
402
+ self.class.mailer_name = value
403
+ end
404
+
405
+ # The mail object instance referenced by this mailer.
406
+ attr_reader :mail
407
+ attr_reader :template_name, :default_template_name, :action_name
408
+
409
+ class << self
410
+ attr_writer :mailer_name
411
+
412
+ def mailer_name
413
+ @mailer_name ||= name.underscore
414
+ end
415
+
416
+ # for ActionView compatibility
417
+ alias_method :controller_name, :mailer_name
418
+ alias_method :controller_path, :mailer_name
419
+
420
+ def respond_to?(method_symbol, include_private = false) #:nodoc:
421
+ matches_dynamic_method?(method_symbol) || super
422
+ end
423
+
424
+ def method_missing(method_symbol, *parameters) #:nodoc:
425
+ if match = matches_dynamic_method?(method_symbol)
426
+ case match[1]
427
+ when 'create' then new(match[2], *parameters).mail
428
+ when 'deliver' then new(match[2], *parameters).deliver!
429
+ when 'new' then nil
430
+ else super
431
+ end
432
+ else
433
+ super
434
+ end
435
+ end
436
+
437
+ # Receives a raw email, parses it into an email object, decodes it,
438
+ # instantiates a new mailer, and passes the email object to the mailer
439
+ # object's +receive+ method. If you want your mailer to be able to
440
+ # process incoming messages, you'll need to implement a +receive+
441
+ # method that accepts the email object as a parameter:
442
+ #
443
+ # class MyMailer < ActionMailer::Base
444
+ # def receive(mail)
445
+ # ...
446
+ # end
447
+ # end
448
+ def receive(raw_email)
449
+ logger.info "Received mail:\n #{raw_email}" unless logger.nil?
450
+ mail = TMail::Mail.parse(raw_email)
451
+ mail.base64_decode
452
+ new.receive(mail)
453
+ end
454
+
455
+ # Deliver the given mail object directly. This can be used to deliver
456
+ # a preconstructed mail object, like:
457
+ #
458
+ # email = MyMailer.create_some_mail(parameters)
459
+ # email.set_some_obscure_header "frobnicate"
460
+ # MyMailer.deliver(email)
461
+ def deliver(mail)
462
+ new.deliver!(mail)
463
+ end
464
+
465
+ def template_root
466
+ self.view_paths && self.view_paths.first
467
+ end
468
+
469
+ def template_root=(root)
470
+ self.view_paths = ActionView::Base.process_view_paths(root)
471
+ end
472
+
473
+ private
474
+ def matches_dynamic_method?(method_name) #:nodoc:
475
+ method_name = method_name.to_s
476
+ /^(create|deliver)_([_a-z]\w*)/.match(method_name) || /^(new)$/.match(method_name)
477
+ end
478
+ end
479
+
480
+ # Instantiate a new mailer object. If +method_name+ is not +nil+, the mailer
481
+ # will be initialized according to the named method. If not, the mailer will
482
+ # remain uninitialized (useful when you only need to invoke the "receive"
483
+ # method, for instance).
484
+ def initialize(method_name=nil, *parameters) #:nodoc:
485
+ create!(method_name, *parameters) if method_name
486
+ end
487
+
488
+ # Initialize the mailer via the given +method_name+. The body will be
489
+ # rendered and a new TMail::Mail object created.
490
+ def create!(method_name, *parameters) #:nodoc:
491
+ initialize_defaults(method_name)
492
+ __send__(method_name, *parameters)
493
+
494
+ # If an explicit, textual body has not been set, we check assumptions.
495
+ unless String === @body
496
+ # First, we look to see if there are any likely templates that match,
497
+ # which include the content-type in their file name (i.e.,
498
+ # "the_template_file.text.html.erb", etc.). Only do this if parts
499
+ # have not already been specified manually.
500
+ if @parts.empty?
501
+ Dir.glob("#{template_path}/#{@template}.*").each do |path|
502
+ template = template_root["#{mailer_name}/#{File.basename(path)}"]
503
+
504
+ # Skip unless template has a multipart format
505
+ next unless template && template.multipart?
506
+
507
+ @parts << Part.new(
508
+ :content_type => template.content_type,
509
+ :disposition => "inline",
510
+ :charset => charset,
511
+ :body => render_message(template, @body)
512
+ )
513
+ end
514
+ unless @parts.empty?
515
+ @content_type = "multipart/alternative" if @content_type !~ /^multipart/
516
+ @parts = sort_parts(@parts, @implicit_parts_order)
517
+ end
518
+ end
519
+
520
+ # Then, if there were such templates, we check to see if we ought to
521
+ # also render a "normal" template (without the content type). If a
522
+ # normal template exists (or if there were no implicit parts) we render
523
+ # it.
524
+ template_exists = @parts.empty?
525
+ template_exists ||= template_root["#{mailer_name}/#{@template}"]
526
+ @body = render_message(@template, @body) if template_exists
527
+
528
+ # Finally, if there are other message parts and a textual body exists,
529
+ # we shift it onto the front of the parts and set the body to nil (so
530
+ # that create_mail doesn't try to render it in addition to the parts).
531
+ if !@parts.empty? && String === @body
532
+ @parts.unshift Part.new(:charset => charset, :body => @body)
533
+ @body = nil
534
+ end
535
+ end
536
+
537
+ # If this is a multipart e-mail add the mime_version if it is not
538
+ # already set.
539
+ @mime_version ||= "1.0" if !@parts.empty?
540
+
541
+ # build the mail object itself
542
+ @mail = create_mail
543
+ end
544
+
545
+ # Delivers a TMail::Mail object. By default, it delivers the cached mail
546
+ # object (from the <tt>create!</tt> method). If no cached mail object exists, and
547
+ # no alternate has been given as the parameter, this will fail.
548
+ def deliver!(mail = @mail)
549
+ raise "no mail object available for delivery!" unless mail
550
+ unless logger.nil?
551
+ logger.info "Sent mail to #{Array(recipients).join(', ')}"
552
+ logger.debug "\n#{mail.encoded}"
553
+ end
554
+
555
+ begin
556
+ __send__("perform_delivery_#{delivery_method}", mail) if perform_deliveries
557
+ rescue Exception => e # Net::SMTP errors or sendmail pipe errors
558
+ raise e if raise_delivery_errors
559
+ end
560
+
561
+ return mail
562
+ end
563
+
564
+ private
565
+ # Set up the default values for the various instance variables of this
566
+ # mailer. Subclasses may override this method to provide different
567
+ # defaults.
568
+ def initialize_defaults(method_name)
569
+ @charset ||= @@default_charset.dup
570
+ @content_type ||= @@default_content_type.dup
571
+ @implicit_parts_order ||= @@default_implicit_parts_order.dup
572
+ @template ||= method_name
573
+ @default_template_name = @action_name = @template
574
+ @mailer_name ||= self.class.name.underscore
575
+ @parts ||= []
576
+ @headers ||= {}
577
+ @body ||= {}
578
+ @mime_version = @@default_mime_version.dup if @@default_mime_version
579
+ @sent_on ||= Time.now
580
+ end
581
+
582
+ def render_message(method_name, body)
583
+ if method_name.respond_to?(:content_type)
584
+ @current_template_content_type = method_name.content_type
585
+ end
586
+ render :file => method_name, :body => body
587
+ ensure
588
+ @current_template_content_type = nil
589
+ end
590
+
591
+ def render(opts)
592
+ body = opts.delete(:body)
593
+ if opts[:file] && (opts[:file] !~ /\// && !opts[:file].respond_to?(:render))
594
+ opts[:file] = "#{mailer_name}/#{opts[:file]}"
595
+ end
596
+
597
+ begin
598
+ old_template, @template = @template, initialize_template_class(body)
599
+ layout = respond_to?(:pick_layout, true) ? pick_layout(opts) : false
600
+ @template.render(opts.merge(:layout => layout))
601
+ ensure
602
+ @template = old_template
603
+ end
604
+ end
605
+
606
+ def default_template_format
607
+ if @current_template_content_type
608
+ Mime::Type.lookup(@current_template_content_type).to_sym
609
+ else
610
+ :html
611
+ end
612
+ end
613
+
614
+ def candidate_for_layout?(options)
615
+ !self.view_paths.find_template(default_template_name, default_template_format).exempt_from_layout?
616
+ rescue ActionView::MissingTemplate
617
+ return true
618
+ end
619
+
620
+ def template_root
621
+ self.class.template_root
622
+ end
623
+
624
+ def template_root=(root)
625
+ self.class.template_root = root
626
+ end
627
+
628
+ def template_path
629
+ File.join(template_root, mailer_name)
630
+ end
631
+
632
+ def initialize_template_class(assigns)
633
+ template = ActionView::Base.new(self.class.view_paths, assigns, self)
634
+ template.template_format = default_template_format
635
+ template
636
+ end
637
+
638
+ def sort_parts(parts, order = [])
639
+ order = order.collect { |s| s.downcase }
640
+
641
+ parts = parts.sort do |a, b|
642
+ a_ct = a.content_type.downcase
643
+ b_ct = b.content_type.downcase
644
+
645
+ a_in = order.include? a_ct
646
+ b_in = order.include? b_ct
647
+
648
+ s = case
649
+ when a_in && b_in
650
+ order.index(a_ct) <=> order.index(b_ct)
651
+ when a_in
652
+ -1
653
+ when b_in
654
+ 1
655
+ else
656
+ a_ct <=> b_ct
657
+ end
658
+
659
+ # reverse the ordering because parts that come last are displayed
660
+ # first in mail clients
661
+ (s * -1)
662
+ end
663
+
664
+ parts
665
+ end
666
+
667
+ def create_mail
668
+ m = TMail::Mail.new
669
+
670
+ m.subject, = quote_any_if_necessary(charset, subject)
671
+ m.to, m.from = quote_any_address_if_necessary(charset, recipients, from)
672
+ m.bcc = quote_address_if_necessary(bcc, charset) unless bcc.nil?
673
+ m.cc = quote_address_if_necessary(cc, charset) unless cc.nil?
674
+ m.reply_to = quote_address_if_necessary(reply_to, charset) unless reply_to.nil?
675
+ m.mime_version = mime_version unless mime_version.nil?
676
+ m.date = sent_on.to_time rescue sent_on if sent_on
677
+
678
+ headers.each { |k, v| m[k] = v }
679
+
680
+ real_content_type, ctype_attrs = parse_content_type
681
+
682
+ if @parts.empty?
683
+ m.set_content_type(real_content_type, nil, ctype_attrs)
684
+ m.body = normalize_new_lines(body)
685
+ else
686
+ if String === body
687
+ part = TMail::Mail.new
688
+ part.body = normalize_new_lines(body)
689
+ part.set_content_type(real_content_type, nil, ctype_attrs)
690
+ part.set_content_disposition "inline"
691
+ m.parts << part
692
+ end
693
+
694
+ @parts.each do |p|
695
+ part = (TMail::Mail === p ? p : p.to_mail(self))
696
+ m.parts << part
697
+ end
698
+
699
+ if real_content_type =~ /multipart/
700
+ ctype_attrs.delete "charset"
701
+ m.set_content_type(real_content_type, nil, ctype_attrs)
702
+ end
703
+ end
704
+
705
+ @mail = m
706
+ end
707
+
708
+ def perform_delivery_smtp(mail)
709
+ destinations = mail.destinations
710
+ mail.ready_to_send
711
+ sender = (mail['return-path'] && mail['return-path'].spec) || Array(mail.from).first
712
+
713
+ smtp = Net::SMTP.new(smtp_settings[:address], smtp_settings[:port])
714
+ smtp.enable_starttls_auto if smtp_settings[:enable_starttls_auto] && smtp.respond_to?(:enable_starttls_auto)
715
+ smtp.start(smtp_settings[:domain], smtp_settings[:user_name], smtp_settings[:password],
716
+ smtp_settings[:authentication]) do |smtp|
717
+ smtp.sendmail(mail.encoded, sender, destinations)
718
+ end
719
+ end
720
+
721
+ def perform_delivery_sendmail(mail)
722
+ sendmail_args = sendmail_settings[:arguments]
723
+ sendmail_args += " -f \"#{mail['return-path']}\"" if mail['return-path']
724
+ IO.popen("#{sendmail_settings[:location]} #{sendmail_args}","w+") do |sm|
725
+ sm.print(mail.encoded.gsub(/\r/, ''))
726
+ sm.flush
727
+ end
728
+ end
729
+
730
+ def perform_delivery_test(mail)
731
+ deliveries << mail
732
+ end
733
+ end
734
+
735
+ Base.class_eval do
736
+ include Helpers
737
+ helper MailHelper
738
+ end
739
+ end