0
@@ -1,5 +1,7 @@
0
 *SVN*
0
 
0
+* Backport of documentation enhancements. [Kevin Clark, Marcel Molina Jr]
0
+
0
 * Correct spurious documentation example code which results in a SyntaxError. [Marcel Molina Jr.]
0
 
0
 * Mailer template root applies to a class and its subclasses rather than acting globally. #5555 [somekool@gmail.com]

0
@@ -5,20 +5,92 @@ require 'action_mailer/utils'
0
 require 'tmail/net'
0
 
0
 module ActionMailer #:nodoc:
0
-  # Usage:
0
+  # ActionMailer allows you to send email from your application using a mailer model and views.
0
   #
0
-  #   class ApplicationMailer < ActionMailer::Base
0
-  #     # Set up properties
0
-  #     # Properties can also be specified via accessor methods
0
-  #     # (i.e. self.subject = "foo") and instance variables (@subject = "foo").
0
+  # = Mailer Models
0
+  # To use ActionMailer, you need to create a mailer model.
0
+  #   
0
+  #   $ script/generate mailer Notifier
0
+  #
0
+  # The generated model inherits from ActionMailer::Base. Emails are defined by creating methods within the model which are then 
0
+  # used to set variables to be used in the mail template, to change options on the mail, or 
0
+  # to add attachments.
0
+  #
0
+  # Examples:
0
+  #
0
+  #  class Notifier < ActionMailer::Base
0
+  #    def signup_notification(recipient)
0
+  #      recipients recipient.email_address_with_name
0
+  #      from       "system@example.com"
0
+  #      subject    "New account information"
0
+  #      body       "account" => recipient
0
+  #    end
0
+  #  end
0
+  #
0
+  # Mailer methods have the following configuration methods available.
0
+  #
0
+  # * <tt>recipients</tt> - Takes one or more email addresses. These addresses are where your email will be delivered to. Sets the <tt>To:</tt> header.
0
+  # * <tt>subject</tt> - The subject of your email. Sets the <tt>Subject:</tt> header.
0
+  # * <tt>from</tt> - Who the email you are sending is from. Sets the <tt>From:</tt> header.
0
+  # * <tt>cc</tt> - Takes one or more email addresses. These addresses will receive a carbon copy of your email. Sets the <tt>Cc:</tt> header.
0
+  # * <tt>bcc</tt> - Takes one or more email address. These addresses will receive a blind carbon copy of your email. Sets the <tt>Bcc</tt> header.
0
+  # * <tt>sent_on</tt> - The date on which the message was sent. If not set, the header wil be set by the delivery agent.
0
+  # * <tt>content_type</tt> - Specify the content type of the message. Defaults to <tt>text/plain</tt>.
0
+  # * <tt>headers</tt> - Specify additional headers to be set for the message, e.g. <tt>headers 'X-Mail-Count' => 107370</tt>.
0
+  #
0
+  # The <tt>body</tt> method has special behavior. It takes a hash which generates an instance variable
0
+  # named after each key in the hash containing the value that that key points to.
0
+  #
0
+  # So, for example, <tt>body "account" => recipient</tt> would result
0
+  # in an instance variable <tt>@account</tt> with the value of <tt>recipient</tt> being accessible in the 
0
+  # view.
0
+  #
0
+  # = Mailer Views
0
+  # Like ActionController, each mailer class has a corresponding view directory
0
+  # in which each method of the class looks for a template with its name.
0
+  # To define a template to be used with a mailing, create an <tt>.rhtml</tt> file with the same name as the method
0
+  # in your mailer model. For example, in the mailer defined above, the template at 
0
+  # <tt>app/views/notifier/signup_notification.rhtml</tt> would be used to generate the email.
0
+  #
0
+  # Variables defined in the model are accessible as instance variables in the view.
0
+  #
0
+  # Emails by default are sent in plain text, so a sample view for our model example might look like this:
0
+  #
0
+  #   Hi <%= @account.name %>,
0
+  #   Thanks for joining our service! Please check back often.
0
+  #
0
+  # = Sending Mail
0
+  # Once a mailer action and template are defined, you can deliver your message or create it and save it 
0
+  # for delivery later:
0
+  #
0
+  #   Notifier.deliver_signup_notification(david) # sends the email
0
+  #   mail = Notifier.create_signup_notification(david)  # => a tmail object
0
+  #   Notifier.deliver(mail)
0
+  # 
0
+  # You never instantiate your mailer class. Rather, your delivery instance
0
+  # methods are automatically wrapped in class methods that start with the word
0
+  # <tt>deliver_</tt> followed by the name of the mailer method that you would
0
+  # like to deliver. The <tt>signup_notification</tt> method defined above is
0
+  # delivered by invoking <tt>Notifier.deliver_signup_notification</tt>.
0
+  #
0
+  # = HTML Email
0
+  # To send mail as HTML, make sure your view (the <tt>.rhtml</tt> file) generates HTML and
0
+  # set the content type to html.
0
+  #
0
+  #   class MyMailer < ActionMailer::Base
0
   #     def signup_notification(recipient)
