lib/action_mailer/base.rb in actionmailer-1.0.1 vs lib/action_mailer/base.rb in actionmailer-1.1.1

@@ -2,11 +2,11 @@
 require 'action_mailer/part'
 require 'action_mailer/part_container'
 require 'action_mailer/utils'
 require 'tmail/net'
 
-module ActionMailer #:nodoc:
+module ActionMailer
   # Usage:
   #
   #   class ApplicationMailer < ActionMailer::Base
   #     # Set up properties
   #     # (Properties can also be specified via accessor methods
@@ -108,10 +108,13 @@
   #
   # * <tt>default_charset</tt> - The default charset used for the body and to encode the subject. Defaults to UTF-8. You can also 
   #   pick a different charset from inside a method with <tt>@charset</tt>.
   # * <tt>default_content_type</tt> - The default content type used for main part of the message. Defaults to "text/plain". You
   #   can also pick a different content type from inside a method with <tt>@content_type</tt>. 
+  # * <tt>default_mime_version</tt> - The default mime version used for the message. Defaults to nil. You
+  #   can also pick a different value from inside a method with <tt>@mime_version</tt>. When multipart messages are in
+  #   use, <tt>@mime_version</tt> will be set to "1.0" if it is not set inside a method.
   # * <tt>default_implicit_parts_order</tt> - When a message is built implicitly (i.e. multiple parts are assemble from templates
   #   which specify the content type in their filenames) this variable controls how the parts are ordered. Defaults to
   #   ["text/html", "text/enriched", "text/plain"]. Items that appear first in the array have higher priority in the mail client
   #   and appear last in the mime encoded message. You can also pick a different order from inside a method with
   #   <tt>@implicit_parts_order</tt>.
@@ -148,20 +151,112 @@
     @@default_charset = "utf-8"
     cattr_accessor :default_charset
 
     @@default_content_type = "text/plain"
     cattr_accessor :default_content_type
+    
+    @@default_mime_version = nil
+    cattr_accessor :default_mime_version
 
     @@default_implicit_parts_order = [ "text/html", "text/enriched", "text/plain" ]
     cattr_accessor :default_implicit_parts_order
 
-    adv_attr_accessor :recipients, :subject, :body, :from, :sent_on, :headers,
-                      :bcc, :cc, :charset, :content_type, :implicit_parts_order,
-                      :template
+    # Specify the BCC addresses for the message
+    adv_attr_accessor :bcc
+    
+    # Define the body of the message. This is either a Hash (in which case it
+    # specifies the variables to pass to the template when it is rendered),
+    # or a string, in which case it specifies the actual text of the message.
+    adv_attr_accessor :body
+    
+    # Specify the CC addresses for the message.
+    adv_attr_accessor :cc
+    
+    # Specify the charset to use for the message. This defaults to the
+    # +default_charset+ specified for ActionMailer::Base.
+    adv_attr_accessor :charset
+    
+    # Specify the content type for the message. This defaults to <tt>text/plain</tt>
+    # in most cases, but can be automatically set in some situations.
+    adv_attr_accessor :content_type
+    
+    # Specify the from address for the message.
+    adv_attr_accessor :from
+    
+    # Specify additional headers to be added to the message.
+    adv_attr_accessor :headers
+    
+    # Specify the order in which parts should be sorted, based on content-type.
+    # This defaults to the value for the +default_implicit_parts_order+.
+    adv_attr_accessor :implicit_parts_order
+    
+    # Override the mailer name, which defaults to an inflected version of the
+    # mailer's class name. If you want to use a template in a non-standard
+    # location, you can use this to specify that location.
+    adv_attr_accessor :mailer_name
+    
+    # Defaults to "1.0", but may be explicitly given if needed.
+    adv_attr_accessor :mime_version
+    
+    # The recipient addresses for the message, either as a string (for a single
+    # address) or an array (for multiple addresses).
+    adv_attr_accessor :recipients
+    
+    # The date on which the message was sent. If not set (the default), the
+    # header will be set by the delivery agent.
+    adv_attr_accessor :sent_on
+    
+    # Specify the subject of the message.
+    adv_attr_accessor :subject
+    
+    # Specify the template name to use for current message. This is the "base"
+    # template name, without the extension or directory, and may be used to
+    # have multiple mailer methods share the same template.
+    adv_attr_accessor :template
 
