actionmailer 0.9.1 → 1.0.0

data/CHANGELOG

@@ -1,3 +1,52 @@
+*1.0.0* (6 July, 2005)
+
+* Avoid adding nil header values #1392
+
+* Better multipart support with implicit multipart/alternative and sorting of subparts [John Long]
+
+* Allow for nested parts in multipart mails #1570 [Flurin Egger]
+
+* Normalize line endings in outgoing mail bodies to "\n" #1536 [John Long]
+
+* Allow template to be explicitly specified #1448 [tuxie@dekadance.se]
+
+* Allow specific "multipart/xxx" content-type to be set on multipart messages #1412 [Flurin Egger]
+
+* Unquoted @ characters in headers are now accepted in spite of RFC 822 #1206
+
+* Helper support (borrowed from ActionPack)
+
+* Silently ignore Errno::EINVAL errors when converting text.
+
+* Don't cause an error when parsing an encoded attachment name #1340 [lon@speedymac.com]
+
+* Nested multipart message parts are correctly processed in TMail::Mail#body
+
+* BCC headers are removed when sending via SMTP #1402
+
+* Added 'content_type' accessor, to allow content type to be set on a per-message basis. content_type defaults to "text/plain".
+
+* Silently ignore Iconv::IllegalSequence errors when converting text #1341 [lon@speedymac.com]
+
+* Support attachments and multipart messages.
+
+* Added new accessors for the various mail properties.
+
+* Fix to only perform the charset conversion if a 'from' and a 'to' charset are given (make no assumptions about what the charset was) #1276 [Jamis Buck]
+
+* Fix attachments and content-type problems #1276 [Jamis Buck]
+
+* Fixed the TMail#body method to look at the content-transfer-encoding header and unquote the body according to the rules it specifies #1265 [Jamis Buck]
+
+* Added unquoting even if the iconv lib can't be loaded--in that case, only the charset conversion is skipped #1265 [Jamis Buck]
+
+* Added automatic decoding of base64 bodies #1214 [Jamis Buck]
+
+* Added that delivery errors are caught in a way so the mail is still returned whether the delivery was successful or not
+
+* Fixed that email address like "Jamis Buck, M.D." <wild.medicine@example.net> would cause the quoter to generate emails resulting in "bad address" errors from the mail server #1220 [Jamis Buck]
+
+
 *0.9.1* (20th April, 2005)
 
 * Depend on Action Pack 1.8.1
@@ -87,7 +136,7 @@
 * Consolidated the server configuration options into Base#server_settings= and expanded that with controls for authentication and more [Marten]
   NOTE: This is an API change that could potentially break your application if you used the old application form. Please do change!
 
-* Added Base#deliveries as an accessor for an array of emails sent out through that ActionMailer class when using the :test delivery option. [bitsweat]
+* Added Base#deliveries as an accessor for an array of emails sent out through that ActionMailer class when using the :test delivery option. [Jeremy Kemper]
 
 * Added Base#perform_deliveries= which can be set to false to turn off the actual delivery of the email through smtp or sendmail.
   This is especially useful for functional testing that shouldn't send off real emails, but still trigger delivery_* methods.
@@ -100,4 +149,4 @@
 
 *0.3*
 
-* First release
+* First release

data/README

@@ -16,16 +16,15 @@ in methods on the service layer. Subject, recipients, sender, and timestamp
 are all set up this way. An example of such a method:
 
   def signed_up(recipient)
-    @recipients   = recipient
-    @subject      = "[Signed up] Welcome #{recipient}"
-    @from         = "system@loudthinking.com"
-    @sent_on      = Time.local(2004, 12, 12)
+    recipients recipient
+    subject    "[Signed up] Welcome #{recipient}"
+    from       "system@loudthinking.com"
 
