Parent

Files

Merb::MailController

Sending mail from a controller involves three steps:

First, create a file in app/mailers that subclasses Merb::MailController. The actions in this controller will do nothing but render mail.

  # app/mailers/article_mailer.rb
  class ArticleMailer < Merb::MailController

    def notify
      @user = params[:user]
      render_mail
    end

  end

You also can access the params hash for values passed with the Controller.send_mail method. See also the documentation for render_mail to see all the ways it can be called.

Create a template in a subdirectory of app/mailers/views that corresponds to the controller and action name. Put plain text and ERB tags here:

  # app/mailers/views/article_mailer/notify.text.erb
  Hey, <%= @user.name %>,

  We're running a sale on dog bones!

Finally, call the Controller.send_mail method from a standard Merb controller.

  class Articles < Application

    def index
      @user = User.find_by_name('louie')

      send_mail(ArticleMailer, :notify, {
        :from => "me@example.com",
        :to => "louie@example.com",
        :subject => "Sale on Dog Bones!"
      }, { :user => @user })
      render
    end

  end

Note: If you don’t pass a fourth argument to Controller.send_mail, the controller’s params will be sent to the MailController subclass as params. However, you can explicitly send a hash of objects that will populate the params hash instead. In either case, you must set instance variables in the MailController’s actions if you want to use them in the MailController’s views.

The MailController class is very powerful. You can:

Attributes

params[RW]
mailer[RW]
mail[RW]
base_controller[R]

Public Class Methods

dispatch_and_deliver(method, mail_params, send_params = {}) click to toggle source

A convenience method that creates a blank copy of the MailController and runs dispatch_and_deliver on it.

Parameters

method<~to_s>

The method name to dispatch to.

mail_params

Parameters to send to MailFactory.

send_params

Configuration parameters for the MailController.

     # File lib/merb-mailer/mail_controller.rb, line 337
337:     def self.dispatch_and_deliver(method, mail_params, send_params = {})
338:       new(send_params).dispatch_and_deliver method, mail_params
339:     end
inherited(klass) click to toggle source

Sets the template root to the default mailer view directory.

Parameters

klass

The Merb::MailController inheriting from the base class.

     # File lib/merb-mailer/mail_controller.rb, line 130
130:     def self.inherited(klass)
131:       super
132:       klass._template_root = Merb.dir_for(:mailer) / "views" unless self._template_root
133:     end
new(params = {}, controller = nil) click to toggle source

Parameters

params

Configuration parameters for the MailController.

controller

The base controller.

     # File lib/merb-mailer/mail_controller.rb, line 115
115:     def initialize(params = {}, controller = nil)
116:       @params = params
117:       @base_controller = controller
118:       super
119:     end
subclasses_list() click to toggle source

Returns

Array[Class]

Classes that inherit from Merb::MailController.

    # File lib/merb-mailer/mail_controller.rb, line 79
79:     def self.subclasses_list() _subclasses end

Public Instance Methods

_absolute_template_location(template, type) click to toggle source

The location to look for a template and mime-type. This is overridden from AbstractController, which defines a version of this that does not involve mime-types.

Parameters

template

The absolute path to a template - without mime and template extension. The mime-type extension is optional - it will be appended from the current content type if it hasn’t been added already.

type<~to_s>

The mime-type of the template that will be rendered. Defaults to nil.

@public

     # File lib/merb-mailer/mail_controller.rb, line 108
