Permalink
Browse files

Merge documentation changes from docrails.

commit 0fc3381
Author: Xavier Noria <fxn@hashref.com>
Date:   Fri May 16 23:44:51 2008 +0200

    Conventions. Formatting. Revising docs all over the rails.

    This revision encourages the modern resource-oriented form_for usage. In addition corrects some markup and other details.

commit 70e4bcf
Author: Chris Kampmeier <chris@kampers.net>
Date:   Fri May 16 12:09:46 2008 -0700

    Fix a couple spelling errors in docs

commit 6ea5e42
Author: Chris O'Sullivan <thechrisoshow@gmail.com>
Date:   Fri May 16 16:09:11 2008 +0100

    Added docs about source_type for has_one association

commit a01a017
Author: miloops <miloops@gmail.com>
Date:   Wed May 14 09:22:39 2008 +0000

    Change migration generator USAGE to explain the timestamped migrations behaviour

commit 4e2bc02
Author: Xavier Noria <fxn@hashref.com>
Date:   Fri May 16 00:43:03 2008 +0200

    minor revision in url_for docs

    Made explicit that RESTful and controller/action styles are not interchangeable, and revised some markup.

commit d6ecce6
Author: Michael Hartl <michael@michaelhartl.com>
Date:   Thu May 15 10:46:40 2008 -0700

    Expanded and updated the link_to documentation

commit b8c46c8
Author: Cody Fauser <cody@jadedpixel.com>
Date:   Wed May 14 09:10:02 2008 -0400

    Improve and cleanup ActionMailer documentation

commit 9546ee2
Author: Yehuda Katz <wycats@gmail.com>
Date:   Mon May 12 23:41:43 2008 -0700

    Add documentation for Inflector.inflections

commit cbd5db8
Author: Manik Juneja <mjuneja@manik-junejas-computer.local>
Date:   Mon May 12 23:43:31 2008 +0530

    minor changes in railties/README. Added dbconsole introduction

commit 130a280
Author: Gaurav Sharma <gaurav@norbauer.com>
Date:   Mon May 12 18:00:19 2008 +0530

    adding documentation for cached_attributes

commit 164c958
Author: TomK32 <tomk32@tomk32.de>
Date:   Mon May 12 10:59:33 2008 +0200

    proper heading for "Example:"

commit 35634fe
Author: Matt Boehlig <thetamind@gmail.com>
Date:   Sun May 11 16:46:07 2008 -0500

    Cleanup whitespace and change_table documentation

commit 80bba28
Author: Xavier Noria <fxn@hashref.com>
Date:   Sun May 11 02:54:02 2008 +0200

    documented the source annotation extractor

commit e6823bb
Author: Mike Mondragon <mikemondragon@gmail.com>
Date:   Fri May 9 13:49:56 2008 -0700

    Added additional information about processing email with ActionMailer and the strategy one might want to employ to do so.

commit e6afd8b
Author: Xavier Noria <fxn@hashref.com>
Date:   Thu May 8 23:49:36 2008 +0200

    corrected and completed docs of increment/decrement/toggle in AR::Base

commit 2fead68
Author: Austin Putman <austin@emmanuel.local>
Date:   Wed May 7 19:35:46 2008 -0700

    Documented class methods on ActionController::Routing.  These are dangerous, and mostly used for testing.

commit f5b8418
Author: Teflon Ted <github@rudiment.net>
Date:   Wed May 7 16:08:49 2008 -0400

    Added explanation about errant inflections not being patched in the future in order to avoid breaking legacy applications.

commit 370f4f5
Author: Sunny Ripert <negatif@gmail.com>
Date:   Wed May 7 14:00:59 2008 +0200

    Applied list conventions in AR::Base

commit 5bd1842
Author: Sunny Ripert <negatif@gmail.com>
Date:   Wed May 7 13:53:35 2008 +0200

    Renamed Options list to Attributes list whenever they weren't option hashes in AR::Base

