Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

backport of ActionMailer documentation enhancements from trunk

git-svn-id: http://svn-commit.rubyonrails.org/rails/branches/stable@4732 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
commit 4874df1d674bccbe2fa41a12bb93fa63a5d489ee 1 parent 94a1758
Michael Koziarski NZKoz authored

Showing 2 changed files with 102 additions and 36 deletions. Show diff stats Hide diff stats

  1. +2 0  actionmailer/CHANGELOG
  2. +100 36 actionmailer/lib/action_mailer/base.rb
2  actionmailer/CHANGELOG
... ... @@ -1,5 +1,7 @@
1 1 *SVN*
2 2
  3 +* Backport of documentation enhancements. [Kevin Clark, Marcel Molina Jr]
  4 +
3 5 * Correct spurious documentation example code which results in a SyntaxError. [Marcel Molina Jr.]
4 6
5 7 * Mailer template root applies to a class and its subclasses rather than acting globally. #5555 [somekool@gmail.com]
136 actionmailer/lib/action_mailer/base.rb
@@ -5,20 +5,92 @@
5 5 require 'tmail/net'
6 6
7 7 module ActionMailer #:nodoc:
8   - # Usage:
  8 + # ActionMailer allows you to send email from your application using a mailer model and views.
9 9 #
10   - # class ApplicationMailer < ActionMailer::Base
11   - # # Set up properties
12   - # # Properties can also be specified via accessor methods
13   - # # (i.e. self.subject = "foo") and instance variables (@subject = "foo").
  10 + # = Mailer Models
  11 + # To use ActionMailer, you need to create a mailer model.
  12 + #
  13 + # $ script/generate mailer Notifier
  14 + #
  15 + # The generated model inherits from ActionMailer::Base. Emails are defined by creating methods within the model which are then
  16 + # used to set variables to be used in the mail template, to change options on the mail, or
  17 + # to add attachments.
  18 + #
  19 + # Examples:
  20 + #
  21 + # class Notifier < ActionMailer::Base
  22 + # def signup_notification(recipient)
  23 + # recipients recipient.email_address_with_name
  24 + # from "system@example.com"
  25 + # subject "New account information"
  26 + # body "account" => recipient
  27 + # end
  28 + # end
  29 + #
  30 + # Mailer methods have the following configuration methods available.
  31 + #
  32 + # * <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.
  33 + # * <tt>subject</tt> - The subject of your email. Sets the <tt>Subject:</tt> header.
  34 + # * <tt>from</tt> - Who the email you are sending is from. Sets the <tt>From:</tt> header.
  35 + # * <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.
  36 + # * <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.
  37 + # * <tt>sent_on</tt> - The date on which the message was sent. If not set, the header wil be set by the delivery agent.
  38 + # * <tt>content_type</tt> - Specify the content type of the message. Defaults to <tt>text/plain</tt>.
  39 + # * <tt>headers</tt> - Specify additional headers to be set for the message, e.g. <tt>headers 'X-Mail-Count' => 107370</tt>.
  40 + #
  41 + # The <tt>body</tt> method has special behavior. It takes a hash which generates an instance variable
  42 + # named after each key in the hash containing the value that that key points to.
  43 + #
  44 + # So, for example, <tt>body "account" => recipient</tt> would result
  45 + # in an instance variable <tt>@account</tt> with the value of <tt>recipient</tt> being accessible in the
  46 + # view.
  47 + #
  48 + # = Mailer Views
  49 + # Like ActionController, each mailer class has a corresponding view directory
  50 + # in which each method of the class looks for a template with its name.
  51 + # To define a template to be used with a mailing, create an <tt>.rhtml</tt> file with the same name as the method
  52 + # in your mailer model. For example, in the mailer defined above, the template at
  53 + # <tt>app/views/notifier/signup_notification.rhtml</tt> would be used to generate the email.
  54 + #
  55 + # Variables defined in the model are accessible as instance variables in the view.
  56 + #
  57 + # Emails by default are sent in plain text, so a sample view for our model example might look like this:
  58 + #
  59 + # Hi <%= @account.name %>,
  60 + # Thanks for joining our service! Please check back often.
  61 + #
  62 + # = Sending Mail
  63 + # Once a mailer action and template are defined, you can deliver your message or create it and save it
  64 + # for delivery later:
  65 + #
  66 + # Notifier.deliver_signup_notification(david) # sends the email
  67 + # mail = Notifier.create_signup_notification(david) # => a tmail object
  68 + # Notifier.deliver(mail)
  69 + #
  70 + # You never instantiate your mailer class. Rather, your delivery instance
  71 + # methods are automatically wrapped in class methods that start with the word
  72 + # <tt>deliver_</tt> followed by the name of the mailer method that you would
  73 + # like to deliver. The <tt>signup_notification</tt> method defined above is
  74 + # delivered by invoking <tt>Notifier.deliver_signup_notification</tt>.
  75 + #
  76 + # = HTML Email
  77 + # To send mail as HTML, make sure your view (the <tt>.rhtml</tt> file) generates HTML and
  78 + # set the content type to html.
  79 + #
  80 + # class MyMailer < ActionMailer::Base