108:     def _absolute_template_location(template, type)
109:       template.match(/\.#{type.to_s.escape_regexp}$/) ? template : "#{template}.#{type}"
110:     end
_template_location(action, type = nil, controller = controller_name) click to toggle source

Parameters

action<~to_s>

The name of the action that will be rendered.

type<~to_s>

The mime-type of the template that will be rendered. Defaults to nil.

controller<~to_s>

The name of the controller that will be rendered. Defaults to controller_name.

Returns

String

The template location, i.e. “:controller/:action.:type”.

    # File lib/merb-mailer/mail_controller.rb, line 91
91:     def _template_location(action, type = nil, controller = controller_name)
92:       "#{controller}/#{action}.#{type}"
93:     end
absolute_url(name, *args) click to toggle source

Mimic the behavior of absolute_url in AbstractController but use @base_controller.request

     # File lib/merb-mailer/mail_controller.rb, line 264
264:     def absolute_url(name, *args)
265:       return base_controller.absolute_url(name, *args) if base_controller
266:       super
267:     end
attach( file_or_files, filename = file_or_files.is_a?(File) ? File.basename(file_or_files.path) : nil, type = nil, headers = nil) click to toggle source

Attaches a file or multiple files to an email. You call this from a method in your MailController (including a before filter).

Parameters

file_or_files

File(s) to attach.

filename
type<~to_s>

The attachment MIME type. If left out, it will be determined from file_or_files.

headers

Additional attachment headers.

Examples

  attach File.open("foo")
  attach [File.open("foo"), File.open("bar")]

If you are passing an array of files, you should use an array of the allowed parameters:

  attach [[File.open("foo"), "bar", "text/html"], [File.open("baz"),
    "bat", "text/css"]

 which would attach two files ("foo" and "baz" in the filesystem) as

“bar” and “bat” respectively. It would also set the mime-type as “text/html“ and “text/css“ respectively.

     # File lib/merb-mailer/mail_controller.rb, line 293
293:     def attach( file_or_files, filename = file_or_files.is_a?(File) ? File.basename(file_or_files.path) : nil,
294:       type = nil, headers = nil)
295:       @mailer.attach(file_or_files, filename, type, headers)
296:     end
dispatch_and_deliver(method, mail_params) click to toggle source

Parameters

method<~to_s>

The method name to dispatch to.

mail_params

Parameters to send to MailFactory (see below).

Options (mail_params)

MailFactory recognizes the following parameters:

  • :to

  • :from

  • :replyto

  • :subject

  • :body

  • :cc

Other parameters passed in will be interpreted as email headers, with underscores converted to dashes.

     # File lib/merb-mailer/mail_controller.rb, line 313
313:     def dispatch_and_deliver(method, mail_params)
314:       @mailer         = self.class._mailer_klass.new(mail_params)
315:       @mail           = @mailer.mail
316:       @method         = method
317: 
318:       # dispatch and render use params[:action], so set it
319:       self.action_name = method
320: 
321:       body             = _dispatch method
322:       if !@mail.html.blank? || !@mail.text.blank?
323:         @mailer.deliver!
324:         Merb.logger.info "#{method} sent to #{@mail.to} about #{@mail.subject}"
325:       else
326:         Merb.logger.info "#{method} was not sent because nothing was rendered for it"
327:       end
328:     end
filters_halted() click to toggle source

Override filters halted to return nothing.

     # File lib/merb-mailer/mail_controller.rb, line 136
136:     def filters_halted
137:     end
relative_url(name, *args) click to toggle source
Alias for: url
render_mail(options = @method) click to toggle source

Allows you to render various types of things into the text and HTML parts of an email If you include just text, the email will be sent as plain-text. If you include HTML, the email will be sent as a multi-part email.

Parameters

options<~to_s, Hash>

Options for rendering the email or an action name. See examples below for usage.

Examples

There are a lot of ways to use render_mail, but it works similarly to the default Merb render method.

First of all, you’ll need to store email files in your app/mailers/views directory. They should be under a directory that matches the name of your mailer (e.g. TestMailer’s views would be stored under test_mailer).

The files themselves should be named action_name.mime_type.extension. For example, an erb template that should be the HTML part of the email, and rendered from the “foo” action would be named foo.html.erb.

The only mime-types currently supported are “html” and “text”, which correspond to text/html and text/plain respectively. All template systems supported by your app are available to MailController, and the extensions are the same as they are throughout the rest of Merb.

render_mail can take any of the following option patterns:

  render_mail

will attempt to render the current action. If the current action is “foo”, this is identical to render_mail :foo.

  render_mail :foo

checks for foo.html.ext and foo.text.ext and applies them as appropriate.

  render_mail :action => {:html => :foo, :text => :bar}

checks for foo.html.ext and bar.text.ext in the view directory of the current controller and adds them to the mail object if found

  render_mail :template => {:html => "foo/bar", :text => "foo/baz"}

checks for bar.html.ext and baz.text.ext in the foo directory and adds them to the mail object if found.

  render_mail :html => :foo, :text => :bar

the same as render_mail :action => {html => :foo, :text => :bar }

  render_mail :html => "FOO", :text => "BAR"

adds the text “FOO” as the html part of the email and the text “BAR” as the text part of the email. The difference between the last two examples is that symbols represent actions to render, while string represent the literal text to render. Note that you can use regular render methods instead of literal strings here, like:

  render_mail :html => render(:action => :foo)

but you’re probably better off just using render_mail :action at that point.

You can also mix and match:

  render_mail :action => {:html => :foo}, :text => "BAR"

which would be identical to:

  render_mail :html => :foo, :text => "BAR"
     # File lib/merb-mailer/mail_controller.rb, line 212
212:     def render_mail(options = @method)
213:       @_missing_templates = false # used to make sure that at least one template was found
214:       # If the options are not a hash, normalize to an action hash
215:       options = {:action => {:html => options, :text => options}} if !options.is_a?(Hash)
216: 
217:       # Take care of the options
218:       opts_hash = {}
219:       opts = options.dup
220:       actions = opts.delete(:action) if opts[:action].is_a?(Hash)
221:       templates = opts.delete(:template) if opts[:template].is_a?(Hash)
222: 
223:       # Prepare the options hash for each format
224:       # We need to delete anything relating to the other format here
225:       # before we try to render the template.
226:       [:html, :text].each do |fmt|
227:         opts_hash[fmt] = opts.delete(fmt)
228:         opts_hash[fmt] ||= actions[fmt] if actions && actions[fmt]
229:         opts_hash[:template] = templates[fmt] if templates && templates[fmt]
230:       end
231: 
232:       # Send the result to the mailer
233:       { :html => "rawhtml=", :text => "text="}.each do |fmt,meth|
234:         begin
235:           local_opts = opts.merge(:format => fmt)
236:           local_opts.merge!(:layout => false) if opts_hash[fmt].is_a?(String)
237: 
238:           clear_content
239:           value = render opts_hash[fmt], local_opts
240:           @mail.send(meth,value) unless value.nil? || value.empty?
241:         rescue Merb::ControllerExceptions::TemplateNotFound => e
242:           # An error should be logged if no template is found instead of an error raised
243:           if @_missing_templates
244:             Merb.logger.error(e.message)
245:           else
246:             @_missing_templates = true
247:           end
248:         end
249:       end
250:       @mail
251:     end
session() click to toggle source
     # File lib/merb-mailer/mail_controller.rb, line 121
121:     def session
122:       self.base_controller.request.session rescue {}
123:     end
url(name, *args) click to toggle source

Mimic the behavior of absolute_url in AbstractController but use @base_controller.request

     # File lib/merb-mailer/mail_controller.rb, line 255
255:     def url(name, *args)
256:       return base_controller.url(name, *args) if base_controller
257:       super
258:     end
Also aliased as: relative_url

Protected Instance Methods

route() click to toggle source

Returns

Hash

The route from base controller.

     # File lib/merb-mailer/mail_controller.rb, line 345
345:     def route
346:       @base_controller.route if @base_controller
347:     end

Private Instance Methods

get_controller_for_url_generation(opts) click to toggle source

This method is here to overwrite the one in the general_controller mixin The method ensures that when a url is generated with a hash, it contains a controller.

Parameters

opts

The options to get the controller from (see below).

Options (opts)

:controller

The controller.

Returns

Merb::Controller

The controller. If no controller was specified in opts, attempt to find it in the base controller params.

     # File lib/merb-mailer/mail_controller.rb, line 364
364:     def get_controller_for_url_generation(opts)
365:       controller = opts[:controller] || ( @base_controller.params[:controller] if @base_controller)
366:       raise "No Controller Specified for url()" unless controller
367:       controller
368:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.