commit 2fa628e
Author: Xavier Noria <fxn@hashref.com>
Date:   Wed May 7 11:52:33 2008 +0200

    revised details in Exceptions section of AR::Base docs

commit d912bd5
Author: Yaroslav Markin <yaroslav@markin.net>
Date:   Wed May 7 13:50:28 2008 +0400

    Add a filter_parameter_logging usage hint to generated ApplicationController.
    This may help to remind the developer to filter sensitive information from application logs.
    Closes #11578

commit f81d771
Author: Jack Danger Canty <git@6brand.com>
Date:   Tue May 6 23:35:05 2008 -0700

    doc: ActiveRecord::Reflection::AssociationReflection#through_reflection

    Added documentation demonstrating the use of #through_reflection for
    finding intervening reflection objects for HasManyThrough
    and HasOneThrough.

commit ae6b46f
Author: Cheah Chu Yeow <chuyeow@gmail.com>
Date:   Wed May 7 13:47:41 2008 +0800

    Document AttributeAssignmentError and MultiparameterAssignmentErrors.

commit 8f46355
Author: John Barnette <jbarnette@gmail.com>
Date:   Tue May 6 22:46:44 2008 -0700

    Killing/fixing a bunch of outdated language in the AR README.

commit 284a930
Author: Jonathan Dance <jd@wuputah.com>
Date:   Tue May 6 14:58:26 2008 -0400

    improvements to the page caching docs

commit 9482da6
Author: Sunny Ripert <negatif@gmail.com>
Date:   Mon May 5 18:13:40 2008 +0200

    validates_numericality_of() "integer" option really is "only_integer"

commit e9afd67
Author: Sunny Ripert <negatif@gmail.com>
Date:   Mon May 5 12:11:59 2008 +0200

    Harmonized hash notation in AR::Base

commit 67ebf14
Author: Sunny Ripert <negatif@gmail.com>
Date:   Mon May 5 12:06:19 2008 +0200

    Turned options into rdoc-lists in AR::Base

commit 0ec7c0a
Author: Marshall Huss <mwhuss@Macbook.local>
Date:   Sun May 4 23:21:33 2008 -0400

    Added information of how to set element_name in the case the user has a name confliction with an existing model

Signed-off-by: Pratik Naik <pratiknaik@gmail.com>
  • Loading branch information...