-    @body["recipient"] = recipient
+    body(:recipient => recipient)
   end
 
 The body of the email is created by using an Action View template (regular
-ERb) that has the content of the @body hash available as instance variables. 
+ERb) that has the content of the body hash parameter available as instance variables. 
 So the corresponding body template for the method above could look like this:
 
   Hello there, 

data/lib/action_mailer.rb

@@ -28,19 +28,26 @@ rescue LoadError
     require File.dirname(__FILE__) + '/../../actionpack/lib/action_controller'
   rescue LoadError
     require 'rubygems'
-    require_gem 'actionpack', '>= 1.6.0'
+    require_gem 'actionpack', '>= 1.9.0'
   end
 end
 
 $:.unshift(File.dirname(__FILE__) + "/action_mailer/vendor/")
 
 require 'action_mailer/base'
+require 'action_mailer/helpers'
 require 'action_mailer/mail_helper'
+require 'action_mailer/quoting'
 require 'action_mailer/vendor/tmail'
 require 'net/smtp'
 
-ActionView::Base.class_eval { include MailHelper }
+ActionMailer::Base.class_eval do
+  include ActionMailer::Quoting
+  include ActionMailer::Helpers
+
+  helper MailHelper
+end
 
 old_verbose, $VERBOSE = $VERBOSE, nil
 TMail::Encoder.const_set("MAX_LINE_LEN", 200)
-$VERBOSE = old_verbose
+$VERBOSE = old_verbose

data/lib/action_mailer/adv_attr_accessor.rb

@@ -0,0 +1,56 @@
+module ActionMailer
+  module AdvAttrAccessor #:nodoc:
+    def self.append_features(base)
+      super
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods #:nodoc:
+      def adv_attr_accessor(*names)
+        names.each do |name|
+          define_method("#{name}=") do |value|
+            instance_variable_set("@#{name}", value)
+          end
+
+          define_method(name) do |*parameters|
+            raise ArgumentError, "expected 0 or 1 parameters" unless parameters.length <= 1
+            if parameters.empty?
+              instance_variable_get("@#{name}")
+            else
+              instance_variable_set("@#{name}", parameters.first)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+module ActionMailer
+  module AdvAttrAccessor #:nodoc:
+    def self.append_features(base)
+      super
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods #:nodoc:
+      def adv_attr_accessor(*names)
+        names.each do |name|
+          define_method("#{name}=") do |value|
+            instance_variable_set("@#{name}", value)
+          end
+
+          define_method(name) do |*parameters|
+            raise ArgumentError, "expected 0 or 1 parameters" unless parameters.length <= 1
+            if parameters.empty?
+              instance_variable_get("@#{name}")
+            else
+              instance_variable_set("@#{name}", parameters.first)
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/action_mailer/base.rb

@@ -1,23 +1,73 @@
+require 'action_mailer/adv_attr_accessor'
+require 'action_mailer/part'
+require 'action_mailer/part_container'
+require 'action_mailer/utils'
+require 'tmail/net'
+
 module ActionMailer #:nodoc:
   # Usage:
   #
   #   class ApplicationMailer < ActionMailer::Base
-  #     def post_notification(recipients, post)
-  #       @recipients          = recipients
-  #       @from                = post.author.email_address_with_name
-  #       @headers["bcc"]      = SYSTEM_ADMINISTRATOR_EMAIL
-  #       @headers["reply-to"] = "notifications@example.com"
-  #       @subject             = "[#{post.account.name} #{post.title}]"
-  #       @body["post"]        = post
+  #     # Set up properties
+  #     # (Properties can also be specified via accessor methods
+  #     # i.e. self.subject = "foo") and instance variables (@subject = "foo").
+  #     def signup_notification(recipient)
+  #       recipients recipient.email_address_with_name
+  #       subject    "New account information"
+  #       body       { "account" => recipient }
+  #       from       "system@example.com"
+  #     end
+  #
+  #     # explicitly specify multipart messages
+  #     def signup_notification(recipient)
+  #       recipients      recipient.email_address_with_name
+  #       subject         "New account information"
+  #       from            "system@example.com"
+  #
+  #       part :content_type => "text/html",
+  #         :body => render_message("signup-as-html", :account => recipient)
+  #
+  #       part "text/plain" do |p|
+  #         p.body = render_message("signup-as-plain", :account => recipient)
+  #         p.transfer_encoding = "base64"
+  #       end
+  #     end
+  #
+  #     # attachments
+  #     def signup_notification(recipient)
+  #       recipients      recipient.email_address_with_name
+  #       subject         "New account information"
+  #       from            "system@example.com"
+  #
+  #       attachment :content_type => "image/jpeg",
+  #         :body => File.read("an-image.jpg")
+  #
+  #       attachment "application/pdf" do |a|
+  #         a.body = generate_your_pdf_here()
+  #       end
   #     end
