0
@@ -1,5 +1,5 @@
0
 module Merb
0
-  
0
+
0
   # Sending mail from a controller involves three steps:
0
   #
0
   # * Set mail settings in merb_init.rb (Not shown here...see the Mailer docs).
0
@@ -62,43 +62,64 @@ module Merb
0
   # * Attach files.
0
   # * Render layouts and other templates.
0
   # * Use any template engine supported by Merb.
0
-  
0
+
0
   class MailController < AbstractController
0
-   
0
+
0
     class_inheritable_accessor :_mailer_klass
0
     self._mailer_klass  = Merb::Mailer
0
-    
0
+
0
     attr_accessor :params, :mailer, :mail
0
     attr_reader   :session, :base_controller
0
-    
0
+
0
+    # ==== Parameters
0
+    # action<~to_s>:: The name of the action that will be rendered.
0
+    # type<~to_s>::
0
+    #    The mime-type of the template that will be rendered. Defaults to nil.
0
+    # controller<~to_s>::
0
+    #   The name of the controller that will be rendered. Defaults to
0
+    #   controller_name.
0
+    #
0
+    # ==== Returns
0
+    # String:: The template location, i.e. ":controller/:action.:type".
0
     def _template_location(action, type = nil, controller = controller_name)
0
       "#{controller}/#{action}.#{type}"
0
     end
0
-    
0
-    # You can initialize a MailController with a series of parameters that can
0
-    # be used by methods in the class. You can also pass in a controller
0
-    # object, which will be available to the MailController methods as
0
-    # base_controller.
0
+
0
+    # ==== Parameters
0
+    # params<Hash>:: Configuration parameters for the MailController.
0
+    # controller<Merb::Controller>:: The base controller.
0
     def initialize(params = {}, controller = nil)
0
       @params = params
0
       @base_controller = controller
0
       @session = (controller && controller.session) || {}
0
       super
0
     end
0
-    
0
+
0
+    # Sets the template root to the default mailer view directory.
0
+    #
0
+    # ==== Parameters
0
+    # klass<Class>::
0
+    #   The Merb::MailController inheriting from the base class.  
0
     def self.inherited(klass)
0
       super
0
       klass.class_eval %{self._template_root = Merb.dir_for(:mailer) / "views"}
0
     end
0
-    
0
+
0
+    # Override filters halted to return nothing.
0
     def filters_halted
0
     end
0
-    
0
+
0
     # Allows you to render various types of things into the text and HTML parts
0
     # of an email If you include just text, the email will be sent as
0
     # plain-text. If you include HTML, the email will be sent as a multi-part
0
     # email.
0
     #
0
+    # ==== Parameters
0
+    # options<~to_s, Hash>::
0
+    #   Options for rendering the email or an action name. See examples below
0
+    #   for usage.
0
+    #
0
+    # ==== Examples
0
     # There are a lot of ways to use render_mail, but it works similarly to the
0
     # default Merb render method.
0
     #
0
@@ -165,13 +186,13 @@ module Merb
0
       @_missing_templates = false # used to make sure that at least one template was found
0
       # # If the options are not a hash, normalize to an action hash
0
       options = {:action => {:html => options, :text => options}} if !options.is_a?(Hash)
0
-      
0
+  
0
       # Take care of the options
0
       opts_hash = {}
0
       opts = options.dup
0
       actions = opts.delete(:action) if opts[:action].is_a?(Hash)
0
       templates = opts.delete(:template) if opts[:template].is_a?(Hash)
0
-      
0
+  
0
       # Prepare the options hash for each format
0
       # We need to delete anything relating to the other format here
0
       # before we try to render the template.
0
@@ -183,13 +204,13 @@ module Merb
0
 
0
       # require 'ruby-debug'
0
       # debugger if $DEBUGGER
0
-            
0
+        
0
       # Send the result to the mailer
0
       { :html => "rawhtml=", :text => "text="}.each do |fmt,meth|
0
         begin
0
           local_opts = opts.merge(:format => fmt)
0
           local_opts.merge!(:layout => false) if opts_hash[fmt].is_a?(String)
0
-          
0
+      
0
           value = render opts_hash[fmt], local_opts
0
           @mail.send(meth,value) unless value.nil? || value.empty?
0
         rescue => e
0
@@ -203,21 +224,27 @@ module Merb
0
       end
0
       @mail
0
     end
0
-    
0
+
0
     # Attaches a file or multiple files to an email. You call this from a
0
     # method in your MailController (including a before filter).