lifo committed May 16, 2008
1 parent 345f030 commit 46f30f902fb5e705683dea19ec22179c61e5f208
View
@@ -19,8 +19,7 @@ are all set up this way. An example of such a method:
recipients recipient
subject "[Signed up] Welcome #{recipient}"
from "system@loudthinking.com"
-
- body(:recipient => recipient)
+ body :recipient => recipient
end
The body of the email is created by using an Action View template (regular
@@ -78,21 +77,26 @@ Example:
end
end
-This Mailman can be the target for Postfix. In Rails, you would use the runner like this:
+This Mailman can be the target for Postfix or other MTAs. In Rails, you would use the runner in the
+trivial case like this:
./script/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
-}
+ 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
@@ -35,7 +35,7 @@ module ActionMailer #:nodoc:
# * <tt>subject</tt> - The subject of your email. Sets the <tt>Subject:</tt> header.
# * <tt>from</tt> - Who the email you are sending is from. Sets the <tt>From:</tt> header.
# * <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.
- # * <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.
+ # * <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.
# * <tt>sent_on</tt> - The date on which the message was sent. If not set, the header wil be set by the delivery agent.
# * <tt>content_type</tt> - Specify the content type of the message. Defaults to <tt>text/plain</tt>.
# * <tt>headers</tt> - Specify additional headers to be set for the message, e.g. <tt>headers 'X-Mail-Count' => 107370</tt>.
@@ -127,11 +127,11 @@ module ActionMailer #:nodoc:
#
# class MyMailer < ActionMailer::Base
# def signup_notification(recipient)
- # recipients recipient.email_address_with_name
- # subject "New account information"
- # body "account" => recipient
- # from "system@example.com"
- # content_type "text/html" # Here's where the magic happens
+ # recipients recipient.email_address_with_name
+ # subject "New account information"
+ # from "system@example.com"
+ # body :account => recipient
+ # content_type "text/html"
# end
# end
#
@@ -145,6 +145,7 @@ module ActionMailer #:nodoc:
# recipients recipient.email_address_with_name
# subject "New account information"
# from "system@example.com"
+ # content_type "multipart/alternative"
#
# part :content_type => "text/html",
# :body => render_message("signup-as-html", :account => recipient)
@@ -167,9 +168,14 @@ module ActionMailer #:nodoc:
# * signup_notification.text.x-yaml.erb
#
# Each would be rendered and added as a separate part to the message,
- # with the corresponding content type. The same body hash is passed to
- # each template.
+ # with the corresponding content type. The content type for the entire
+ # message is automatically set to <tt>multipart/alternative</tt>, which indicates
+ # that the email contains multiple different representations of the same email
+ # body. The same body hash is passed to each template.
#
+ # Implicit template rendering is not performed if any attachments or parts have been added to the email.
+ # This means that you'll have to manually add each part to the email and set the content type of the email
+ # to <tt>multipart/alternative</tt>.
#
# = Attachments
#
@@ -209,12 +215,12 @@ module ActionMailer #:nodoc:
# * <tt>:domain</tt> - If you need to specify a HELO domain, you can do it here.
# * <tt>:user_name</tt> - If your mail server requires authentication, set the username in this setting.
# * <tt>:password</tt> - If your mail server requires authentication, set the password in this setting.
- # * <tt>:authentication</tt> - If your mail server requires authentication, you need to specify the authentication type here.
- # This is a symbol and one of <tt>:plain</tt>, <tt>:login</tt>, <tt>:cram_md5</tt>
+ # * <tt>:authentication</tt> - If your mail server requires authentication, you need to specify the authentication type here.
+ # This is a symbol and one of <tt>:plain</tt>, <tt>:login</tt>, <tt>:cram_md5</tt>.
#
- # * <tt>sendmail_settings</tt> - Allows you to override options for the <tt>:sendmail</tt> delivery method
- # * <tt>:location</tt> - The location of the sendmail executable, defaults to "/usr/sbin/sendmail"
- # * <tt>:arguments</tt> - The command line arguments
+ # * <tt>sendmail_settings</tt> - Allows you to override options for the <tt>:sendmail</tt> delivery method.
+ # * <tt>:location</tt> - The location of the sendmail executable. Defaults to <tt>/usr/sbin/sendmail</tt>.
+ # * <tt>:arguments</tt> - The command line arguments. Defaults to <tt>-i -t</tt>.
#
# * <tt>raise_delivery_errors</tt> - Whether or not errors should be raised if the email fails to be delivered.
#
@@ -226,17 +232,17 @@ module ActionMailer #:nodoc:
# * <tt>deliveries</tt> - Keeps an array of all the emails sent out through the Action Mailer with <tt>delivery_method :test</tt>. Most useful
# for unit and functional testing.
#
- # * <tt>default_charset</tt> - The default charset used for the body and to encode the subject. Defaults to UTF-8. You can also
- # pick a different charset from inside a method with <tt>@charset</tt>.
+ # * <tt>default_charset</tt> - The default charset used for the body and to encode the subject. Defaults to UTF-8. You can also
+ # pick a different charset from inside a method with +charset+.
# * <tt>default_content_type</tt> - The default content type used for the main part of the message. Defaults to "text/plain". You
- # can also pick a different content type from inside a method with <tt>@content_type</tt>.
- # * <tt>default_mime_version</tt> - The default mime version used for the message. Defaults to "1.0". You
- # can also pick a different value from inside a method with <tt>@mime_version</tt>.
+ # can also pick a different content type from inside a method with +content_type+.
+ # * <tt>default_mime_version</tt> - The default mime version used for the message. Defaults to <tt>1.0</tt>. You
+ # can also pick a different value from inside a method with +mime_version+.
# * <tt>default_implicit_parts_order</tt> - When a message is built implicitly (i.e. multiple parts are assembled from templates
# which specify the content type in their filenames) this variable controls how the parts are ordered. Defaults to
- # ["text/html", "text/enriched", "text/plain"]. Items that appear first in the array have higher priority in the mail client
+ # <tt>["text/html", "text/enriched", "text/plain"]</tt>. Items that appear first in the array have higher priority in the mail client
# and appear last in the mime encoded message. You can also pick a different order from inside a method with
- # <tt>@implicit_parts_order</tt>.
+ # +implicit_parts_order+.
class Base
include AdvAttrAccessor, PartContainer
include ActionController::UrlWriter if Object.const_defined?(:ActionController)
@@ -92,7 +92,7 @@ module InstanceMethods
# with the remaining data.
#
# Note that you can define your own XML parameter parser which would allow you to describe multiple entities
- # in a single request (i.e., by wrapping them all in a single root note), but if you just go with the flow
+ # in a single request (i.e., by wrapping them all in a single root node), but if you just go with the flow
# and accept Rails' defaults, life will be much easier.
#
# If you need to use a MIME type which isn't supported by default, you can register your own handlers in
@@ -73,30 +73,54 @@ module Helpers
# There are also methods for helping to build form tags in link:classes/ActionView/Helpers/FormOptionsHelper.html,
# link:classes/ActionView/Helpers/DateHelper.html, and link:classes/ActionView/Helpers/ActiveRecordHelper.html
module FormHelper
- # Creates a form and a scope around a specific model object that is used as a base for questioning about
- # values for the fields.
+ # Creates a form and a scope around a specific model object that is used as
+ # a base for questioning about values for the fields.
#
- # <% form_for :person, @person, :url => { :action => "update" } do |f| %>
- # <%= f.error_messages %>
- # First name: <%= f.text_field :first_name %>
- # Last name : <%= f.text_field :last_name %>
- # Biography : <%= f.text_area :biography %>
- # Admin? : <%= f.check_box :admin %>
+ # Rails provides succint resource-oriented form generation with +form_for+
+ # like this:
+ #
+ # <% form_for @offer do |f| %>
+ # <%= f.label :version, 'Version' %>:
+ # <%= f.text_field :version %><br />
+ # <%= f.label :author, 'Author' %>:
+ # <%= f.text_field :author %><br />
# <% end %>
#
- # Worth noting is that the form_for tag is called in a ERb evaluation block, not an ERb output block. So that's <tt><% %></tt>,
- # not <tt><%= %></tt>. Also worth noting is that form_for yields a <tt>form_builder</tt> object, in this example as <tt>f</tt>, which emulates
- # the API for the stand-alone FormHelper methods, but without the object name. So instead of <tt>text_field :person, :name</tt>,
- # you get away with <tt>f.text_field :name</tt>. Notice that you can even do <tt><%= f.error_messages %></tt> to display the
- # error messsages of the model object in question.
+ # There, +form_for+ is able to generate the rest of RESTful parameters
+ # based on introspection on the record, but to understand what it does we
+ # need to dig first into the alternative generic usage it is based upon.
+ #
+ # === Generic form_for
#
- # Even further, the form_for method allows you to more easily escape the instance variable convention. So while the stand-alone
- # approach would require <tt>text_field :person, :name, :object => person</tt>
- # to work with local variables instead of instance ones, the form_for calls remain the same. You simply declare once with
- # <tt>:person, person</tt> and all subsequent field calls save <tt>:person</tt> and <tt>:object => person</tt>.
+ # The generic way to call +form_for+ requires a few arguments:
#
- # Also note that form_for doesn't create an exclusive scope. It's still possible to use both the stand-alone FormHelper methods
- # and methods from FormTagHelper. For example:
+ # <% form_for :person, @person, :url => { :action => "update" } do |f| %>
+ # <%= f.error_messages %>
+ # First name: <%= f.text_field :first_name %><br />
+ # Last name : <%= f.text_field :last_name %><br />
+ # Biography : <%= f.text_area :biography %><br />
+ # Admin? : <%= f.check_box :admin %><br />
+ # <% end %>
+ #
+ # Worth noting is that the +form_for+ tag is called in a ERb evaluation block,
+ # not an ERb output block. So that's <tt><% %></tt>, not <tt><%= %></tt>. Also
+ # worth noting is that +form_for+ yields a form builder object, in this
+ # example as +f+, which emulates the API for the stand-alone FormHelper
+ # methods, but without the object name. So instead of <tt>text_field :person, :name</tt>,
+ # you get away with <tt>f.text_field :name</tt>. Notice that you can even do
+ # <tt><%= f.error_messages %></tt> to display the error messsages of the model
+ # object in question.
+ #
+ # Even further, the +form_for+ method allows you to more easily escape the
+ # instance variable convention. So while the stand-alone approach would require
+ # <tt>text_field :person, :name, :object => person</tt> to work with local
+ # variables instead of instance ones, the +form_for+ calls remain the same.
+ # You simply declare once with <tt>:person, person</tt> and all subsequent
+ # field calls save <tt>:person</tt> and <tt>:object => person</tt>.
+ #
+ # Also note that +form_for+ doesn't create an exclusive scope. It's still
+ # possible to use both the stand-alone FormHelper methods and methods from
+ # FormTagHelper. For example:
#
# <% form_for :person, @person, :url => { :action => "update" } do |f| %>
# First name: <%= f.text_field :first_name %>
@@ -105,22 +129,26 @@ module FormHelper
# Admin? : <%= check_box_tag "person[admin]", @person.company.admin? %>
# <% end %>
#
- # Note: This also works for the methods in FormOptionHelper and DateHelper that are designed to work with an object as base,
- # like FormOptionHelper#collection_select and DateHelper#datetime_select.
+ # This also works for the methods in FormOptionHelper and DateHelper that are
+ # designed to work with an object as base, like FormOptionHelper#collection_select
+ # and DateHelper#datetime_select.
#
- # HTML attributes for the form tag can be given as <tt>:html => {...}</tt>. For example:
+ # HTML attributes for the form tag can be given as <tt>:html => {...}</tt>.
+ # For example:
#
# <% form_for :person, @person, :html => {:id => 'person_form'} do |f| %>
# ...
# <% end %>
#
- # The above form will then have the <tt>id</tt> attribute with the value </tt>person_form</tt>, which you can then
- # style with CSS or manipulate with JavaScript.
+ # The above form will then have the +id+ attribute with the value "person_form",
+ # which you can then style with CSS or manipulate with JavaScript.
#
# === Relying on record identification
#
- # In addition to manually configuring the form_for call, you can also rely on record identification, which will use
- # the conventions and named routes of that approach. Examples:
+ # As we said above, in addition to manually configuring the +form_for+ call,
+ # you can rely on record identification, which will use the conventions and
+ # named routes of that approach. This is the preferred way to use +form_for+
+ # nowadays:
#
# <% form_for(@post) do |f| %>
# ...
@@ -140,7 +168,7 @@ module FormHelper
#
# This will expand to be the same as:
#
- # <% form_for :post, @post, :url => posts_path, :html => { :class => "new_post", :id => "new_post" } do |f| %>
+ # <% form_for :post, Post.new, :url => posts_path, :html => { :class => "new_post", :id => "new_post" } do |f| %>
# ...
# <% end %>
#
@@ -150,7 +178,7 @@ module FormHelper
# ...
# <% end %>
#
- # And for namespaced routes, like admin_post_url:
+ # And for namespaced routes, like +admin_post_url+:
#
# <% form_for([:admin, @post]) do |f| %>
# ...
Oops, something went wrong.

0 comments on commit 46f30f9

Please sign in to comment.