-  #     
-  #     def comment_notification(recipient, comment)
-  #       @recipients      = recipient.email_address_with_name
-  #       @subject         = "[#{comment.post.project.client.firm.account.name}]" +
-  #                          " Re: #{comment.post.title}"
-  #       @body["comment"] = comment
-  #       @from            = comment.author.email_address_with_name
-  #       @sent_on         = comment.posted_on
+  #
+  #     # implicitly multipart messages
+  #     def signup_notification(recipient)
+  #       recipients      recipient.email_address_with_name
+  #       subject         "New account information"
+  #       from            "system@example.com"
+  #       body(:account => "recipient")
+  #
+  #       # ActionMailer will automatically detect and use multipart templates,
+  #       # where each template is named after the name of the action, followed
+  #       # by the content type. Each such detected template will be added as
+  #       # a separate part to the message.
+  #       #
+  #       # for example, if the following templates existed:
+  #       #   * signup_notification.text.plain.rhtml
+  #       #   * signup_notification.text.html.rhtml
+  #       #   * signup_notification.text.xml.rxml
+  #       #   * signup_notification.text.x-yaml.rhtml
+  #       #
+  #       # Each would be rendered and added as a separate part to the message,
+  #       # with the corresponding content type. The same body hash is passed to
+  #       # each template.
   #     end
   #   end
   #
@@ -57,8 +107,18 @@ module ActionMailer #:nodoc:
   #   for unit and functional testing.
   #
   # * <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>@encoding</tt>.
+  #   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_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>.
   class Base
+    include ActionMailer::AdvAttrAccessor
+    include ActionMailer::PartContainer
+
     private_class_method :new #:nodoc:
 
     cattr_accessor :template_root
@@ -89,146 +149,210 @@ module ActionMailer #:nodoc:
     @@default_charset = "utf-8"
     cattr_accessor :default_charset
 
-    attr_accessor :recipients, :subject, :body, :from, :sent_on, :headers, :bcc, :cc, :charset
+    @@default_content_type = "text/plain"
+    cattr_accessor :default_content_type
+
+    @@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
 
-    def initialize
-      @bcc = @cc = @from = @recipients = @sent_on = @subject = @body = nil
+    attr_reader       :mail
+
+    # 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:
+      create!(method_name, *parameters) if method_name 
+    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 = {}
-    end
+      @body = {}
 
-    class << self
-      def method_missing(method_symbol, *parameters)#:nodoc:
-        case method_symbol.id2name
-          when /^create_([_a-z]\w*)/
-            create_from_action($1, *parameters)
-          when /^deliver_([_a-z]\w*)/
-            begin
-              deliver(send("create_" + $1, *parameters))
-            rescue Object => e
-              raise e if raise_delivery_errors
-            end
+      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.).
+        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?
+            @parts << Part.new(:content_type => type,
+              :disposition => "inline", :charset => charset,
+              :body => render_message(File.basename(path).split(".")[0..-2].join('.'), @body))
+          end
+          unless @parts.empty?
+            @content_type = "multipart/alternative"
+            @parts = sort_parts(@parts, @implicit_parts_order)
+          end
         end
-      end
 
