diff options
Diffstat (limited to 'actionmailer/README')
-rw-r--r-- | actionmailer/README | 62 |
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 |