thorero-mailer 0.9.4
Sign up to get free protection for your applications and to get access to all the features.
- data/LICENSE +20 -0
- data/README.textile +282 -0
- data/Rakefile +66 -0
- data/TODO +5 -0
- data/lib/merb-mailer.rb +5 -0
- data/lib/merb-mailer/mail_controller.rb +359 -0
- data/lib/merb-mailer/mailer.rb +104 -0
- data/lib/merb-mailer/mailer_mixin.rb +25 -0
- data/merb_generators/mail_controller/USAGE +1 -0
- data/merb_generators/mail_controller/mail_controller_generator.rb +59 -0
- data/merb_generators/mail_controller/templates/app/mailers/%controller_file_name%_mailer.rb +20 -0
- data/merb_generators/mail_controller/templates/app/mailers/views/%controller_file_name%_mailer/notify_on_event.text.erb +1 -0
- data/merb_generators/mail_controller/templates/spec/mailers/%controller_file_name%_mailer_spec.rb +39 -0
- data/spec/mail_controller_spec.rb +174 -0
- data/spec/mailer_spec.rb +87 -0
- data/spec/mailers/views/layout/application.html.erb +3 -0
- data/spec/mailers/views/layout/application.text.erb +3 -0
- data/spec/mailers/views/test_mail_controller/eighth.html.erb +1 -0
- data/spec/mailers/views/test_mail_controller/eighth.text.erb +1 -0
- data/spec/mailers/views/test_mail_controller/first.html.erb +1 -0
- data/spec/mailers/views/test_mail_controller/first.text.erb +1 -0
- data/spec/mailers/views/test_mail_controller/ninth.html.erb +1 -0
- data/spec/mailers/views/test_mail_controller/ninth.text.erb +1 -0
- data/spec/mailers/views/test_mail_controller/second.text.erb +1 -0
- data/spec/mailers/views/test_mail_controller/third.html.erb +1 -0
- data/spec/spec_helper.rb +7 -0
- metadata +112 -0
data/LICENSE
ADDED
@@ -0,0 +1,20 @@
|
|
1
|
+
Copyright (c) 2008 YOUR NAME
|
2
|
+
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
4
|
+
a copy of this software and associated documentation files (the
|
5
|
+
"Software"), to deal in the Software without restriction, including
|
6
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
7
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
8
|
+
permit persons to whom the Software is furnished to do so, subject to
|
9
|
+
the following conditions:
|
10
|
+
|
11
|
+
The above copyright notice and this permission notice shall be
|
12
|
+
included in all copies or substantial portions of the Software.
|
13
|
+
|
14
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
15
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
16
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
17
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
18
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
19
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
20
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.textile
ADDED
@@ -0,0 +1,282 @@
|
|
1
|
+
h2. Overview.
|
2
|
+
|
3
|
+
A plugin for the Merb framework that allows you to send email from Merb application.
|
4
|
+
It separates email composition and sending into micro MVC: you may have mail controllers
|
5
|
+
that compose complex emails, emails have their own views and models (models use MailFactory
|
6
|
+
library and non-persistable).
|
7
|
+
|
8
|
+
|
9
|
+
h2. Installation.
|
10
|
+
|
11
|
+
(sudo) gem install merb-mailer
|
12
|
+
|
13
|
+
It will install "mailfactory":http://mailfactory.rubyforge.org/ gem and "mime-types":http://mime-types.rubyforge.org/ that mailfactory depends on.
|
14
|
+
|
15
|
+
|
16
|
+
h2. Configuration.
|
17
|
+
|
18
|
+
In init.rb, include a dependency on 'merb-mailer'.With versions of Merb earlier than 0.9.3 Merb::Mailer may raise a NameError when configuration is put into
|
19
|
+
after_app_loads block. Put it to the very end of your init file and it should work. This problem does not exist in Git HEAD.
|
20
|
+
|
21
|
+
|
22
|
+
h3. Using SMTP.
|
23
|
+
|
24
|
+
<pre><code class="ruby">
|
25
|
+
Merb::Mailer.config = {
|
26
|
+
:host => 'smtp.yourserver.com',
|
27
|
+
:port => '25',
|
28
|
+
:user => 'user',
|
29
|
+
:pass => 'pass',
|
30
|
+
:auth => :plain # :plain, :login, :cram_md5, the default is no auth
|
31
|
+
:domain => "localhost.localdomain" # the HELO domain provided by the client to the server
|
32
|
+
}
|
33
|
+
</code></pre>
|
34
|
+
|
35
|
+
|
36
|
+
h3. Using Gmail SMTP.
|
37
|
+
|
38
|
+
Configuration example for Gmail SMTP:
|
39
|
+
|
40
|
+
<pre><code class="ruby">
|
41
|
+
Merb::Mailer.config = {
|
42
|
+
:host => 'smtp.gmail.com',
|
43
|
+
:port => '587',
|
44
|
+
:user => 'user@gmail.com',
|
45
|
+
:pass => 'pass',
|
46
|
+
:auth => :plain
|
47
|
+
}
|
48
|
+
</code></pre>
|
49
|
+
|
50
|
+
* require "smtp_tls":http://www.rubyinside.com/how-to-use-gmails-smtp-server-with-rails-394.html
|
51
|
+
* Use :text option instead of :body when deliver.
|
52
|
+
|
53
|
+
<pre><code class="ruby">
|
54
|
+
m = Merb::Mailer.new :to => 'foo@bar.com',
|
55
|
+
:from => 'bar@foo.com',
|
56
|
+
:subject => 'Welcome to whatever!',
|
57
|
+
:text => partial(:sometemplate)
|
58
|
+
m.deliver!
|
59
|
+
</code></pre>
|
60
|
+
|
61
|
+
h3. Using Sendmail.
|
62
|
+
|
63
|
+
Merb::Mailer.config = {:sendmail_path => '/somewhere/odd'}
|
64
|
+
Merb::Mailer.delivery_method = :sendmail
|
65
|
+
|
66
|
+
|
67
|
+
|
68
|
+
h2. Sending mail from controllers.
|
69
|
+
|
70
|
+
Merb mailer plugin has idea of separation of mailer logic from mailer templates
|
71
|
+
to the point mailers in Merb have own tiny MVC architecture for emails.
|
72
|
+
Your application controllers usually delegate email sending to mail controllers
|
73
|
+
instead of doing it on their own.
|
74
|
+
|
75
|
+
To send your mail using mail controller you use send_mail method that
|
76
|
+
takes mail controller class, action name, mail parameters and action parameters.
|
77
|
+
params hash with action parameters mentioned above is accessible in mail controller's
|
78
|
+
action.
|
79
|
+
|
80
|
+
<pre>
|
81
|
+
<code class="ruby">
|
82
|
+
def send_activation_email(person)
|
83
|
+
send_mail PeopleMailer, :activation, {
|
84
|
+
:from => "no-reply@example.com",
|
85
|
+
:to => person.email,
|
86
|
+
:subject => "Please activate your account"
|
87
|
+
}, {
|
88
|
+
:name => person.name
|
89
|
+
}
|
90
|
+
end
|
91
|
+
</code>
|
92
|
+
</pre>
|
93
|
+
|
94
|
+
Mail parameters you can specify:
|
95
|
+
|
96
|
+
* :to
|
97
|
+
* :from
|
98
|
+
* :replyto
|
99
|
+
* :subject
|
100
|
+
* :body
|
101
|
+
* :cc
|
102
|
+
|
103
|
+
|
104
|
+
Example of Merb controller:
|
105
|
+
<pre>
|
106
|
+
<code class="ruby">
|
107
|
+
class ProductDeliveryMailer < Merb::MailController
|
108
|
+
def notify_on_delivery
|
109
|
+
@delivery_info = params[:details]
|
110
|
+
# you can access @delivery_info in rendered template
|
111
|
+
render_mail
|
112
|
+
end
|
113
|
+
end
|
114
|
+
</code>
|
115
|
+
</pre>
|
116
|
+
|
117
|
+
Mail templates are kept under app/views/mail controller name/template name just like with regular controllers.
|
118
|
+
Content types in template name may be either text or html, like in
|
119
|
+
app/mailers/views/user_mailer/hello.text.erb for the mailer controller above:
|
120
|
+
|
121
|
+
<pre>
|
122
|
+
Hello <%= params[:name] %>
|
123
|
+
</pre>
|
124
|
+
|
125
|
+
render_mail works similarly to render method. It takes either action as Symbol or Hash of
|
126
|
+
template paths. Most of the times naming templates the same as your actions works so you
|
127
|
+
can just use
|
128
|
+
|
129
|
+
<pre>
|
130
|
+
<code class="ruby">
|
131
|
+
class ResourceShortageMailer < Merb::MailController
|
132
|
+
def notify_on_disk_space_shortage
|
133
|
+
render_mail
|
134
|
+
end
|
135
|
+
end
|
136
|
+
</code>
|
137
|
+
</pre>
|
138
|
+
|
139
|
+
and it will render app/mailers/views/resource_shortage_mailer/notify_on_disk_space_shortage.text.erb.
|
140
|
+
|
141
|
+
If you need to specify template path explicitly, you can do it for both text and html:
|
142
|
+
|
143
|
+
<pre>
|
144
|
+
<code class="ruby">
|
145
|
+
class ResourceShortageMailer < Merb::MailController
|
146
|
+
def notify_on_disk_space_shortage
|
147
|
+
render_mail :action => { :html => :hdd_space_shortage_detailed, :text => :hdd_space_shortage }
|
148
|
+
end
|
149
|
+
end
|
150
|
+
</code>
|
151
|
+
</pre>
|
152
|
+
|
153
|
+
This will look for app/mailers/views/resource_shortage_mailer/hdd_space_shortage_detailed.html.erb for
|
154
|
+
html and app/mailers/views/resource_shortage_mailer/hdd_space_shortage.text.erb for text.
|
155
|
+
|
156
|
+
See "render_mail documentation":http://merbivore.com/documentation/merb-more/0.9.3/merb-mailer/index.html?a=M000019&name=render_mail
|
157
|
+
for more examples, this method has a lot of options how you can use it.
|
158
|
+
|
159
|
+
|
160
|
+
|
161
|
+
h2. Using Merb mailer to send emails outside of controllers.
|
162
|
+
|
163
|
+
There are two ways of sending email with merb-mailer: using mail controllers and using just Merb::Mailer.
|
164
|
+
Here is example of using Merb::Mailer to deliver emails from model hook.
|
165
|
+
|
166
|
+
class Person
|
167
|
+
include DataMapper::Resource
|
168
|
+
|
169
|
+
after :create, :deliver_activation_notification
|
170
|
+
|
171
|
+
protected
|
172
|
+
|
173
|
+
def deliver_activation_notification
|
174
|
+
body_string = <<-EOS
|
175
|
+
Please activate your account...
|
176
|
+
EOS
|
177
|
+
|
178
|
+
Merb::Mailer.new(
|
179
|
+
:from => "no-reply@webapp.com",
|
180
|
+
:to => self.email,
|
181
|
+
:subject => "Activate your account",
|
182
|
+
:body => body_string
|
183
|
+
).deliver!
|
184
|
+
end
|
185
|
+
end
|
186
|
+
|
187
|
+
In this example we deliver signup activation email from model hook.
|
188
|
+
Keep in mind that Merb::Mailer is a thin wrapper around MailFactory that
|
189
|
+
provides several ways of sending emails. You can access plain text email body
|
190
|
+
with text method of mailer and html body with html method, respectively.
|
191
|
+
|
192
|
+
|
193
|
+
|
194
|
+
h2. Testing mailers.
|
195
|
+
|
196
|
+
A word of warning: merb-mailer does not raise exceptions when your template is not found.
|
197
|
+
So if nothing gets rendered, check merb test environment log to make sure you have no
|
198
|
+
warnings. If it is considered a bug, file a ticket to LightHouse.
|
199
|
+
|
200
|
+
Make sure you use test sending method so emails won't be sent on each tests run.
|
201
|
+
Add this line to your test file:
|
202
|
+
|
203
|
+
<pre>
|
204
|
+
<code class="ruby">
|
205
|
+
Merb::Mailer.delivery_method = :test_send
|
206
|
+
</code>
|
207
|
+
</pre>
|
208
|
+
|
209
|
+
Here is an example of helper to test mailers themselves:
|
210
|
+
<pre>
|
211
|
+
<code class="ruby">
|
212
|
+
def describe_mail(mailer, template, &block)
|
213
|
+
describe "/#{mailer.to_s.downcase}/#{template}" do
|
214
|
+
before :each do
|
215
|
+
@mailer_class, @template = mailer, template
|
216
|
+
@assigns = {}
|
217
|
+
end
|
218
|
+
|
219
|
+
def deliver(send_params={}, mail_params={})
|
220
|
+
mail_params = {:from => "from@example.com", :to => "to@example.com", :subject => "Please activate your account"}.merge(mail_params)
|
221
|
+
@mailer_class.new(send_params).dispatch_and_deliver @template.to_sym, mail_params
|
222
|
+
@mail = Merb::Mailer.deliveries.last
|
223
|
+
end
|
224
|
+
|
225
|
+
instance_eval &block
|
226
|
+
end
|
227
|
+
end
|
228
|
+
</code>
|
229
|
+
</pre>
|
230
|
+
|
231
|
+
Mailer controller specs may look like this then:
|
232
|
+
<pre>
|
233
|
+
<code class="ruby">
|
234
|
+
require File.join(File.dirname(__FILE__),'..','spec_helper')
|
235
|
+
|
236
|
+
describe_mail UserMailer, :hello do
|
237
|
+
it "sends activation" do
|
238
|
+
deliver :name => "Jamie"
|
239
|
+
@mail.text.should == "Please activate your account, Jamie"
|
240
|
+
end
|
241
|
+
end
|
242
|
+
</code>
|
243
|
+
</pre>
|
244
|
+
|
245
|
+
Most of mail controller specs verify delivered email headers like
|
246
|
+
to, subject or body. To access deliveries you use Merb::Mailer.deliveries
|
247
|
+
array.
|
248
|
+
|
249
|
+
It is recommended to clear it on test setup first:
|
250
|
+
|
251
|
+
<pre>
|
252
|
+
<code class="ruby">
|
253
|
+
require File.join(File.dirname(__FILE__),'..','spec_helper')
|
254
|
+
|
255
|
+
describe_mail UserMailer, :hello do
|
256
|
+
before :each do
|
257
|
+
Merb::Mailer.deliveries.clear
|
258
|
+
end
|
259
|
+
end
|
260
|
+
</code>
|
261
|
+
</pre>
|
262
|
+
|
263
|
+
To do actual matching you can create a helper like this:
|
264
|
+
|
265
|
+
<pre>
|
266
|
+
<code class="ruby">
|
267
|
+
def last_delivered_email
|
268
|
+
Merb::Mailer.deliveries.last
|
269
|
+
end
|
270
|
+
</code>
|
271
|
+
</pre>
|
272
|
+
|
273
|
+
and use it like this:
|
274
|
+
|
275
|
+
<pre>
|
276
|
+
<code class="ruby">
|
277
|
+
last_delivered_email.from.first.should == "no-reply@webapp.com"
|
278
|
+
</code>
|
279
|
+
</pre>
|
280
|
+
|
281
|
+
Note that MailFactory that is used by merb-mailer under the covers returns headers
|
282
|
+
as Arrays. This is why we used from.first in example above.
|
data/Rakefile
ADDED
@@ -0,0 +1,66 @@
|
|
1
|
+
require 'rubygems'
|
2
|
+
require 'rake/gempackagetask'
|
3
|
+
require "extlib"
|
4
|
+
require 'merb-core/tasks/merb_rake_helper'
|
5
|
+
require "spec/rake/spectask"
|
6
|
+
|
7
|
+
##############################################################################
|
8
|
+
# Package && release
|
9
|
+
##############################################################################
|
10
|
+
RUBY_FORGE_PROJECT = "thorero"
|
11
|
+
PROJECT_URL = "http://merbivore.com"
|
12
|
+
PROJECT_SUMMARY = "Merb plugin that provides mailer functionality to Merb"
|
13
|
+
PROJECT_DESCRIPTION = PROJECT_SUMMARY
|
14
|
+
|
15
|
+
GEM_AUTHOR = "Yehuda Katz"
|
16
|
+
GEM_EMAIL = "ykatz@engineyard.com"
|
17
|
+
|
18
|
+
GEM_NAME = "thorero-mailer"
|
19
|
+
PKG_BUILD = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
|
20
|
+
GEM_VERSION = (Merb::MORE_VERSION rescue "0.9.4") + PKG_BUILD
|
21
|
+
|
22
|
+
RELEASE_NAME = "REL #{GEM_VERSION}"
|
23
|
+
|
24
|
+
require "extlib/tasks/release"
|
25
|
+
|
26
|
+
spec = Gem::Specification.new do |s|
|
27
|
+
s.rubyforge_project = RUBY_FORGE_PROJECT
|
28
|
+
s.name = GEM_NAME
|
29
|
+
s.version = GEM_VERSION
|
30
|
+
s.platform = Gem::Platform::RUBY
|
31
|
+
s.has_rdoc = true
|
32
|
+
s.extra_rdoc_files = ["README.textile", "LICENSE", 'TODO']
|
33
|
+
s.summary = PROJECT_SUMMARY
|
34
|
+
s.description = PROJECT_DESCRIPTION
|
35
|
+
s.author = GEM_AUTHOR
|
36
|
+
s.email = GEM_EMAIL
|
37
|
+
s.homepage = PROJECT_URL
|
38
|
+
s.add_dependency('merb-core', '>= 0.9.4')
|
39
|
+
s.add_dependency('mailfactory', '>= 1.2.3')
|
40
|
+
s.require_path = 'lib'
|
41
|
+
s.files = %w(LICENSE README.textile Rakefile TODO) + Dir.glob("{lib,spec,merb_generators}/**/*")
|
42
|
+
end
|
43
|
+
|
44
|
+
Rake::GemPackageTask.new(spec) do |pkg|
|
45
|
+
pkg.gem_spec = spec
|
46
|
+
end
|
47
|
+
|
48
|
+
desc "Install the gem"
|
49
|
+
task :install => [:package] do
|
50
|
+
sh %{#{sudo} gem install #{install_home} pkg/#{GEM_NAME}-#{GEM_VERSION} --no-update-sources}
|
51
|
+
end
|
52
|
+
|
53
|
+
namespace :jruby do
|
54
|
+
|
55
|
+
desc "Run :package and install the resulting .gem with jruby"
|
56
|
+
task :install => :package do
|
57
|
+
sh %{#{sudo} jruby -S gem install #{install_home} pkg/#{GEM_NAME}-#{GEM_VERSION}.gem --no-rdoc --no-ri}
|
58
|
+
end
|
59
|
+
|
60
|
+
end
|
61
|
+
|
62
|
+
desc "Run all specs"
|
63
|
+
Spec::Rake::SpecTask.new("specs") do |t|
|
64
|
+
t.spec_opts = ["--format", "specdoc", "--colour"]
|
65
|
+
t.spec_files = Dir["spec/**/*_spec.rb"].sort
|
66
|
+
end
|
data/TODO
ADDED
data/lib/merb-mailer.rb
ADDED
@@ -0,0 +1,359 @@
|
|
1
|
+
module Merb
|
2
|
+
|
3
|
+
# Sending mail from a controller involves three steps:
|
4
|
+
#
|
5
|
+
# * Set mail settings in merb_init.rb (Not shown here...see the Mailer docs).
|
6
|
+
# * Create a MailController subclass with actions and templates.
|
7
|
+
# * Call the MailController from another Controller via the send_mail method.
|
8
|
+
#
|
9
|
+
# First, create a file in app/mailers that subclasses Merb::MailController.
|
10
|
+
# The actions in this controller will do nothing but render mail.
|
11
|
+
#
|
12
|
+
# # app/mailers/article_mailer.rb
|
13
|
+
# class ArticleMailer < Merb::MailController
|
14
|
+
#
|
15
|
+
# def notify
|
16
|
+
# @user = params[:user]
|
17
|
+
# render_mail
|
18
|
+
# end
|
19
|
+
#
|
20
|
+
# end
|
21
|
+
#
|
22
|
+
# You also can access the params hash for values passed with the
|
23
|
+
# Controller.send_mail method. See also the documentation for
|
24
|
+
# render_mail to see all the ways it can be called.
|
25
|
+
#
|
26
|
+
# Create a template in a subdirectory of app/mailers/views that corresponds
|
27
|
+
# to the controller and action name. Put plain text and ERB tags here:
|
28
|
+
#
|
29
|
+
# # app/mailers/views/article_mailer/notify.text.erb
|
30
|
+
# Hey, <%= @user.name %>,
|
31
|
+
#
|
32
|
+
# We're running a sale on dog bones!
|
33
|
+
#
|
34
|
+
# Finally, call the Controller.send_mail method from a standard
|
35
|
+
# Merb controller.
|
36
|
+
#
|
37
|
+
# class Articles < Application
|
38
|
+
#
|
39
|
+
# def index
|
40
|
+
# @user = User.find_by_name('louie')
|
41
|
+
#
|
42
|
+
# send_mail(ArticleMailer, :notify, {
|
43
|
+
# :from => "me@example.com",
|
44
|
+
# :to => "louie@example.com",
|
45
|
+
# :subject => "Sale on Dog Bones!"
|
46
|
+
# }, { :user => @user })
|
47
|
+
# render
|
48
|
+
# end
|
49
|
+
#
|
50
|
+
# end
|
51
|
+
#
|
52
|
+
# Note: If you don't pass a fourth argument to Controller.send_mail,
|
53
|
+
# the controller's params will be sent to the MailController subclass
|
54
|
+
# as params. However, you can explicitly send a hash of objects that
|
55
|
+
# will populate the params hash instead. In either case, you must
|
56
|
+
# set instance variables in the MailController's actions if you
|
57
|
+
# want to use them in the MailController's views.
|
58
|
+
#
|
59
|
+
# The MailController class is very powerful. You can:
|
60
|
+
#
|
61
|
+
# * Send multipart email with a single call to render_mail.
|
62
|
+
# * Attach files.
|
63
|
+
# * Render layouts and other templates.
|
64
|
+
# * Use any template engine supported by Merb.
|
65
|
+
|
66
|
+
class MailController < AbstractController
|
67
|
+
|
68
|
+
class_inheritable_accessor :_mailer_klass
|
69
|
+
self._mailer_klass = Merb::Mailer
|
70
|
+
|
71
|
+
attr_accessor :params, :mailer, :mail
|
72
|
+
attr_reader :session, :base_controller
|
73
|
+
|
74
|
+
cattr_accessor :_subclasses
|
75
|
+
self._subclasses = Set.new
|
76
|
+
|
77
|
+
# ==== Returns
|
78
|
+
# Array[Class]:: Classes that inherit from Merb::MailController.
|
79
|
+
def self.subclasses_list() _subclasses end
|
80
|
+
|
81
|
+
# ==== Parameters
|
82
|
+
# action<~to_s>:: The name of the action that will be rendered.
|
83
|
+
# type<~to_s>::
|
84
|
+
# The mime-type of the template that will be rendered. Defaults to nil.
|
85
|
+
# controller<~to_s>::
|
86
|
+
# The name of the controller that will be rendered. Defaults to
|
87
|
+
# controller_name.
|
88
|
+
#
|
89
|
+
# ==== Returns
|
90
|
+
# String:: The template location, i.e. ":controller/:action.:type".
|
91
|
+
def _template_location(action, type = nil, controller = controller_name)
|
92
|
+
"#{controller}/#{action}.#{type}"
|
93
|
+
end
|
94
|
+
|
95
|
+
# The location to look for a template and mime-type. This is overridden
|
96
|
+
# from AbstractController, which defines a version of this that does not
|
97
|
+
# involve mime-types.
|
98
|
+
#
|
99
|
+
# ==== Parameters
|
100
|
+
# template<String>::
|
101
|
+
# The absolute path to a template - without mime and template extension.
|
102
|
+
# The mime-type extension is optional - it will be appended from the
|
103
|
+
# current content type if it hasn't been added already.
|
104
|
+
# type<~to_s>::
|
105
|
+
# The mime-type of the template that will be rendered. Defaults to nil.
|
106
|
+
#
|
107
|
+
# @public
|
108
|
+
def _absolute_template_location(template, type)
|
109
|
+
template.match(/\.#{type.to_s.escape_regexp}$/) ? template : "#{template}.#{type}"
|
110
|
+
end
|
111
|
+
|
112
|
+
# ==== Parameters
|
113
|
+
# params<Hash>:: Configuration parameters for the MailController.
|
114
|
+
# controller<Merb::Controller>:: The base controller.
|
115
|
+
def initialize(params = {}, controller = nil)
|
116
|
+
@params = params
|
117
|
+
@base_controller = controller
|
118
|
+
@session = (controller && controller.session) || {}
|
119
|
+
super
|
120
|
+
end
|
121
|
+
|
122
|
+
# Sets the template root to the default mailer view directory.
|
123
|
+
#
|
124
|
+
# ==== Parameters
|
125
|
+
# klass<Class>::
|
126
|
+
# The Merb::MailController inheriting from the base class.
|
127
|
+
def self.inherited(klass)
|
128
|
+
super
|
129
|
+
klass._template_root = Merb.dir_for(:mailer) / "views" unless self._template_root
|
130
|
+
end
|
131
|
+
|
132
|
+
# Override filters halted to return nothing.
|
133
|
+
def filters_halted
|
134
|
+
end
|
135
|
+
|
136
|
+
# Allows you to render various types of things into the text and HTML parts
|
137
|
+
# of an email If you include just text, the email will be sent as
|
138
|
+
# plain-text. If you include HTML, the email will be sent as a multi-part
|
139
|
+
# email.
|
140
|
+
#
|
141
|
+
# ==== Parameters
|
142
|
+
# options<~to_s, Hash>::
|
143
|
+
# Options for rendering the email or an action name. See examples below
|
144
|
+
# for usage.
|
145
|
+
#
|
146
|
+
# ==== Examples
|
147
|
+
# There are a lot of ways to use render_mail, but it works similarly to the
|
148
|
+
# default Merb render method.
|
149
|
+
#
|
150
|
+
# First of all, you'll need to store email files in your
|
151
|
+
# app/mailers/views directory. They should be under a directory that
|
152
|
+
# matches the name of your mailer (e.g. TestMailer's views would be stored
|
153
|
+
# under test_mailer).
|
154
|
+
#
|
155
|
+
# The files themselves should be named action_name.mime_type.extension. For
|
156
|
+
# example, an erb template that should be the HTML part of the email, and
|
157
|
+
# rendered from the "foo" action would be named foo.html.erb.
|
158
|
+
#
|
159
|
+
# The only mime-types currently supported are "html" and "text", which
|
160
|
+
# correspond to text/html and text/plain respectively. All template systems
|
161
|
+
# supported by your app are available to MailController, and the extensions
|
162
|
+
# are the same as they are throughout the rest of Merb.
|
163
|
+
#
|
164
|
+
# render_mail can take any of the following option patterns:
|
165
|
+
#
|
166
|
+
# render_mail
|
167
|
+
#
|
168
|
+
# will attempt to render the current action. If the current action is
|
169
|
+
# "foo", this is identical to render_mail :foo.
|
170
|
+
#
|
171
|
+
# render_mail :foo
|
172
|
+
#
|
173
|
+
# checks for foo.html.ext and foo.text.ext and applies them as appropriate.
|
174
|
+
#
|
175
|
+
# render_mail :action => {:html => :foo, :text => :bar}
|
176
|
+
#
|
177
|
+
# checks for foo.html.ext and bar.text.ext in the view directory of the
|
178
|
+
# current controller and adds them to the mail object if found
|
179
|
+
#
|
180
|
+
# render_mail :template => {:html => "foo/bar", :text => "foo/baz"}
|
181
|
+
#
|
182
|
+
# checks for bar.html.ext and baz.text.ext in the foo directory and adds
|
183
|
+
# them to the mail object if found.
|
184
|
+
#
|
185
|
+
# render_mail :html => :foo, :text => :bar
|
186
|
+
#
|
187
|
+
# the same as render_mail :action => {html => :foo, :text => :bar }
|
188
|
+
#
|
189
|
+
# render_mail :html => "FOO", :text => "BAR"
|
190
|
+
#
|
191
|
+
# adds the text "FOO" as the html part of the email and the text "BAR" as
|
192
|
+
# the text part of the email. The difference between the last two examples
|
193
|
+
# is that symbols represent actions to render, while string represent the
|
194
|
+
# literal text to render. Note that you can use regular render methods
|
195
|
+
# instead of literal strings here, like:
|
196
|
+
#
|
197
|
+
# render_mail :html => render(:action => :foo)
|
198
|
+
#
|
199
|
+
# but you're probably better off just using render_mail :action at that
|
200
|
+
# point.
|
201
|
+
#
|
202
|
+
# You can also mix and match:
|
203
|
+
#
|
204
|
+
# render_mail :action => {:html => :foo}, :text => "BAR"
|
205
|
+
#
|
206
|
+
# which would be identical to:
|
207
|
+
#
|
208
|
+
# render_mail :html => :foo, :text => "BAR"
|
209
|
+
def render_mail(options = @method)
|
210
|
+
@_missing_templates = false # used to make sure that at least one template was found
|
211
|
+
# If the options are not a hash, normalize to an action hash
|
212
|
+
options = {:action => {:html => options, :text => options}} if !options.is_a?(Hash)
|
213
|
+
|
214
|
+
# Take care of the options
|
215
|
+
opts_hash = {}
|
216
|
+
opts = options.dup
|
217
|
+
actions = opts.delete(:action) if opts[:action].is_a?(Hash)
|
218
|
+
templates = opts.delete(:template) if opts[:template].is_a?(Hash)
|
219
|
+
|
220
|
+
# Prepare the options hash for each format
|
221
|
+
# We need to delete anything relating to the other format here
|
222
|
+
# before we try to render the template.
|
223
|
+
[:html, :text].each do |fmt|
|
224
|
+
opts_hash[fmt] = opts.delete(fmt)
|
225
|
+
opts_hash[fmt] ||= actions[fmt] if actions && actions[fmt]
|
226
|
+
opts_hash[:template] = templates[fmt] if templates && templates[fmt]
|
227
|
+
end
|
228
|
+
|
229
|
+
# Send the result to the mailer
|
230
|
+
{ :html => "rawhtml=", :text => "text="}.each do |fmt,meth|
|
231
|
+
begin
|
232
|
+
local_opts = opts.merge(:format => fmt)
|
233
|
+
local_opts.merge!(:layout => false) if opts_hash[fmt].is_a?(String)
|
234
|
+
|
235
|
+
value = render opts_hash[fmt], local_opts
|
236
|
+
@mail.send(meth,value) unless value.nil? || value.empty?
|
237
|
+
rescue Merb::ControllerExceptions::TemplateNotFound => e
|
238
|
+
# An error should be logged if no template is found instead of an error raised
|
239
|
+
if @_missing_templates
|
240
|
+
Merb.logger.error(e)
|
241
|
+
else
|
242
|
+
@_missing_templates = true
|
243
|
+
end
|
244
|
+
end
|
245
|
+
end
|
246
|
+
@mail
|
247
|
+
end
|
248
|
+
|
249
|
+
# Mimic the behavior of absolute_url in AbstractController
|
250
|
+
# but use @base_controller.request
|
251
|
+
def absolute_url(name, rparams={})
|
252
|
+
req = @base_controller.request
|
253
|
+
uri = req.protocol + req.host + url(name, rparams)
|
254
|
+
end
|
255
|
+
|
256
|
+
# Attaches a file or multiple files to an email. You call this from a
|
257
|
+
# method in your MailController (including a before filter).
|
258
|
+
#
|
259
|
+
# ==== Parameters
|
260
|
+
# file_or_files<File, Array[File]>:: File(s) to attach.
|
261
|
+
# filename<String>::
|
262
|
+
# type<~to_s>::
|
263
|
+
# The attachment MIME type. If left out, it will be determined from
|
264
|
+
# file_or_files.
|
265
|
+
# headers<String, Array>:: Additional attachment headers.
|
266
|
+
#
|
267
|
+
# ==== Examples
|
268
|
+
# attach File.open("foo")
|
269
|
+
# attach [File.open("foo"), File.open("bar")]
|
270
|
+
#
|
271
|
+
# If you are passing an array of files, you should use an array of the
|
272
|
+
# allowed parameters:
|
273
|
+
#
|
274
|
+
# attach [[File.open("foo"), "bar", "text/html"], [File.open("baz"),
|
275
|
+
# "bat", "text/css"]
|
276
|
+
#
|
277
|
+
# which would attach two files ("foo" and "baz" in the filesystem) as
|
278
|
+
# "bar" and "bat" respectively. It would also set the mime-type as
|
279
|
+
# "text/html" and "text/css" respectively.
|
280
|
+
def attach( file_or_files, filename = file_or_files.is_a?(File) ? File.basename(file_or_files.path) : nil,
|
281
|
+
type = nil, headers = nil)
|
282
|
+
@mailer.attach(file_or_files, filename, type, headers)
|
283
|
+
end
|
284
|
+
|
285
|
+
# ==== Parameters
|
286
|
+
# method<~to_s>:: The method name to dispatch to.
|
287
|
+
# mail_params<Hash>:: Parameters to send to MailFactory (see below).
|
288
|
+
#
|
289
|
+
# ==== Options (mail_params)
|
290
|
+
# MailFactory recognizes the following parameters:
|
291
|
+
# * :to
|
292
|
+
# * :from
|
293
|
+
# * :replyto
|
294
|
+
# * :subject
|
295
|
+
# * :body
|
296
|
+
# * :cc
|
297
|
+
#
|
298
|
+
# Other parameters passed in will be interpreted as email headers, with
|
299
|
+
# underscores converted to dashes.
|
300
|
+
def dispatch_and_deliver(method, mail_params)
|
301
|
+
@mailer = self.class._mailer_klass.new(mail_params)
|
302
|
+
@mail = @mailer.mail
|
303
|
+
@method = method
|
304
|
+
|
305
|
+
# dispatch and render use params[:action], so set it
|
306
|
+
self.action_name = method
|
307
|
+
|
308
|
+
body = _dispatch method
|
309
|
+
if !@mail.html.blank? || !@mail.text.blank?
|
310
|
+
@mailer.deliver!
|
311
|
+
Merb.logger.info "#{method} sent to #{@mail.to} about #{@mail.subject}"
|
312
|
+
else
|
313
|
+
Merb.logger.info "#{method} was not sent because nothing was rendered for it"
|
314
|
+
end
|
315
|
+
end
|
316
|
+
|
317
|
+
# A convenience method that creates a blank copy of the MailController and
|
318
|
+
# runs dispatch_and_deliver on it.
|
319
|
+
#
|
320
|
+
# ==== Parameters
|
321
|
+
# method<~to_s>:: The method name to dispatch to.
|
322
|
+
# mail_params<Hash>:: Parameters to send to MailFactory.
|
323
|
+
# send_params<Hash>:: Configuration parameters for the MailController.
|
324
|
+
def self.dispatch_and_deliver(method, mail_params, send_params = {})
|
325
|
+
new(send_params).dispatch_and_deliver method, mail_params
|
326
|
+
end
|
327
|
+
|
328
|
+
protected
|
329
|
+
|
330
|
+
# ==== Returns
|
331
|
+
# Hash:: The route from base controller.
|
332
|
+
def route
|
333
|
+
@base_controller.route if @base_controller
|
334
|
+
end
|
335
|
+
|
336
|
+
private
|
337
|
+
# This method is here to overwrite the one in the general_controller mixin
|
338
|
+
# The method ensures that when a url is generated with a hash, it contains
|
339
|
+
# a controller.
|
340
|
+
#
|
341
|
+
# ==== Parameters
|
342
|
+
# opts<Hash>:: The options to get the controller from (see below).
|
343
|
+
#
|
344
|
+
# ==== Options (opts)
|
345
|
+
# :controller<Merb::Controller>:: The controller.
|
346
|
+
#
|
347
|
+
# ==== Returns
|
348
|
+
# Merb::Controller::
|
349
|
+
# The controller. If no controller was specified in opts, attempt to find
|
350
|
+
# it in the base controller params.
|
351
|
+
def get_controller_for_url_generation(opts)
|
352
|
+
controller = opts[:controller] || ( @base_controller.params[:controller] if @base_controller)
|
353
|
+
raise "No Controller Specified for url()" unless controller
|
354
|
+
controller
|
355
|
+
end
|
356
|
+
|
357
|
+
|
358
|
+
end
|
359
|
+
end
|