-      def mail(to, subject, body, from, timestamp = nil, headers = {}, charset = @@default_charset) #:nodoc:
-        deliver(create(to, subject, body, from, timestamp, headers, charset))
+        # Then, if there were such templates, we check to see if we ought to
+        # also render a "normal" template (without the content type). If a
+        # normal template exists (or if there were no implicit parts) we render
+        # it.
+        template_exists = @parts.empty?
+        template_exists ||= Dir.glob("#{template_path}/#{@template}.*").any? { |i| i.split(".").length == 2 }
+        @body = render_message(@template, @body) if template_exists
+
+        # Finally, if there are other message parts and a textual body exists,
+        # we shift it onto the front of the parts and set the body to nil (so
+        # that create_mail doesn't try to render it in addition to the parts).
+        if !@parts.empty? && String === @body
+          @parts.unshift Part.new(:charset => charset, :body => @body)
+          @body = nil
+        end
       end
 
-      def create(to, subject, body, from, timestamp = nil, headers = {}, charset = @@default_charset) #:nodoc:
-        m = TMail::Mail.new
-        m.body = body
-        m.subject, = quote_any_if_necessary(charset, subject)
-        m.to, m.from = quote_any_address_if_necessary(charset, to, from)
+      # build the mail object itself
+      @mail = create_mail
+    end
 
-        m.date = timestamp.respond_to?("to_time") ? timestamp.to_time : (timestamp || Time.now)    
+    # 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
+      logger.info "Sent mail:\n #{mail.encoded}" unless logger.nil?
 
-        m.set_content_type "text", "plain", { "charset" => charset }
+      begin
+        send("perform_delivery_#{delivery_method}", @mail) if perform_deliveries
+      rescue Object => e
+        raise e if raise_delivery_errors
+      end
 
-        headers.each do |k, v|
-          m[k] = v
-        end
+      return @mail
+    end
 
-        return m
+    private
+      def render_message(method_name, body)
+        initialize_template_class(body).render_file(method_name)
       end
-
-      def deliver(mail) #:nodoc:
-        logger.info "Sent mail:\n #{mail.encoded}" unless logger.nil?
-        send("perform_delivery_#{delivery_method}", mail) if perform_deliveries
-        return mail
+        
+      def template_path
+        template_root + "/" + Inflector.underscore(self.class.name)
       end
 
-      def quoted_printable(text, charset)#:nodoc:
-        text = text.gsub( /[^a-z ]/i ) { "=%02x" % $&[0] }.gsub( / /, "_" )
-        "=?#{charset}?Q?#{text}?="
+      def initialize_template_class(assigns)
+        ActionView::Base.new(template_path, assigns, self)
       end
 
-      CHARS_NEEDING_QUOTING = /[\000-\011\013\014\016-\037\177-\377]/
+      def sort_parts(parts, order = [])
+        order = order.collect { |s| s.downcase }
 
-      # Quote the given text if it contains any "illegal" characters
-      def quote_if_necessary(text, charset)
-        (text =~ CHARS_NEEDING_QUOTING) ?
-          quoted_printable(text, charset) :
-          text
-      end
+        parts = parts.sort do |a, b|
+          a_ct = a.content_type.downcase
+          b_ct = b.content_type.downcase
 
-      # Quote any of the given strings if they contain any "illegal" characters
-      def quote_any_if_necessary(charset, *args)
-        args.map { |v| quote_if_necessary(v, charset) }
-      end
+          a_in = order.include? a_ct
+          b_in = order.include? b_ct
 
