diff options
Diffstat (limited to 'railties')
| -rw-r--r-- | railties/doc/guides/html/configuring.html | 168 | ||||
| -rw-r--r-- | railties/doc/guides/html/form_helpers.html | 590 | ||||
| -rw-r--r-- | railties/doc/guides/html/getting_started_with_rails.html | 366 | ||||
| -rw-r--r-- | railties/doc/guides/html/index.html | 15 | ||||
| -rw-r--r-- | railties/doc/guides/html/layouts_and_rendering.html | 2 | ||||
| -rw-r--r-- | railties/doc/guides/html/routing_outside_in.html | 1011 | ||||
| -rw-r--r-- | railties/doc/guides/source/configuring.txt | 89 | ||||
| -rw-r--r-- | railties/doc/guides/source/getting_started_with_rails.txt | 72 | ||||
| -rw-r--r-- | railties/doc/guides/source/index.txt | 6 | ||||
| -rw-r--r-- | railties/doc/guides/source/layouts_and_rendering.txt | 2 | ||||
| -rw-r--r-- | railties/doc/guides/source/routing_outside_in.txt | 113 |
11 files changed, 1226 insertions, 1208 deletions
diff --git a/railties/doc/guides/html/configuring.html b/railties/doc/guides/html/configuring.html index 3497b09ff9..7b7202b2f4 100644 --- a/railties/doc/guides/html/configuring.html +++ b/railties/doc/guides/html/configuring.html @@ -205,9 +205,6 @@ ul#navMain { <a href="#_using_a_preinitializer">Using a Preinitializer</a> </li> <li> - <a href="#_initialization_process_settings">Initialization Process Settings</a> - </li> - <li> <a href="#_configuring_rails_components">Configuring Rails Components</a> <ul> @@ -259,26 +256,70 @@ Add additional code to be run at application start time </p>
</li>
</ul></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">The first edition of this Guide was written from the Rails 2.3 source code. While the information it contains is broadly applicable to Rails 2.2, backwards compatibility is not guaranteed.</td>
+</tr></table>
+</div>
</div>
</div>
<h2 id="_locations_for_initialization_code">1. Locations for Initialization Code</h2>
<div class="sectionbody">
-<div class="paragraph"><p>preinitializers
-environment.rb first
-env-specific files
-initializers (load_application_initializers)
-after-initializer</p></div>
+<div class="paragraph"><p>Rails offers (at least) five good spots to place initialization code:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Preinitializers
+</p>
+</li>
+<li>
+<p>
+environment.rb
+</p>
+</li>
+<li>
+<p>
+Environment-specific Configuration Files
+</p>
+</li>
+<li>
+<p>
+Initializers (load_application_initializers)
+</p>
+</li>
+<li>
+<p>
+After-Initializers
+</p>
+</li>
+</ul></div>
</div>
<h2 id="_using_a_preinitializer">2. Using a Preinitializer</h2>
<div class="sectionbody">
+<div class="paragraph"><p>Rails allows you to use a preinitializer to run code before the framework itself is loaded. If you save code in <tt>RAILS_ROOT/config/preinitializer.rb</tt>, that code will be the first thing loaded, before any of the framework components (Active Record, Action Pack, and so on.) If you want to change the behavior of one of the classes that is used in the initialization process, you can do so in this file.</p></div>
</div>
-<h2 id="_initialization_process_settings">3. Initialization Process Settings</h2>
-<div class="sectionbody">
-</div>
-<h2 id="_configuring_rails_components">4. Configuring Rails Components</h2>
+<h2 id="_configuring_rails_components">3. Configuring Rails Components</h2>
<div class="sectionbody">
-<h3 id="_configuring_active_record">4.1. Configuring Active Record</h3>
-<div class="paragraph"><p><tt>ActiveRecord::Base</tt> includej a variety of configuration options:</p></div>
+<div class="paragraph"><p>In general, the work of configuring Rails means configuring the components of Rails, as well as configuring Rails itself. The <tt>environment.rb</tt> and environment-specific configuration files (such as <tt>config/environments/production.rb</tt>) allow you to specify the various settings that you want to pass down to all of the components. For example, the default Rails 2.3 <tt>environment.rb</tt> file includes one setting:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>config<span style="color: #990000">.</span>time_zone <span style="color: #990000">=</span> <span style="color: #FF0000">'UTC'</span></tt></pre></div></div>
+<div class="paragraph"><p>This is a setting for Rails itself. If you want to pass settings to individual Rails components, you can do so via the same <tt>config</tt> object:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>config<span style="color: #990000">.</span>active_record<span style="color: #990000">.</span>colorize_logging <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">false</span></span></tt></pre></div></div>
+<div class="paragraph"><p>Rails will use that particular setting to configure Active Record.</p></div>
+<h3 id="_configuring_active_record">3.1. Configuring Active Record</h3>
+<div class="paragraph"><p><tt>ActiveRecord::Base</tt> includes a variety of configuration options:</p></div>
<div class="paragraph"><p><tt>logger</tt> accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then passed on to any new database connections made. You can retrieve this logger by calling <tt>logger</tt> on either an ActiveRecord model class or an ActiveRecord model instance. Set to nil to disable logging.</p></div>
<div class="paragraph"><p><tt>primary_key_prefix_type</tt> lets you adjust the naming for primary key columns. By default, Rails assumes that primary key columns are named <tt>id</tt> (and this configuration option doesn’t need to be set.) There are two other choices:</p></div>
<div class="ulist"><ul>
@@ -305,7 +346,7 @@ after-initializer</p></div> <div class="paragraph"><p><tt>ActiveRecord::ConnectionAdapters::MysqlAdapter.emulate_booleans</tt> controls whether ActiveRecord will consider all <tt>tinyint(1)</tt> columns in a MySQL database to be booleans. By default this is <tt>true</tt>.</p></div>
<div class="paragraph"><p>The schema dumper adds one additional configuration option:</p></div>
<div class="paragraph"><p><tt>ActiveRecord::SchemaDumper.ignore_tables</tt> accepts an array of tables that should <em>not</em> be included in any generated schema file. This setting is ignored unless <tt>ActiveRecord::Base.schema_format == :ruby</tt>.</p></div>
-<h3 id="_configuring_action_controller">4.2. Configuring Action Controller</h3>
+<h3 id="_configuring_action_controller">3.2. Configuring Action Controller</h3>
<div class="paragraph"><p>ActionController::Base includes a number of configuration settings:</p></div>
<div class="paragraph"><p><tt>asset_host</tt> provides a string that is prepended to all of the URL-generating helpers in <tt>AssetHelper</tt>. This is designed to allow moving all javascript, CSS, and image files to a separate asset host.</p></div>
<div class="paragraph"><p><tt>consider_all_requests_local</tt> is generally set to <tt>true</tt> during development and <tt>false</tt> during production; if it is set to <tt>true</tt>, then any error will cause detailed debugging information to be dumped in the HTTP response. For finer-grained control, set this to <tt>false</tt> and implement <tt>local_request?</tt> to specify which requests should provide debugging information on errors.</p></div>
@@ -327,7 +368,7 @@ after-initializer</p></div> <div class="paragraph"><p><tt>ActionController::Dispatcher.error_file_path</tt> gives the path where Rails will look for error files such as <tt>404.html</tt>. The default is <tt>Rails.public_path</tt>.</p></div>
<div class="paragraph"><p>The Active Record session store can also be configured:</p></div>
<div class="paragraph"><p><tt>CGI::Session::ActiveRecordStore::Session.data_column_name</tt> sets the name of the column to use to store session data. By default it is <em>data</em></p></div>
-<h3 id="_configuring_action_view">4.3. Configuring Action View</h3>
+<h3 id="_configuring_action_view">3.3. Configuring Action View</h3>
<div class="paragraph"><p>There are only a few configuration options for Action View, starting with four on <tt>ActionView::Base</tt>:</p></div>
<div class="paragraph"><p><tt>debug_rjs</tt> specifies whether RJS responses should be wrapped in a try/catch block that alert()s the caught exception (and then re-raises it). The default is <tt>false</tt>.</p></div>
<div class="paragraph"><p><tt>warn_cache_misses</tt> tells Rails to display a warning whenever an action results in a cache miss on your view paths. The default is <tt>false</tt>.</p></div>
@@ -335,7 +376,7 @@ after-initializer</p></div> <div class="paragraph"><p><tt>default_form_builder</tt> tells Rails which form builder to use by default. The default is <tt>ActionView::Helpers::FormBuilder</tt>.</p></div>
<div class="paragraph"><p>The ERB template handler supplies one additional option:</p></div>
<div class="paragraph"><p><tt>ActionView::TemplateHandlers::ERB.erb_trim_mode</tt> gives the trim mode to be used by ERB. It defaults to <tt><em>-</em></tt>. See the <a href="http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/">ERB documentation</a> for more information.</p></div>
-<h3 id="_configuring_action_mailer">4.4. Configuring Action Mailer</h3>
+<h3 id="_configuring_action_mailer">3.4. Configuring Action Mailer</h3>
<div class="paragraph"><p>There are a number of settings available on <tt>ActionMailer::Base</tt>:</p></div>
<div class="paragraph"><p><tt>template_root</tt> gives the root folder for Action Mailer templates.</p></div>
<div class="paragraph"><p><tt>logger</tt> accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then used to log information from Action Mailer. Set to nil to disable logging.</p></div>
@@ -343,32 +384,32 @@ after-initializer</p></div> <div class="ulist"><ul>
<li>
<p>
-<tt>:address</tt> - Allows you to use a remote mail server. Just change it from its default "localhost" setting.
+<tt>:address</tt> - Allows you to use a remote mail server. Just change it from its default "localhost" setting.
</p>
</li>
<li>
<p>
-<tt>:port</tt> - On the off chance that your mail server doesn’t run on port 25, you can change it.
+<tt>:port</tt> - On the off chance that your mail server doesn’t run on port 25, you can change it.
</p>
</li>
<li>
<p>
-<tt>:domain</tt> - If you need to specify a HELO domain, you can do it here.
+<tt>:domain</tt> - If you need to specify a HELO domain, you can do it here.
</p>
</li>
<li>
<p>
-<tt>:user_name</tt> - If your mail server requires authentication, set the username in this setting.
+<tt>:user_name</tt> - If your mail server requires authentication, set the username in this setting.
</p>
</li>
<li>
<p>
-<tt>:password</tt> - If your mail server requires authentication, set the password in this setting.
+<tt>:password</tt> - If your mail server requires authentication, set the password in this setting.
</p>
</li>
<li>
<p>
-<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>.
</p>
</li>
</ul></div>
@@ -376,66 +417,99 @@ after-initializer</p></div> <div class="ulist"><ul>
<li>
<p>
-<tt>:location</tt> - The location of the sendmail executable. Defaults to <tt>/usr/sbin/sendmail</tt>.
+<tt>:location</tt> - The location of the sendmail executable. Defaults to <tt>/usr/sbin/sendmail</tt>.
</p>
</li>
<li>
<p>
-<tt>:arguments</tt> - The command line arguments. Defaults to <tt>-i -t</tt>.
+<tt>:arguments</tt> - The command line arguments. Defaults to <tt>-i -t</tt>.
</p>
</li>
</ul></div>
<div class="paragraph"><p><tt>raise_delivery_errors</tt> specifies whether to raise an error if email delivery cannot be completed. It defaults to <tt>true</tt>.</p></div>
-<div class="paragraph"><p><tt>delivery_method</tt> defines the delivery method. The allowed values are <tt>:smtp</tt> (default), <tt>:sendmail</tt>, and <tt>:test</tt>.</p></div>
+<div class="paragraph"><p><tt>delivery_method</tt> defines the delivery method. The allowed values are <tt>:smtp</tt> (default), <tt>:sendmail</tt>, and <tt>:test</tt>.</p></div>
<div class="paragraph"><p><tt>perform_deliveries</tt> specifies whether mail will actually be delivered. By default this is <tt>true</tt>; it can be convenient to set it to <tt>false</tt> for testing.</p></div>
<div class="paragraph"><p><tt>default_charset</tt> tells Action Mailer which character set to use for the body and for encoding the subject. It defaults to <tt>utf-8</tt>.</p></div>
<div class="paragraph"><p><tt>default_content_type</tt> specifies the default content type used for the main part of the message. It defaults to "text/plain"</p></div>
<div class="paragraph"><p><tt>default_mime_version</tt> is the default MIME version for the message. It defaults to <tt>1.0</tt>.</p></div>
<div class="paragraph"><p><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
-<tt>["text/html", "text/enriched", "text/plain"]</tt>. 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.</p></div>
-<h3 id="_configuring_active_resource">4.5. Configuring Active Resource</h3>
+<h3 id="_configuring_active_resource">3.5. Configuring Active Resource</h3>
<div class="paragraph"><p>There is a single configuration setting available on <tt>ActiveResource::Base</tt>:</p></div>
<div class="paragraph"><p><tt>logger</tt> accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then used to log information from Active Resource. Set to nil to disable logging.</p></div>
-<h3 id="_configuring_active_support">4.6. Configuring Active Support</h3>
+<h3 id="_configuring_active_support">3.6. Configuring Active Support</h3>
<div class="paragraph"><p>There are a few configuration options available in Active Support:</p></div>
<div class="paragraph"><p><tt>ActiveSupport::BufferedLogger.silencer</tt> is set to <tt>false</tt> to disable the ability to silence logging in a block. The default is <tt>true</tt>.</p></div>
<div class="paragraph"><p><tt>ActiveSupport::Cache::Store.logger</tt> specifies the logger to use within cache store operations.</p></div>
<div class="paragraph"><p><tt>ActiveSupport::Logger.silencer</tt> is set to <tt>false</tt> to disable the ability to silence logging in a block. The default is <tt>true</tt>.</p></div>
-<h3 id="_configuring_active_model">4.7. Configuring Active Model</h3>
+<h3 id="_configuring_active_model">3.7. Configuring Active Model</h3>
<div class="paragraph"><p>Active Model currently has a single configuration setting:</p></div>
-<div class="paragraph"><p>+ActiveModel::Errors.default_error_messages is an array containing all of the validation error messages.</p></div>
+<div class="paragraph"><p><tt>ActiveModel::Errors.default_error_messages</tt> is an array containing all of the validation error messages.</p></div>
</div>
-<h2 id="_using_initializers">5. Using Initializers</h2>
+<h2 id="_using_initializers">4. Using Initializers</h2>
<div class="sectionbody">
-<div class="literalblock">
-<div class="content">
-<pre><tt>organization, controlling load order</tt></pre>
-</div></div>
+<div class="paragraph"><p>After it loads the framework plus any gems and plugins in your application, Rails turns to loading initializers. An initializer is any file of ruby code stored under <tt>/config/initializers</tt> in your application. You can use initializers to hold configuration settings that should be made after all of the frameworks and plugins are loaded.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">You can use subfolders to organize your initializers if you like, because Rails will look into the whole file hierarchy from the <tt>initializers</tt> folder on down.</td>
+</tr></table>
</div>
-<h2 id="_using_an_after_initializer">6. Using an After-Initializer</h2>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/tip.png" alt="Tip" />
+</td>
+<td class="content">If you have any ordering dependency in your initializers, you can control the load order by naming. For example, <tt>01_critical.rb</tt> will be loaded before <tt>02_normal.rb</tt>.</td>
+</tr></table>
+</div>
+</div>
+<h2 id="_using_an_after_initializer">5. Using an After-Initializer</h2>
<div class="sectionbody">
+<div class="paragraph"><p>After-initializers are run (as you might guess) after any initializers are loaded. You can supply an <tt>after_initialize</tt> block (or an array of such blocks) by setting up <tt>config.after_initialize</tt> in any of the Rails configuration files:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>config<span style="color: #990000">.</span>after_initialize <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>
+ SomeClass<span style="color: #990000">.</span>init
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/warning.png" alt="Warning" />
+</td>
+<td class="content">Some parts of your application, notably observers and routing, are not yet set up at the point where the <tt>after_initialize</tt> block is called.</td>
+</tr></table>
+</div>
</div>
-<h2 id="_rails_environment_settings">7. Rails Environment Settings</h2>
+<h2 id="_rails_environment_settings">6. Rails Environment Settings</h2>
<div class="sectionbody">
-<div class="paragraph"><p>ENV</p></div>
+<div class="paragraph"><p>Some parts of Rails can also be configured externally by supplying environment variables. The following environment variables are recognized by various parts of Rails:</p></div>
+<div class="paragraph"><p><tt>ENV[<em>RAILS_ENV</em>]</tt> defines the Rails environment (production, development, test, and so on) that Rails will run under.</p></div>
+<div class="paragraph"><p><tt>ENV[<em>RAILS_RELATIVE_URL_ROOT</em>]</tt> is used by the routing code to recognize URLs when you deploy your application to a subdirectory.</p></div>
+<div class="paragraph"><p><tt>ENV["RAILS_ASSET_ID"]</tt> will override the default cache-busting timestamps that Rails generates for downloadable assets.</p></div>
+<div class="paragraph"><p><tt>ENV["RAILS_CACHE_ID"]</tt> and <tt>ENV["RAILS_APP_VERSION"]</tt> are used to generate expanded cache keys in Rails' caching code. This allows you to have multiple separate caches from the same application.</p></div>
+<div class="paragraph"><p><tt>ENV[<em>RAILS_GEM_VERSION</em>]</tt> defines the version of the Rails gems to use, if <tt>RAILS_GEM_VERSION</tt> is not defined in your <tt>environment.rb</tt> file.</p></div>
</div>
-<h2 id="_changelog">8. Changelog</h2>
+<h2 id="_changelog">7. Changelog</h2>
<div class="sectionbody">
<div class="paragraph"><p><a href="http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/28">Lighthouse ticket</a></p></div>
<div class="ulist"><ul>
<li>
<p>
-November 5, 2008: Rough outline by <a href="../authors.html#mgunderloy">Mike Gunderloy</a>
+January 3, 2009: First reasonably complete draft by <a href="../authors.html#mgunderloy">Mike Gunderloy</a>
</p>
-<div class="qlist"><ol>
-<li>
-<p><em>
-need to look for def self. ?
-</em></p>
</li>
-</ol></div>
+<li>
+<p>
+November 5, 2008: Rough outline by <a href="../authors.html#mgunderloy">Mike Gunderloy</a>
+</p>
</li>
</ul></div>
</div>
diff --git a/railties/doc/guides/html/form_helpers.html b/railties/doc/guides/html/form_helpers.html index 134679b9f2..84f22d0a9c 100644 --- a/railties/doc/guides/html/form_helpers.html +++ b/railties/doc/guides/html/form_helpers.html @@ -213,6 +213,16 @@ ul#navMain { </ul> </li> <li> + <a href="#_different_families_of_helpers">Different Families of helpers</a> + <ul> + + <li><a href="#_barebones_helpers">Barebones helpers</a></li> + + <li><a href="#_model_object_helpers">Model object helpers</a></li> + + </ul> + </li> + <li> <a href="#_forms_that_deal_with_model_attributes">Forms that deal with model attributes</a> <ul> @@ -226,7 +236,7 @@ ul#navMain { <li><a href="#_the_select_tag_and_options">The select tag and options</a></li> - <li><a href="#_select_helpers_for_dealing_with_models">Select helpers for dealing with models</a></li> + <li><a href="#_select_boxes_for_dealing_with_models">Select boxes for dealing with models</a></li> <li><a href="#_option_tags_from_a_collection_of_arbitrary_objects">Option tags from a collection of arbitrary objects</a></li> @@ -235,17 +245,53 @@ ul#navMain { </ul> </li> <li> - <a href="#_miscellaneous">Miscellaneous</a> + <a href="#_date_and_time_select_boxes">Date and time select boxes</a> <ul> - <li><a href="#_file_upload_form">File upload form</a></li> + <li><a href="#_barebones_helpers_2">Barebones helpers</a></li> + + <li><a href="#_model_object_helpers_2">Model object helpers</a></li> + + <li><a href="#_common_options">Common options</a></li> + + </ul> + </li> + <li> + <a href="#_form_builders">Form builders</a> + <ul> <li><a href="#_scoping_out_form_controls_with_tt_fields_for_tt">Scoping out form controls with <tt>fields_for</tt></a></li> - <li><a href="#_making_custom_form_builders">Making custom form builders</a></li> + </ul> + </li> + <li> + <a href="#_file_uploads">File Uploads</a> + <ul> + + <li><a href="#_what_gets_uploaded">What gets uploaded</a></li> + + <li><a href="#_dealing_with_ajax">Dealing with Ajax</a></li> + + </ul> + </li> + <li> + <a href="#_parameter_names">Parameter Names</a> + <ul> + + <li><a href="#_basic_structures">Basic structures</a></li> + + <li><a href="#_combining_them">Combining them</a></li> + + <li><a href="#_using_form_helpers">Using form helpers</a></li> </ul> </li> + <li> + <a href="#_complex_forms">Complex forms</a> + </li> + <li> + <a href="#_changelog">Changelog</a> + </li> </ol> </div> @@ -254,7 +300,7 @@ ul#navMain { <div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>Forms in web applications are an essential interface for user input. However, form markup can quickly become tedious to write and maintain because of form control naming and their numerous attributes. Rails deals away with these complexities by providing view helpers for generating form markup. However, since they have different use-cases, developers are required to know all the differences between similar helper methods before putting them to use.</p></div>
-<div class="paragraph"><p>In this guide we will:</p></div>
+<div class="paragraph"><p>In this guide you will:</p></div>
<div class="ulist"><ul>
<li>
<p>
@@ -276,11 +322,6 @@ Generate select boxes from multiple types of data; Learn what makes a file upload form different;
</p>
</li>
-<li>
-<p>
-Build complex, multi-model forms.
-</p>
-</li>
</ul></div>
<div class="admonitionblock">
<table><tr>
@@ -303,7 +344,7 @@ Build complex, multi-model forms. </div></div>
<div class="paragraph"><p>When called without arguments like this, it creates a form element that has the current page for action attribute and "POST" as method (some line breaks added for readability):</p></div>
<div class="listingblock">
-<div class="title">Sample rendering of <tt>form_tag</tt></div>
+<div class="title">Sample output from <tt>form_tag</tt></div>
<div class="content">
<pre><tt><form action="/home/index" method="post">
<div style="margin:0;padding:0">
@@ -312,7 +353,7 @@ Build complex, multi-model forms. Form contents
</form></tt></pre>
</div></div>
-<div class="paragraph"><p>If you carefully observe this output, you can see that the helper generated something we didn’t specify: a <tt>div</tt> element with a hidden input inside. This is a security feature of Rails called <strong>cross-site request forgery protection</strong> and form helpers generate it for every form which action isn’t "GET" (provided that this security feature is enabled).</p></div>
+<div class="paragraph"><p>If you carefully observe this output, you can see that the helper generated something you didn’t specify: a <tt>div</tt> element with a hidden input inside. This is a security feature of Rails called <strong>cross-site request forgery protection</strong> and form helpers generate it for every form which action isn’t "GET" (provided that this security feature is enabled).</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
@@ -350,10 +391,10 @@ a submit element. <td class="icon">
<img src="./images/icons/important.png" alt="Important" />
</td>
-<td class="content">Always use "GET" as the method for search forms. Benefits are many: users are able to bookmark a specific search and get back to it; browsers cache results of "GET" requests, but not "POST"; and other.</td>
+<td class="content">Always use "GET" as the method for search forms. Benefits are many: users are able to bookmark a specific search and get back to it; browsers cache results of "GET" requests, but not "POST"; and others.</td>
</tr></table>
</div>
-<div class="paragraph"><p>To create that, we will use <tt>form_tag</tt>, <tt>label_tag</tt>, <tt>text_field_tag</tt> and <tt>submit_tag</tt>, respectively.</p></div>
+<div class="paragraph"><p>To create that, you will use <tt>form_tag</tt>, <tt>label_tag</tt>, <tt>text_field_tag</tt> and <tt>submit_tag</tt>, respectively.</p></div>
<div class="listingblock">
<div class="title">A basic search form</div>
<div class="content">
@@ -393,24 +434,24 @@ a submit element. <td class="icon">
<img src="./images/icons/tip.png" alt="Tip" />
</td>
-<td class="content">For every form input, an ID attribute is generated from its name ("q" in our example). These IDs can be very useful for CSS styling or manipulation of form controls with JavaScript.</td>
+<td class="content">For every form input, an ID attribute is generated from its name ("q" in the example). These IDs can be very useful for CSS styling or manipulation of form controls with JavaScript.</td>
</tr></table>
</div>
<h3 id="_multiple_hashes_in_form_helper_attributes">1.2. Multiple hashes in form helper attributes</h3>
-<div class="paragraph"><p>By now we’ve seen that the <tt>form_tag</tt> helper accepts 2 arguments: the path for the action attribute and an options hash for parameters (like <tt>:method</tt>).</p></div>
-<div class="paragraph"><p>Identical to the ‘link_to` helper, the path argument doesn’t have to be given as string or a named route. It can be a hash of URL parameters that Rails’ routing mechanism will turn into a valid URL. Still, we cannot simply write this:</p></div>
+<div class="paragraph"><p>By now you’ve seen that the <tt>form_tag</tt> helper accepts 2 arguments: the path for the action and an options hash. This hash specifies the method of form submission and HTML options such as the form element’s class.</p></div>
+<div class="paragraph"><p>As with the ‘link_to` helper, the path argument doesn’t have to be given a string. It can be a hash of URL parameters that Rails’ routing mechanism will turn into a valid URL. Still, you cannot simply write this:</p></div>
<div class="listingblock">
<div class="title">A bad way to pass multiple hashes as method arguments</div>
<div class="content">
-<pre><tt>form_tag(:controller => "people", :action => "search", :method => "get")
-# => <form action="/people/search?method=get" method="post"></tt></pre>
+<pre><tt>form_tag(:controller => "people", :action => "search", :method => "get", :class => "nifty_form")
+# => <form action="/people/search?method=get&class=nifty_form" method="post"></tt></pre>
</div></div>
-<div class="paragraph"><p>Here we wanted to pass two hashes, but the Ruby interpreter sees only one hash, so Rails will construct a URL that we didn’t want. The solution is to delimit the first hash (or both hashes) with curly brackets:</p></div>
+<div class="paragraph"><p>Here you wanted to pass two hashes, but the Ruby interpreter sees only one hash, so Rails will construct a URL with extraneous parameters. The solution is to delimit the first hash (or both hashes) with curly brackets:</p></div>
<div class="listingblock">
<div class="title">The correct way of passing multiple hashes as arguments</div>
<div class="content">
-<pre><tt>form_tag({:controller => "people", :action => "search"}, :method => "get")
-# => <form action="/people/search" method="get"></tt></pre>
+<pre><tt>form_tag({:controller => "people", :action => "search"}, :method => "get", :class => "nifty_form")
+# => <form action="/people/search" method="get" class="nifty_form"></tt></pre>
</div></div>
<div class="paragraph"><p>This is a common pitfall when using form helpers, since many of them accept multiple hashes. So in future, if a helper produces unexpected output, make sure that you have delimited the hash parameters properly.</p></div>
<div class="admonitionblock">
@@ -460,7 +501,7 @@ output: <td class="content">Always use labels for each checkbox and radio button. They associate text with a specific option and provide a larger clickable region.</td>
</tr></table>
</div>
-<div class="paragraph"><p>Other form controls we might mention are the text area, password input and hidden input:</p></div>
+<div class="paragraph"><p>Other form controls worth mentioning are the text area, password input and hidden input:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt><%= text_area_tag(:message, "Hi, nice site", :size => "24x6") %>
@@ -484,7 +525,7 @@ output: </div>
<h3 id="_how_do_forms_with_put_or_delete_methods_work">1.4. How do forms with PUT or DELETE methods work?</h3>
<div class="paragraph"><p>Rails framework encourages RESTful design of your applications, which means you’ll be making a lot of "PUT" and "DELETE" requests (besides "GET" and "POST"). Still, most browsers <em>don’t support</em> methods other than "GET" and "POST" when it comes to submitting forms. How does this work, then?</p></div>
-<div class="paragraph"><p>Rails works around this issue by emulating other methods over POST with a hidden input named <tt>"_method"</tt> that is set to reflect the wanted method:</p></div>
+<div class="paragraph"><p>Rails works around this issue by emulating other methods over POST with a hidden input named <tt>"_method"</tt> that is set to reflect the desired method:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>form_tag(search_path, :method => "put")
@@ -500,9 +541,48 @@ output: </div></div>
<div class="paragraph"><p>When parsing POSTed data, Rails will take into account the special <tt>"_method"</tt> parameter and act as if the HTTP method was the one specified inside it ("PUT" in this example).</p></div>
</div>
-<h2 id="_forms_that_deal_with_model_attributes">2. Forms that deal with model attributes</h2>
+<h2 id="_different_families_of_helpers">2. Different Families of helpers</h2>
<div class="sectionbody">
-<div class="paragraph"><p>When we’re dealing with an actual model, we will use a different set of form helpers and have Rails take care of some details in the background. In the following examples we will handle an Article model. First, let us have the controller create one:</p></div>
+<div class="paragraph"><p>Most of Rails' form helpers are available in two forms.</p></div>
+<h3 id="_barebones_helpers">2.1. Barebones helpers</h3>
+<div class="paragraph"><p>These just generate the appropriate markup. These have names ending in _tag such as <tt>text_field_tag</tt>, <tt>check_box_tag</tt>. The first parameter to these is always the name of the input. This is the name under which value will appear in the <tt>params</tt> hash in the controller. For example if the form contains</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><%= text_field_tag(:query) %></tt></pre>
+</div></div>
+<div class="paragraph"><p>then the controller code should use</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>params[:query]</tt></pre>
+</div></div>
+<div class="paragraph"><p>to retrieve the value entered by the user. When naming inputs be aware that Rails uses certain conventions that control whether values appear at the top level of the params hash, inside an array or a nested hash and so on. You can read more about them in the <a href="#parameter_names">parameter names</a> section. For details on the precise usage of these helpers, please refer to the <a href="http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html">API documentation</a>.</p></div>
+<h3 id="_model_object_helpers">2.2. Model object helpers</h3>
+<div class="paragraph"><p>These are designed to work with a model object (commonly an Active Record object but this need not be the case). These lack the _tag suffix, for example <tt>text_field</tt>, <tt>text_area</tt>.</p></div>
+<div class="paragraph"><p>For these helpers the first arguement is the name of an instance variable and the second is the name a method (usually an attribute) to call on that object. Rails will set the value of the input control to the return value of that method for the object and set an appropriate input name. If your controller has defined <tt>@person</tt> and that person’s name is Henry then a form containing:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><%= text_field(:person, :name) %></tt></pre>
+</div></div>
+<div class="paragraph"><p>will produce output similar to</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><input id="person_name" name="person[name]" type="text" value="Henry"/></tt></pre>
+</div></div>
+<div class="paragraph"><p>Upon form submission the value entered by the user will be stored in <tt>params[:person][:name]</tt>. The params[:person] hash is suitable for passing to <tt>Person.new</tt> or, if <tt>@person</tt> is an instance of Person, <tt>@person.update_attributes</tt>.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/warning.png" alt="Warning" />
+</td>
+<td class="content">
+<div class="paragraph"><p>You must pass the name of an instance variable, i.e. <tt>:person</tt> or <tt>"person"</tt>, not an actual instance of your model object.</p></div>
+</td>
+</tr></table>
+</div>
+</div>
+<h2 id="_forms_that_deal_with_model_attributes">3. Forms that deal with model attributes</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>While the helpers seen so far are handy Rails can save you some work. For example typically a form is used to edit multiple attributes of a single object, so having to repeat the name of the object being edited is clumsy. The following examples will handle an Article model. First, have the controller create one:</p></div>
<div class="listingblock">
<div class="title">articles_controller.rb</div>
<div class="content">
@@ -510,11 +590,11 @@ output: @article = Article.new
end</tt></pre>
</div></div>
-<div class="paragraph"><p>Now we switch to the view. The first thing to remember is that we should use <tt>form_for</tt> helper instead of <tt>form_tag</tt>, and that we should pass the model name and object as arguments:</p></div>
+<div class="paragraph"><p>Now switch to the view. The first thing to remember is to use the <tt>form_for</tt> helper instead of <tt>form_tag</tt>, and that you should pass the model name and object as arguments:</p></div>
<div class="listingblock">
<div class="title">articles/new.html.erb</div>
<div class="content">
-<pre><tt><% form_for :article, @article, :url => { :action => "create" } do |f| %>
+<pre><tt><% form_for :article, @article, :url => { :action => "create" }, :html => {:class => "nifty_form"} do |f| %>
<%= f.text_field :title %>
<%= f.text_area :body, :size => "60x12" %>
<%= submit_tag "Create" %>
@@ -524,12 +604,12 @@ end</tt></pre> <div class="olist"><ol>
<li>
<p>
-<tt>:article</tt> is the name of the model and <tt>@article</tt> is our record.
+<tt>:article</tt> is the name of the model and <tt>@article</tt> is the record.
</p>
</li>
<li>
<p>
-The URL for the action attribute is passed as a parameter named <tt>:url</tt>.
+There is a single hash of options. Routing options are passed inside <tt>:url</tt> hash, HTML options are passed in the <tt>:html</tt> hash.
</p>
</li>
<li>
@@ -539,32 +619,24 @@ The <tt>form_for</tt> method yields <strong>a form builder</strong> object (the </li>
<li>
<p>
-Methods to create form controls are called <strong>on</strong> the form builder object <tt>f</tt> and <strong>without</strong> the <tt>"_tag"</tt> suffix (so <tt>text_field_tag</tt> becomes <tt>f.text_field</tt>).
+Methods to create form controls are called <strong>on</strong> the form builder object <tt>f</tt>
</p>
</li>
</ol></div>
<div class="paragraph"><p>The resulting HTML is:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt><form action="/articles/create" method="post">
+<pre><tt><form action="/articles/create" method="post" class="nifty_form">
<input id="article_title" name="article[title]" size="30" type="text" />
<textarea id="article_body" name="article[body]" cols="60" rows="12"></textarea>
<input name="commit" type="submit" value="Create" />
</form></tt></pre>
</div></div>
-<div class="paragraph"><p>A nice thing about <tt>f.text_field</tt> and other helper methods is that they will pre-fill the form control with the value read from the corresponding attribute in the model. For example, if we created the article instance by supplying an initial value for the title in the controller:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><tt>@article = Article.new(:title => "Rails makes forms easy")</tt></pre>
-</div></div>
-<div class="paragraph"><p>... the corresponding input will be rendered with a value:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><tt><input id="post_title" name="post[title]" size="30" type="text" value="Rails makes forms easy" /></tt></pre>
-</div></div>
-<h3 id="_relying_on_record_identification">2.1. Relying on record identification</h3>
-<div class="paragraph"><p>In the previous chapter we handled the Article model. This model is directly available to users of our application, so — following the best practices for developing with Rails — we should declare it <strong>a resource</strong>.</p></div>
-<div class="paragraph"><p>When dealing with RESTful resources, our calls to <tt>form_for</tt> can get significantly easier if we rely on <strong>record identification</strong>. In short, we can just pass the model instance and have Rails figure out model name and the rest:</p></div>
+<div class="paragraph"><p>The name passed to <tt>form_for</tt> controls where in the params hash the form values will appear. Here the name is <tt>article</tt> and so all the inputs have names of the form <tt>article[attribute_name]</tt>. Accordingly, in the <tt>create</tt> action <tt>params[:article]</tt> will be a hash with keys <tt>:title</tt> and <tt>:body</tt>. You can read more about the significance of input names in the <a href="#parameter_names">parameter names</a> section.</p></div>
+<div class="paragraph"><p>The helper methods called on the form builder are identical to the model object helpers except that it is not necessary to specify which object is being edited since this is already managed by the form builder.</p></div>
+<h3 id="_relying_on_record_identification">3.1. Relying on record identification</h3>
+<div class="paragraph"><p>In the previous chapter you handled the Article model. This model is directly available to users of our application, so — following the best practices for developing with Rails — you should declare it <strong>a resource</strong>.</p></div>
+<div class="paragraph"><p>When dealing with RESTful resources, calls to <tt>form_for</tt> can get significantly easier if you rely on <strong>record identification</strong>. In short, you can just pass the model instance and have Rails figure out model name and the rest:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>## Creating a new article
@@ -579,7 +651,8 @@ form_for(:article, @article, :url => article_path(@article), :method => "p # short-style:
form_for(@article)</tt></pre>
</div></div>
-<div class="paragraph"><p>Notice how the short-style <tt>form_for</tt> invocation is conveniently the same, regardless of the record being new or existing. Record identification is smart enough to figure out if the record is new by asking <tt>record.new_record?</tt>.</p></div>
+<div class="paragraph"><p>Notice how the short-style <tt>form_for</tt> invocation is conveniently the same, regardless of the record being new or existing. Record identification is smart enough to figure out if the record is new by asking <tt>record.new_record?</tt>. It also selects the correct path to submit to and the name based on the class of the object.</p></div>
+<div class="paragraph"><p>Rails will also automatically set the class and id of the form appropriately: a form creating an article would have id and class <tt>new_article</tt>. If you were editing the article with id 23 the class would be set to <tt>edit_article</tt> and the id to <tt>edit_article_23</tt>. The attributes will be omitted or brevity in the rest of this guide.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
@@ -588,8 +661,20 @@ form_for(@article)</tt></pre> <td class="content">When you’re using STI (single-table inheritance) with your models, you can’t rely on record identification on a subclass if only their parent class is declared a resource. You will have to specify the model name, <tt>:url</tt> and <tt>:method</tt> explicitly.</td>
</tr></table>
</div>
+<h4 id="_dealing_with_namespaces">3.1.1. Dealing with namespaces</h4>
+<div class="paragraph"><p>If you have created namespaced routes <tt>form_for</tt> has a nifty shorthand for that too. If your application has an admin namespace then</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>form_for [:admin, @article]</tt></pre>
+</div></div>
+<div class="paragraph"><p>will create a form that submits to the articles controller inside the admin namespace (submitting to <tt>admin_article_path(@article)</tt> in the case of an update). If you have several levels of namespacing then the syntax is similar:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>form_for [:admin, :management, @article]</tt></pre>
+</div></div>
+<div class="paragraph"><p>For more information on Rails' routing system and the associated conventions, please see the <a href="../routing_outside_in.html">routing guide</a>.</p></div>
</div>
-<h2 id="_making_select_boxes_with_ease">3. Making select boxes with ease</h2>
+<h2 id="_making_select_boxes_with_ease">4. Making select boxes with ease</h2>
<div class="sectionbody">
<div class="paragraph"><p>Select boxes in HTML require a significant amount of markup (one <tt>OPTION</tt> element for each option to choose from), therefore it makes the most sense for them to be dynamically generated from data stored in arrays or hashes.</p></div>
<div class="paragraph"><p>Here is what our wanted markup might look like:</p></div>
@@ -602,14 +687,14 @@ form_for(@article)</tt></pre> <option value="12">Berlin</option>
</select></tt></pre>
</div></div>
-<div class="paragraph"><p>Here we have a list of cities where their names are presented to the user, but internally we want to handle just their IDs so we keep them in value attributes. Let’s see how Rails can help out here.</p></div>
-<h3 id="_the_select_tag_and_options">3.1. The select tag and options</h3>
+<div class="paragraph"><p>Here you have a list of cities where their names are presented to the user, but internally the application only wants to handle their IDs so they are used as the options' value attributes. Let’s see how Rails can help out here.</p></div>
+<h3 id="_the_select_tag_and_options">4.1. The select tag and options</h3>
<div class="paragraph"><p>The most generic helper is <tt>select_tag</tt>, which — as the name implies — simply generates the <tt>SELECT</tt> tag that encapsulates an options string:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt><%= select_tag(:city_id, '<option value="1">Lisabon</option>...') %></tt></pre>
</div></div>
-<div class="paragraph"><p>This is a start, but it doesn’t dynamically create our option tags. We can generate option tags with the <tt>options_for_select</tt> helper:</p></div>
+<div class="paragraph"><p>This is a start, but it doesn’t dynamically create our option tags. You can generate option tags with the <tt>options_for_select</tt> helper:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt><%= options_for_select([['Lisabon', 1], ['Madrid', 2], ...]) %>
@@ -620,16 +705,16 @@ output: <option value="2">Madrid</option>
...</tt></pre>
</div></div>
-<div class="paragraph"><p>For input data we used a nested array where each item has two elements: option text (city name) and option value (city id).</p></div>
+<div class="paragraph"><p>For input data you use a nested array where each element has two elements: option text (city name) and option value (city id). The option value is what will get submitted to your controller. It is often true that the option value is the id of a corresponding database object but this does not have to be the case.</p></div>
<div class="paragraph"><p>Knowing this, you can combine <tt>select_tag</tt> and <tt>options_for_select</tt> to achieve the desired, complete markup:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt><%= select_tag(:city_id, options_for_select(...)) %></tt></pre>
</div></div>
-<div class="paragraph"><p>Sometimes, depending on our application’s needs, we also wish a specific option to be pre-selected. The <tt>options_for_select</tt> helper supports this with an optional second argument:</p></div>
+<div class="paragraph"><p>Sometimes, depending on an application’s needs, you also wish a specific option to be pre-selected. The <tt>options_for_select</tt> helper supports this with an optional second argument:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt><%= options_for_select(cities_array, 2) %>
+<pre><tt><%= options_for_select([['Lisabon', 1], ['Madrid', 2], ...], 2) %>
output:
@@ -638,9 +723,19 @@ output: ...</tt></pre>
</div></div>
<div class="paragraph"><p>So whenever Rails sees that the internal value of an option being generated matches this value, it will add the <tt>selected</tt> attribute to that option.</p></div>
-<h3 id="_select_helpers_for_dealing_with_models">3.2. Select helpers for dealing with models</h3>
-<div class="paragraph"><p>Until now we’ve covered how to make generic select boxes, but in most cases our form controls will be tied to a specific database model. So, to continue from our previous examples, let’s assume that we have a "Person" model with a <tt>city_id</tt> attribute.</p></div>
-<div class="paragraph"><p>Consistent with other form helpers, when dealing with models we drop the <tt>"_tag"</tt> suffix from <tt>select_tag</tt> that we used in previous examples:</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/tip.png" alt="Tip" />
+</td>
+<td class="content">
+<div class="paragraph"><p>The second argument to <tt>options_for_select</tt> must be exactly equal to the desired internal value. In particular if the internal value is the integer 2 you cannot pass "2" to <tt>options_for_select</tt> — you must pass 2. Be aware of values extracted from the params hash as they are all strings.</p></div>
+</td>
+</tr></table>
+</div>
+<h3 id="_select_boxes_for_dealing_with_models">4.2. Select boxes for dealing with models</h3>
+<div class="paragraph"><p>Until now you’ve seen how to make generic select boxes, but in most cases our form controls will be tied to a specific database model. So, to continue from our previous examples, let’s assume that you have a "Person" model with a <tt>city_id</tt> attribute.</p></div>
+<div class="paragraph"><p>Consistent with other form helpers, when dealing with models you drop the <tt>_tag</tt> suffix from <tt>select_tag</tt>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt># controller:
@@ -649,83 +744,392 @@ output: # view:
<%= select(:person, :city_id, [['Lisabon', 1], ['Madrid', 2], ...]) %></tt></pre>
</div></div>
-<div class="paragraph"><p>Notice that the third parameter, the options array, is the same kind of argument we pass to <tt>options_for_select</tt>. One thing that we have as an advantage here is that we don’t have to worry about pre-selecting the correct city if the user already has one — Rails will do this for us by reading from <tt>@person.city_id</tt> attribute.</p></div>
-<div class="paragraph"><p>As before, if we were to use <tt>select</tt> helper on a form builder scoped to <tt>@person</tt> object, the syntax would be:</p></div>
+<div class="paragraph"><p>Notice that the third parameter, the options array, is the same kind of argument you pass to <tt>options_for_select</tt>. One advantage here is that you don’t have to worry about pre-selecting the correct city if the user already has one — Rails will do this for you by reading from the <tt>@person.city_id</tt> attribute.</p></div>
+<div class="paragraph"><p>As before, if you were to use <tt>select</tt> helper on a form builder scoped to <tt>@person</tt> object, the syntax would be:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt># select on a form builder
<%= f.select(:city_id, ...) %></tt></pre>
</div></div>
-<h3 id="_option_tags_from_a_collection_of_arbitrary_objects">3.3. Option tags from a collection of arbitrary objects</h3>
-<div class="paragraph"><p>Until now we were generating option tags from nested arrays with the help of <tt>options_for_select</tt> method. Data in our array were raw values:</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/warning.png" alt="Warning" />
+</td>
+<td class="content">
+<div class="paragraph"><p>If you are using <tt>select</tt> (or similar helpers such as <tt>collection_select</tt>, <tt>select_tag</tt>) to set a <tt>belongs_to</tt> association you must pass the name of the foreign key (in the example above <tt>city_id</tt>), not the name of association itself. If you specify <tt>city</tt> instead of `city_id Active Record will raise an error along the lines of</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got Fixnum(#1138750)</tt></pre>
+</div></div>
+<div class="paragraph"><p>when you pass the params hash to <tt>Person.new</tt> or <tt>update_attributes</tt>. Another way of looking at this is that form helpers only edit attributes.</p></div>
+</td>
+</tr></table>
+</div>
+<h3 id="_option_tags_from_a_collection_of_arbitrary_objects">4.3. Option tags from a collection of arbitrary objects</h3>
+<div class="paragraph"><p>Until now you were generating option tags from nested arrays with the help of <tt>options_for_select</tt> method. Data in our array were raw values:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt><%= options_for_select([['Lisabon', 1], ['Madrid', 2], ...]) %></tt></pre>
</div></div>
-<div class="paragraph"><p>But what if we had a <strong>City</strong> model (perhaps an ActiveRecord one) and we wanted to generate option tags from a collection of those objects? One solution would be to make a nested array by iterating over them:</p></div>
+<div class="paragraph"><p>But what if you had a <strong>City</strong> model (perhaps an Active Record one) and you wanted to generate option tags from a collection of those objects? One solution would be to make a nested array by iterating over them:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt><% cities_array = City.find(:all).map { |city| [city.name, city.id] } %>
<%= options_for_select(cities_array) %></tt></pre>
</div></div>
-<div class="paragraph"><p>This is a perfectly valid solution, but Rails provides us with a less verbose alternative: <tt>options_from_collection_for_select</tt>. This helper expects a collection of arbitrary objects and two additional arguments: the names of the methods to read the option <strong>value</strong> and <strong>text</strong> from, respectively:</p></div>
+<div class="paragraph"><p>This is a perfectly valid solution, but Rails provides a less verbose alternative: <tt>options_from_collection_for_select</tt>. This helper expects a collection of arbitrary objects and two additional arguments: the names of the methods to read the option <strong>value</strong> and <strong>text</strong> from, respectively:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt><%= options_from_collection_for_select(City.all, :id, :name) %></tt></pre>
</div></div>
-<div class="paragraph"><p>As the name implies, this only generates option tags. A method to go along with it is <tt>collection_select</tt>:</p></div>
+<div class="paragraph"><p>As the name implies, this only generates option tags. To generate a working select box you would need to use it in conjunction with <tt>select_tag</tt>, just as you would with <tt>options_for_select</tt>. A method to go along with it is <tt>collection_select</tt>:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt><%= collection_select(:person, :city_id, City.all, :id, :name) %></tt></pre>
</div></div>
-<div class="paragraph"><p>To recap, <tt>options_from_collection_for_select</tt> are to <tt>collection_select</tt> what <tt>options_for_select</tt> are to <tt>select</tt>.</p></div>
-<h3 id="_time_zone_and_country_select">3.4. Time zone and country select</h3>
-<div class="paragraph"><p>To leverage time zone support in Rails, we have to ask our users what time zone they are in. Doing so would require generating select options from a list of pre-defined TimeZone objects using <tt>collection_select</tt>, but we can simply use the <tt>time_zone_select</tt> helper that already wraps this:</p></div>
+<div class="paragraph"><p>To recap, <tt>options_from_collection_for_select</tt> is to <tt>collection_select</tt> what <tt>options_for_select</tt> is to <tt>select</tt>.</p></div>
+<h3 id="_time_zone_and_country_select">4.4. Time zone and country select</h3>
+<div class="paragraph"><p>To leverage time zone support in Rails, you have to ask our users what time zone they are in. Doing so would require generating select options from a list of pre-defined TimeZone objects using <tt>collection_select</tt>, but you can simply use the <tt>time_zone_select</tt> helper that already wraps this:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt><%= time_zone_select(:person, :city_id) %></tt></pre>
</div></div>
<div class="paragraph"><p>There is also <tt>time_zone_options_for_select</tt> helper for a more manual (therefore more customizable) way of doing this. Read the API documentation to learn about the possible arguments for these two methods.</p></div>
-<div class="paragraph"><p>When it comes to country select, Rails <em>used</em> to have the built-in helper <tt>country_select</tt> but was extracted to a plugin.
-TODO: plugin URL</p></div>
+<div class="paragraph"><p>Rails <em>used</em> to have a <tt>country_select</tt> helper for choosing countries but this has been extracted to the <a href="http://github.com/rails/country_select/tree/master">country_select plugin</a>. When using this do be aware that the exclusion or inclusion of certain names from the list can be somewhat controversial (and was the reason this functionality was extracted from rails)</p></div>
+</div>
+<h2 id="_date_and_time_select_boxes">5. Date and time select boxes</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The date and time helpers differ from all the other form helpers in two important respects:</p></div>
+<div class="olist"><ol>
+<li>
+<p>
+Unlike other attributes you might typically have, dates and times are not representable by a single input element. Instead you have several, one for each component (year, month, day etc...). So in particular, there is no single value in your params hash with your date or time.
+</p>
+</li>
+<li>
+<p>
+Other helpers use the _tag suffix to indicate whether a helper is a barebones helper or one that operates on model objects. With dates and times, <tt>select\_date</tt>, <tt>select\_time</tt> and <tt>select_datetime</tt> are the barebones helpers, <tt>date_select</tt>, <tt>time_select</tt> and <tt>datetime_select</tt> are the equivalent model object helpers
+</p>
+</li>
+</ol></div>
+<div class="paragraph"><p>Both of these families of helpers will create a series of select boxes for the different components (year, month, day etc...).</p></div>
+<h3 id="_barebones_helpers_2">5.1. Barebones helpers</h3>
+<div class="paragraph"><p>The <tt>select_*</tt> family of helpers take as their first argument an instance of Date, Time or DateTime that is used as the currently selected value. You may omit this parameter, in which case the current date is used. For example</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><%= select_date Date::today, :prefix => :start_date %></tt></pre>
+</div></div>
+<div class="paragraph"><p>outputs (with the actual option values omitted for brevity)</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><select id="start_date_year" name="start_date[year]"> ... </select>
+<select id="start_date_month" name="start_date[month]"> ... </select>
+<select id="start_date_day" name="start_date[day]"> ... </select></tt></pre>
+</div></div>
+<div class="paragraph"><p>The above inputs would result in <tt>params[:start_date]</tt> being a hash with keys :year, :month, :day. To get an actual Time or Date object you would have to extract these values and pass them to the appropriate constructor, for example</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>Date::civil(params[:start_date][:year].to_i, params[:start_date][:month].to_i, params[:start_date][:day].to_i)</tt></pre>
+</div></div>
+<div class="paragraph"><p>The :prefix option controls where in the params hash the date components will be placed. Here it was set to <tt>start_date</tt>, if omitted it will default to <tt>date</tt>.</p></div>
+<h3 id="_model_object_helpers_2">5.2. Model object helpers</h3>
+<div class="paragraph"><p><tt>select_date</tt> does not work well with forms that update or create Active Record objects as Active Record expects each element of the params hash to correspond to one attribute.
+The model object helpers for dates and times submit parameters with special names. When Active Record sees parameters with such names it knows they must be combined with the other parameters and given to a constructor appropriate to the column type. For example</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><%= date_select :person, :birth_date %></tt></pre>
+</div></div>
+<div class="paragraph"><p>outputs (with the actual option values omitted for brevity)</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><select id="person_birth_date_1i" name="person[birth_date(1i)]"> ... </select>
+<select id="person_birth_date_2i" name="person[birth_date(2i)]"> ... </select>
+<select id="person_birth_date_3i" name="person[birth_date(3i)]"> ... </select></tt></pre>
+</div></div>
+<div class="paragraph"><p>which results in a params hash like</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>{:person => {'birth_date(1i)' => '2008', 'birth_date(2i)' => '11', 'birth_date(3i)' => '22'}}</tt></pre>
+</div></div>
+<div class="paragraph"><p>When this is passed to <tt>Person.new</tt>, Active Record spots that these parameters should all be used to construct the <tt>birth_date</tt> attribute and uses the suffixed information to determine in which order it should pass these parameters to functions such as <tt>Date::civil</tt>.</p></div>
+<h3 id="_common_options">5.3. Common options</h3>
+<div class="paragraph"><p>Both families of helpers use the same core set of functions to generate the individual select tags and so both accept largely the same options. In particular, by default Rails will generate year options 5 years either side of the current year. If this is not an appropriate range, the <tt>:start_year</tt> and <tt>:end_year</tt> options override this. For an exhaustive list of the available options, refer to the <a href="http://api.rubyonrails.org/classes/ActionView/Helpers/DateHelper.html">API documentation</a>.</p></div>
+<div class="paragraph"><p>As a rule of thumb you should be using <tt>date_select</tt> when working with model objects and <tt>select_date</tt> in others cases, such as a search form which filters results by date.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">In many cases the built in date pickers are clumsy as they do not aid the user in working out the relationship between the date and the day of the week.</td>
+</tr></table>
+</div>
</div>
-<h2 id="_miscellaneous">4. Miscellaneous</h2>
+<h2 id="_form_builders">6. Form builders</h2>
<div class="sectionbody">
-<h3 id="_file_upload_form">4.1. File upload form</h3>
-<div class="paragraph"><p>:multipart - If set to true, the enctype is set to "multipart/form-data".</p></div>
-<h3 id="_scoping_out_form_controls_with_tt_fields_for_tt">4.2. Scoping out form controls with <tt>fields_for</tt></h3>
-<div class="paragraph"><p>Creates a scope around a specific model object like <tt>form_for</tt>, but doesn’t create the form tags themselves. This makes <tt>fields_for</tt> suitable for specifying additional model objects in the same form:</p></div>
-<h3 id="_making_custom_form_builders">4.3. Making custom form builders</h3>
-<div class="paragraph"><p>You can also build forms using a customized FormBuilder class. Subclass FormBuilder and override or define some more helpers, then use your custom builder. For example, let’s say you made a helper to automatically add labels to form inputs.</p></div>
+<div class="paragraph"><p>As mentioned previously the object yielded by <tt>form_for</tt> and <tt>fields_for</tt> is an instance of FormBuilder (or a subclass thereof). Form builders encapsulate the notion of displaying a form elements for a single object. While you can of course write helpers for your forms in the usual way you can also subclass FormBuilder and add the helpers there. For example</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><% form_for @person do |f| %>
+ <%= text_field_with_label f, :first_name %>
+<% end %></tt></pre>
+</div></div>
+<div class="paragraph"><p>can be replaced with</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt><% form_for :person, @person, :url => { :action => "update" }, :builder => LabellingFormBuilder do |f| %>
+<pre><tt><% form_for @person, :builder => LabellingFormBuilder do |f| %>
<%= f.text_field :first_name %>
- <%= f.text_field :last_name %>
- <%= text_area :person, :biography %>
- <%= check_box_tag "person[admin]", @person.company.admin? %>
<% end %></tt></pre>
</div></div>
+<div class="paragraph"><p>by defining a LabellingFormBuilder class similar to the following:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> LabellingFormBuilder <span style="color: #990000"><</span> FormBuilder
+ <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> text_field attribute<span style="color: #990000">,</span> options<span style="color: #990000">=</span><span style="color: #FF0000">{}</span>
+ label<span style="color: #990000">(</span>attribute<span style="color: #990000">)</span> <span style="color: #990000">+</span> text_field<span style="color: #990000">(</span>attribute<span style="color: #990000">,</span> options<span style="color: #990000">)</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
+<div class="paragraph"><p>If you reuse this frequently you could define a <tt>labeled_form_for</tt> helper that automatically applies the <tt>:builder => LabellingFormBuilder</tt> option.</p></div>
+<div class="paragraph"><p>The form builder used also determines what happens when you do</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><%= render :partial => f %></tt></pre>
+</div></div>
+<div class="paragraph"><p>If <tt>f</tt> is an instance of FormBuilder then this will render the <em>form</em> partial, setting the partial’s object to the form builder. If the form builder is of class LabellingFormBuilder then the <em>labelling_form</em> partial would be rendered instead.</p></div>
+<h3 id="_scoping_out_form_controls_with_tt_fields_for_tt">6.1. Scoping out form controls with <tt>fields_for</tt></h3>
+<div class="paragraph"><p><tt>fields_for</tt> creates a form builder in exactly the same way as <tt>form_for</tt> but doesn’t create the actual <tt><form></tt> tags. It creates a scope around a specific model object like <tt>form_for</tt>, which is useful for specifying additional model objects in the same form. For example if you had a Person model with an associated ContactDetail model you could create a form for editing both like so:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><% form_for @person do |person_form| %>
+ <%= person_form.text_field :name %>
+ <% fields_for @person.contact_detail do |contact_details_form| %>
+ <%= contact_details_form.text_field :phone_number %>
+ <% end %>
+<% end %></tt></pre>
+</div></div>
+<div class="paragraph"><p>which produces the following output:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><form action="/people/1" class="edit_person" id="edit_person_1" method="post">
+ <input id="person_name" name="person[name]" size="30" type="text" />
+ <input id="contact_detail_phone_number" name="contact_detail[phone_number]" size="30" type="text" />
+</form></tt></pre>
+</div></div>
+</div>
+<h2 id="_file_uploads">7. File Uploads</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>A common task is uploading some sort of file, whether it’s a picture of a person or a CSV file containing data to process. The most important thing to remember with file uploads is that the form’s encoding <strong>MUST</strong> be set to multipart/form-data. If you forget to do this the file will not be uploaded. This can be done by passing <tt>:multi_part => true</tt> as an HTML option. This means that in the case of <tt>form_tag</tt> it must be passed in the second options hash and in the case of <tt>form_for</tt> inside the <tt>:html</tt> hash.</p></div>
+<div class="paragraph"><p>The following two forms both upload a file.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><% form_tag({:action => :upload}, :multipart => true) do %>
+ <%= file_field_tag 'picture' %>
+<% end %>
+
+<% form_for @person, :html => {:multipart => true} do |f| %>
+ <%= f.file_field :picture %>
+<% end %></tt></pre>
+</div></div>
+<div class="paragraph"><p>Rails provides the usual pair of helpers: the barebones <tt>file_field_tag</tt> and the model oriented <tt>file_field</tt>. The only difference with other helpers is that you cannot set a default value for file inputs as this would have no meaning. As you would expect in the first case the uploaded file is in <tt>params[:picture]</tt> and in the second case in <tt>params[:person][:picture]</tt>.</p></div>
+<h3 id="_what_gets_uploaded">7.1. What gets uploaded</h3>
+<div class="paragraph"><p>The object in the params hash is an instance of a subclass of IO. Depending on the size of the uploaded file it may in fact be a StringIO or an instance of File backed by a temporary file. In both cases the object will have an <tt>original_filename</tt> attribute containing the name the file had on the user’s computer and a <tt>content_type</tt> attribute containing the MIME type of the uploaded file. The following snippet saves the uploaded content in <tt>#{RAILS_ROOT}/public/uploads</tt> under the same name as the original file (assuming the form was the one in the previous example).</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">def</span></span> upload
+ uploaded_io <span style="color: #990000">=</span> params<span style="color: #990000">[:</span>person<span style="color: #990000">][:</span>picture<span style="color: #990000">]</span>
+ File<span style="color: #990000">.</span>open<span style="color: #990000">(</span>Rails<span style="color: #990000">.</span>root<span style="color: #990000">.</span>join<span style="color: #990000">(</span><span style="color: #FF0000">'public'</span><span style="color: #990000">,</span> <span style="color: #FF0000">'uploads'</span><span style="color: #990000">,</span> uploaded_io<span style="color: #990000">.</span>original_filename<span style="color: #990000">),</span> <span style="color: #FF0000">'w'</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>file<span style="color: #990000">|</span>
+ file<span style="color: #990000">.</span>write<span style="color: #990000">(</span>uploaded_io<span style="color: #990000">.</span>read<span style="color: #990000">)</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
+<div class="paragraph"><p>Once a file has been uploaded there are a multitude of potential tasks, ranging from where to store the files (on disk, Amazon S3, etc) and associating them with models to resizing image files and generating thumbnails. The intricacies of this are beyond the scope of this guide, but there are several plugins designed to assist with these. Two of the better known ones are <a href="http://github.com/technoweenie/attachment_fu">Attachment-Fu</a> and <a href="http://www.thoughtbot.com/projects/paperclip">Paperclip</a>.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">If the user has not selected a file the corresponding parameter will be an empty string.</td>
+</tr></table>
+</div>
+<h3 id="_dealing_with_ajax">7.2. Dealing with Ajax</h3>
+<div class="paragraph"><p>Unlike other forms making an asynchronous file upload form is not as simple as replacing <tt>form_for</tt> with <tt>remote_form_for</tt>. With an AJAX form the serialization is done by javascript running inside the browser and since javascript cannot read files from your hard drive the file cannot be uploaded. The most common workaround is to use an invisible iframe that serves as the target for the form submission.</p></div>
+</div>
+<h2 id="_parameter_names">8. Parameter Names</h2>
+<div class="sectionbody">
+<div class="paragraph" id="parameter_names"><p>As you’ve seen in the previous sections values from forms can appear either at the top level of the params hash or may appear nested in another hash. For example in a standard create
+action for a Person model, <tt>params[:model]</tt> would usually be a hash of all the attributes for the person to create. The params hash can also contain arrays, arrays of hashes and so on.</p></div>
+<div class="paragraph"><p>Fundamentally HTML forms don’t know about any sort of structured data. All they know about is name-value pairs. Rails tacks some conventions onto parameter names which it uses to express some structure.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/tip.png" alt="Tip" />
+</td>
+<td class="content">
+<div class="paragraph"><p>You may find you can try out examples in this section faster by using the console to directly invoke Rails' parameter parser. For example</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>ActionController::RequestParser.parse_query_parameters "name=fred&phone=0123456789"
+#=> {"name"=>"fred", "phone"=>"0123456789"}</tt></pre>
+</div></div>
+</td>
+</tr></table>
+</div>
+<h3 id="_basic_structures">8.1. Basic structures</h3>
+<div class="paragraph"><p>The two basic structures are arrays and hashes. Hashes mirror the syntax used for accessing the value in the params. For example if a form contains</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><input id="person_name" name="person[name]" type="text" value="Henry"/></tt></pre>
+</div></div>
+<div class="paragraph"><p>the params hash will contain</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #FF0000">{</span><span style="color: #FF0000">'person'</span> <span style="color: #990000">=></span> <span style="color: #FF0000">{</span><span style="color: #FF0000">'name'</span> <span style="color: #990000">=></span> <span style="color: #FF0000">'Henry'</span><span style="color: #FF0000">}}</span></tt></pre></div></div>
+<div class="paragraph"><p>and ‘params['name\’]` will retrieve the submitted value in the controller.</p></div>
+<div class="paragraph"><p>Hashes can be nested as many levels as required, for example</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><input id="person_address_city" name="person[address][city]" type="text" value="New York"/></tt></pre>
+</div></div>
+<div class="paragraph"><p>will result in the params hash being</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #FF0000">{</span><span style="color: #FF0000">'person'</span> <span style="color: #990000">=></span> <span style="color: #FF0000">{</span><span style="color: #FF0000">'address'</span> <span style="color: #990000">=></span> <span style="color: #FF0000">{</span><span style="color: #FF0000">'city'</span> <span style="color: #990000">=></span> <span style="color: #FF0000">'New York'</span><span style="color: #FF0000">}}}</span></tt></pre></div></div>
+<div class="paragraph"><p>Normally Rails ignores duplicate parameter names. If the parameter name contains [] then they will be accumulated in an array. If you wanted people to be able to input multiple phone numbers, your could place this in the form:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><input name="person[phone_number][]" type="text"/>
+<input name="person[phone_number][]" type="text"/>
+<input name="person[phone_number][]" type="text"/></tt></pre>
+</div></div>
+<div class="paragraph"><p>This would result in <tt>params[:person][:phone_number]</tt> being an array.</p></div>
+<h3 id="_combining_them">8.2. Combining them</h3>
+<div class="paragraph"><p>We can mix and match these two concepts. For example, one element of a hash might be an array as in the previous example, or you can have an array of hashes. For example a form might let you create any number of addresses by repeating the following form fragment</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><input name="addresses[][line1]" type="text"/>
+<input name="addresses[][line2]" type="text"/>
+<input name="addresses[][city]" type="text"/></tt></pre>
+</div></div>
+<div class="paragraph"><p>This would result in <tt>params[:addresses]</tt> being an array of hashes with keys <tt>line1</tt>, <tt>line2</tt> and <tt>city</tt>. Rails decides to start accumulating values in a new hash whenever it encounters a input name that already exists in the current hash.</p></div>
+<div class="paragraph"><p>The one restriction is that although hashes can be nested arbitrarily deep then can be only one level of "arrayness". Frequently arrays can be usually replaced by hashes, for example instead of having an array of model objects one can have a hash of model objects keyed by their id.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/warning.png" alt="Warning" />
+</td>
+<td class="content">Array parameters do not play well with the <tt>check_box</tt> helper. According to the HTML specification unchecked checkboxes submit no value. However it is often convenient for a checkbox to always submit a value. The <tt>check_box</tt> helper fakes this by creating a second hidden input with the same name. If the checkbox is unchecked only the hidden input is submitted. If the checkbox is checked then both are submitted but the value submitted by the checkbox takes precedence. When working with array parameters this duplicate submission will confuse Rails since duplicate input names are how it decides when to start a new hash. It is preferable to either use <tt>check_box_tag</tt> or to use hashes instead of arrays.</td>
+</tr></table>
+</div>
+<h3 id="_using_form_helpers">8.3. Using form helpers</h3>
+<div class="paragraph"><p>The previous sections did not use the Rails form helpers at all. While you can craft the input names yourself and pass them directly to helpers such as <tt>text_field_tag</tt> Rails also provides higher level support. The two tools at your disposal here are the name parameter to <tt>form_for</tt>/<tt>fields_for</tt> and the <tt>:index</tt> option.</p></div>
+<div class="paragraph"><p>You might want to render a form with a set of edit fields for each of a person’s addresses. Something a little like this will do the trick</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><% form_for @person do |person_form| %>
+ <%= person_form.text_field :name%>
+ <% for address in @person.addresses %>
+ <% person_form.fields_for address, :index => address do |address_form|%>
+ <%= address_form.text_field :city %>
+ <% end %>
+ <% end %>
+<% end %></tt></pre>
+</div></div>
+<div class="paragraph"><p>Assuming our person had two addresses, with ids 23 and 45 this would create output similar to this:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><form action="/people/1" class="edit_person" id="edit_person_1" method="post">
+ <input id="person_name" name="person[name]" size="30" type="text" />
+ <input id="person_address_23_city" name="person[address][23][city]" size="30" type="text" />
+ <input id="person_address_45_city" name="person[address][45][city]" size="30" type="text" />
+</form></tt></pre>
+</div></div>
+<div class="paragraph"><p>This will result in a params hash that looks like</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #FF0000">{</span><span style="color: #FF0000">'person'</span> <span style="color: #990000">=></span> <span style="color: #FF0000">{</span><span style="color: #FF0000">'name'</span> <span style="color: #990000">=></span> <span style="color: #FF0000">'Bob'</span><span style="color: #990000">,</span> <span style="color: #FF0000">'address'</span> <span style="color: #990000">=></span> <span style="color: #FF0000">{</span> <span style="color: #FF0000">'23'</span> <span style="color: #990000">=></span> <span style="color: #FF0000">{</span><span style="color: #FF0000">'city'</span> <span style="color: #990000">=></span> <span style="color: #FF0000">'Paris'</span><span style="color: #FF0000">}</span><span style="color: #990000">,</span> <span style="color: #FF0000">'45'</span> <span style="color: #990000">=></span> <span style="color: #FF0000">{</span><span style="color: #FF0000">'city'</span> <span style="color: #990000">=></span> <span style="color: #FF0000">'London'</span><span style="color: #FF0000">}</span> <span style="color: #FF0000">}}}</span></tt></pre></div></div>
+<div class="paragraph"><p>Rails knows that all these inputs should be part of the person hash because you called <tt>fields_for</tt> on the first form builder. By specifying an <tt>:index</tt> option you’re telling rails that instead of naming the inputs <tt>person[address][city]</tt> it should insert that index surrounded by [] between the address and the city. If you pass an Active Record object as we did then Rails will call <tt>to_param</tt> on it, which by default returns the database id. This is often useful it is then easy to locate which Address record should be modified but you could pass numbers with some other significance, strings or even nil (which will result in an array parameter being created).</p></div>
+<div class="paragraph"><p>To create more intricate nestings, you can specify the first part of the input name (<tt>person[address]</tt> in the previous example) explicitly, for example</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><% fields_for 'person[address][primary]', address, :index => address do |address_form| %>
+ <%= address_form.text_field :city %>
+<% end %></tt></pre>
+</div></div>
+<div class="paragraph"><p>will create inputs like</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><input id="person_address_primary_1_city" name="person[address][primary][1][city]" size="30" type="text" value="bologna" /></tt></pre>
+</div></div>
+<div class="paragraph"><p>As a general rule the final input name is the concatenation of the name given to <tt>fields_for</tt>/<tt>form_for</tt>, the index value and the name of the attribute. You can also pass an <tt>:index</tt> option directly to helpers such as <tt>text_field</tt>, but usually it is less repetitive to specify this at the form builder level rather than on individual input controls.</p></div>
+<div class="paragraph"><p>As a shortcut you can append [] to the name and omit the <tt>:index</tt> option. This is the same as specifing <tt>:index => address</tt> so</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><% fields_for 'person[address][primary][]', address do |address_form| %>
+ <%= address_form.text_field :city %>
+<% end %></tt></pre>
+</div></div>
+<div class="paragraph"><p>produces exactly the same output as the previous example.</p></div>
+</div>
+<h2 id="_complex_forms">9. Complex forms</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Many apps grow beyond simple forms editing a single object. For example when creating a Person instance you might want to allow the user to (on the same form) create multiple address records (home, work etc...). When later editing that person the user should be able to add, remove or amend addresses as necessary. While this guide has shown you all the pieces necessary to handle this, Rails does not yet have a standard end-to-end way of accomplishing this, but many have come up with viable approaches. These include:</p></div>
<div class="ulist"><ul>
<li>
<p>
-<tt>form_for</tt> within a namespace
+Ryan Bates' series of railscasts on <a href="http://railscasts.com/episodes/75">complex forms</a>
+</p>
+</li>
+<li>
+<p>
+Handle Multiple Models in One Form from <a href="http://media.pragprog.com/titles/fr_arr/multiple_models_one_form.pdf">Advanced Rails Recipes</a>
+</p>
+</li>
+<li>
+<p>
+Eloy Duran’s <a href="http://github.com/alloy/complex-form-examples/tree/alloy-nested_params">nested_params</a> plugin
+</p>
+</li>
+<li>
+<p>
+Lance Ivy’s <a href="http://github.com/cainlevy/nested_assignment/tree/master">nested_assignment</a> plugin and <a href="http://github.com/cainlevy/complex-form-examples/tree/cainlevy">sample application</a>
+</p>
+</li>
+<li>
+<p>
+James Golick’s <a href="http://github.com/giraffesoft/attribute_fu/tree">attribute_fu</a> plugin
+</p>
+</li>
+</ul></div>
+</div>
+<h2 id="_changelog">10. Changelog</h2>
+<div class="sectionbody">
+<div class="paragraph"><p><a href="http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/1">Lighthouse ticket</a></p></div>
+<div class="ulist"><div class="title">Authors</div><ul>
+<li>
+<p>
+Mislav Marohnić <<a href="mailto:mislav.marohnic@gmail.com">mislav.marohnic@gmail.com</a>>
+</p>
+</li>
+<li>
+<p>
+<a href="../authors.html#fcheung">Frederick Cheung</a>
</p>
</li>
</ul></div>
-<div class="listingblock">
-<div class="content">
-<pre><tt>select_tag(name, option_tags = nil, html_options = { :multiple, :disabled })
-
-select(object, method, choices, options = {}, html_options = {})
-options_for_select(container, selected = nil)
-
-collection_select(object, method, collection, value_method, text_method, options = {}, html_options = {})
-options_from_collection_for_select(collection, value_method, text_method, selected = nil)
-
-time_zone_options_for_select(selected = nil, priority_zones = nil, model = ::ActiveSupport::TimeZone)
-time_zone_select(object, method, priority_zones = nil, options = {}, html_options = {})</tt></pre>
-</div></div>
</div>
</div> diff --git a/railties/doc/guides/html/getting_started_with_rails.html b/railties/doc/guides/html/getting_started_with_rails.html index f0b30e6218..dcf112ef6d 100644 --- a/railties/doc/guides/html/getting_started_with_rails.html +++ b/railties/doc/guides/html/getting_started_with_rails.html @@ -572,125 +572,70 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>In any case, Rails will create a folder in your working directory called <tt>blog</tt>. Open up that folder and explore its contents. Most of the work in this tutorial will happen in the <tt>app/</tt> folder, but here’s a basic rundown on the function of each folder that Rails creates in a new application by default:</p></div>
<div class="tableblock">
<table rules="all"
-frame="hsides"
+width="100%"
+frame="border"
cellspacing="0" cellpadding="4">
-<col width="137" />
-<col width="1440" />
-<thead>
- <tr>
- <th align="left">
- File/Folder
- </th>
- <th align="left">
- Purpose
- </th>
- </tr>
+<col width="50%" />
+<col width="50%" />
+<thead valign="top">
+<tr>
+<th align="left">File/Folder </th>
+<th align="left">Purpose</th>
+</tr>
</thead>
<tbody valign="top">
- <tr>
- <td align="left">
- <tt>README</tt>
- </td>
- <td align="left">
- This is a brief instruction manual for your application. Use it to tell others what your application does, how to set it up, and so on.
- </td>
- </tr>
- <tr>
- <td align="left">
- <tt>Rakefile</tt>
- </td>
- <td align="left">
- This file contains batch jobs that can be run from the terminal.
- </td>
- </tr>
- <tr>
- <td align="left">
- <tt>app/</tt>
- </td>
- <td align="left">
- Contains the controllers, models, and views for your application. You’ll focus on this folder for the remainder of this guide.
- </td>
- </tr>
- <tr>
- <td align="left">
- <tt>config/</tt>
- </td>
- <td align="left">
- Configure your application’s runtime rules, routes, database, and more.
- </td>
- </tr>
- <tr>
- <td align="left">
- <tt>db/</tt>
- </td>
- <td align="left">
- Shows your current database schema, as well as the database migrations. You’ll learn about migrations shortly.
- </td>
- </tr>
- <tr>
- <td align="left">
- <tt>doc/</tt>
- </td>
- <td align="left">
- In-depth documentation for your application.
- </td>
- </tr>
- <tr>
- <td align="left">
- <tt>lib/</tt>
- </td>
- <td align="left">
- Extended modules for your application (not covered in this guide).
- </td>
- </tr>
- <tr>
- <td align="left">
- <tt>log/</tt>
- </td>
- <td align="left">
- Application log files.
- </td>
- </tr>
- <tr>
- <td align="left">
- <tt>public/</tt>
- </td>
- <td align="left">
- The only folder seen to the world as-is. This is where your images, javascript, stylesheets (CSS), and other static files go.
- </td>
- </tr>
- <tr>
- <td align="left">
- <tt>script/</tt>
- </td>
- <td align="left">
- Scripts provided by Rails to do recurring tasks, such as benchmarking, plugin installation, and starting the console or the web server.
- </td>
- </tr>
- <tr>
- <td align="left">
- <tt>test/</tt>
- </td>
- <td align="left">
- Unit tests, fixtures, and other test apparatus. These are covered in <a href="../testing_rails_applications.html">Testing Rails Applications</a>
- </td>
- </tr>
- <tr>
- <td align="left">
- <tt>tmp/</tt>
- </td>
- <td align="left">
- Temporary files
- </td>
- </tr>
- <tr>
- <td align="left">
- <tt>vendor/</tt>
- </td>
- <td align="left">
- A place for third-party code. In a typical Rails application, this includes Ruby Gems, the Rails source code (if you install it into your project) and plugins containing additional prepackaged functionality.
- </td>
- </tr>
+<tr>
+<td align="left"><p class="table"><tt>README</tt></p></td>
+<td align="left"><p class="table">This is a brief instruction manual for your application. Use it to tell others what your application does, how to set it up, and so on.</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table"><tt>Rakefile</tt></p></td>
+<td align="left"><p class="table">This file contains batch jobs that can be run from the terminal.</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table"><tt>app/</tt></p></td>
+<td align="left"><p class="table">Contains the controllers, models, and views for your application. You’ll focus on this folder for the remainder of this guide.</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table"><tt>config/</tt></p></td>
+<td align="left"><p class="table">Configure your application’s runtime rules, routes, database, and more.</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table"><tt>db/</tt></p></td>
+<td align="left"><p class="table">Shows your current database schema, as well as the database migrations. You’ll learn about migrations shortly.</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table"><tt>doc/</tt></p></td>
+<td align="left"><p class="table">In-depth documentation for your application.</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table"><tt>lib/</tt></p></td>
+<td align="left"><p class="table">Extended modules for your application (not covered in this guide).</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table"><tt>log/</tt></p></td>
+<td align="left"><p class="table">Application log files.</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table"><tt>public/</tt></p></td>
+<td align="left"><p class="table">The only folder seen to the world as-is. This is where your images, javascript, stylesheets (CSS), and other static files go.</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table"><tt>script/</tt></p></td>
+<td align="left"><p class="table">Scripts provided by Rails to do recurring tasks, such as benchmarking, plugin installation, and starting the console or the web server.</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table"><tt>test/</tt></p></td>
+<td align="left"><p class="table">Unit tests, fixtures, and other test apparatus. These are covered in <a href="../testing_rails_applications.html">Testing Rails Applications</a></p></td>
+</tr>
+<tr>
+<td align="left"><p class="table"><tt>tmp/</tt></p></td>
+<td align="left"><p class="table">Temporary files</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table"><tt>vendor/</tt></p></td>
+<td align="left"><p class="table">A place for third-party code. In a typical Rails application, this includes Ruby Gems, the Rails source code (if you install it into your project) and plugins containing additional prepackaged functionality.</p></td>
+</tr>
</tbody>
</table>
</div>
@@ -876,133 +821,74 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>The scaffold generator will build 13 files in your application, along with some folders, and edit one more. Here’s a quick overview of what it creates:</p></div>
<div class="tableblock">
<table rules="all"
-frame="hsides"
+width="100%"
+frame="border"
cellspacing="0" cellpadding="4">
-<col width="525" />
-<col width="1062" />
-<thead>
- <tr>
- <th align="left">
- File
- </th>
- <th align="left">
- Purpose
- </th>
- </tr>
+<col width="50%" />
+<col width="50%" />
+<thead valign="top">
+<tr>
+<th align="left">File </th>
+<th align="left">Purpose</th>
+</tr>
</thead>
<tbody valign="top">
- <tr>
- <td align="left">
- app/models/post.rb
- </td>
- <td align="left">
- The Post model
- </td>
- </tr>
- <tr>
- <td align="left">
- db/migrate/20081013124235_create_posts.rb
- </td>
- <td align="left">
- Migration to create the posts table in your database (your name will include a different timestamp)
- </td>
- </tr>
- <tr>
- <td align="left">
- app/views/posts/index.html.erb
- </td>
- <td align="left">
- A view to display an index of all posts
- </td>
- </tr>
- <tr>
- <td align="left">
- app/views/posts/show.html.erb
- </td>
- <td align="left">
- A view to display a single post
- </td>
- </tr>
- <tr>
- <td align="left">
- app/views/posts/new.html.erb
- </td>
- <td align="left">
- A view to create a new post
- </td>
- </tr>
- <tr>
- <td align="left">
- app/views/posts/edit.html.erb
- </td>
- <td align="left">
- A view to edit an existing post
- </td>
- </tr>
- <tr>
- <td align="left">
- app/views/layouts/posts.html.erb
- </td>
- <td align="left">
- A view to control the overall look and feel of the other posts views
- </td>
- </tr>
- <tr>
- <td align="left">
- public/stylesheets/scaffold.css
- </td>
- <td align="left">
- Cascading style sheet to make the scaffolded views look better
- </td>
- </tr>
- <tr>
- <td align="left">
- app/controllers/posts_controller.rb
- </td>
- <td align="left">
- The Posts controller
- </td>
- </tr>
- <tr>
- <td align="left">
- test/functional/posts_controller_test.rb
- </td>
- <td align="left">
- Functional testing harness for the posts controller
- </td>
- </tr>
- <tr>
- <td align="left">
- app/helpers/posts_helper.rb
- </td>
- <td align="left">
- Helper functions to be used from the posts views
- </td>
- </tr>
- <tr>
- <td align="left">
- config/routes.rb
- </td>
- <td align="left">
- Edited to include routing information for posts
- </td>
- </tr>
- <tr>
- <td align="left">
- test/fixtures/posts.yml
- </td>
- <td align="left">
- Dummy posts for use in testing
- </td>
- </tr>
- <tr>
- <td align="left">
- test/unit/post_test.rb
- </td>
- <td align="left">
- Unit testing harness for the posts model
- </td>
- </tr>
+<tr>
+<td align="left"><p class="table">app/models/post.rb</p></td>
+<td align="left"><p class="table">The Post model</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">db/migrate/20081013124235_create_posts.rb</p></td>
+<td align="left"><p class="table">Migration to create the posts table in your database (your name will include a different timestamp)</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">app/views/posts/index.html.erb</p></td>
+<td align="left"><p class="table">A view to display an index of all posts</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">app/views/posts/show.html.erb</p></td>
+<td align="left"><p class="table">A view to display a single post</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">app/views/posts/new.html.erb</p></td>
+<td align="left"><p class="table">A view to create a new post</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">app/views/posts/edit.html.erb</p></td>
+<td align="left"><p class="table">A view to edit an existing post</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">app/views/layouts/posts.html.erb</p></td>
+<td align="left"><p class="table">A view to control the overall look and feel of the other posts views</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">public/stylesheets/scaffold.css</p></td>
+<td align="left"><p class="table">Cascading style sheet to make the scaffolded views look better</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">app/controllers/posts_controller.rb</p></td>
+<td align="left"><p class="table">The Posts controller</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">test/functional/posts_controller_test.rb</p></td>
+<td align="left"><p class="table">Functional testing harness for the posts controller</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">app/helpers/posts_helper.rb</p></td>
+<td align="left"><p class="table">Helper functions to be used from the posts views</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">config/routes.rb</p></td>
+<td align="left"><p class="table">Edited to include routing information for posts</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">test/fixtures/posts.yml</p></td>
+<td align="left"><p class="table">Dummy posts for use in testing</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">test/unit/post_test.rb</p></td>
+<td align="left"><p class="table">Unit testing harness for the posts model</p></td>
+</tr>
</tbody>
</table>
</div>
diff --git a/railties/doc/guides/html/index.html b/railties/doc/guides/html/index.html index 78dcf7194c..38e1b310d7 100644 --- a/railties/doc/guides/html/index.html +++ b/railties/doc/guides/html/index.html @@ -179,7 +179,7 @@ ul#navMain { </style> </head> <body> - <div id="header" > + <div id="header" class="notoc"> <div id="logo"> <a href="index.html" title="Ruby on Rails"><img src="images/rails_logo_remix.gif" alt="Rails" height="140" width="110" /></a> </div> @@ -193,13 +193,7 @@ ul#navMain { </ul> </div> - <div id="container"> - - <div id="sidebar"> - <h2>Chapters</h2> - <ol> - </ol> - </div> + <div id="container" class="notoc"> <div id="content"> <h1>Ruby on Rails Guides</h1> @@ -383,6 +377,11 @@ of your code.</p></div> </div>
<div class="paragraph"><p>This guide introduces you to the basic concepts and features of the Rails I18n API and shows you how to localize your application.</p></div>
</div></div>
+<div class="sidebarblock">
+<div class="sidebar-content">
+<div class="sidebar-title"><a href="configuring.html">Configuring Rails Applications</a></div>
+<div class="paragraph"><p>This guide covers the basic configuration settings for a Rails application.</p></div>
+</div></div>
<div class="paragraph"><p>Authors who have contributed to complete guides are listed <a href="authors.html">here</a>.</p></div>
<div class="paragraph"><p>This work is licensed under a <a href="http://creativecommons.org/licenses/by-nc-sa/3.0/">Creative Commons Attribution-Noncommercial-Share Alike 3.0 License</a></p></div>
</div>
diff --git a/railties/doc/guides/html/layouts_and_rendering.html b/railties/doc/guides/html/layouts_and_rendering.html index a94c2d4b57..91c3f3350d 100644 --- a/railties/doc/guides/html/layouts_and_rendering.html +++ b/railties/doc/guides/html/layouts_and_rendering.html @@ -1404,7 +1404,7 @@ http://www.gnu.org/software/src-highlite --> <div class="ulist"><ul>
<li>
<p>
-December 27, 2007: Merge patch from Rodrigo Rosenfeld Rosas covering subtemplates
+December 27, 2008: Merge patch from Rodrigo Rosenfeld Rosas covering subtemplates
</p>
</li>
<li>
diff --git a/railties/doc/guides/html/routing_outside_in.html b/railties/doc/guides/html/routing_outside_in.html index d15d6208f5..0b5ccc1219 100644 --- a/railties/doc/guides/html/routing_outside_in.html +++ b/railties/doc/guides/html/routing_outside_in.html @@ -487,152 +487,73 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>creates seven different routes in your application:</p></div>
<div class="tableblock">
<table rules="all"
-frame="hsides"
+width="100%"
+frame="border"
cellspacing="0" cellpadding="4">
-<col width="125" />
-<col width="182" />
-<col width="137" />
-<col width="102" />
-<col width="502" />
-<thead>
- <tr>
- <th align="left">
- HTTP verb
- </th>
- <th align="left">
- URL
- </th>
- <th align="left">
- controller
- </th>
- <th align="left">
- action
- </th>
- <th align="left">
- used for
- </th>
- </tr>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<thead valign="top">
+<tr>
+<th align="left">HTTP verb </th>
+<th align="left">URL </th>
+<th align="left">controller </th>
+<th align="left">action </th>
+<th align="left">used for</th>
+</tr>
</thead>
<tbody valign="top">
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /photos
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- index
- </td>
- <td align="left">
- display a list of all photos
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /photos/new
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- new
- </td>
- <td align="left">
- return an HTML form for creating a new photo
- </td>
- </tr>
- <tr>
- <td align="left">
- POST
- </td>
- <td align="left">
- /photos
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- create
- </td>
- <td align="left">
- create a new photo
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /photos/1
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- show
- </td>
- <td align="left">
- display a specific photo
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /photos/1/edit
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- edit
- </td>
- <td align="left">
- return an HTML form for editing a photo
- </td>
- </tr>
- <tr>
- <td align="left">
- PUT
- </td>
- <td align="left">
- /photos/1
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- update
- </td>
- <td align="left">
- update a specific photo
- </td>
- </tr>
- <tr>
- <td align="left">
- DELETE
- </td>
- <td align="left">
- /photos/1
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- destroy
- </td>
- <td align="left">
- delete a specific photo
- </td>
- </tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/photos</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">index</p></td>
+<td align="left"><p class="table">display a list of all photos</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/photos/new</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">new</p></td>
+<td align="left"><p class="table">return an HTML form for creating a new photo</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">POST</p></td>
+<td align="left"><p class="table">/photos</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">create</p></td>
+<td align="left"><p class="table">create a new photo</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/photos/1</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">show</p></td>
+<td align="left"><p class="table">display a specific photo</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/photos/1/edit</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">edit</p></td>
+<td align="left"><p class="table">return an HTML form for editing a photo</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">PUT</p></td>
+<td align="left"><p class="table">/photos/1</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">update</p></td>
+<td align="left"><p class="table">update a specific photo</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">DELETE</p></td>
+<td align="left"><p class="table">/photos/1</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">destroy</p></td>
+<td align="left"><p class="table">delete a specific photo</p></td>
+</tr>
</tbody>
</table>
</div>
@@ -713,135 +634,66 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>creates six different routes in your application:</p></div>
<div class="tableblock">
<table rules="all"
-frame="hsides"
+width="100%"
+frame="border"
cellspacing="0" cellpadding="4">
-<col width="125" />
-<col width="182" />
-<col width="137" />
-<col width="102" />
-<col width="502" />
-<thead>
- <tr>
- <th align="left">
- HTTP verb
- </th>
- <th align="left">
- URL
- </th>
- <th align="left">
- controller
- </th>
- <th align="left">
- action
- </th>
- <th align="left">
- used for
- </th>
- </tr>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<thead valign="top">
+<tr>
+<th align="left">HTTP verb </th>
+<th align="left">URL </th>
+<th align="left">controller </th>
+<th align="left">action </th>
+<th align="left">used for</th>
+</tr>
</thead>
<tbody valign="top">
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /geocoder/new
- </td>
- <td align="left">
- Geocoders
- </td>
- <td align="left">
- new
- </td>
- <td align="left">
- return an HTML form for creating the new geocoder
- </td>
- </tr>
- <tr>
- <td align="left">
- POST
- </td>
- <td align="left">
- /geocoder
- </td>
- <td align="left">
- Geocoders
- </td>
- <td align="left">
- create
- </td>
- <td align="left">
- create the new geocoder
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /geocoder
- </td>
- <td align="left">
- Geocoders
- </td>
- <td align="left">
- show
- </td>
- <td align="left">
- display the one and only geocoder resource
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /geocoder/edit
- </td>
- <td align="left">
- Geocoders
- </td>
- <td align="left">
- edit
- </td>
- <td align="left">
- return an HTML form for editing the geocoder
- </td>
- </tr>
- <tr>
- <td align="left">
- PUT
- </td>
- <td align="left">
- /geocoder
- </td>
- <td align="left">
- Geocoders
- </td>
- <td align="left">
- update
- </td>
- <td align="left">
- update the one and only geocoder resource
- </td>
- </tr>
- <tr>
- <td align="left">
- DELETE
- </td>
- <td align="left">
- /geocoder
- </td>
- <td align="left">
- Geocoders
- </td>
- <td align="left">
- destroy
- </td>
- <td align="left">
- delete the geocoder resource
- </td>
- </tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/geocoder/new</p></td>
+<td align="left"><p class="table">Geocoders</p></td>
+<td align="left"><p class="table">new</p></td>
+<td align="left"><p class="table">return an HTML form for creating the new geocoder</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">POST</p></td>
+<td align="left"><p class="table">/geocoder</p></td>
+<td align="left"><p class="table">Geocoders</p></td>
+<td align="left"><p class="table">create</p></td>
+<td align="left"><p class="table">create the new geocoder</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/geocoder</p></td>
+<td align="left"><p class="table">Geocoders</p></td>
+<td align="left"><p class="table">show</p></td>
+<td align="left"><p class="table">display the one and only geocoder resource</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/geocoder/edit</p></td>
+<td align="left"><p class="table">Geocoders</p></td>
+<td align="left"><p class="table">edit</p></td>
+<td align="left"><p class="table">return an HTML form for editing the geocoder</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">PUT</p></td>
+<td align="left"><p class="table">/geocoder</p></td>
+<td align="left"><p class="table">Geocoders</p></td>
+<td align="left"><p class="table">update</p></td>
+<td align="left"><p class="table">update the one and only geocoder resource</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">DELETE</p></td>
+<td align="left"><p class="table">/geocoder</p></td>
+<td align="left"><p class="table">Geocoders</p></td>
+<td align="left"><p class="table">destroy</p></td>
+<td align="left"><p class="table">delete the geocoder resource</p></td>
+</tr>
</tbody>
</table>
</div>
@@ -937,152 +789,73 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>will recognize incoming URLs containing <tt>photo</tt> but route the requests to the Images controller:</p></div>
<div class="tableblock">
<table rules="all"
-frame="hsides"
+width="100%"
+frame="border"
cellspacing="0" cellpadding="4">
-<col width="125" />
-<col width="182" />
-<col width="137" />
-<col width="102" />
-<col width="502" />
-<thead>
- <tr>
- <th align="left">
- HTTP verb
- </th>
- <th align="left">
- URL
- </th>
- <th align="left">
- controller
- </th>
- <th align="left">
- action
- </th>
- <th align="left">
- used for
- </th>
- </tr>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<thead valign="top">
+<tr>
+<th align="left">HTTP verb </th>
+<th align="left">URL </th>
+<th align="left">controller </th>
+<th align="left">action </th>
+<th align="left">used for</th>
+</tr>
</thead>
<tbody valign="top">
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /photos
- </td>
- <td align="left">
- Images
- </td>
- <td align="left">
- index
- </td>
- <td align="left">
- display a list of all images
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /photos/new
- </td>
- <td align="left">
- Images
- </td>
- <td align="left">
- new
- </td>
- <td align="left">
- return an HTML form for creating a new image
- </td>
- </tr>
- <tr>
- <td align="left">
- POST
- </td>
- <td align="left">
- /photos
- </td>
- <td align="left">
- Images
- </td>
- <td align="left">
- create
- </td>
- <td align="left">
- create a new image
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /photos/1
- </td>
- <td align="left">
- Images
- </td>
- <td align="left">
- show
- </td>
- <td align="left">
- display a specific image
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /photos/1/edit
- </td>
- <td align="left">
- Images
- </td>
- <td align="left">
- edit
- </td>
- <td align="left">
- return an HTML form for editing a image
- </td>
- </tr>
- <tr>
- <td align="left">
- PUT
- </td>
- <td align="left">
- /photos/1
- </td>
- <td align="left">
- Images
- </td>
- <td align="left">
- update
- </td>
- <td align="left">
- update a specific image
- </td>
- </tr>
- <tr>
- <td align="left">
- DELETE
- </td>
- <td align="left">
- /photos/1
- </td>
- <td align="left">
- Images
- </td>
- <td align="left">
- destroy
- </td>
- <td align="left">
- delete a specific image
- </td>
- </tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/photos</p></td>
+<td align="left"><p class="table">Images</p></td>
+<td align="left"><p class="table">index</p></td>
+<td align="left"><p class="table">display a list of all images</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/photos/new</p></td>
+<td align="left"><p class="table">Images</p></td>
+<td align="left"><p class="table">new</p></td>
+<td align="left"><p class="table">return an HTML form for creating a new image</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">POST</p></td>
+<td align="left"><p class="table">/photos</p></td>
+<td align="left"><p class="table">Images</p></td>
+<td align="left"><p class="table">create</p></td>
+<td align="left"><p class="table">create a new image</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/photos/1</p></td>
+<td align="left"><p class="table">Images</p></td>
+<td align="left"><p class="table">show</p></td>
+<td align="left"><p class="table">display a specific image</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/photos/1/edit</p></td>
+<td align="left"><p class="table">Images</p></td>
+<td align="left"><p class="table">edit</p></td>
+<td align="left"><p class="table">return an HTML form for editing a image</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">PUT</p></td>
+<td align="left"><p class="table">/photos/1</p></td>
+<td align="left"><p class="table">Images</p></td>
+<td align="left"><p class="table">update</p></td>
+<td align="left"><p class="table">update a specific image</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">DELETE</p></td>
+<td align="left"><p class="table">/photos/1</p></td>
+<td align="left"><p class="table">Images</p></td>
+<td align="left"><p class="table">destroy</p></td>
+<td align="left"><p class="table">delete a specific image</p></td>
+</tr>
</tbody>
</table>
</div>
@@ -1166,152 +939,73 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>will recognize incoming URLs containing <tt>image</tt> but route the requests to the Photos controller:</p></div>
<div class="tableblock">
<table rules="all"
-frame="hsides"
+width="100%"
+frame="border"
cellspacing="0" cellpadding="4">
-<col width="125" />
-<col width="182" />
-<col width="137" />
-<col width="102" />
-<col width="502" />
-<thead>
- <tr>
- <th align="left">
- HTTP verb
- </th>
- <th align="left">
- URL
- </th>
- <th align="left">
- controller
- </th>
- <th align="left">
- action
- </th>
- <th align="left">
- used for
- </th>
- </tr>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<thead valign="top">
+<tr>
+<th align="left">HTTP verb </th>
+<th align="left">URL </th>
+<th align="left">controller </th>
+<th align="left">action </th>
+<th align="left">used for</th>
+</tr>
</thead>
<tbody valign="top">
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /images
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- index
- </td>
- <td align="left">
- display a list of all photos
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /images/new
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- new
- </td>
- <td align="left">
- return an HTML form for creating a new photo
- </td>
- </tr>
- <tr>
- <td align="left">
- POST
- </td>
- <td align="left">
- /images
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- create
- </td>
- <td align="left">
- create a new photo
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /images/1
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- show
- </td>
- <td align="left">
- display a specific photo
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /images/1/edit
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- edit
- </td>
- <td align="left">
- return an HTML form for editing a photo
- </td>
- </tr>
- <tr>
- <td align="left">
- PUT
- </td>
- <td align="left">
- /images/1
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- update
- </td>
- <td align="left">
- update a specific photo
- </td>
- </tr>
- <tr>
- <td align="left">
- DELETE
- </td>
- <td align="left">
- /images/1
- </td>
- <td align="left">
- Photos
- </td>
- <td align="left">
- destroy
- </td>
- <td align="left">
- delete a specific photo
- </td>
- </tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/images</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">index</p></td>
+<td align="left"><p class="table">display a list of all photos</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/images/new</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">new</p></td>
+<td align="left"><p class="table">return an HTML form for creating a new photo</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">POST</p></td>
+<td align="left"><p class="table">/images</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">create</p></td>
+<td align="left"><p class="table">create a new photo</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/images/1</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">show</p></td>
+<td align="left"><p class="table">display a specific photo</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/images/1/edit</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">edit</p></td>
+<td align="left"><p class="table">return an HTML form for editing a photo</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">PUT</p></td>
+<td align="left"><p class="table">/images/1</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">update</p></td>
+<td align="left"><p class="table">update a specific photo</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">DELETE</p></td>
+<td align="left"><p class="table">/images/1</p></td>
+<td align="left"><p class="table">Photos</p></td>
+<td align="left"><p class="table">destroy</p></td>
+<td align="left"><p class="table">delete a specific photo</p></td>
+</tr>
</tbody>
</table>
</div>
@@ -1459,152 +1153,73 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>In addition to the routes for magazines, this declaration will also create routes for ads, each of which requires the specification of a magazine in the URL:</p></div>
<div class="tableblock">
<table rules="all"
-frame="hsides"
+width="100%"
+frame="border"
cellspacing="0" cellpadding="4">
-<col width="125" />
-<col width="274" />
-<col width="137" />
-<col width="102" />
-<col width="502" />
-<thead>
- <tr>
- <th align="left">
- HTTP verb
- </th>
- <th align="left">
- URL
- </th>
- <th align="left">
- controller
- </th>
- <th align="left">
- action
- </th>
- <th align="left">
- used for
- </th>
- </tr>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<thead valign="top">
+<tr>
+<th align="left">HTTP verb </th>
+<th align="left">URL </th>
+<th align="left">controller </th>
+<th align="left">action </th>
+<th align="left">used for</th>
+</tr>
</thead>
<tbody valign="top">
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /magazines/1/ads
- </td>
- <td align="left">
- Ads
- </td>
- <td align="left">
- index
- </td>
- <td align="left">
- display a list of all ads for a specific magazine
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /magazines/1/ads/new
- </td>
- <td align="left">
- Ads
- </td>
- <td align="left">
- new
- </td>
- <td align="left">
- return an HTML form for creating a new ad belonging to a specific magazine
- </td>
- </tr>
- <tr>
- <td align="left">
- POST
- </td>
- <td align="left">
- /magazines/1/ads
- </td>
- <td align="left">
- Ads
- </td>
- <td align="left">
- create
- </td>
- <td align="left">
- create a new ad belonging to a specific magazine
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /magazines/1/ads/1
- </td>
- <td align="left">
- Ads
- </td>
- <td align="left">
- show
- </td>
- <td align="left">
- display a specific ad belonging to a specific magazine
- </td>
- </tr>
- <tr>
- <td align="left">
- GET
- </td>
- <td align="left">
- /magazines/1/ads/1/edit
- </td>
- <td align="left">
- Ads
- </td>
- <td align="left">
- edit
- </td>
- <td align="left">
- return an HTML form for editing an ad belonging to a specific magazine
- </td>
- </tr>
- <tr>
- <td align="left">
- PUT
- </td>
- <td align="left">
- /magazines/1/ads/1
- </td>
- <td align="left">
- Ads
- </td>
- <td align="left">
- update
- </td>
- <td align="left">
- update a specific ad belonging to a specific magazine
- </td>
- </tr>
- <tr>
- <td align="left">
- DELETE
- </td>
- <td align="left">
- /magazines/1/ads/1
- </td>
- <td align="left">
- Ads
- </td>
- <td align="left">
- destroy
- </td>
- <td align="left">
- delete a specific ad belonging to a specific magazine
- </td>
- </tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/magazines/1/ads</p></td>
+<td align="left"><p class="table">Ads</p></td>
+<td align="left"><p class="table">index</p></td>
+<td align="left"><p class="table">display a list of all ads for a specific magazine</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/magazines/1/ads/new</p></td>
+<td align="left"><p class="table">Ads</p></td>
+<td align="left"><p class="table">new</p></td>
+<td align="left"><p class="table">return an HTML form for creating a new ad belonging to a specific magazine</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">POST</p></td>
+<td align="left"><p class="table">/magazines/1/ads</p></td>
+<td align="left"><p class="table">Ads</p></td>
+<td align="left"><p class="table">create</p></td>
+<td align="left"><p class="table">create a new ad belonging to a specific magazine</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/magazines/1/ads/1</p></td>
+<td align="left"><p class="table">Ads</p></td>
+<td align="left"><p class="table">show</p></td>
+<td align="left"><p class="table">display a specific ad belonging to a specific magazine</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">GET</p></td>
+<td align="left"><p class="table">/magazines/1/ads/1/edit</p></td>
+<td align="left"><p class="table">Ads</p></td>
+<td align="left"><p class="table">edit</p></td>
+<td align="left"><p class="table">return an HTML form for editing an ad belonging to a specific magazine</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">PUT</p></td>
+<td align="left"><p class="table">/magazines/1/ads/1</p></td>
+<td align="left"><p class="table">Ads</p></td>
+<td align="left"><p class="table">update</p></td>
+<td align="left"><p class="table">update a specific ad belonging to a specific magazine</p></td>
+</tr>
+<tr>
+<td align="left"><p class="table">DELETE</p></td>
+<td align="left"><p class="table">/magazines/1/ads/1</p></td>
+<td align="left"><p class="table">Ads</p></td>
+<td align="left"><p class="table">destroy</p></td>
+<td align="left"><p class="table">delete a specific ad belonging to a specific magazine</p></td>
+</tr>
</tbody>
</table>
</div>
diff --git a/railties/doc/guides/source/configuring.txt b/railties/doc/guides/source/configuring.txt index 945e48cd45..489e205eb1 100644 --- a/railties/doc/guides/source/configuring.txt +++ b/railties/doc/guides/source/configuring.txt @@ -6,23 +6,43 @@ This guide covers the configuration and initialization features available to Rai * Adjust the behavior of your Rails applications * Add additional code to be run at application start time +NOTE: The first edition of this Guide was written from the Rails 2.3 source code. While the information it contains is broadly applicable to Rails 2.2, backwards compatibility is not guaranteed. + == Locations for Initialization Code -preinitializers -environment.rb first -env-specific files -initializers (load_application_initializers) -after-initializer +Rails offers (at least) five good spots to place initialization code: + +* Preinitializers +* environment.rb +* Environment-specific Configuration Files +* Initializers (load_application_initializers) +* After-Initializers == Using a Preinitializer -== Initialization Process Settings +Rails allows you to use a preinitializer to run code before the framework itself is loaded. If you save code in +RAILS_ROOT/config/preinitializer.rb+, that code will be the first thing loaded, before any of the framework components (Active Record, Action Pack, and so on.) If you want to change the behavior of one of the classes that is used in the initialization process, you can do so in this file. == Configuring Rails Components +In general, the work of configuring Rails means configuring the components of Rails, as well as configuring Rails itself. The +environment.rb+ and environment-specific configuration files (such as +config/environments/production.rb+) allow you to specify the various settings that you want to pass down to all of the components. For example, the default Rails 2.3 +environment.rb+ file includes one setting: + +[source, ruby] +------------------------------------------------------- +config.time_zone = 'UTC' +------------------------------------------------------- + +This is a setting for Rails itself. If you want to pass settings to individual Rails components, you can do so via the same +config+ object: + +[source, ruby] +------------------------------------------------------- +config.active_record.colorize_logging = false +------------------------------------------------------- + +Rails will use that particular setting to configure Active Record. + === Configuring Active Record -+ActiveRecord::Base+ includej a variety of configuration options: ++ActiveRecord::Base+ includes a variety of configuration options: +logger+ accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then passed on to any new database connections made. You can retrieve this logger by calling +logger+ on either an ActiveRecord model class or an ActiveRecord model instance. Set to nil to disable logging. @@ -125,21 +145,21 @@ There are a number of settings available on +ActionMailer::Base+: +smtp_settings+ allows detailed configuration for the +:smtp+ delivery method. It accepts a hash of options, which can include any of these options: -* <tt>:address</tt> - Allows you to use a remote mail server. Just change it from its default "localhost" setting. -* <tt>:port</tt> - On the off chance that your mail server doesn't run on port 25, you can change it. -* <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>. +* +:address+ - Allows you to use a remote mail server. Just change it from its default "localhost" setting. +* +:port+ - On the off chance that your mail server doesn't run on port 25, you can change it. +* +:domain+ - If you need to specify a HELO domain, you can do it here. +* +:user_name+ - If your mail server requires authentication, set the username in this setting. +* +:password+ - If your mail server requires authentication, set the password in this setting. +* +:authentication+ - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of +:plain+, +:login+, +:cram_md5+. +sendmail_settings+ allows detailed configuration for the +sendmail+ delivery method. It accepts a hash of options, which can include any of these options: -* <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>. +* +:location+ - The location of the sendmail executable. Defaults to +/usr/sbin/sendmail+. +* +:arguments+ - The command line arguments. Defaults to +-i -t+. +raise_delivery_errors+ specifies whether to raise an error if email delivery cannot be completed. It defaults to +true+. -+delivery_method+ defines the delivery method. The allowed values are <tt>:smtp</tt> (default), <tt>:sendmail</tt>, and <tt>:test</tt>. ++delivery_method+ defines the delivery method. The allowed values are +:smtp+ (default), +:sendmail+, and +:test+. +perform_deliveries+ specifies whether mail will actually be delivered. By default this is +true+; it can be convenient to set it to +false+ for testing. @@ -151,7 +171,7 @@ There are a number of settings available on +ActionMailer::Base+: +default_implicit_parts_order+ - 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 -<tt>["text/html", "text/enriched", "text/plain"]</tt>. Items that appear first in the array have higher priority in the mail client ++["text/html", "text/enriched", "text/plain"]+. Items that appear first in the array have higher priority in the mail client and appear last in the mime encoded message. === Configuring Active Resource @@ -174,21 +194,46 @@ There are a few configuration options available in Active Support: Active Model currently has a single configuration setting: -+ActiveModel::Errors.default_error_messages is an array containing all of the validation error messages. ++ActiveModel::Errors.default_error_messages+ is an array containing all of the validation error messages. == Using Initializers - organization, controlling load order + +After it loads the framework plus any gems and plugins in your application, Rails turns to loading initializers. An initializer is any file of ruby code stored under +/config/initializers+ in your application. You can use initializers to hold configuration settings that should be made after all of the frameworks and plugins are loaded. + +NOTE: You can use subfolders to organize your initializers if you like, because Rails will look into the whole file hierarchy from the +initializers+ folder on down. + +TIP: If you have any ordering dependency in your initializers, you can control the load order by naming. For example, +01_critical.rb+ will be loaded before +02_normal.rb+. == Using an After-Initializer +After-initializers are run (as you might guess) after any initializers are loaded. You can supply an +after_initialize+ block (or an array of such blocks) by setting up +config.after_initialize+ in any of the Rails configuration files: + +[source, ruby] +------------------------------------------------------------------ +config.after_initialize do + SomeClass.init +end +------------------------------------------------------------------ + +WARNING: Some parts of your application, notably observers and routing, are not yet set up at the point where the +after_initialize+ block is called. + == Rails Environment Settings -ENV +Some parts of Rails can also be configured externally by supplying environment variables. The following environment variables are recognized by various parts of Rails: + ++ENV['RAILS_ENV']+ defines the Rails environment (production, development, test, and so on) that Rails will run under. + ++ENV['RAILS_RELATIVE_URL_ROOT']+ is used by the routing code to recognize URLs when you deploy your application to a subdirectory. + ++ENV["RAILS_ASSET_ID"]+ will override the default cache-busting timestamps that Rails generates for downloadable assets. + ++ENV["RAILS_CACHE_ID"]+ and +ENV["RAILS_APP_VERSION"]+ are used to generate expanded cache keys in Rails' caching code. This allows you to have multiple separate caches from the same application. + ++ENV['RAILS_GEM_VERSION']+ defines the version of the Rails gems to use, if +RAILS_GEM_VERSION+ is not defined in your +environment.rb+ file. == Changelog == http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/28[Lighthouse ticket] +* January 3, 2009: First reasonably complete draft by link:../authors.html#mgunderloy[Mike Gunderloy] * November 5, 2008: Rough outline by link:../authors.html#mgunderloy[Mike Gunderloy] - -need to look for def self. ??? diff --git a/railties/doc/guides/source/getting_started_with_rails.txt b/railties/doc/guides/source/getting_started_with_rails.txt index 58eff9fd3d..7e87c2935e 100644 --- a/railties/doc/guides/source/getting_started_with_rails.txt +++ b/railties/doc/guides/source/getting_started_with_rails.txt @@ -163,24 +163,23 @@ $ cd blog In any case, Rails will create a folder in your working directory called +blog+. Open up that folder and explore its contents. Most of the work in this tutorial will happen in the +app/+ folder, but here's a basic rundown on the function of each folder that Rails creates in a new application by default: -[grid="all"] -`-----------`----------------------------------------------------------------------------------------------------------------------------- -File/Folder Purpose ------------------------------------------------------------------------------------------------------------------------------------------- -+README+ This is a brief instruction manual for your application. Use it to tell others what your application does, how to set it up, and so on. -+Rakefile+ This file contains batch jobs that can be run from the terminal. -+app/+ Contains the controllers, models, and views for your application. You'll focus on this folder for the remainder of this guide. -+config/+ Configure your application's runtime rules, routes, database, and more. -+db/+ Shows your current database schema, as well as the database migrations. You'll learn about migrations shortly. -+doc/+ In-depth documentation for your application. -+lib/+ Extended modules for your application (not covered in this guide). -+log/+ Application log files. -+public/+ The only folder seen to the world as-is. This is where your images, javascript, stylesheets (CSS), and other static files go. -+script/+ Scripts provided by Rails to do recurring tasks, such as benchmarking, plugin installation, and starting the console or the web server. -+test/+ Unit tests, fixtures, and other test apparatus. These are covered in link:../testing_rails_applications.html[Testing Rails Applications] -+tmp/+ Temporary files -+vendor/+ A place for third-party code. In a typical Rails application, this includes Ruby Gems, the Rails source code (if you install it into your project) and plugins containing additional prepackaged functionality. -------------------------------------------------------------------------------------------------------------------------------------------- +[options="header"] +|========================================================================================================== +|File/Folder |Purpose +|+README+ |This is a brief instruction manual for your application. Use it to tell others what your application does, how to set it up, and so on. +|+Rakefile+ |This file contains batch jobs that can be run from the terminal. +|+app/+ |Contains the controllers, models, and views for your application. You'll focus on this folder for the remainder of this guide. +|+config/+ |Configure your application's runtime rules, routes, database, and more. +|+db/+ |Shows your current database schema, as well as the database migrations. You'll learn about migrations shortly. +|+doc/+ |In-depth documentation for your application. +|+lib/+ |Extended modules for your application (not covered in this guide). +|+log/+ |Application log files. +|+public/+ |The only folder seen to the world as-is. This is where your images, javascript, stylesheets (CSS), and other static files go. +|+script/+ |Scripts provided by Rails to do recurring tasks, such as benchmarking, plugin installation, and starting the console or the web server. +|+test/+ |Unit tests, fixtures, and other test apparatus. These are covered in link:../testing_rails_applications.html[Testing Rails Applications] +|+tmp/+ |Temporary files +|+vendor/+ |A place for third-party code. In a typical Rails application, this includes Ruby Gems, the Rails source code (if you install it into your project) and plugins containing additional prepackaged functionality. +|========================================================================================================== === Configuring a Database @@ -339,25 +338,24 @@ NOTE: While scaffolding will get you up and running quickly, the "one size fits The scaffold generator will build 13 files in your application, along with some folders, and edit one more. Here's a quick overview of what it creates: -[grid="all"] -`---------------------------------------------`-------------------------------------------------------------------------------------------- -File Purpose ------------------------------------------------------------------------------------------------------------------------------------------- -app/models/post.rb The Post model -db/migrate/20081013124235_create_posts.rb Migration to create the posts table in your database (your name will include a different timestamp) -app/views/posts/index.html.erb A view to display an index of all posts -app/views/posts/show.html.erb A view to display a single post -app/views/posts/new.html.erb A view to create a new post -app/views/posts/edit.html.erb A view to edit an existing post -app/views/layouts/posts.html.erb A view to control the overall look and feel of the other posts views -public/stylesheets/scaffold.css Cascading style sheet to make the scaffolded views look better -app/controllers/posts_controller.rb The Posts controller -test/functional/posts_controller_test.rb Functional testing harness for the posts controller -app/helpers/posts_helper.rb Helper functions to be used from the posts views -config/routes.rb Edited to include routing information for posts -test/fixtures/posts.yml Dummy posts for use in testing -test/unit/post_test.rb Unit testing harness for the posts model -------------------------------------------------------------------------------------------------------------------------------------------- +[options="header"] +|========================================================================================================== +|File |Purpose +|app/models/post.rb |The Post model +|db/migrate/20081013124235_create_posts.rb |Migration to create the posts table in your database (your name will include a different timestamp) +|app/views/posts/index.html.erb |A view to display an index of all posts +|app/views/posts/show.html.erb |A view to display a single post +|app/views/posts/new.html.erb |A view to create a new post +|app/views/posts/edit.html.erb |A view to edit an existing post +|app/views/layouts/posts.html.erb |A view to control the overall look and feel of the other posts views +|public/stylesheets/scaffold.css |Cascading style sheet to make the scaffolded views look better +|app/controllers/posts_controller.rb |The Posts controller +|test/functional/posts_controller_test.rb |Functional testing harness for the posts controller +|app/helpers/posts_helper.rb |Helper functions to be used from the posts views +|config/routes.rb |Edited to include routing information for posts +|test/fixtures/posts.yml |Dummy posts for use in testing +|test/unit/post_test.rb |Unit testing harness for the posts model +|========================================================================================================== === Running a Migration diff --git a/railties/doc/guides/source/index.txt b/railties/doc/guides/source/index.txt index 174267d630..cd536873e7 100644 --- a/railties/doc/guides/source/index.txt +++ b/railties/doc/guides/source/index.txt @@ -132,8 +132,10 @@ CAUTION: still a basic draft This guide introduces you to the basic concepts and features of the Rails I18n API and shows you how to localize your application. *********************************************************** - - +.link:configuring.html[Configuring Rails Applications] +*********************************************************** +This guide covers the basic configuration settings for a Rails application. +*********************************************************** Authors who have contributed to complete guides are listed link:authors.html[here]. diff --git a/railties/doc/guides/source/layouts_and_rendering.txt b/railties/doc/guides/source/layouts_and_rendering.txt index 5834307d7b..23cb83c512 100644 --- a/railties/doc/guides/source/layouts_and_rendering.txt +++ b/railties/doc/guides/source/layouts_and_rendering.txt @@ -1028,7 +1028,7 @@ There are several ways of getting similar results with differents sub-templating http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/15[Lighthouse ticket] -* December 27, 2007: Merge patch from Rodrigo Rosenfeld Rosas covering subtemplates +* December 27, 2008: Merge patch from Rodrigo Rosenfeld Rosas covering subtemplates * December 27, 2008: Information on new rendering defaults by link:../authors.html#mgunderloy[Mike Gunderloy] * November 9, 2008: Added partial collection counter by link:../authors.html#mgunderloy[Mike Gunderloy] * November 1, 2008: Added +:js+ option for +render+ by link:../authors.html#mgunderloy[Mike Gunderloy] diff --git a/railties/doc/guides/source/routing_outside_in.txt b/railties/doc/guides/source/routing_outside_in.txt index 3f6c80de5c..235832e4f3 100644 --- a/railties/doc/guides/source/routing_outside_in.txt +++ b/railties/doc/guides/source/routing_outside_in.txt @@ -132,18 +132,17 @@ map.resources :photos creates seven different routes in your application: -[grid="all"] -`----------`---------------`-----------`--------`------------------------------------------- -HTTP verb URL controller action used for --------------------------------------------------------------------------------------------- -GET /photos Photos index display a list of all photos -GET /photos/new Photos new return an HTML form for creating a new photo -POST /photos Photos create create a new photo -GET /photos/1 Photos show display a specific photo -GET /photos/1/edit Photos edit return an HTML form for editing a photo -PUT /photos/1 Photos update update a specific photo -DELETE /photos/1 Photos destroy delete a specific photo --------------------------------------------------------------------------------------------- +[options="header"] +|========================================================================================================== +|HTTP verb |URL |controller |action |used for +|GET |/photos |Photos |index |display a list of all photos +|GET |/photos/new |Photos |new |return an HTML form for creating a new photo +|POST |/photos |Photos |create |create a new photo +|GET |/photos/1 |Photos |show |display a specific photo +|GET |/photos/1/edit |Photos |edit |return an HTML form for editing a photo +|PUT |/photos/1 |Photos |update |update a specific photo +|DELETE |/photos/1 |Photos |destroy |delete a specific photo +|========================================================================================================== For the specific routes (those that reference just a single resource), the identifier for the resource will be available within the corresponding controller action as +params[:id]+. @@ -197,17 +196,16 @@ map.resource :geocoder creates six different routes in your application: -[grid="all"] -`----------`---------------`-----------`--------`------------------------------------------- -HTTP verb URL controller action used for --------------------------------------------------------------------------------------------- -GET /geocoder/new Geocoders new return an HTML form for creating the new geocoder -POST /geocoder Geocoders create create the new geocoder -GET /geocoder Geocoders show display the one and only geocoder resource -GET /geocoder/edit Geocoders edit return an HTML form for editing the geocoder -PUT /geocoder Geocoders update update the one and only geocoder resource -DELETE /geocoder Geocoders destroy delete the geocoder resource --------------------------------------------------------------------------------------------- +[options="header"] +|========================================================================================================== +|HTTP verb |URL |controller |action |used for +|GET |/geocoder/new |Geocoders |new |return an HTML form for creating the new geocoder +|POST |/geocoder |Geocoders |create |create the new geocoder +|GET |/geocoder |Geocoders |show |display the one and only geocoder resource +|GET |/geocoder/edit |Geocoders |edit |return an HTML form for editing the geocoder +|PUT |/geocoder |Geocoders |update |update the one and only geocoder resource +|DELETE |/geocoder |Geocoders |destroy |delete the geocoder resource +|========================================================================================================== NOTE: Even though the name of the resource is singular in +routes.rb+, the matching controller is still plural. @@ -245,18 +243,17 @@ map.resources :photos, :controller => "images" will recognize incoming URLs containing +photo+ but route the requests to the Images controller: -[grid="all"] -`----------`---------------`-----------`--------`------------------------------------------- -HTTP verb URL controller action used for --------------------------------------------------------------------------------------------- -GET /photos Images index display a list of all images -GET /photos/new Images new return an HTML form for creating a new image -POST /photos Images create create a new image -GET /photos/1 Images show display a specific image -GET /photos/1/edit Images edit return an HTML form for editing a image -PUT /photos/1 Images update update a specific image -DELETE /photos/1 Images destroy delete a specific image --------------------------------------------------------------------------------------------- +[options="header"] +|========================================================================================================== +|HTTP verb |URL |controller |action |used for +|GET |/photos |Images |index |display a list of all images +|GET |/photos/new |Images |new |return an HTML form for creating a new image +|POST |/photos |Images |create |create a new image +|GET |/photos/1 |Images |show |display a specific image +|GET |/photos/1/edit |Images |edit |return an HTML form for editing a image +|PUT |/photos/1 |Images |update |update a specific image +|DELETE |/photos/1 |Images |destroy |delete a specific image +|========================================================================================================== NOTE: The helpers will be generated with the name of the resource, not the name of the controller. So in this case, you'd still get +photos_path+, +new_photo_path+, and so on. @@ -328,18 +325,17 @@ map.resources :photos, :as => "images" will recognize incoming URLs containing +image+ but route the requests to the Photos controller: -[grid="all"] -`----------`---------------`-----------`--------`------------------------------------------- -HTTP verb URL controller action used for --------------------------------------------------------------------------------------------- -GET /images Photos index display a list of all photos -GET /images/new Photos new return an HTML form for creating a new photo -POST /images Photos create create a new photo -GET /images/1 Photos show display a specific photo -GET /images/1/edit Photos edit return an HTML form for editing a photo -PUT /images/1 Photos update update a specific photo -DELETE /images/1 Photos destroy delete a specific photo --------------------------------------------------------------------------------------------- +[options="header"] +|========================================================================================================== +|HTTP verb |URL |controller |action |used for +|GET |/images |Photos |index |display a list of all photos +|GET |/images/new |Photos |new |return an HTML form for creating a new photo +|POST |/images |Photos |create |create a new photo +|GET |/images/1 |Photos |show |display a specific photo +|GET |/images/1/edit |Photos |edit |return an HTML form for editing a photo +|PUT |/images/1 |Photos |update |update a specific photo +|DELETE |/images/1 |Photos |destroy |delete a specific photo +|========================================================================================================== NOTE: The helpers will be generated with the name of the resource, not the path name. So in this case, you'd still get +photos_path+, +new_photo_path+, and so on. @@ -452,18 +448,17 @@ end In addition to the routes for magazines, this declaration will also create routes for ads, each of which requires the specification of a magazine in the URL: -[grid="all"] -`----------`-----------------------`-----------`--------`------------------------------------------- -HTTP verb URL controller action used for --------------------------------------------------------------------------------------------- -GET /magazines/1/ads Ads index display a list of all ads for a specific magazine -GET /magazines/1/ads/new Ads new return an HTML form for creating a new ad belonging to a specific magazine -POST /magazines/1/ads Ads create create a new ad belonging to a specific magazine -GET /magazines/1/ads/1 Ads show display a specific ad belonging to a specific magazine -GET /magazines/1/ads/1/edit Ads edit return an HTML form for editing an ad belonging to a specific magazine -PUT /magazines/1/ads/1 Ads update update a specific ad belonging to a specific magazine -DELETE /magazines/1/ads/1 Ads destroy delete a specific ad belonging to a specific magazine --------------------------------------------------------------------------------------------- +[options="header"] +|========================================================================================================== +|HTTP verb |URL |controller |action |used for +|GET |/magazines/1/ads |Ads |index |display a list of all ads for a specific magazine +|GET |/magazines/1/ads/new |Ads |new |return an HTML form for creating a new ad belonging to a specific magazine +|POST |/magazines/1/ads |Ads |create |create a new ad belonging to a specific magazine +|GET |/magazines/1/ads/1 |Ads |show |display a specific ad belonging to a specific magazine +|GET |/magazines/1/ads/1/edit |Ads |edit |return an HTML form for editing an ad belonging to a specific magazine +|PUT |/magazines/1/ads/1 |Ads |update |update a specific ad belonging to a specific magazine +|DELETE |/magazines/1/ads/1 |Ads |destroy |delete a specific ad belonging to a specific magazine +|========================================================================================================== This will also create routing helpers such as +magazine_ads_url+ and +edit_magazine_ad_path+. |