-    attr_reader       :mail
+    # The mail object instance referenced by this mailer.
+    attr_reader :mail
 
+    class << self
+      def method_missing(method_symbol, *parameters)#:nodoc:
+        case method_symbol.id2name
+          when /^create_([_a-z]\w*)/  then new($1, *parameters).mail
+          when /^deliver_([_a-z]\w*)/ then new($1, *parameters).deliver!
+          when "new" then nil
+          else super
+        end
+      end
+
+      # Receives a raw email, parses it into an email object, decodes it,
+      # instantiates a new mailer, and passes the email object to the mailer
+      # object's #receive method. If you want your mailer to be able to
+      # process incoming messages, you'll need to implement a #receive
+      # method that accepts the email object as a parameter:
+      #
+      #   class MyMailer < ActionMailer::Base
+      #     def receive(mail)
+      #       ...
+      #     end
+      #   end
+      def receive(raw_email)
+        logger.info "Received mail:\n #{raw_email}" unless logger.nil?
+        mail = TMail::Mail.parse(raw_email)
+        mail.base64_decode
+        new.receive(mail)
+      end
+
+      # Deliver the given mail object directly. This can be used to deliver
+      # a preconstructed mail object, like:
+      #
+      #   email = MyMailer.create_some_mail(parameters)
+      #   email.set_some_obscure_header "frobnicate"
+      #   MyMailer.deliver(email)
+      def deliver(mail)
+        new.deliver!(mail)
+      end
+    end
+
     # Instantiate a new mailer object. If +method_name+ is not +nil+, the mailer
     # will be initialized according to the named method. If not, the mailer will
     # remain uninitialized (useful when you only need to invoke the "receive"
     # method, for instance).
     def initialize(method_name=nil, *parameters) #:nodoc:
@@ -169,26 +264,19 @@
     end
 
     # Initialize the mailer via the given +method_name+. The body will be
     # rendered and a new TMail::Mail object created.
     def create!(method_name, *parameters) #:nodoc:
-      @bcc = @cc = @from = @recipients = @sent_on = @subject = nil
-      @charset = @@default_charset.dup
-      @content_type = @@default_content_type.dup
-      @implicit_parts_order = @@default_implicit_parts_order.dup
-      @template = method_name
-      @parts = []
-      @headers = {}
-      @body = {}
-
+      initialize_defaults(method_name)
       send(method_name, *parameters)
 
       # If an explicit, textual body has not been set, we check assumptions.
       unless String === @body
         # First, we look to see if there are any likely templates that match,
         # which include the content-type in their file name (i.e.,
-        # "the_template_file.text.html.rhtml", etc.).
+        # "the_template_file.text.html.rhtml", etc.). Only do this if parts
+        # have not already been specified manually.
         if @parts.empty?
           templates = Dir.glob("#{template_path}/#{@template}.*")
           templates.each do |path|
             type = (File.basename(path).split(".")[1..-2] || []).join("/")
             next if type.empty?
@@ -196,10 +284,11 @@
               :disposition => "inline", :charset => charset,
               :body => render_message(File.basename(path).split(".")[0..-2].join('.'), @body))
           end
           unless @parts.empty?
             @content_type = "multipart/alternative"
+            @charset = nil
             @parts = sort_parts(@parts, @implicit_parts_order)
           end
         end
 
         # Then, if there were such templates, we check to see if we ought to
@@ -217,36 +306,62 @@
           @parts.unshift Part.new(:charset => charset, :body => @body)
           @body = nil
         end
       end
 
