Skip to content
This repository
Browse code

ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, …

…Marcel Molina Jr.]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@4332 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
commit 0a407bca505db3116eb9ff71022022a14300ee47 1 parent 5a960d2
authored May 10, 2006
2  actionmailer/CHANGELOG
... ...
@@ -1,5 +1,7 @@
1 1
 *SVN*
2 2
 
  3
+* ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Marcel Molina Jr.]
  4
+
3 5
 * Replace alias method chaining with Module#alias_method_chain. [Marcel Molina Jr.] 
4 6
 
5 7
 * Replace Ruby's deprecated append_features in favor of included. [Marcel Molina Jr.]
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 notes on commit 0a407bc

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