From 59f1df1b5b37a9e16a6b03d931c7b620075034d5 Mon Sep 17 00:00:00 2001 From: Jamis Buck Date: Sun, 16 Oct 2005 15:00:27 +0000 Subject: Update/extend ActionMailer documentation (rdoc) git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@2648 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- actionmailer/lib/action_mailer/base.rb | 75 +++++++++++++++++++++--- actionmailer/lib/action_mailer/helpers.rb | 6 +- actionmailer/lib/action_mailer/mail_helper.rb | 4 +- actionmailer/lib/action_mailer/part.rb | 38 +++++++++++- actionmailer/lib/action_mailer/part_container.rb | 19 +++++- actionmailer/lib/action_mailer/version.rb | 2 +- 6 files changed, 128 insertions(+), 16 deletions(-) (limited to 'actionmailer/lib/action_mailer') diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb index 699714c78f..a77f9ce018 100644 --- a/actionmailer/lib/action_mailer/base.rb +++ b/actionmailer/lib/action_mailer/base.rb @@ -4,7 +4,7 @@ require 'action_mailer/part_container' require 'action_mailer/utils' require 'tmail/net' -module ActionMailer #:nodoc: +module ActionMailer # Usage: # # class ApplicationMailer < ActionMailer::Base @@ -160,11 +160,61 @@ module ActionMailer #:nodoc: @@default_implicit_parts_order = [ "text/html", "text/enriched", "text/plain" ] cattr_accessor :default_implicit_parts_order - adv_attr_accessor :recipients, :subject, :body, :from, :sent_on, :headers, - :bcc, :cc, :charset, :content_type, :implicit_parts_order, - :template, :mailer_name, :mime_version + # Specify the BCC addresses for the message + adv_attr_accessor :bcc + + # Define the body of the message. This is either a Hash (in which case it + # specifies the variables to pass to the template when it is rendered), + # or a string, in which case it specifies the actual text of the message. + adv_attr_accessor :body + + # Specify the CC addresses for the message. + adv_attr_accessor :cc + + # Specify the charset to use for the message. This defaults to the + # +default_charset+ specified for ActionMailer::Base. + adv_attr_accessor :charset + + # Specify the content type for the message. This defaults to text/plain + # in most cases, but can be automatically set in some situations. + adv_attr_accessor :content_type + + # Specify the from address for the message. + adv_attr_accessor :from + + # Specify additional headers to be added to the message. + adv_attr_accessor :headers + + # Specify the order in which parts should be sorted, based on content-type. + # This defaults to the value for the +default_implicit_parts_order+. + adv_attr_accessor :implicit_parts_order + + # Override the mailer name, which defaults to an inflected version of the + # mailer's class name. If you want to use a template in a non-standard + # location, you can use this to specify that location. + adv_attr_accessor :mailer_name + + # Defaults to "1.0", but may be explicitly given if needed. + adv_attr_accessor :mime_version + + # The recipient addresses for the message, either as a string (for a single + # address) or an array (for multiple addresses). + adv_attr_accessor :recipients + + # The date on which the message was sent. If not set (the default), the + # header will be set by the delivery agent. + adv_attr_accessor :sent_on + + # Specify the subject of the message. + adv_attr_accessor :subject + + # Specify the template name to use for current message. This is the "base" + # template name, without the extension or directory, and may be used to + # have multiple mailer methods share the same template. + adv_attr_accessor :template - attr_reader :mail + # The mail object instance referenced by this mailer. + attr_reader :mail class << self def method_missing(method_symbol, *parameters)#:nodoc: @@ -176,7 +226,18 @@ module ActionMailer #:nodoc: end end - def receive(raw_email) #:nodoc: + # Receives a raw email, parses it into an email object, decodes it, + # instantiates a new mailer, and passes the email object to the mailer + # object's #receive method. If you want your mailer to be able to + # process incoming messages, you'll need to implement a #receive + # method that accepts the email object as a parameter: + # + # class MyMailer < ActionMailer::Base + # def receive(mail) + # ... + # end + # end + def receive(raw_email) logger.info "Received mail:\n #{raw_email}" unless logger.nil? mail = TMail::Mail.parse(raw_email) mail.base64_decode @@ -258,7 +319,7 @@ module ActionMailer #:nodoc: # Delivers a TMail::Mail object. By default, it delivers the cached mail # object (from the #create! method). If no cached mail object exists, and # no alternate has been given as the parameter, this will fail. - def deliver!(mail = @mail) #:nodoc: + def deliver!(mail = @mail) raise "no mail object available for delivery!" unless mail logger.info "Sent mail:\n #{mail.encoded}" unless logger.nil? diff --git a/actionmailer/lib/action_mailer/helpers.rb b/actionmailer/lib/action_mailer/helpers.rb index f482758386..b53326ca72 100644 --- a/actionmailer/lib/action_mailer/helpers.rb +++ b/actionmailer/lib/action_mailer/helpers.rb @@ -1,6 +1,6 @@ -module ActionMailer #:nodoc: +module ActionMailer module Helpers #:nodoc: - def self.append_features(base) + def self.append_features(base) #:nodoc: super # Initialize the base module to aggregate its helpers. @@ -24,7 +24,7 @@ module ActionMailer #:nodoc: end end - module ClassMethods #:nodoc: + module ClassMethods # Makes all the (instance) methods in the helper module available to templates rendered through this controller. # See ActionView::Helpers (link:classes/ActionView/Helpers.html) for more about making your own helper modules # available to the templates. diff --git a/actionmailer/lib/action_mailer/mail_helper.rb b/actionmailer/lib/action_mailer/mail_helper.rb index 9c7370065f..11fd7d77e0 100644 --- a/actionmailer/lib/action_mailer/mail_helper.rb +++ b/actionmailer/lib/action_mailer/mail_helper.rb @@ -1,6 +1,8 @@ require 'text/format' -module MailHelper#:nodoc: +module MailHelper + # Uses Text::Format to take the text and format it, indented two spaces for + # each line, and wrapped at 72 columns. def block_format(text) formatted = text.split(/\n\r\n/).collect { |paragraph| Text::Format.new( diff --git a/actionmailer/lib/action_mailer/part.rb b/actionmailer/lib/action_mailer/part.rb index d4b8e3b9d9..0036d04da0 100644 --- a/actionmailer/lib/action_mailer/part.rb +++ b/actionmailer/lib/action_mailer/part.rb @@ -3,13 +3,43 @@ require 'action_mailer/part_container' require 'action_mailer/utils' module ActionMailer - class Part #:nodoc: + # Represents a subpart of an email message. It shares many similar + # attributes of ActionMailer::Base. Although you can create parts manually + # and add them to the #parts list of the mailer, it is easier + # to use the helper methods in ActionMailer::PartContainer. + class Part include ActionMailer::AdvAttrAccessor include ActionMailer::PartContainer - adv_attr_accessor :content_type, :content_disposition, :charset, :body - adv_attr_accessor :filename, :transfer_encoding, :headers + # Represents the body of the part, as a string. This should not be a + # Hash (like ActionMailer::Base), but if you want a template to be rendered + # into the body of a subpart you can do it with the mailer's #render method + # and assign the result here. + adv_attr_accessor :body + + # Specify the charset for this subpart. By default, it will be the charset + # of the containing part or mailer. + adv_attr_accessor :charset + + # The content disposition of this part, typically either "inline" or + # "attachment". + adv_attr_accessor :content_disposition + + # The content type of the part. + adv_attr_accessor :content_type + + # The filename to use for this subpart (usually for attachments). + adv_attr_accessor :filename + + # Accessor for specifying additional headers to include with this part. + adv_attr_accessor :headers + + # The transfer encoding to use for this subpart, like "base64" or + # "quoted-printable". + adv_attr_accessor :transfer_encoding + # Create a new part from the given +params+ hash. The valid params keys + # correspond to the accessors. def initialize(params) @content_type = params[:content_type] @content_disposition = params[:disposition] || "inline" @@ -21,6 +51,8 @@ module ActionMailer @parts = [] end + # Convert the part to a mail object which can be included in the parts + # list of another mail object. def to_mail(defaults) part = TMail::Mail.new diff --git a/actionmailer/lib/action_mailer/part_container.rb b/actionmailer/lib/action_mailer/part_container.rb index 7a69efeb49..9cbdd35497 100644 --- a/actionmailer/lib/action_mailer/part_container.rb +++ b/actionmailer/lib/action_mailer/part_container.rb @@ -1,5 +1,22 @@ module ActionMailer - module PartContainer #:nodoc: + # Accessors and helpers that ActionMailer::Base and ActionMailer::Part have + # in common. Using these helpers you can easily add subparts or attachments + # to your message: + # + # def my_mail_message(...) + # ... + # part "text/plain" do |p| + # p.body "hello, world" + # p.transfer_encoding "base64" + # end + # + # attachment "image/jpg" do |a| + # a.body = File.read("hello.jpg") + # a.filename = "hello.jpg" + # end + # end + module PartContainer + # The list of subparts of this container attr_reader :parts # Add a part to a multipart message, with the given content-type. The diff --git a/actionmailer/lib/action_mailer/version.rb b/actionmailer/lib/action_mailer/version.rb index 557b05f14e..2108ffb282 100644 --- a/actionmailer/lib/action_mailer/version.rb +++ b/actionmailer/lib/action_mailer/version.rb @@ -1,5 +1,5 @@ module ActionMailer - module Version + module Version #:nodoc: MAJOR = 1 MINOR = 0 TINY = 1 -- cgit v1.2.3