Added initial documentation for the new API

1 files changed, 41 insertions, 21 deletions

diff --git a/actionmailer/README b/actionmailer/README
index 0e16ea6ec6..542996f87b 100644
--- a/actionmailer/README
+++ b/actionmailer/README
@@ -5,51 +5,74 @@ are used to consolidate code for sending out forgotten passwords, welcome
 wishes on signup, invoices for billing, and any other use case that requires
 a written notification to either a person or another system.
 
+Action Mailer is in essence a wrapper around Action Controller and the 
+Mail gem.  It provides a way to make emails using templates in the same
+way that Action Controller renders views using templates.
+
 Additionally, an Action Mailer class can be used to process incoming email,
 such as allowing a weblog to accept new posts from an email (which could even
 have been sent from a phone).
 
 == Sending emails
 
-The framework works by setting up all the email details, except the body,
-in methods on the service layer. Subject, recipients, sender, and timestamp
-are all set up this way. An example of such a method:
+The framework works by initializing any instance variables you want to be
+available in the email template, followed by a call to +mail+ to deliver
+the email.
+
+This can be as simple as:
+
+  class Notifier < ActionMailer::Base
+  
+    delivers_from 'system@loudthinking.com'
+  
+    def welcome(recipient)
+      @recipient = recipient
+      mail(:to => recipient,
+           :subject => "[Signed up] Welcome #{recipient}")
+    end
 
-  def signed_up(recipient)
-    recipients recipient
-    subject    "[Signed up] Welcome #{recipient}"
-    from       "system@loudthinking.com"
-    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 parameter available as instance variables. 
+ERb) that has the instance variables that are declared in the mailer action.
+
 So the corresponding body template for the method above could look like this:
 
   Hello there, 
 
   Mr. <%= @recipient %>
+
+  Thank you for signing up!
   
 And if the recipient was given as "david@loudthinking.com", the email 
 generated would look like this:
 
-  Date: Sun, 12 Dec 2004 00:00:00 +0100
+  Date: Mon, 25 Jan 2010 22:48:09 +1100
   From: system@loudthinking.com
   To: david@loudthinking.com
+  Message-ID: <4b5d84f9dd6a5_7380800b81ac29578@void.loudthinking.com.mail>
   Subject: [Signed up] Welcome david@loudthinking.com
+  Mime-Version: 1.0
+  Content-Type: text/plain;
+  	charset="US-ASCII";
+  Content-Transfer-Encoding: 7bit
 
   Hello there, 
 
   Mr. david@loudthinking.com
 
-You never actually call the instance methods like signed_up directly. Instead,
-you call class methods like deliver_* and create_* that are automatically
-created for each instance method. So if the signed_up method sat on
-ApplicationMailer, it would look like this:
+In previous version of rails you would call <tt>create_method_name</tt> and
+<tt>deliver_method_name</tt>.  Rails 3.0 has a much simpler interface, you
+simply call the method and optionally call +deliver+ on the return value.
+
+Calling the method returns a Mail Message object:
+
+  message = Notifier.welcome  #=> Returns a Mail::Message object
+  message.deliver             #=> delivers the email
 
-  ApplicationMailer.create_signed_up("david@loudthinking.com")  # => tmail object for testing
-  ApplicationMailer.deliver_signed_up("david@loudthinking.com") # sends the email
-  ApplicationMailer.new.signed_up("david@loudthinking.com")     # won't work!
+Or you can just chain the methods together like:
+
+  Notifier.welcome.deliver    # Creates the email and sends it immediately
 
 == Receiving emails
 
@@ -103,16 +126,13 @@ The Base class has the full list of configuration options. Here's an example:
 Action Mailer requires that the Action Pack is either available to be required immediately
 or is accessible as a GEM.
 
+Additionally, Action Mailer requires the Mail gem, http://github.com/mikel/mail
 
 == Bundled software
 
-* tmail 0.10.8 by Minero Aoki released under LGPL
-  Read more on http://i.loveruby.net/en/prog/tmail.html
-
 * Text::Format 0.63 by Austin Ziegler released under OpenSource
   Read more on http://www.halostatue.ca/ruby/Text__Format.html
 
-
 == Download
 
 The latest version of Action Mailer can be found at