actionmailer 1.0.1 → 1.1.1

data/CHANGELOG

@@ -1,3 +1,37 @@
+*1.1.1* (October 19th, 2005)
+
+* Upgraded to Action Pack 1.10.1
+
+
+*1.1.0* (October 16th, 2005)
+
+* Update and extend documentation (rdoc)
+
+* Minero Aoki made TMail available to Rails/ActionMailer under the MIT license (instead of LGPL) [RubyConf '05]
+
+* Austin Ziegler made Text::Simple available to Rails/ActionMailer under a MIT-like licens [See rails ML, subject "Text::Format Licence Exception" on Oct 15, 2005]
+
+* Fix vendor require paths to prevent files being required twice
+
+* Don't add charset to content-type header for a part that contains subparts (for AOL compatibility) #2013 [John Long]
+
+* Preserve underscores when unquoting message bodies #1930
+
+* Encode multibyte characters correctly #1894
+
+* Multipart messages specify a MIME-Version header automatically #2003 [John Long]
+
+* Add a unified render method to ActionMailer (delegates to ActionView::Base#render)
+
+* Move mailer initialization to a separate (overridable) method, so that subclasses may alter the various defaults #1727
+
+* Look at content-location header (if available) to determine filename of attachments #1670
+
+* ActionMailer::Base.deliver(email) had been accidentally removed, but was documented in the Rails book #1849
+
+* Fix problem with sendmail delivery where headers should be delimited by \n characters instead of \r\n, which confuses some mail readers #1742 [Kent Sibilev]
+
+
 *1.0.1* (11 July, 2005)
 
 * Bind to Action Pack 1.9.1

data/lib/action_mailer.rb

@@ -38,7 +38,7 @@ require 'action_mailer/base'
 require 'action_mailer/helpers'
 require 'action_mailer/mail_helper'
 require 'action_mailer/quoting'
-require 'action_mailer/vendor/tmail'
+require 'tmail'
 require 'net/smtp'
 
 ActionMailer::Base.class_eval do
@@ -48,6 +48,4 @@ ActionMailer::Base.class_eval do
   helper MailHelper
 end
 
-old_verbose, $VERBOSE = $VERBOSE, nil
-TMail::Encoder.const_set("MAX_LINE_LEN", 200)
-$VERBOSE = old_verbose
+silence_warnings { TMail::Encoder.const_set("MAX_LINE_LEN", 200) }

data/lib/action_mailer/adv_attr_accessor.rb

@@ -25,32 +25,3 @@ module ActionMailer
     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

@@ -4,7 +4,7 @@ require 'action_mailer/part_container'
 require 'action_mailer/utils'
 require 'tmail/net'
 
-module ActionMailer #:nodoc:
+module ActionMailer
   # Usage:
   #
   #   class ApplicationMailer < ActionMailer::Base
@@ -110,6 +110,9 @@ module ActionMailer #:nodoc:
   #   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
@@ -150,15 +153,107 @@ module ActionMailer #:nodoc:
 
     @@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
+
+    # 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
 
-    attr_reader       :mail
+      # 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
@@ -171,22 +266,15 @@ module ActionMailer #:nodoc:
     # 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|
@@ -198,6 +286,7 @@ module ActionMailer #:nodoc:
           end
           unless @parts.empty?
             @content_type = "multipart/alternative"
+            @charset = nil
             @parts = sort_parts(@parts, @implicit_parts_order)
           end
         end
@@ -219,32 +308,58 @@ module ActionMailer #:nodoc:
         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)
@@ -288,6 +403,7 @@ module ActionMailer #:nodoc:
         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 }
 
@@ -326,7 +442,7 @@ module ActionMailer #:nodoc:
 
       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
@@ -334,24 +450,5 @@ module ActionMailer #:nodoc:
       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

data/lib/action_mailer/helpers.rb

@@ -1,6 +1,6 @@
-module ActionMailer #:nodoc:
+module ActionMailer
   module Helpers #:nodoc:
-    def self.append_features(base)
+    def self.append_features(base) #:nodoc:
       super
 
       # Initialize the base module to aggregate its helpers.
@@ -24,7 +24,7 @@ module ActionMailer #:nodoc:
       end
     end
 
-    module ClassMethods #:nodoc:
+    module ClassMethods
       # Makes all the (instance) methods in the helper module available to templates rendered through this controller.
       # See ActionView::Helpers (link:classes/ActionView/Helpers.html) for more about making your own helper modules 
       # available to the templates.

data/lib/action_mailer/mail_helper.rb

@@ -1,6 +1,8 @@
-require 'action_mailer/vendor/text/format'
+require 'text/format'
 
-module MailHelper#:nodoc:
+module MailHelper
+  # Uses Text::Format to take the text and format it, indented two spaces for
+  # each line, and wrapped at 72 columns.
   def block_format(text)
     formatted = text.split(/\n\r\n/).collect { |paragraph| 
       Text::Format.new(
@@ -14,4 +16,4 @@ module MailHelper#:nodoc:
 
     formatted
   end
-end
+end

data/lib/action_mailer/part.rb

@@ -3,13 +3,43 @@ require 'action_mailer/part_container'
 require 'action_mailer/utils'
 
 module ActionMailer
-  class Part #:nodoc:
+  # Represents a subpart of an email message. It shares many similar
+  # attributes of ActionMailer::Base.  Although you can create parts manually
+  # and add them to the #parts list of the mailer, it is easier
+  # to use the helper methods in ActionMailer::PartContainer.
+  class Part
     include ActionMailer::AdvAttrAccessor
     include ActionMailer::PartContainer
 
-    adv_attr_accessor :content_type, :content_disposition, :charset, :body
-    adv_attr_accessor :filename, :transfer_encoding, :headers
+    # Represents the body of the part, as a string. This should not be a
+    # Hash (like ActionMailer::Base), but if you want a template to be rendered
+    # into the body of a subpart you can do it with the mailer's #render method
+    # and assign the result here.
+    adv_attr_accessor :body
+    
+    # Specify the charset for this subpart. By default, it will be the charset
+    # of the containing part or mailer.
+    adv_attr_accessor :charset
+    
+    # The content disposition of this part, typically either "inline" or
+    # "attachment".
+    adv_attr_accessor :content_disposition
+    
+    # The content type of the part.
+    adv_attr_accessor :content_type
+    
+    # The filename to use for this subpart (usually for attachments).
+    adv_attr_accessor :filename
+    
+    # Accessor for specifying additional headers to include with this part.
+    adv_attr_accessor :headers
+    
+    # The transfer encoding to use for this subpart, like "base64" or
+    # "quoted-printable".
+    adv_attr_accessor :transfer_encoding
 
+    # Create a new part from the given +params+ hash. The valid params keys
+    # correspond to the accessors.
     def initialize(params)
       @content_type = params[:content_type]
       @content_disposition = params[:disposition] || "inline"
@@ -21,6 +51,8 @@ module ActionMailer
       @parts = []
     end
 
+    # Convert the part to a mail object which can be included in the parts
+    # list of another mail object.
     def to_mail(defaults)
       part = TMail::Mail.new