14 81 # def signup_notification(recipient)
15 82 # recipients recipient.email_address_with_name
16 83 # subject "New account information"
17 84 # body "account" => recipient
18 85 # from "system@example.com"
  86 + # content_type "text/html" # Here's where the magic happens
19 87 # end
  88 + # end
  89 + #
  90 + # = Multipart Email
  91 + # You can explicitly specify multipart messages:
20 92 #
21   - # # explicitly specify multipart messages
  93 + # class ApplicationMailer < ActionMailer::Base
22 94 # def signup_notification(recipient)
23 95 # recipients recipient.email_address_with_name
24 96 # subject "New account information"
@@ -32,7 +104,28 @@ module ActionMailer #:nodoc:
32 104 # p.transfer_encoding = "base64"
33 105 # end
34 106 # end
  107 + # end
  108 + #
  109 + # Multipart messages can also be used implicitly because ActionMailer will automatically
  110 + # detect and use multipart templates, where each template is named after the name of the action, followed
  111 + # by the content type. Each such detected template will be added as separate part to the message.
  112 + #
  113 + # For example, if the following templates existed:
  114 + # * signup_notification.text.plain.rhtml
  115 + # * signup_notification.text.html.rhtml
  116 + # * signup_notification.text.xml.rxml
  117 + # * signup_notification.text.x-yaml.rhtml
  118 + #
  119 + # Each would be rendered and added as a separate part to the message,
  120 + # with the corresponding content type. The same body hash is passed to
  121 + # each template.
35 122 #
  123 + # = Attachments
  124 + # Attachments can be added by using the +attachment+ method.
  125 + #
  126 + # Example:
  127 + #
  128 + # class ApplicationMailer < ActionMailer::Base
36 129 # # attachments
37 130 # def signup_notification(recipient)
38 131 # recipients recipient.email_address_with_name
@@ -46,36 +139,7 @@ module ActionMailer #:nodoc:
46 139 # a.body = generate_your_pdf_here()
47 140 # end
48 141 # end
49   - #
50   - # # implicitly multipart messages
51   - # def signup_notification(recipient)
52   - # recipients recipient.email_address_with_name
53   - # subject "New account information"
54   - # from "system@example.com"
55   - # body(:account => "recipient")
56   - #
57   - # # ActionMailer will automatically detect and use multipart templates,
58   - # # where each template is named after the name of the action, followed
59   - # # by the content type. Each such detected template will be added as
60   - # # a separate part to the message.
61   - # #
62   - # # for example, if the following templates existed:
63   - # # * signup_notification.text.plain.rhtml
64   - # # * signup_notification.text.html.rhtml
65   - # # * signup_notification.text.xml.rxml
66   - # # * signup_notification.text.x-yaml.rhtml
67   - # #
68   - # # Each would be rendered and added as a separate part to the message,
69   - # # with the corresponding content type. The same body hash is passed to
70   - # # each template.
71   - # end
72   - # end
73   - #
74   - # # After this, post_notification will look for "templates/application_mailer/post_notification.rhtml"
75   - # ApplicationMailer.template_root = "templates"
76   - #
77   - # ApplicationMailer.create_comment_notification(david, hello_world) # => a tmail object
78   - # ApplicationMailer.deliver_comment_notification(david, hello_world) # sends the email
  142 + # end
79 143 #
80 144 # = Configuration options
81 145 #

0 comments on commit 4874df1

Please sign in to comment.
Something went wrong with that request. Please try again.