Ruby on Rails | Screencasts | Download | Documentation | Weblog | Community | Source

Changeset 4732

Show
Ignore:
Timestamp:
08/08/06 23:37:59 (2 years ago)
Author:
nzkoz
Message:

backport of ActionMailer documentation enhancements from trunk

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • branches/stable/actionmailer/CHANGELOG

    r4708 r4732  
    11*SVN* 
     2 
     3* Backport of documentation enhancements. [Kevin Clark, Marcel Molina Jr] 
    24 
    35* Correct spurious documentation example code which results in a SyntaxError. [Marcel Molina Jr.] 

  • branches/stable/actionmailer/lib/action_mailer/base.rb

    r4708 r4732  
    66 
    77module ActionMailer #:nodoc: 
    8   # Usage: 
    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"). 
     8  # ActionMailer allows you to send email from your application using a mailer model and views. 
     9  # 
     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 
    1481  #     def signup_notification(recipient) 
    1582  #       recipients recipient.email_address_with_name 
    …… 
    1784  #       body       "account" => recipient 
    1885  #       from       "system@example.com" 
     86  #       content_type "text/html"   #    Here's where the magic happens 
    1987  #     end 
    20   # 
    21   #     # explicitly specify multipart messages 
     88  #   end   
     89  # 
     90  # = Multipart Email 
     91  # You can explicitly specify multipart messages: 
     92  # 
     93  #   class ApplicationMailer < ActionMailer::Base 
    2294  #     def signup_notification(recipient) 
    2395  #       recipients      recipient.email_address_with_name 
    …… 
    33105  #       end 
    34106  #     end 
    35   # 
     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. 
     122  # 
     123  # = Attachments 
     124  # Attachments can be added by using the +attachment+ method. 
     125  # 
     126  # Example: 
     127  # 
     128  #   class ApplicationMailer < ActionMailer::Base 
    36129  #     # attachments 
    37130  #     def signup_notification(recipient) 
    …… 
    47140  #       end 
    48141  #     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  
    79143  # 
    80144  # = Configuration options