Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Update/extend ActionMailer documentation (rdoc)

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@2648 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
commit 59f1df1b5b37a9e16a6b03d931c7b620075034d5 1 parent 0453525
@jamis jamis authored
View
2  actionmailer/CHANGELOG
@@ -1,5 +1,7 @@
*SVN*
+* Update and extend documentation (rdoc)
+
* Minero Aoki made TMail available to Rails/ActionMailer under the MIT license (instead of LGPL) [RubyConf '05]
* Austin Ziegler made Text::Simple available to Rails/ActionMailer under a MIT-like licens [See rails ML, subject "Text::Format Licence Exception" on Oct 15, 2005]
View
2  actionmailer/Rakefile
@@ -32,7 +32,7 @@ Rake::TestTask.new { |t|
Rake::RDocTask.new { |rdoc|
rdoc.rdoc_dir = 'doc'
rdoc.title = "Action Mailer -- Easy email delivery and testing"
- rdoc.options << '--line-numbers --inline-source --main README'
+ rdoc.options << '--line-numbers --inline-source --main README --accessor adv_attr_accessor=M'
rdoc.template = "#{ENV['template']}.rb" if ENV['template']
rdoc.rdoc_files.include('README', 'CHANGELOG')
rdoc.rdoc_files.include('lib/action_mailer.rb')
View
75 actionmailer/lib/action_mailer/base.rb
@@ -4,7 +4,7 @@
require 'action_mailer/utils'
require 'tmail/net'
-module ActionMailer #:nodoc:
+module ActionMailer
# Usage:
#
# class ApplicationMailer < ActionMailer::Base
@@ -160,11 +160,61 @@ class Base
@@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 <tt>text/plain</tt>
+ # 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 @@ def method_missing(method_symbol, *parameters)#: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 @@ def create!(method_name, *parameters) #: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?
View
6 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 @@ class << self
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.
View
4 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(
View
38 actionmailer/lib/action_mailer/part.rb
@@ -3,13 +3,43 @@
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 @@ def initialize(params)
@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
View
19 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
View
2  actionmailer/lib/action_mailer/version.rb
@@ -1,5 +1,5 @@
module ActionMailer
- module Version
+ module Version #:nodoc:
MAJOR = 1
MINOR = 0
TINY = 1
Please sign in to comment.
Something went wrong with that request. Please try again.