0
     # 
0
+    # ==== Parameters
0
+    # file_or_files<File, Array[File]>:: File(s) to attach.
0
+    # filename<String>::
0
+    # type<~to_s>::
0
+    #   The attachment MIME type. If left out, it will be determined from
0
+    #   file_or_files.
0
+    # headers<String, Array>:: Additional attachment headers.
0
+    #
0
+    # ==== Examples
0
     #   attach File.open("foo")
0
     #   attach [File.open("foo"), File.open("bar")]
0
     # 
0
-    # You can also include the filename, mime-type, or headers in the
0
-    # subsequent parameters.
0
-    # 
0
     # If you are passing an array of files, you should use an array of the
0
     # allowed parameters:
0
     # 
0
     #   attach [[File.open("foo"), "bar", "text/html"], [File.open("baz"),
0
-    # "bat", "text/css"]
0
+    #     "bat", "text/css"]
0
     # 
0
     #  which would attach two files ("foo" and "baz" in the filesystem) as
0
     # "bar" and "bat" respectively. It would also set the mime-type as
0
@@ -226,24 +253,27 @@ module Merb
0
       type = nil, headers = nil)
0
       @mailer.attach(file_or_files, filename, type, headers)
0
     end
0
-    
0
-    # take a method name to dispatch to and mail parameters for the MailFactory object.
0
-    #
0
-    # Available mail parameters include:
0
-    #   to
0
-    #   from
0
-    #   replyto
0
-    #   subject
0
-    #   body
0
-    #   cc
0
-    #
0
-    # Other parameters passed in will be interpreted as email headers, with _'s converted
0
-    # to -'s.
0
+
0
+    # ==== Parameters
0
+    # method<~to_s>:: The method name to dispatch to.
0
+    # mail_params<Hash>:: Parameters to send to MailFactory (see below).
0
+    #
0
+    # ==== Options (mail_params)
0
+    # MailFactory recognizes the following parameters:
0
+    # * :to
0
+    # * :from
0
+    # * :replyto
0
+    # * :subject
0
+    # * :body
0
+    # * :cc
0
+    #
0
+    # Other parameters passed in will be interpreted as email headers, with
0
+    # underscores converted to dashes.
0
     def dispatch_and_deliver(method, mail_params)
0
       @mailer         = self.class._mailer_klass.new(mail_params)
0
       @mail           = @mailer.mail
0
       @method         = method
0
-      
0
+  
0
       # dispatch and render use params[:action], so set it
0
       self.action_name = method
0
 
0
@@ -256,26 +286,46 @@ module Merb
0
       end
0
     end
0
 
0
-    # A convenience method that creates a blank copy of the MailController and runs
0
-    # dispatch_and_deliver on it.
0
+    # A convenience method that creates a blank copy of the MailController and
0
+    # runs dispatch_and_deliver on it.
0
+    #
0
+    # ==== Parameters
0
+    # method<~to_s>:: The method name to dispatch to.
0
+    # mail_params<Hash>:: Parameters to send to MailFactory.
0
+    # send_params<Hash>:: Configuration parameters for the MailController.
0
     def self.dispatch_and_deliver(method, mail_params, send_params = {})
0
       new(send_params).dispatch_and_deliver method, mail_params
0
     end
0
-    
0
+
0
     protected
0
+
0
+    # ==== Returns
0
+    # Hash:: The route from base controller.
0
     def route
0
       @base_controller.route if @base_controller
0
     end
0
 
0
     private
0
     # This method is here to overwrite the one in the general_controller mixin
0
-    # The method ensures that when a url is generated with a hash, it contains a controller
0
+    # The method ensures that when a url is generated with a hash, it contains
0
+    # a controller.
0
+    #
0
+    # ==== Parameters
0
+    # opts<Hash>:: The options to get the controller from (see below).
0
+    #
0
+    # ==== Options (opts)
0
+    # :controller<Merb::Controller>:: The controller.
0
+    #
0
+    # ==== Returns
0
+    # Merb::Controller::
0
+    #   The controller. If no controller was specified in opts, attempt to find
0
+    #   it in the base controller params.
0
     def get_controller_for_url_generation(opts)
0
       controller = opts[:controller] || ( @base_controller.params[:controller] if @base_controller)
0
-       raise "No Controller Specified for url()" unless controller
0
-       controller
0
+      raise "No Controller Specified for url()" unless controller
0
+      controller
0
     end
0
-    
0
-    
0
+
0
+
0
   end
0
 end
0
\ No newline at end of file