0
   #       recipients recipient.email_address_with_name
0
   #       subject    "New account information"
0
   #       body       "account" => recipient
0
   #       from       "system@example.com"
0
+  #       content_type "text/html"   #    Here's where the magic happens
0
   #     end
0
+  #   end  
0
+  #
0
+  # = Multipart Email
0
+  # You can explicitly specify multipart messages:
0
   #
0
-  #     # explicitly specify multipart messages
0
+  #   class ApplicationMailer < ActionMailer::Base
0
   #     def signup_notification(recipient)
0
   #       recipients      recipient.email_address_with_name
0
   #       subject         "New account information"
0
@@ -32,7 +104,28 @@ module ActionMailer #:nodoc:
0
   #         p.transfer_encoding = "base64"
0
   #       end
0
   #     end
0
+  #   end
0
+  #  
0
+  # Multipart messages can also be used implicitly because ActionMailer will automatically
0
+  # detect and use multipart templates, where each template is named after the name of the action, followed
0
+  # by the content type. Each such detected template will be added as separate part to the message.
0
+  # 
0
+  # For example, if the following templates existed:
0
+  # * signup_notification.text.plain.rhtml
0
+  # * signup_notification.text.html.rhtml
0
+  # * signup_notification.text.xml.rxml
0
+  # * signup_notification.text.x-yaml.rhtml
0
+  #  
0
+  # Each would be rendered and added as a separate part to the message,
0
+  # with the corresponding content type. The same body hash is passed to
0
+  # each template.
0
   #
0
+  # = Attachments
0
+  # Attachments can be added by using the +attachment+ method.
0
+  #
0
+  # Example:
0
+  #
0
+  #   class ApplicationMailer < ActionMailer::Base
0
   #     # attachments
0
   #     def signup_notification(recipient)
0
   #       recipients      recipient.email_address_with_name
0
@@ -46,36 +139,7 @@ module ActionMailer #:nodoc:
0
   #         a.body = generate_your_pdf_here()
0
   #       end
0
   #     end
0
-  #
0
-  #     # implicitly multipart messages
0
-  #     def signup_notification(recipient)
0
-  #       recipients      recipient.email_address_with_name
0
-  #       subject         "New account information"
0
-  #       from            "system@example.com"
0
-  #       body(:account => "recipient")
0
-  #
0
-  #       # ActionMailer will automatically detect and use multipart templates,
0
-  #       # where each template is named after the name of the action, followed
0
-  #       # by the content type. Each such detected template will be added as
0
-  #       # a separate part to the message.
0
-  #       #
0
-  #       # for example, if the following templates existed:
0
-  #       #   * signup_notification.text.plain.rhtml
0
-  #       #   * signup_notification.text.html.rhtml
0
-  #       #   * signup_notification.text.xml.rxml
0
-  #       #   * signup_notification.text.x-yaml.rhtml
0
-  #       #
0
-  #       # Each would be rendered and added as a separate part to the message,
0
-  #       # with the corresponding content type. The same body hash is passed to
0
-  #       # each template.
0
-  #     end
0
-  #   end
0
-  #
0
-  #   # After this, post_notification will look for "templates/application_mailer/post_notification.rhtml"
0
-  #   ApplicationMailer.template_root = "templates"
0
-  #  
0
-  #   ApplicationMailer.create_comment_notification(david, hello_world)  # => a tmail object
0
-  #   ApplicationMailer.deliver_comment_notification(david, hello_world) # sends the email
0
+  #   end 
0
   #
0
   # = Configuration options
0
   #