+      # If this is a multipart e-mail add the mime_version if it is not
+      # already set.
+      @mime_version ||= "1.0" if !@parts.empty?
+
       # build the mail object itself
       @mail = create_mail
     end
 
-    # Delivers the cached TMail::Mail object. If no TMail::Mail object has been
-    # created (via the #create! method, for instance) this will fail.
-    def deliver! #:nodoc:
-      raise "no mail object available for delivery!" unless @mail
+    # Delivers a TMail::Mail object. By default, it delivers the cached mail
+    # object (from the #create! method). If no cached mail object exists, and
+    # no alternate has been given as the parameter, this will fail.
+    def deliver!(mail = @mail)
+      raise "no mail object available for delivery!" unless mail
       logger.info "Sent mail:\n #{mail.encoded}" unless logger.nil?
 
       begin
-        send("perform_delivery_#{delivery_method}", @mail) if perform_deliveries
+        send("perform_delivery_#{delivery_method}", mail) if perform_deliveries
       rescue Object => e
         raise e if raise_delivery_errors
       end
 
-      return @mail
+      return mail
     end
 
     private
+      # Set up the default values for the various instance variables of this
+      # mailer. Subclasses may override this method to provide different
+      # defaults.
+      def initialize_defaults(method_name)
+        @bcc = @cc = @from = @recipients = @sent_on = @subject = nil
+        @charset = @@default_charset.dup
+        @content_type = @@default_content_type.dup
+        @implicit_parts_order = @@default_implicit_parts_order.dup
+        @template = method_name
+        @mailer_name = Inflector.underscore(self.class.name)
+        @parts = []
+        @headers = {}
+        @body = {}
+        @mime_version = @@default_mime_version.dup if @@default_mime_version
+      end
+
       def render_message(method_name, body)
-        initialize_template_class(body).render_file(method_name)
+        render :file => method_name, :body => body
       end
-        
+
+      def render(opts)
+        body = opts.delete(:body)
+        initialize_template_class(body).render(opts)
+      end
+
       def template_path
-        template_root + "/" + Inflector.underscore(self.class.name)
+        "#{template_root}/#{mailer_name}"
       end
 
       def initialize_template_class(assigns)
         ActionView::Base.new(template_path, assigns, self)
       end
@@ -286,10 +401,11 @@
         m.subject, = quote_any_if_necessary(charset, subject)
         m.to, m.from = quote_any_address_if_necessary(charset, recipients, from)
         m.bcc = quote_address_if_necessary(bcc, charset) unless bcc.nil?
         m.cc  = quote_address_if_necessary(cc, charset) unless cc.nil?
 
+        m.mime_version = mime_version unless mime_version.nil?
         m.date = sent_on.to_time rescue sent_on if sent_on
         headers.each { |k, v| m[k] = v }
 
         if @parts.empty?
           m.set_content_type content_type, nil, { "charset" => charset }
@@ -324,34 +440,15 @@
         end
       end
 
       def perform_delivery_sendmail(mail)
         IO.popen("/usr/sbin/sendmail -i -t","w+") do |sm|
-          sm.print(mail.encoded)
+          sm.print(mail.encoded.gsub(/\r/, ''))
           sm.flush
         end
       end
 
       def perform_delivery_test(mail)
         deliveries << mail
       end
-
-    class << self
-      def method_missing(method_symbol, *parameters)#:nodoc:
-        case method_symbol.id2name
-          when /^create_([_a-z]\w*)/  then new($1, *parameters).mail
-          when /^deliver_([_a-z]\w*)/ then new($1, *parameters).deliver!
-          when "new" then nil
-          else super
-        end
-      end
-
-      def receive(raw_email)
-        logger.info "Received mail:\n #{raw_email}" unless logger.nil?
-        mail = TMail::Mail.parse(raw_email)
-        mail.base64_decode
-        new.receive(mail)
-      end
-
-    end
   end
 end