From e033b5d037c303a34e0c5aec2b38ec6270f00f86 Mon Sep 17 00:00:00 2001
From: Pratik Naik <pratiknaik@gmail.com>
Date: Sat, 25 Jul 2009 16:03:58 +0100
Subject: Merge docrails

---
 railties/guides/source/form_helpers.textile | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

(limited to 'railties/guides/source/form_helpers.textile')

diff --git a/railties/guides/source/form_helpers.textile b/railties/guides/source/form_helpers.textile
index 22d24b0903..ac0769e219 100644
--- a/railties/guides/source/form_helpers.textile
+++ b/railties/guides/source/form_helpers.textile
@@ -211,9 +211,7 @@ h4. Binding a Form to an Object
 
 While this is an increase in comfort it is far from perfect. If Person has many attributes to edit then we would be repeating the name of the edited object many times. What we want to do is somehow bind a form to a model object, which is exactly what +form_for+ does.
 
-Assume we have a controller for dealing with articles:
-
-articles_controller.rb:
+Assume we have a controller for dealing with articles +app/controllers/articles_controller.rb+:
 
 <ruby>
 def new
@@ -221,9 +219,7 @@ def new
 end
 </ruby>
 
-The corresponding view using +form_for+ looks like this
-
-articles/new.html.erb:
+The corresponding view +app/views/articles/new.html.erb+ using +form_for+ looks like this:
 
 <erb>
 <% form_for :article, @article, :url => { :action => "create" }, :html => {:class => "nifty_form"} do |f| %>
@@ -278,7 +274,13 @@ The object yielded by +fields_for+ is a form builder like the one yielded by +fo
 
 h4. Relying on Record Identification
 
-The Article model is directly available to users of the application, so -- following the best practices for developing with Rails -- you should declare it *a resource*.
+The Article model is directly available to users of the application, so -- following the best practices for developing with Rails -- you should declare it *a resource*:
+
+<ruby>
+map.resources :articles
+</ruby>
+
+TIP: Declaring a resource has a number of side-affects. See "Rails Routing From the Outside In":routing.html#restful-routing-the-rails-default for more information on setting up and using resources.
 
 When dealing with RESTful resources, calls to +form_for+ can get significantly easier if you rely on *record identification*. In short, you can just pass the model instance and have Rails figure out model name and the rest:
 
@@ -316,7 +318,7 @@ will create a form that submits to the articles controller inside the admin name
 form_for [:admin, :management, @article]
 </ruby>
 
-For more information on Rails' routing system and the associated conventions, please see the "routing guide":./routing_outside_in.html.
+For more information on Rails' routing system and the associated conventions, please see the "routing guide":routing.html.
 
 
 h4. How do forms with PUT or DELETE methods work?
@@ -464,7 +466,7 @@ To leverage time zone support in Rails, you have to ask your users what time zon
 
 There is also +time_zone_options_for_select+ 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.
 
-Rails _used_ to have a +country_select+ helper for choosing countries, but this has been extracted to the "country_select plugin":http://github.com/rails/country_select/tree/master. When using this, 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).
+Rails _used_ to have a +country_select+ helper for choosing countries, but this has been extracted to the "country_select plugin":http://github.com/rails/country_select/tree/master. When using this, 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).
 
 h3. Using Date and Time Form Helpers
 
@@ -584,7 +586,7 @@ h4. Dealing with Ajax
 
 Unlike other forms making an asynchronous file upload form is not as simple as replacing +form_for+ with +remote_form_for+. 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.
 
-h3. Customising Form Builders
+h3. Customizing Form Builders
 
 As mentioned previously the object yielded by +form_for+ and +fields_for+ is an instance of FormBuilder (or a subclass thereof). Form builders encapsulate the notion of displaying 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
 
@@ -718,7 +720,7 @@ This will result in a +params+ hash that looks like
 {'person' => {'name' => 'Bob', 'address' => {'23' => {'city' => 'Paris'}, '45' => {'city' => 'London'}}}}
 </ruby>
 
-Rails knows that all these inputs should be part of the person hash because you called +fields_for+ on the first form builder. By specifying an +:index+ option you're telling rails that instead of naming the inputs +person[address][city]+ 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 +to_param+ on it, which by default returns the database id. This is often useful as it is then easy to locate which Address record should be modified. You can pass numbers with some other significance, strings or even +nil+ (which will result in an array parameter being created).
+Rails knows that all these inputs should be part of the person hash because you called +fields_for+ on the first form builder. By specifying an +:index+ option you're telling Rails that instead of naming the inputs +person[address][city]+ 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 +to_param+ on it, which by default returns the database id. This is often useful as it is then easy to locate which Address record should be modified. You can pass numbers with some other significance, strings or even +nil+ (which will result in an array parameter being created).
 
 To create more intricate nestings, you can specify the first part of the input name (+person[address]+ in the previous example) explicitly, for example
 
@@ -736,7 +738,7 @@ will create inputs like
 
 As a general rule the final input name is the concatenation of the name given to +fields_for+/+form_for+, the index value and the name of the attribute. You can also pass an +:index+ option directly to helpers such as +text_field+, but it is usually less repetitive to specify this at the form builder level rather than on individual input controls.
 
-As a shortcut you can append [] to the name and omit the +:index+ option. This is the same as specifing +:index => address+ so
+As a shortcut you can append [] to the name and omit the +:index+ option. This is the same as specifying +:index => address+ so
 
 <erb>
 <% fields_for 'person[address][primary][]', address do |address_form| %>
@@ -750,7 +752,7 @@ h3. Building Complex Forms
 
 Many apps grow beyond simple forms editing a single object. For example when creating a Person 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:
 
-* Ryan Bates' series of railscasts on "complex forms":http://railscasts.com/episodes/75
+* Ryan Bates' series of Railscasts on "complex forms":http://railscasts.com/episodes/75
 * Handle Multiple Models in One Form from "Advanced Rails Recipes":http://media.pragprog.com/titles/fr_arr/multiple_models_one_form.pdf
 * Eloy Duran's "nested_params":http://github.com/alloy/complex-form-examples/tree/alloy-nested_params plugin
 * Lance Ivy's "nested_assignment":http://github.com/cainlevy/nested_assignment/tree/master plugin and "sample application":http://github.com/cainlevy/complex-form-examples/tree/cainlevy
-- 
cgit v1.2.3