-      # Quote the given address if it needs to be. The address may be a
-      # regular email address, or it can be a phrase followed by an address in
-      # brackets. The phrase is the only part that will be quoted, and only if
-      # it needs to be. This allows extended characters to be used in the
-      # "to", "from", "cc", and "bcc" headers.
-      def quote_address_if_necessary(address, charset)
-        if Array === address
-          address.map { |a| quote_address_if_necessary(a, charset) }
-        elsif address =~ /^(\S.*)\s+(<.*>)$/
-          address = $2
-          phrase = quote_if_necessary($1.gsub(/^['"](.*)['"]$/, '\1'), charset)
-          "#{phrase} #{address}"
-        else
-          address
+          s = case
+          when a_in && b_in
+            order.index(a_ct) <=> order.index(b_ct)
+          when a_in
+            -1
+          when b_in
+            1
+          else
+            a_ct <=> b_ct
+          end
+
+          # reverse the ordering because parts that come last are displayed
+          # first in mail clients
+          (s * -1)
         end
-      end
 
-      # Quote any of the given addresses, if they need to be.
-      def quote_any_address_if_necessary(charset, *args)
-        args.map { |v| quote_address_if_necessary(v, charset) }
+        parts
       end
 
-      def receive(raw_email)
-        logger.info "Received mail:\n #{raw_email}" unless logger.nil?
-        new.receive(TMail::Mail.parse(raw_email))
-      end
+      def create_mail
+        m = TMail::Mail.new
+
+        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?
 
-      private
-        def perform_delivery_smtp(mail)
-          Net::SMTP.start(server_settings[:address], server_settings[:port], server_settings[:domain], 
-              server_settings[:user_name], server_settings[:password], server_settings[:authentication]) do |smtp|
-            smtp.sendmail(mail.encoded, mail.from, mail.destinations)
+        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 }
+          m.body = Utils.normalize_new_lines(body)
+        else
+          if String === body
+            part = TMail::Mail.new
+            part.body = Utils.normalize_new_lines(body)
+            part.set_content_type content_type, nil, { "charset" => charset }
+            part.set_content_disposition "inline"
+            m.parts << part
           end
-        end
 
-        def perform_delivery_sendmail(mail)
-          IO.popen("/usr/sbin/sendmail -i -t","w+") do |sm|
-            sm.print(mail.encoded)
-            sm.flush
+          @parts.each do |p|
+            part = (TMail::Mail === p ? p : p.to_mail(self))
+            m.parts << part
           end
+          
+          m.set_content_type(content_type, nil, { "charset" => charset }) if content_type =~ /multipart/
         end
 
-        def perform_delivery_test(mail)
-          deliveries << mail
-        end
+        @mail = m
+      end
 
-        def create_from_action(method_name, *parameters)
-          mailer = new
-          mailer.body = {}
-          mailer.send(method_name, *parameters)
+      def perform_delivery_smtp(mail)
+        destinations = mail.destinations
+        mail.ready_to_send
 
-          unless String === mailer.body then
-            mailer.body = render_body mailer, method_name
-          end
+        Net::SMTP.start(server_settings[:address], server_settings[:port], server_settings[:domain], 
+            server_settings[:user_name], server_settings[:password], server_settings[:authentication]) do |smtp|
+          smtp.sendmail(mail.encoded, mail.from, destinations)
+        end
+      end
 
-          mail = create(mailer.recipients, mailer.subject, mailer.body,
-                        mailer.from, mailer.sent_on, mailer.headers,
-                        mailer.charset)
+      def perform_delivery_sendmail(mail)
+        IO.popen("/usr/sbin/sendmail -i -t","w+") do |sm|
+          sm.print(mail.encoded)
+          sm.flush
+        end
+      end
 
-          mail.bcc = quote_address_if_necessary(mailer.bcc, mailer.charset) unless mailer.bcc.nil?
-          mail.cc  = quote_address_if_necessary(mailer.cc, mailer.charset)  unless mailer.cc.nil?
+      def perform_delivery_test(mail)
+        deliveries << mail
+      end
 
-          return mail
-        end
-  
-        def render_body(mailer, method_name)
-          ActionView::Base.new(template_path, mailer.body).render_file(method_name)
-        end
-        
-        def template_path
-          template_root + "/" + Inflector.underscore(self.to_s)
+    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