From 508fba9e070e09f0a321f2dd7acf7938967468f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Wed, 21 Jul 2010 12:51:14 +0200 Subject: Add .rdoc extension to README files. --- actionmailer/README | 151 ----------------------------------------------- actionmailer/README.rdoc | 151 +++++++++++++++++++++++++++++++++++++++++++++++ actionmailer/Rakefile | 2 +- 3 files changed, 152 insertions(+), 152 deletions(-) delete mode 100644 actionmailer/README create mode 100644 actionmailer/README.rdoc (limited to 'actionmailer') diff --git a/actionmailer/README b/actionmailer/README deleted file mode 100644 index 3dd56a6fd8..0000000000 --- a/actionmailer/README +++ /dev/null @@ -1,151 +0,0 @@ -= Action Mailer -- Easy email delivery and testing - -Action Mailer is a framework for designing email-service layers. These layers -are used to consolidate code for sending out forgotten passwords, welcome -wishes on signup, invoices for billing, and any other use case that requires -a written notification to either a person or another system. - -Action Mailer is in essence a wrapper around Action Controller and the -Mail gem. It provides a way to make emails using templates in the same -way that Action Controller renders views using templates. - -Additionally, an Action Mailer class can be used to process incoming email, -such as allowing a weblog to accept new posts from an email (which could even -have been sent from a phone). - -== Sending emails - -The framework works by initializing any instance variables you want to be -available in the email template, followed by a call to +mail+ to deliver -the email. - -This can be as simple as: - - class Notifier < ActionMailer::Base - delivers_from 'system@loudthinking.com' - - def welcome(recipient) - @recipient = recipient - mail(:to => recipient, - :subject => "[Signed up] Welcome #{recipient}") - end - end - -The body of the email is created by using an Action View template (regular -ERb) that has the instance variables that are declared in the mailer action. - -So the corresponding body template for the method above could look like this: - - Hello there, - - Mr. <%= @recipient %> - - Thank you for signing up! - -And if the recipient was given as "david@loudthinking.com", the email -generated would look like this: - - Date: Mon, 25 Jan 2010 22:48:09 +1100 - From: system@loudthinking.com - To: david@loudthinking.com - Message-ID: <4b5d84f9dd6a5_7380800b81ac29578@void.loudthinking.com.mail> - Subject: [Signed up] Welcome david@loudthinking.com - Mime-Version: 1.0 - Content-Type: text/plain; - charset="US-ASCII"; - Content-Transfer-Encoding: 7bit - - Hello there, - - Mr. david@loudthinking.com - -In previous version of rails you would call create_method_name and -deliver_method_name. Rails 3.0 has a much simpler interface, you -simply call the method and optionally call +deliver+ on the return value. - -Calling the method returns a Mail Message object: - - message = Notifier.welcome #=> Returns a Mail::Message object - message.deliver #=> delivers the email - -Or you can just chain the methods together like: - - Notifier.welcome.deliver # Creates the email and sends it immediately - -== Receiving emails - -To receive emails, you need to implement a public instance method called receive that takes a -tmail object as its single parameter. The Action Mailer framework has a corresponding class method, -which is also called receive, that accepts a raw, unprocessed email as a string, which it then turns -into the tmail object and calls the receive instance method. - -Example: - - class Mailman < ActionMailer::Base - def receive(email) - page = Page.find_by_address(email.to.first) - page.emails.create( - :subject => email.subject, :body => email.body - ) - - if email.has_attachments? - for attachment in email.attachments - page.attachments.create({ - :file => attachment, :description => email.subject - }) - end - end - end - end - -This Mailman can be the target for Postfix or other MTAs. In Rails, you would use the runner in the -trivial case like this: - - rails runner 'Mailman.receive(STDIN.read)' - -However, invoking Rails in the runner for each mail to be received is very resource intensive. A single -instance of Rails should be run within a daemon if it is going to be utilized to process more than just -a limited number of email. - -== Configuration - -The Base class has the full list of configuration options. Here's an example: - - ActionMailer::Base.smtp_settings = { - :address => 'smtp.yourserver.com', # default: localhost - :port => '25', # default: 25 - :user_name => 'user', - :password => 'pass', - :authentication => :plain # :plain, :login or :cram_md5 - } - -== Dependencies - -Action Mailer requires that the Action Pack is either available to be required immediately -or is accessible as a GEM. - -Additionally, Action Mailer requires the Mail gem, http://github.com/mikel/mail - -== Download - -The latest version of Action Mailer can be installed with Rubygems: - -* gem install actionmailer - -Documentation can be found at - -* http://api.rubyonrails.org - -== License - -Action Mailer is released under the MIT license. - -== Support - -The Action Mailer homepage is http://www.rubyonrails.org. You can find -the Action Mailer RubyForge page at http://rubyforge.org/projects/actionmailer. -And as Jim from Rake says: - - Feel free to submit commits or feature requests. If you send a patch, - remember to update the corresponding unit tests. If fact, I prefer - new feature to be submitted in the form of new unit tests. diff --git a/actionmailer/README.rdoc b/actionmailer/README.rdoc new file mode 100644 index 0000000000..3dd56a6fd8 --- /dev/null +++ b/actionmailer/README.rdoc @@ -0,0 +1,151 @@ += Action Mailer -- Easy email delivery and testing + +Action Mailer is a framework for designing email-service layers. These layers +are used to consolidate code for sending out forgotten passwords, welcome +wishes on signup, invoices for billing, and any other use case that requires +a written notification to either a person or another system. + +Action Mailer is in essence a wrapper around Action Controller and the +Mail gem. It provides a way to make emails using templates in the same +way that Action Controller renders views using templates. + +Additionally, an Action Mailer class can be used to process incoming email, +such as allowing a weblog to accept new posts from an email (which could even +have been sent from a phone). + +== Sending emails + +The framework works by initializing any instance variables you want to be +available in the email template, followed by a call to +mail+ to deliver +the email. + +This can be as simple as: + + class Notifier < ActionMailer::Base + delivers_from 'system@loudthinking.com' + + def welcome(recipient) + @recipient = recipient + mail(:to => recipient, + :subject => "[Signed up] Welcome #{recipient}") + end + end + +The body of the email is created by using an Action View template (regular +ERb) that has the instance variables that are declared in the mailer action. + +So the corresponding body template for the method above could look like this: + + Hello there, + + Mr. <%= @recipient %> + + Thank you for signing up! + +And if the recipient was given as "david@loudthinking.com", the email +generated would look like this: + + Date: Mon, 25 Jan 2010 22:48:09 +1100 + From: system@loudthinking.com + To: david@loudthinking.com + Message-ID: <4b5d84f9dd6a5_7380800b81ac29578@void.loudthinking.com.mail> + Subject: [Signed up] Welcome david@loudthinking.com + Mime-Version: 1.0 + Content-Type: text/plain; + charset="US-ASCII"; + Content-Transfer-Encoding: 7bit + + Hello there, + + Mr. david@loudthinking.com + +In previous version of rails you would call create_method_name and +deliver_method_name. Rails 3.0 has a much simpler interface, you +simply call the method and optionally call +deliver+ on the return value. + +Calling the method returns a Mail Message object: + + message = Notifier.welcome #=> Returns a Mail::Message object + message.deliver #=> delivers the email + +Or you can just chain the methods together like: + + Notifier.welcome.deliver # Creates the email and sends it immediately + +== Receiving emails + +To receive emails, you need to implement a public instance method called receive that takes a +tmail object as its single parameter. The Action Mailer framework has a corresponding class method, +which is also called receive, that accepts a raw, unprocessed email as a string, which it then turns +into the tmail object and calls the receive instance method. + +Example: + + class Mailman < ActionMailer::Base + def receive(email) + page = Page.find_by_address(email.to.first) + page.emails.create( + :subject => email.subject, :body => email.body + ) + + if email.has_attachments? + for attachment in email.attachments + page.attachments.create({ + :file => attachment, :description => email.subject + }) + end + end + end + end + +This Mailman can be the target for Postfix or other MTAs. In Rails, you would use the runner in the +trivial case like this: + + rails runner 'Mailman.receive(STDIN.read)' + +However, invoking Rails in the runner for each mail to be received is very resource intensive. A single +instance of Rails should be run within a daemon if it is going to be utilized to process more than just +a limited number of email. + +== Configuration + +The Base class has the full list of configuration options. Here's an example: + + ActionMailer::Base.smtp_settings = { + :address => 'smtp.yourserver.com', # default: localhost + :port => '25', # default: 25 + :user_name => 'user', + :password => 'pass', + :authentication => :plain # :plain, :login or :cram_md5 + } + +== Dependencies + +Action Mailer requires that the Action Pack is either available to be required immediately +or is accessible as a GEM. + +Additionally, Action Mailer requires the Mail gem, http://github.com/mikel/mail + +== Download + +The latest version of Action Mailer can be installed with Rubygems: + +* gem install actionmailer + +Documentation can be found at + +* http://api.rubyonrails.org + +== License + +Action Mailer is released under the MIT license. + +== Support + +The Action Mailer homepage is http://www.rubyonrails.org. You can find +the Action Mailer RubyForge page at http://rubyforge.org/projects/actionmailer. +And as Jim from Rake says: + + Feel free to submit commits or feature requests. If you send a patch, + remember to update the corresponding unit tests. If fact, I prefer + new feature to be submitted in the form of new unit tests. diff --git a/actionmailer/Rakefile b/actionmailer/Rakefile index f20e7ea928..98aeae9818 100644 --- a/actionmailer/Rakefile +++ b/actionmailer/Rakefile @@ -32,7 +32,7 @@ Rake::RDocTask.new { |rdoc| rdoc.options << '--line-numbers' << '--inline-source' << '-A cattr_accessor=object' rdoc.options << '--charset' << 'utf-8' rdoc.template = ENV['template'] ? "#{ENV['template']}.rb" : '../doc/template/horo' - rdoc.rdoc_files.include('README', 'CHANGELOG') + rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG') rdoc.rdoc_files.include('lib/action_mailer.rb') rdoc.rdoc_files.include('lib/action_mailer/*.rb') rdoc.rdoc_files.include('lib/action_mailer/delivery_method/*.rb') -- cgit v1.2.3