Permalink
Browse files

Added initial documentation for the new API

  • Loading branch information...
1 parent 9cb3ca1 commit 4a6eba3232fec13892f36fc4730bb2deef342fc3 José Valim and Mikel Lindsaar committed Jan 25, 2010
Showing with 202 additions and 119 deletions.
  1. +2 −0 actionmailer/CHANGELOG
  2. +41 −21 actionmailer/README
  3. +159 −98 actionmailer/lib/action_mailer/base.rb
View
@@ -1,5 +1,7 @@
*Rails 3.0 (pending)*
+* Whole new API added with tests. See base.rb for full details. Old API is deprecated.
+
* The Mail::Message class has helped methods for all the field types that return 'common' defaults for the common use case, so to get the subject, mail.subject will give you a string, mail.date will give you a DateTime object, mail.from will give you an array of address specs (mikel@test.lindsaar.net) etc. If you want to access the field object itself, call mail[:field_name] which will return the field object you want, which you can then chain, like mail[:from].formatted
* Mail#content_type now returns the content_type field as a string. If you want the mime type of a mail, then you call Mail#mime_type (eg, text/plain), if you want the parameters of the content type field, you call Mail#content_type_parameters which gives you a hash, eg {'format' => 'flowed', 'charset' => 'utf-8'}
View
@@ -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
Oops, something went wrong.

0 comments on commit 4a6eba3

Please sign in to comment.