0
@@ -38,33 +38,48 @@ module Merb
0
   #   m.deliver!                     
0
 
0
   class Mailer
0
-    
0
+
0
     class_inheritable_accessor :config, :delivery_method, :deliveries
0
     attr_accessor :mail
0
     self.deliveries = []
0
-    
0
+
0
+    # Sends the mail using sendmail.
0
     def sendmail
0
       sendmail = IO.popen("#{config[:sendmail_path]} #{@mail.to}", 'w+') 
0
       sendmail.puts @mail.to_s
0
       sendmail.close
0
     end
0
-  
0
-    # :plain, :login, or :cram_md5
0
+
0
+    # Sends the mail using SMTP.
0
     def net_smtp
0
       Net::SMTP.start(config[:host], config[:port].to_i, config[:domain], 
0
                       config[:user], config[:pass], config[:auth]) { |smtp|
0
         smtp.send_message(@mail.to_s, @mail.from.first, @mail.to.to_s.split(/[,;]/))
0
       }
0
     end
0
-    
0
+
0
+    # Tests mail sending by adding the mail to deliveries.
0
     def test_send
0
       deliveries << @mail
0
     end
0
-    
0
+
0
+    # Delivers the mail with the specified delivery method, defaulting to
0
+    # net_smtp.
0
     def deliver!
0
       send(delivery_method || :net_smtp)
0
     end
0
-      
0
+
0
+    # ==== Parameters
0
+    # file_or_files<File, Array[File]>:: File(s) to attach.
0
+    # filename<String>::
0
+    # type<~to_s>::
0
+    #   The attachment MIME type. If left out, it will be determined from
0
+    #   file_or_files.
0
+    # headers<String, Array>:: Additional attachment headers.
0
+    #
0
+    # ==== Raises
0
+    # ArgumentError::
0
+    #   file_or_files was not a File or an Array of File instances.
0
     def attach(file_or_files, filename = file_or_files.is_a?(File) ? File.basename(file_or_files.path) : nil, 
0
       type = nil, headers = nil)
0
       if file_or_files.is_a?(Array)
0
@@ -75,6 +90,8 @@ module Merb
0
       end
0
     end
0
       
0
+    # ==== Parameters
0
+    # o<Hash{~to_s => Object}>:: Configuration commands to send to MailFactory.
0
     def initialize(o={})
0
       self.config = {:sendmail_path => '/usr/sbin/sendmail'} if config.nil? 
0
       o[:rawhtml] = o.delete(:html)

0
@@ -1,19 +1,20 @@
0
 class Merb::Controller
0
   # Sends mail via a MailController (a tutorial can be found in the
0
   # MailController docs).
0
-  # 
0
-  #  send_mail FooMailer, :bar, :from => "foo@bar.com", :to => "baz@bat.com"
0
-  # 
0
-  # would send an email via the FooMailer's bar method.
0
-  # 
0
-  # The mail_params hash would be sent to the mailer, and includes items
0
-  # like from, to subject, and cc. See
0
-  # Merb::MailController#dispatch_and_deliver for more details.
0
-  # 
0
-  # The send_params hash would be sent to the MailController, and is
0
-  # available to methods in the MailController as <tt>params</tt>. If you do
0
-  # not send any send_params, this controller's params will be available to
0
-  # the MailController as <tt>params</tt>
0
+  #
0
+  # ==== Parameters
0
+  # klass<Class>:: The mailer class.
0
+  # method<~to_s>:: The method to call on the mailer.
0
+  # mail_params<Hash>::
0
+  #   Mailing parameters, e.g. :to and :cc. See
0
+  #   Merb::MailController#dispatch_and_deliver for details.
0
+  # send_params<Hash>::
0
+  #   Params to send to the mailer. Defaults to the params of the current
0
+  #   controller.
0
+  #
0
+  # ==== Examples
0
+  #   # Send an email via the FooMailer's bar method.
0
+  #   send_mail FooMailer, :bar, :from => "foo@bar.com", :to => "baz@bat.com"
0
   def send_mail(klass, method, mail_params, send_params = nil)
0
     klass.new(send_params || params, self).dispatch_and_deliver(method, mail_params)
0
   end

0
@@ -34,6 +34,8 @@ module Merb
0
       "#{controller}/#{action}.#{type}"
0
     end
0
 
0
+    # Sets the template root to the default parts view directory.
0
+    #
0
     # ==== Parameters
0
     # klass<Class>::
0
     #   The Merb::PartController inheriting from the base class.