rails 4.2.6.rc1 → 5.2.8.1

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of rails might be problematic. Click here for more details.

Files changed (218) hide show
  1. checksums.yaml +5 -5
  2. data/README.md +24 -12
  3. metadata +54 -248
  4. data/guides/CHANGELOG.md +0 -73
  5. data/guides/Rakefile +0 -79
  6. data/guides/assets/images/akshaysurve.jpg +0 -0
  7. data/guides/assets/images/belongs_to.png +0 -0
  8. data/guides/assets/images/book_icon.gif +0 -0
  9. data/guides/assets/images/bullet.gif +0 -0
  10. data/guides/assets/images/chapters_icon.gif +0 -0
  11. data/guides/assets/images/check_bullet.gif +0 -0
  12. data/guides/assets/images/credits_pic_blank.gif +0 -0
  13. data/guides/assets/images/csrf.png +0 -0
  14. data/guides/assets/images/edge_badge.png +0 -0
  15. data/guides/assets/images/favicon.ico +0 -0
  16. data/guides/assets/images/feature_tile.gif +0 -0
  17. data/guides/assets/images/footer_tile.gif +0 -0
  18. data/guides/assets/images/fxn.png +0 -0
  19. data/guides/assets/images/getting_started/article_with_comments.png +0 -0
  20. data/guides/assets/images/getting_started/challenge.png +0 -0
  21. data/guides/assets/images/getting_started/confirm_dialog.png +0 -0
  22. data/guides/assets/images/getting_started/forbidden_attributes_for_new_article.png +0 -0
  23. data/guides/assets/images/getting_started/form_with_errors.png +0 -0
  24. data/guides/assets/images/getting_started/index_action_with_edit_link.png +0 -0
  25. data/guides/assets/images/getting_started/new_article.png +0 -0
  26. data/guides/assets/images/getting_started/rails_welcome.png +0 -0
  27. data/guides/assets/images/getting_started/routing_error_no_controller.png +0 -0
  28. data/guides/assets/images/getting_started/routing_error_no_route_matches.png +0 -0
  29. data/guides/assets/images/getting_started/show_action_for_articles.png +0 -0
  30. data/guides/assets/images/getting_started/template_is_missing_articles_new.png +0 -0
  31. data/guides/assets/images/getting_started/unknown_action_create_for_articles.png +0 -0
  32. data/guides/assets/images/getting_started/unknown_action_new_for_articles.png +0 -0
  33. data/guides/assets/images/grey_bullet.gif +0 -0
  34. data/guides/assets/images/habtm.png +0 -0
  35. data/guides/assets/images/has_many.png +0 -0
  36. data/guides/assets/images/has_many_through.png +0 -0
  37. data/guides/assets/images/has_one.png +0 -0
  38. data/guides/assets/images/has_one_through.png +0 -0
  39. data/guides/assets/images/header_backdrop.png +0 -0
  40. data/guides/assets/images/header_tile.gif +0 -0
  41. data/guides/assets/images/i18n/demo_html_safe.png +0 -0
  42. data/guides/assets/images/i18n/demo_localized_pirate.png +0 -0
  43. data/guides/assets/images/i18n/demo_translated_en.png +0 -0
  44. data/guides/assets/images/i18n/demo_translated_pirate.png +0 -0
  45. data/guides/assets/images/i18n/demo_translation_missing.png +0 -0
  46. data/guides/assets/images/i18n/demo_untranslated.png +0 -0
  47. data/guides/assets/images/icons/README +0 -5
  48. data/guides/assets/images/icons/callouts/1.png +0 -0
  49. data/guides/assets/images/icons/callouts/10.png +0 -0
  50. data/guides/assets/images/icons/callouts/11.png +0 -0
  51. data/guides/assets/images/icons/callouts/12.png +0 -0
  52. data/guides/assets/images/icons/callouts/13.png +0 -0
  53. data/guides/assets/images/icons/callouts/14.png +0 -0
  54. data/guides/assets/images/icons/callouts/15.png +0 -0
  55. data/guides/assets/images/icons/callouts/2.png +0 -0
  56. data/guides/assets/images/icons/callouts/3.png +0 -0
  57. data/guides/assets/images/icons/callouts/4.png +0 -0
  58. data/guides/assets/images/icons/callouts/5.png +0 -0
  59. data/guides/assets/images/icons/callouts/6.png +0 -0
  60. data/guides/assets/images/icons/callouts/7.png +0 -0
  61. data/guides/assets/images/icons/callouts/8.png +0 -0
  62. data/guides/assets/images/icons/callouts/9.png +0 -0
  63. data/guides/assets/images/icons/caution.png +0 -0
  64. data/guides/assets/images/icons/example.png +0 -0
  65. data/guides/assets/images/icons/home.png +0 -0
  66. data/guides/assets/images/icons/important.png +0 -0
  67. data/guides/assets/images/icons/next.png +0 -0
  68. data/guides/assets/images/icons/note.png +0 -0
  69. data/guides/assets/images/icons/prev.png +0 -0
  70. data/guides/assets/images/icons/tip.png +0 -0
  71. data/guides/assets/images/icons/up.png +0 -0
  72. data/guides/assets/images/icons/warning.png +0 -0
  73. data/guides/assets/images/nav_arrow.gif +0 -0
  74. data/guides/assets/images/oscardelben.jpg +0 -0
  75. data/guides/assets/images/polymorphic.png +0 -0
  76. data/guides/assets/images/radar.png +0 -0
  77. data/guides/assets/images/rails4_features.png +0 -0
  78. data/guides/assets/images/rails_guides_kindle_cover.jpg +0 -0
  79. data/guides/assets/images/rails_guides_logo.gif +0 -0
  80. data/guides/assets/images/rails_logo_remix.gif +0 -0
  81. data/guides/assets/images/session_fixation.png +0 -0
  82. data/guides/assets/images/tab_grey.gif +0 -0
  83. data/guides/assets/images/tab_info.gif +0 -0
  84. data/guides/assets/images/tab_note.gif +0 -0
  85. data/guides/assets/images/tab_red.gif +0 -0
  86. data/guides/assets/images/tab_yellow.gif +0 -0
  87. data/guides/assets/images/tab_yellow.png +0 -0
  88. data/guides/assets/images/vijaydev.jpg +0 -0
  89. data/guides/assets/javascripts/guides.js +0 -59
  90. data/guides/assets/javascripts/jquery.min.js +0 -4
  91. data/guides/assets/javascripts/responsive-tables.js +0 -43
  92. data/guides/assets/javascripts/syntaxhighlighter/shBrushAS3.js +0 -59
  93. data/guides/assets/javascripts/syntaxhighlighter/shBrushAppleScript.js +0 -75
  94. data/guides/assets/javascripts/syntaxhighlighter/shBrushBash.js +0 -59
  95. data/guides/assets/javascripts/syntaxhighlighter/shBrushCSharp.js +0 -65
  96. data/guides/assets/javascripts/syntaxhighlighter/shBrushColdFusion.js +0 -100
  97. data/guides/assets/javascripts/syntaxhighlighter/shBrushCpp.js +0 -97
  98. data/guides/assets/javascripts/syntaxhighlighter/shBrushCss.js +0 -91
  99. data/guides/assets/javascripts/syntaxhighlighter/shBrushDelphi.js +0 -55
  100. data/guides/assets/javascripts/syntaxhighlighter/shBrushDiff.js +0 -41
  101. data/guides/assets/javascripts/syntaxhighlighter/shBrushErlang.js +0 -52
  102. data/guides/assets/javascripts/syntaxhighlighter/shBrushGroovy.js +0 -67
  103. data/guides/assets/javascripts/syntaxhighlighter/shBrushJScript.js +0 -52
  104. data/guides/assets/javascripts/syntaxhighlighter/shBrushJava.js +0 -57
  105. data/guides/assets/javascripts/syntaxhighlighter/shBrushJavaFX.js +0 -58
  106. data/guides/assets/javascripts/syntaxhighlighter/shBrushPerl.js +0 -72
  107. data/guides/assets/javascripts/syntaxhighlighter/shBrushPhp.js +0 -88
  108. data/guides/assets/javascripts/syntaxhighlighter/shBrushPlain.js +0 -33
  109. data/guides/assets/javascripts/syntaxhighlighter/shBrushPowerShell.js +0 -74
  110. data/guides/assets/javascripts/syntaxhighlighter/shBrushPython.js +0 -64
  111. data/guides/assets/javascripts/syntaxhighlighter/shBrushRuby.js +0 -55
  112. data/guides/assets/javascripts/syntaxhighlighter/shBrushSass.js +0 -94
  113. data/guides/assets/javascripts/syntaxhighlighter/shBrushScala.js +0 -51
  114. data/guides/assets/javascripts/syntaxhighlighter/shBrushSql.js +0 -66
  115. data/guides/assets/javascripts/syntaxhighlighter/shBrushVb.js +0 -56
  116. data/guides/assets/javascripts/syntaxhighlighter/shBrushXml.js +0 -69
  117. data/guides/assets/javascripts/syntaxhighlighter/shCore.js +0 -17
  118. data/guides/assets/stylesheets/fixes.css +0 -16
  119. data/guides/assets/stylesheets/kindle.css +0 -11
  120. data/guides/assets/stylesheets/main.css +0 -713
  121. data/guides/assets/stylesheets/print.css +0 -52
  122. data/guides/assets/stylesheets/reset.css +0 -43
  123. data/guides/assets/stylesheets/responsive-tables.css +0 -50
  124. data/guides/assets/stylesheets/style.css +0 -13
  125. data/guides/assets/stylesheets/syntaxhighlighter/shCore.css +0 -226
  126. data/guides/assets/stylesheets/syntaxhighlighter/shCoreDefault.css +0 -328
  127. data/guides/assets/stylesheets/syntaxhighlighter/shCoreDjango.css +0 -331
  128. data/guides/assets/stylesheets/syntaxhighlighter/shCoreEclipse.css +0 -339
  129. data/guides/assets/stylesheets/syntaxhighlighter/shCoreEmacs.css +0 -324
  130. data/guides/assets/stylesheets/syntaxhighlighter/shCoreFadeToGrey.css +0 -328
  131. data/guides/assets/stylesheets/syntaxhighlighter/shCoreMDUltra.css +0 -324
  132. data/guides/assets/stylesheets/syntaxhighlighter/shCoreMidnight.css +0 -324
  133. data/guides/assets/stylesheets/syntaxhighlighter/shCoreRDark.css +0 -324
  134. data/guides/assets/stylesheets/syntaxhighlighter/shThemeDefault.css +0 -117
  135. data/guides/assets/stylesheets/syntaxhighlighter/shThemeDjango.css +0 -120
  136. data/guides/assets/stylesheets/syntaxhighlighter/shThemeEclipse.css +0 -128
  137. data/guides/assets/stylesheets/syntaxhighlighter/shThemeEmacs.css +0 -113
  138. data/guides/assets/stylesheets/syntaxhighlighter/shThemeFadeToGrey.css +0 -117
  139. data/guides/assets/stylesheets/syntaxhighlighter/shThemeMDUltra.css +0 -113
  140. data/guides/assets/stylesheets/syntaxhighlighter/shThemeMidnight.css +0 -113
  141. data/guides/assets/stylesheets/syntaxhighlighter/shThemeRDark.css +0 -113
  142. data/guides/assets/stylesheets/syntaxhighlighter/shThemeRailsGuides.css +0 -116
  143. data/guides/bug_report_templates/action_controller_gem.rb +0 -47
  144. data/guides/bug_report_templates/action_controller_master.rb +0 -54
  145. data/guides/bug_report_templates/active_record_gem.rb +0 -40
  146. data/guides/bug_report_templates/active_record_master.rb +0 -49
  147. data/guides/bug_report_templates/generic_gem.rb +0 -15
  148. data/guides/bug_report_templates/generic_master.rb +0 -26
  149. data/guides/rails_guides/generator.rb +0 -248
  150. data/guides/rails_guides/helpers.rb +0 -53
  151. data/guides/rails_guides/indexer.rb +0 -68
  152. data/guides/rails_guides/kindle.rb +0 -119
  153. data/guides/rails_guides/levenshtein.rb +0 -37
  154. data/guides/rails_guides/markdown/renderer.rb +0 -82
  155. data/guides/rails_guides/markdown.rb +0 -167
  156. data/guides/rails_guides.rb +0 -63
  157. data/guides/source/2_2_release_notes.md +0 -435
  158. data/guides/source/2_3_release_notes.md +0 -621
  159. data/guides/source/3_0_release_notes.md +0 -611
  160. data/guides/source/3_1_release_notes.md +0 -559
  161. data/guides/source/3_2_release_notes.md +0 -568
  162. data/guides/source/4_0_release_notes.md +0 -279
  163. data/guides/source/4_1_release_notes.md +0 -730
  164. data/guides/source/4_2_release_notes.md +0 -877
  165. data/guides/source/_license.html.erb +0 -2
  166. data/guides/source/_welcome.html.erb +0 -23
  167. data/guides/source/action_controller_overview.md +0 -1192
  168. data/guides/source/action_mailer_basics.md +0 -757
  169. data/guides/source/action_view_overview.md +0 -1561
  170. data/guides/source/active_job_basics.md +0 -339
  171. data/guides/source/active_model_basics.md +0 -554
  172. data/guides/source/active_record_basics.md +0 -374
  173. data/guides/source/active_record_callbacks.md +0 -413
  174. data/guides/source/active_record_migrations.md +0 -1018
  175. data/guides/source/active_record_postgresql.md +0 -433
  176. data/guides/source/active_record_querying.md +0 -1781
  177. data/guides/source/active_record_validations.md +0 -1179
  178. data/guides/source/active_support_core_extensions.md +0 -3857
  179. data/guides/source/active_support_instrumentation.md +0 -488
  180. data/guides/source/api_documentation_guidelines.md +0 -361
  181. data/guides/source/asset_pipeline.md +0 -1304
  182. data/guides/source/association_basics.md +0 -2245
  183. data/guides/source/autoloading_and_reloading_constants.md +0 -1311
  184. data/guides/source/caching_with_rails.md +0 -379
  185. data/guides/source/command_line.md +0 -625
  186. data/guides/source/configuring.md +0 -1072
  187. data/guides/source/contributing_to_ruby_on_rails.md +0 -628
  188. data/guides/source/credits.html.erb +0 -80
  189. data/guides/source/debugging_rails_applications.md +0 -861
  190. data/guides/source/development_dependencies_install.md +0 -289
  191. data/guides/source/documents.yaml +0 -205
  192. data/guides/source/engines.md +0 -1412
  193. data/guides/source/form_helpers.md +0 -1024
  194. data/guides/source/generators.md +0 -676
  195. data/guides/source/getting_started.md +0 -2086
  196. data/guides/source/i18n.md +0 -1087
  197. data/guides/source/index.html.erb +0 -28
  198. data/guides/source/initialization.md +0 -704
  199. data/guides/source/kindle/copyright.html.erb +0 -1
  200. data/guides/source/kindle/layout.html.erb +0 -27
  201. data/guides/source/kindle/rails_guides.opf.erb +0 -52
  202. data/guides/source/kindle/toc.html.erb +0 -24
  203. data/guides/source/kindle/toc.ncx.erb +0 -64
  204. data/guides/source/kindle/welcome.html.erb +0 -5
  205. data/guides/source/layout.html.erb +0 -140
  206. data/guides/source/layouts_and_rendering.md +0 -1227
  207. data/guides/source/maintenance_policy.md +0 -78
  208. data/guides/source/nested_model_forms.md +0 -228
  209. data/guides/source/plugins.md +0 -444
  210. data/guides/source/rails_application_templates.md +0 -266
  211. data/guides/source/rails_on_rack.md +0 -336
  212. data/guides/source/routing.md +0 -1155
  213. data/guides/source/ruby_on_rails_guides_guidelines.md +0 -127
  214. data/guides/source/security.md +0 -1024
  215. data/guides/source/testing.md +0 -1132
  216. data/guides/source/upgrading_ruby_on_rails.md +0 -1186
  217. data/guides/source/working_with_javascript_in_rails.md +0 -407
  218. data/guides/w3c_validator.rb +0 -97
@@ -1,757 +0,0 @@
1
- Action Mailer Basics
2
- ====================
3
-
4
- This guide provides you with all you need to get started in sending and
5
- receiving emails from and to your application, and many internals of Action
6
- Mailer. It also covers how to test your mailers.
7
-
8
- After reading this guide, you will know:
9
-
10
- * How to send and receive email within a Rails application.
11
- * How to generate and edit an Action Mailer class and mailer view.
12
- * How to configure Action Mailer for your environment.
13
- * How to test your Action Mailer classes.
14
-
15
- --------------------------------------------------------------------------------
16
-
17
- Introduction
18
- ------------
19
-
20
- Action Mailer allows you to send emails from your application using mailer classes
21
- and views. Mailers work very similarly to controllers. They inherit from
22
- `ActionMailer::Base` and live in `app/mailers`, and they have associated views
23
- that appear in `app/views`.
24
-
25
- Sending Emails
26
- --------------
27
-
28
- This section will provide a step-by-step guide to creating a mailer and its
29
- views.
30
-
31
- ### Walkthrough to Generating a Mailer
32
-
33
- #### Create the Mailer
34
-
35
- ```bash
36
- $ bin/rails generate mailer UserMailer
37
- create app/mailers/user_mailer.rb
38
- create app/mailers/application_mailer.rb
39
- invoke erb
40
- create app/views/user_mailer
41
- create app/views/layouts/mailer.text.erb
42
- create app/views/layouts/mailer.html.erb
43
- invoke test_unit
44
- create test/mailers/user_mailer_test.rb
45
- create test/mailers/previews/user_mailer_preview.rb
46
- ```
47
-
48
- ```ruby
49
- # app/mailers/application_mailer.rb
50
- class ApplicationMailer < ActionMailer::Base
51
- default from: "from@example.com"
52
- layout 'mailer'
53
- end
54
-
55
- # app/mailers/user_mailer.rb
56
- class UserMailer < ApplicationMailer
57
- end
58
- ```
59
-
60
- As you can see, you can generate mailers just like you use other generators with
61
- Rails. Mailers are conceptually similar to controllers, and so we get a mailer,
62
- a directory for views, and a test.
63
-
64
- If you didn't want to use a generator, you could create your own file inside of
65
- app/mailers, just make sure that it inherits from `ActionMailer::Base`:
66
-
67
- ```ruby
68
- class MyMailer < ActionMailer::Base
69
- end
70
- ```
71
-
72
- #### Edit the Mailer
73
-
74
- Mailers are very similar to Rails controllers. They also have methods called
75
- "actions" and use views to structure the content. Where a controller generates
76
- content like HTML to send back to the client, a Mailer creates a message to be
77
- delivered via email.
78
-
79
- `app/mailers/user_mailer.rb` contains an empty mailer:
80
-
81
- ```ruby
82
- class UserMailer < ApplicationMailer
83
- end
84
- ```
85
-
86
- Let's add a method called `welcome_email`, that will send an email to the user's
87
- registered email address:
88
-
89
- ```ruby
90
- class UserMailer < ApplicationMailer
91
- default from: 'notifications@example.com'
92
-
93
- def welcome_email(user)
94
- @user = user
95
- @url = 'http://example.com/login'
96
- mail(to: @user.email, subject: 'Welcome to My Awesome Site')
97
- end
98
- end
99
- ```
100
-
101
- Here is a quick explanation of the items presented in the preceding method. For
102
- a full list of all available options, please have a look further down at the
103
- Complete List of Action Mailer user-settable attributes section.
104
-
105
- * `default Hash` - This is a hash of default values for any email you send from
106
- this mailer. In this case we are setting the `:from` header to a value for all
107
- messages in this class. This can be overridden on a per-email basis.
108
- * `mail` - The actual email message, we are passing the `:to` and `:subject`
109
- headers in.
110
-
111
- Just like controllers, any instance variables we define in the method become
112
- available for use in the views.
113
-
114
- #### Create a Mailer View
115
-
116
- Create a file called `welcome_email.html.erb` in `app/views/user_mailer/`. This
117
- will be the template used for the email, formatted in HTML:
118
-
119
- ```html+erb
120
- <!DOCTYPE html>
121
- <html>
122
- <head>
123
- <meta content='text/html; charset=UTF-8' http-equiv='Content-Type' />
124
- </head>
125
- <body>
126
- <h1>Welcome to example.com, <%= @user.name %></h1>
127
- <p>
128
- You have successfully signed up to example.com,
129
- your username is: <%= @user.login %>.<br>
130
- </p>
131
- <p>
132
- To login to the site, just follow this link: <%= @url %>.
133
- </p>
134
- <p>Thanks for joining and have a great day!</p>
135
- </body>
136
- </html>
137
- ```
138
-
139
- Let's also make a text part for this email. Not all clients prefer HTML emails,
140
- and so sending both is best practice. To do this, create a file called
141
- `welcome_email.text.erb` in `app/views/user_mailer/`:
142
-
143
- ```erb
144
- Welcome to example.com, <%= @user.name %>
145
- ===============================================
146
-
147
- You have successfully signed up to example.com,
148
- your username is: <%= @user.login %>.
149
-
150
- To login to the site, just follow this link: <%= @url %>.
151
-
152
- Thanks for joining and have a great day!
153
- ```
154
-
155
- When you call the `mail` method now, Action Mailer will detect the two templates
156
- (text and HTML) and automatically generate a `multipart/alternative` email.
157
-
158
- #### Calling the Mailer
159
-
160
- Mailers are really just another way to render a view. Instead of rendering a
161
- view and sending out the HTTP protocol, they are just sending it out through the
162
- email protocols instead. Due to this, it makes sense to just have your
163
- controller tell the Mailer to send an email when a user is successfully created.
164
-
165
- Setting this up is painfully simple.
166
-
167
- First, let's create a simple `User` scaffold:
168
-
169
- ```bash
170
- $ bin/rails generate scaffold user name email login
171
- $ bin/rake db:migrate
172
- ```
173
-
174
- Now that we have a user model to play with, we will just edit the
175
- `app/controllers/users_controller.rb` make it instruct the `UserMailer` to deliver
176
- an email to the newly created user by editing the create action and inserting a
177
- call to `UserMailer.welcome_email` right after the user is successfully saved.
178
-
179
- Action Mailer is nicely integrated with Active Job so you can send emails outside
180
- of the request-response cycle, so the user doesn't have to wait on it:
181
-
182
- ```ruby
183
- class UsersController < ApplicationController
184
- # POST /users
185
- # POST /users.json
186
- def create
187
- @user = User.new(params[:user])
188
-
189
- respond_to do |format|
190
- if @user.save
191
- # Tell the UserMailer to send a welcome email after save
192
- UserMailer.welcome_email(@user).deliver_later
193
-
194
- format.html { redirect_to(@user, notice: 'User was successfully created.') }
195
- format.json { render json: @user, status: :created, location: @user }
196
- else
197
- format.html { render action: 'new' }
198
- format.json { render json: @user.errors, status: :unprocessable_entity }
199
- end
200
- end
201
- end
202
- end
203
- ```
204
-
205
- NOTE: Active Job's default behavior is to execute jobs ':inline'. So, you can use
206
- `deliver_later` now to send emails, and when you later decide to start sending
207
- them from a background job, you'll only need to set up Active Job to use a queueing
208
- backend (Sidekiq, Resque, etc).
209
-
210
- If you want to send emails right away (from a cronjob for example) just call
211
- `deliver_now`:
212
-
213
- ```ruby
214
- class SendWeeklySummary
215
- def run
216
- User.find_each do |user|
217
- UserMailer.weekly_summary(user).deliver_now
218
- end
219
- end
220
- end
221
- ```
222
-
223
- The method `welcome_email` returns a `ActionMailer::MessageDelivery` object which
224
- can then just be told `deliver_now` or `deliver_later` to send itself out. The
225
- `ActionMailer::MessageDelivery` object is just a wrapper around a `Mail::Message`. If
226
- you want to inspect, alter or do anything else with the `Mail::Message` object you can
227
- access it with the `message` method on the `ActionMailer::MessageDelivery` object.
228
-
229
- ### Auto encoding header values
230
-
231
- Action Mailer handles the auto encoding of multibyte characters inside of
232
- headers and bodies.
233
-
234
- For more complex examples such as defining alternate character sets or
235
- self-encoding text first, please refer to the
236
- [Mail](https://github.com/mikel/mail) library.
237
-
238
- ### Complete List of Action Mailer Methods
239
-
240
- There are just three methods that you need to send pretty much any email
241
- message:
242
-
243
- * `headers` - Specifies any header on the email you want. You can pass a hash of
244
- header field names and value pairs, or you can call `headers[:field_name] =
245
- 'value'`.
246
- * `attachments` - Allows you to add attachments to your email. For example,
247
- `attachments['file-name.jpg'] = File.read('file-name.jpg')`.
248
- * `mail` - Sends the actual email itself. You can pass in headers as a hash to
249
- the mail method as a parameter, mail will then create an email, either plain
250
- text, or multipart, depending on what email templates you have defined.
251
-
252
- #### Adding Attachments
253
-
254
- Action Mailer makes it very easy to add attachments.
255
-
256
- * Pass the file name and content and Action Mailer and the
257
- [Mail gem](https://github.com/mikel/mail) will automatically guess the
258
- mime_type, set the encoding and create the attachment.
259
-
260
- ```ruby
261
- attachments['filename.jpg'] = File.read('/path/to/filename.jpg')
262
- ```
263
-
264
- When the `mail` method will be triggered, it will send a multipart email with
265
- an attachment, properly nested with the top level being `multipart/mixed` and
266
- the first part being a `multipart/alternative` containing the plain text and
267
- HTML email messages.
268
-
269
- NOTE: Mail will automatically Base64 encode an attachment. If you want something
270
- different, encode your content and pass in the encoded content and encoding in a
271
- `Hash` to the `attachments` method.
272
-
273
- * Pass the file name and specify headers and content and Action Mailer and Mail
274
- will use the settings you pass in.
275
-
276
- ```ruby
277
- encoded_content = SpecialEncode(File.read('/path/to/filename.jpg'))
278
- attachments['filename.jpg'] = {
279
- mime_type: 'application/x-gzip',
280
- encoding: 'SpecialEncoding',
281
- content: encoded_content
282
- }
283
- ```
284
-
285
- NOTE: If you specify an encoding, Mail will assume that your content is already
286
- encoded and not try to Base64 encode it.
287
-
288
- #### Making Inline Attachments
289
-
290
- Action Mailer 3.0 makes inline attachments, which involved a lot of hacking in pre 3.0 versions, much simpler and trivial as they should be.
291
-
292
- * First, to tell Mail to turn an attachment into an inline attachment, you just call `#inline` on the attachments method within your Mailer:
293
-
294
- ```ruby
295
- def welcome
296
- attachments.inline['image.jpg'] = File.read('/path/to/image.jpg')
297
- end
298
- ```
299
-
300
- * Then in your view, you can just reference `attachments` as a hash and specify
301
- which attachment you want to show, calling `url` on it and then passing the
302
- result into the `image_tag` method:
303
-
304
- ```html+erb
305
- <p>Hello there, this is our image</p>
306
-
307
- <%= image_tag attachments['image.jpg'].url %>
308
- ```
309
-
310
- * As this is a standard call to `image_tag` you can pass in an options hash
311
- after the attachment URL as you could for any other image:
312
-
313
- ```html+erb
314
- <p>Hello there, this is our image</p>
315
-
316
- <%= image_tag attachments['image.jpg'].url, alt: 'My Photo', class: 'photos' %>
317
- ```
318
-
319
- #### Sending Email To Multiple Recipients
320
-
321
- It is possible to send email to one or more recipients in one email (e.g.,
322
- informing all admins of a new signup) by setting the list of emails to the `:to`
323
- key. The list of emails can be an array of email addresses or a single string
324
- with the addresses separated by commas.
325
-
326
- ```ruby
327
- class AdminMailer < ActionMailer::Base
328
- default to: Proc.new { Admin.pluck(:email) },
329
- from: 'notification@example.com'
330
-
331
- def new_registration(user)
332
- @user = user
333
- mail(subject: "New User Signup: #{@user.email}")
334
- end
335
- end
336
- ```
337
-
338
- The same format can be used to set carbon copy (Cc:) and blind carbon copy
339
- (Bcc:) recipients, by using the `:cc` and `:bcc` keys respectively.
340
-
341
- #### Sending Email With Name
342
-
343
- Sometimes you wish to show the name of the person instead of just their email
344
- address when they receive the email. The trick to doing that is to format the
345
- email address in the format `"Full Name <email>"`.
346
-
347
- ```ruby
348
- def welcome_email(user)
349
- @user = user
350
- email_with_name = %("#{@user.name}" <#{@user.email}>)
351
- mail(to: email_with_name, subject: 'Welcome to My Awesome Site')
352
- end
353
- ```
354
-
355
- ### Mailer Views
356
-
357
- Mailer views are located in the `app/views/name_of_mailer_class` directory. The
358
- specific mailer view is known to the class because its name is the same as the
359
- mailer method. In our example from above, our mailer view for the
360
- `welcome_email` method will be in `app/views/user_mailer/welcome_email.html.erb`
361
- for the HTML version and `welcome_email.text.erb` for the plain text version.
362
-
363
- To change the default mailer view for your action you do something like:
364
-
365
- ```ruby
366
- class UserMailer < ApplicationMailer
367
- default from: 'notifications@example.com'
368
-
369
- def welcome_email(user)
370
- @user = user
371
- @url = 'http://example.com/login'
372
- mail(to: @user.email,
373
- subject: 'Welcome to My Awesome Site',
374
- template_path: 'notifications',
375
- template_name: 'another')
376
- end
377
- end
378
- ```
379
-
380
- In this case it will look for templates at `app/views/notifications` with name
381
- `another`. You can also specify an array of paths for `template_path`, and they
382
- will be searched in order.
383
-
384
- If you want more flexibility you can also pass a block and render specific
385
- templates or even render inline or text without using a template file:
386
-
387
- ```ruby
388
- class UserMailer < ApplicationMailer
389
- default from: 'notifications@example.com'
390
-
391
- def welcome_email(user)
392
- @user = user
393
- @url = 'http://example.com/login'
394
- mail(to: @user.email,
395
- subject: 'Welcome to My Awesome Site') do |format|
396
- format.html { render 'another_template' }
397
- format.text { render text: 'Render text' }
398
- end
399
- end
400
- end
401
- ```
402
-
403
- This will render the template 'another_template.html.erb' for the HTML part and
404
- use the rendered text for the text part. The render command is the same one used
405
- inside of Action Controller, so you can use all the same options, such as
406
- `:text`, `:inline` etc.
407
-
408
- ### Action Mailer Layouts
409
-
410
- Just like controller views, you can also have mailer layouts. The layout name
411
- needs to be the same as your mailer, such as `user_mailer.html.erb` and
412
- `user_mailer.text.erb` to be automatically recognized by your mailer as a
413
- layout.
414
-
415
- In order to use a different file, call `layout` in your mailer:
416
-
417
- ```ruby
418
- class UserMailer < ApplicationMailer
419
- layout 'awesome' # use awesome.(html|text).erb as the layout
420
- end
421
- ```
422
-
423
- Just like with controller views, use `yield` to render the view inside the
424
- layout.
425
-
426
- You can also pass in a `layout: 'layout_name'` option to the render call inside
427
- the format block to specify different layouts for different formats:
428
-
429
- ```ruby
430
- class UserMailer < ApplicationMailer
431
- def welcome_email(user)
432
- mail(to: user.email) do |format|
433
- format.html { render layout: 'my_layout' }
434
- format.text
435
- end
436
- end
437
- end
438
- ```
439
-
440
- Will render the HTML part using the `my_layout.html.erb` file and the text part
441
- with the usual `user_mailer.text.erb` file if it exists.
442
-
443
- ### Generating URLs in Action Mailer Views
444
-
445
- Unlike controllers, the mailer instance doesn't have any context about the
446
- incoming request so you'll need to provide the `:host` parameter yourself.
447
-
448
- As the `:host` usually is consistent across the application you can configure it
449
- globally in `config/application.rb`:
450
-
451
- ```ruby
452
- config.action_mailer.default_url_options = { host: 'example.com' }
453
- ```
454
-
455
- Because of this behavior you cannot use any of the `*_path` helpers inside of
456
- an email. Instead you will need to use the associated `*_url` helper. For example
457
- instead of using
458
-
459
- ```
460
- <%= link_to 'welcome', welcome_path %>
461
- ```
462
-
463
- You will need to use:
464
-
465
- ```
466
- <%= link_to 'welcome', welcome_url %>
467
- ```
468
-
469
- By using the full URL, your links will now work in your emails.
470
-
471
- #### generating URLs with `url_for`
472
-
473
- You need to pass the `only_path: false` option when using `url_for`. This will
474
- ensure that absolute URLs are generated because the `url_for` view helper will,
475
- by default, generate relative URLs when a `:host` option isn't explicitly
476
- provided.
477
-
478
- ```erb
479
- <%= url_for(controller: 'welcome',
480
- action: 'greeting',
481
- only_path: false) %>
482
- ```
483
-
484
- If you did not configure the `:host` option globally make sure to pass it to
485
- `url_for`.
486
-
487
-
488
- ```erb
489
- <%= url_for(host: 'example.com',
490
- controller: 'welcome',
491
- action: 'greeting') %>
492
- ```
493
-
494
- NOTE: When you explicitly pass the `:host` Rails will always generate absolute
495
- URLs, so there is no need to pass `only_path: false`.
496
-
497
- #### generating URLs with named routes
498
-
499
- Email clients have no web context and so paths have no base URL to form complete
500
- web addresses. Thus, you should always use the "_url" variant of named route
501
- helpers.
502
-
503
- If you did not configure the `:host` option globally make sure to pass it to the
504
- url helper.
505
-
506
- ```erb
507
- <%= user_url(@user, host: 'example.com') %>
508
- ```
509
-
510
- NOTE: non-`GET` links require [jQuery UJS](https://github.com/rails/jquery-ujs)
511
- and won't work in mailer templates. They will result in normal `GET` requests.
512
-
513
- ### Sending Multipart Emails
514
-
515
- Action Mailer will automatically send multipart emails if you have different
516
- templates for the same action. So, for our UserMailer example, if you have
517
- `welcome_email.text.erb` and `welcome_email.html.erb` in
518
- `app/views/user_mailer`, Action Mailer will automatically send a multipart email
519
- with the HTML and text versions setup as different parts.
520
-
521
- The order of the parts getting inserted is determined by the `:parts_order`
522
- inside of the `ActionMailer::Base.default` method.
523
-
524
- ### Sending Emails with Dynamic Delivery Options
525
-
526
- If you wish to override the default delivery options (e.g. SMTP credentials)
527
- while delivering emails, you can do this using `delivery_method_options` in the
528
- mailer action.
529
-
530
- ```ruby
531
- class UserMailer < ApplicationMailer
532
- def welcome_email(user, company)
533
- @user = user
534
- @url = user_url(@user)
535
- delivery_options = { user_name: company.smtp_user,
536
- password: company.smtp_password,
537
- address: company.smtp_host }
538
- mail(to: @user.email,
539
- subject: "Please see the Terms and Conditions attached",
540
- delivery_method_options: delivery_options)
541
- end
542
- end
543
- ```
544
-
545
- ### Sending Emails without Template Rendering
546
-
547
- There may be cases in which you want to skip the template rendering step and
548
- supply the email body as a string. You can achieve this using the `:body`
549
- option. In such cases don't forget to add the `:content_type` option. Rails
550
- will default to `text/plain` otherwise.
551
-
552
- ```ruby
553
- class UserMailer < ApplicationMailer
554
- def welcome_email(user, email_body)
555
- mail(to: user.email,
556
- body: email_body,
557
- content_type: "text/html",
558
- subject: "Already rendered!")
559
- end
560
- end
561
- ```
562
-
563
- Receiving Emails
564
- ----------------
565
-
566
- Receiving and parsing emails with Action Mailer can be a rather complex
567
- endeavor. Before your email reaches your Rails app, you would have had to
568
- configure your system to somehow forward emails to your app, which needs to be
569
- listening for that. So, to receive emails in your Rails app you'll need to:
570
-
571
- * Implement a `receive` method in your mailer.
572
-
573
- * Configure your email server to forward emails from the address(es) you would
574
- like your app to receive to `/path/to/app/bin/rails runner
575
- 'UserMailer.receive(STDIN.read)'`.
576
-
577
- Once a method called `receive` is defined in any mailer, Action Mailer will
578
- parse the raw incoming email into an email object, decode it, instantiate a new
579
- mailer, and pass the email object to the mailer `receive` instance
580
- method. Here's an example:
581
-
582
- ```ruby
583
- class UserMailer < ApplicationMailer
584
- def receive(email)
585
- page = Page.find_by(address: email.to.first)
586
- page.emails.create(
587
- subject: email.subject,
588
- body: email.body
589
- )
590
-
591
- if email.has_attachments?
592
- email.attachments.each do |attachment|
593
- page.attachments.create({
594
- file: attachment,
595
- description: email.subject
596
- })
597
- end
598
- end
599
- end
600
- end
601
- ```
602
-
603
- Action Mailer Callbacks
604
- ---------------------------
605
-
606
- Action Mailer allows for you to specify a `before_action`, `after_action` and
607
- `around_action`.
608
-
609
- * Filters can be specified with a block or a symbol to a method in the mailer
610
- class similar to controllers.
611
-
612
- * You could use a `before_action` to populate the mail object with defaults,
613
- delivery_method_options or insert default headers and attachments.
614
-
615
- * You could use an `after_action` to do similar setup as a `before_action` but
616
- using instance variables set in your mailer action.
617
-
618
- ```ruby
619
- class UserMailer < ApplicationMailer
620
- after_action :set_delivery_options,
621
- :prevent_delivery_to_guests,
622
- :set_business_headers
623
-
624
- def feedback_message(business, user)
625
- @business = business
626
- @user = user
627
- mail
628
- end
629
-
630
- def campaign_message(business, user)
631
- @business = business
632
- @user = user
633
- end
634
-
635
- private
636
-
637
- def set_delivery_options
638
- # You have access to the mail instance,
639
- # @business and @user instance variables here
640
- if @business && @business.has_smtp_settings?
641
- mail.delivery_method.settings.merge!(@business.smtp_settings)
642
- end
643
- end
644
-
645
- def prevent_delivery_to_guests
646
- if @user && @user.guest?
647
- mail.perform_deliveries = false
648
- end
649
- end
650
-
651
- def set_business_headers
652
- if @business
653
- headers["X-SMTPAPI-CATEGORY"] = @business.code
654
- end
655
- end
656
- end
657
- ```
658
-
659
- * Mailer Filters abort further processing if body is set to a non-nil value.
660
-
661
- Using Action Mailer Helpers
662
- ---------------------------
663
-
664
- Action Mailer now just inherits from `AbstractController`, so you have access to
665
- the same generic helpers as you do in Action Controller.
666
-
667
- Action Mailer Configuration
668
- ---------------------------
669
-
670
- The following configuration options are best made in one of the environment
671
- files (environment.rb, production.rb, etc...)
672
-
673
- | Configuration | Description |
674
- |---------------|-------------|
675
- |`logger`|Generates 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.|
676
- |`smtp_settings`|Allows detailed configuration for `:smtp` delivery method:<ul><li>`:address` - Allows you to use a remote mail server. Just change it from its default `"localhost"` setting.</li><li>`:port` - On the off chance that your mail server doesn't run on port 25, you can change it.</li><li>`:domain` - If you need to specify a HELO domain, you can do it here.</li><li>`:user_name` - If your mail server requires authentication, set the username in this setting.</li><li>`:password` - If your mail server requires authentication, set the password in this setting.</li><li>`:authentication` - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of `:plain` (will send the password in the clear), `:login` (will send password Base64 encoded) or `:cram_md5` (combines a Challenge/Response mechanism to exchange information and a cryptographic Message Digest 5 algorithm to hash important information)</li><li>`:enable_starttls_auto` - Detects if STARTTLS is enabled in your SMTP server and starts to use it. Defaults to `true`.</li><li>`:openssl_verify_mode` - 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`, ...).</li></ul>|
677
- |`sendmail_settings`|Allows you to override options for the `:sendmail` delivery method.<ul><li>`:location` - The location of the sendmail executable. Defaults to `/usr/sbin/sendmail`.</li><li>`:arguments` - The command line arguments to be passed to sendmail. Defaults to `-i -t`.</li></ul>|
678
- |`raise_delivery_errors`|Whether or not errors should be raised if the email fails to be delivered. This only works if the external email server is configured for immediate delivery.|
679
- |`delivery_method`|Defines a delivery method. Possible values are:<ul><li>`:smtp` (default), can be configured by using `config.action_mailer.smtp_settings`.</li><li>`:sendmail`, can be configured by using `config.action_mailer.sendmail_settings`.</li><li>`:file`: save emails to files; can be configured by using `config.action_mailer.file_settings`.</li><li>`:test`: save emails to `ActionMailer::Base.deliveries` array.</li></ul>See [API docs](http://api.rubyonrails.org/classes/ActionMailer/Base.html) for more info.|
680
- |`perform_deliveries`|Determines whether deliveries are actually carried out when the `deliver` method is invoked on the Mail message. By default they are, but this can be turned off to help functional testing.|
681
- |`deliveries`|Keeps an array of all the emails sent out through the Action Mailer with delivery_method :test. Most useful for unit and functional testing.|
682
- |`default_options`|Allows you to set default values for the `mail` method options (`:from`, `:reply_to`, etc.).|
683
-
684
- For a complete writeup of possible configurations see the
685
- [Configuring Action Mailer](configuring.html#configuring-action-mailer) in
686
- our Configuring Rails Applications guide.
687
-
688
- ### Example Action Mailer Configuration
689
-
690
- An example would be adding the following to your appropriate
691
- `config/environments/$RAILS_ENV.rb` file:
692
-
693
- ```ruby
694
- config.action_mailer.delivery_method = :sendmail
695
- # Defaults to:
696
- # config.action_mailer.sendmail_settings = {
697
- # location: '/usr/sbin/sendmail',
698
- # arguments: '-i -t'
699
- # }
700
- config.action_mailer.perform_deliveries = true
701
- config.action_mailer.raise_delivery_errors = true
702
- config.action_mailer.default_options = {from: 'no-reply@example.com'}
703
- ```
704
-
705
- ### Action Mailer Configuration for Gmail
706
-
707
- As Action Mailer now uses the [Mail gem](https://github.com/mikel/mail), this
708
- becomes as simple as adding to your `config/environments/$RAILS_ENV.rb` file:
709
-
710
- ```ruby
711
- config.action_mailer.delivery_method = :smtp
712
- config.action_mailer.smtp_settings = {
713
- address: 'smtp.gmail.com',
714
- port: 587,
715
- domain: 'example.com',
716
- user_name: '<username>',
717
- password: '<password>',
718
- authentication: 'plain',
719
- enable_starttls_auto: true }
720
- ```
721
-
722
- Mailer Testing
723
- --------------
724
-
725
- You can find detailed instructions on how to test your mailers in the
726
- [testing guide](testing.html#testing-your-mailers).
727
-
728
- Intercepting Emails
729
- -------------------
730
-
731
- There are situations where you need to edit an email before it's
732
- delivered. Fortunately Action Mailer provides hooks to intercept every
733
- email. You can register an interceptor to make modifications to mail messages
734
- right before they are handed to the delivery agents.
735
-
736
- ```ruby
737
- class SandboxEmailInterceptor
738
- def self.delivering_email(message)
739
- message.to = ['sandbox@example.com']
740
- end
741
- end
742
- ```
743
-
744
- Before the interceptor can do its job you need to register it with the Action
745
- Mailer framework. You can do this in an initializer file
746
- `config/initializers/sandbox_email_interceptor.rb`
747
-
748
- ```ruby
749
- if Rails.env.staging?
750
- ActionMailer::Base.register_interceptor(SandboxEmailInterceptor)
751
- end
752
- ```
753
-
754
- NOTE: The example above uses a custom environment called "staging" for a
755
- production like server but for testing purposes. You can read
756
- [Creating Rails environments](configuring.html#creating-rails-environments)
757
- for more information about custom Rails environments.