From 7bcdb8a9e01b153a3abd4ad11b09a393254b5b3e Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Fri, 23 Jan 2009 15:11:40 +0000 Subject: Add Mailer to the index page and regenerate --- railties/doc/guides/html/form_helpers.html | 68 +++++++++++++++++------------- 1 file changed, 39 insertions(+), 29 deletions(-) (limited to 'railties/doc/guides/html/form_helpers.html') diff --git a/railties/doc/guides/html/form_helpers.html b/railties/doc/guides/html/form_helpers.html index 54155cddb6..978beb4223 100644 --- a/railties/doc/guides/html/form_helpers.html +++ b/railties/doc/guides/html/form_helpers.html @@ -36,7 +36,7 @@
  • Generic search form
    • -
  • Multiple hashes in form helper attributes
    • +
  • Multiple hashes in form helper calls
  • Helpers for generating form elements
    • @@ -125,22 +125,32 @@
    @@ -163,7 +173,7 @@ Learn what makes a file upload form different; Form contents <% end %> -

    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):

    +

    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):

    Sample output from form_tag
    @@ -174,7 +184,7 @@ Learn what makes a file upload form different; Form contents </form>
    -

    If you carefully observe this output, you can see that the helper generated something you didn’t specify: a div element with a hidden input inside. This is a security feature of Rails called cross-site request forgery protection and form helpers generate it for every form which action isn’t "GET" (provided that this security feature is enabled).

    +

    If you carefully observe this output, you can see that the helper generated something you didn’t specify: a div element with a hidden input inside. This is a security feature of Rails called cross-site request forgery protection and form helpers generate it for every form whose action is not "get" (provided that this security feature is enabled).

    - +
    @@ -212,10 +222,10 @@ a submit element. Important 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.Always use "GET" as the method for search forms. This allows users are able to bookmark a specific search and get back to it, more generally Rails encourages you to use the right HTTP verb for an action.
    -

    To create that, you will use form_tag, label_tag, text_field_tag and submit_tag, respectively.

    +

    To create this form you will use form_tag, label_tag, text_field_tag and submit_tag, respectively.

    A basic search form
    @@ -258,8 +268,8 @@ a submit element. 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.
    -

    1.2. Multiple hashes in form helper attributes

    -

    By now you’ve seen that the form_tag 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.

    +

    1.2. Multiple hashes in form helper calls

    +

    By now you’ve seen that the form_tag 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.

    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:

    A bad way to pass multiple hashes as method arguments
    @@ -284,7 +294,7 @@ a submit element.

    1.3. Helpers for generating form elements

    -

    Rails provides a series of helpers for generating form elements such as checkboxes, text fields, radio buttons and so. These basic helpers, with names ending in _tag such as text_field_tag, check_box_tag just generate a single <input> element. The first parameter to these is always the name of the input. This is the name under which value will appear in the params hash in the controller. For example if the form contains

    +

    Rails provides a series of helpers for generating form elements such as checkboxes, text fields, radio buttons and so. These basic helpers, with names ending in _tag such as text_field_tag, check_box_tag just generate a single <input> element. The first parameter to these is always the name of the input. In the controller, this name will be the key in the params hash used to get the value entered by the user. For example if the form contains

    <%= text_field_tag(:query) %>
    @@ -294,7 +304,7 @@ a submit element. 
    params[:query]
    -

    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 parameter names section. For details on the precise usage of these helpers, please refer to the API documentation.

    +

    to retrieve the value entered by the user. When naming inputs be aware that Rails uses certain conventions that control whether values are 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 parameter names section. For details on the precise usage of these helpers, please refer to the API documentation.

    1.3.1. Checkboxes

    Checkboxes are form controls that give the user a set of options they can enable or disable:

    @@ -311,7 +321,7 @@ output: <input id="pet_cat" name="pet_cat" type="checkbox" value="1" /> <label for="pet_cat">I own a cat</label>
    -

    The second parameter to check_box_tag is the value of the input. This is the value that will be submitted by the browser if the checkbox is ticked (i.e. the value that will be present in the params hash). With the above form you would check the value of params[:pet_dog] and params[:pet_cat] to see which pets the user owns.

    +

    The second parameter to check_box_tag is the value of the input. This is the value that will be submitted by the browser if the checkbox is ticked (i.e. the value that will be present in the params hash). With the above form you would check the value of params[:pet_dog] and params[:pet_cat] to see which pets the user owns.

    1.3.2. Radio buttons

    Radio buttons, while similar to checkboxes, are controls that specify a set of options in which they are mutually exclusive (user can only pick one):

    @@ -328,7 +338,7 @@ output: <input id="age_adult" name="age" type="radio" value="adult" /> <label for="age_adult">I'm over 21</label>
    -

    As with check_box_tag the second parameter to radio_button_tag is the value of the input. Because these two radio buttons share the same name (age) the user will only be able to select one and params[:age] will contain either child or adult.

    +

    As with check_box_tag the second parameter to radio_button_tag is the value of the input. Because these two radio buttons share the same name (age) the user will only be able to select one and params[:age] will contain either "child" or "adult".

    @@ -439,7 +449,7 @@ Methods to create form controls are called on the form builder <input name="commit" type="submit" value="Create" /> </form> -

    The name passed to form_for controls where in the params hash the form values will appear. Here the name is article and so all the inputs have names of the form article[attribute_name]. Accordingly, in the create action params[:article] will be a hash with keys :title and :body. You can read more about the significance of input names in the parameter names section.

    +

    The name passed to form_for controls the key used in params for form’s values. Here the name is article and so all the inputs have names of the form article[attribute_name]. Accordingly, in the create action params[:article] will be a hash with keys :title and :body. You can read more about the significance of input names in the parameter names section.

    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.

    You can create a similar binding without actually creating <form> tags with the fields_for helper. This is useful for editing additional model objects with 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:

    @@ -572,7 +582,7 @@ output: Tip
    		-

    The second argument to options_for_select must be exactly equal to the desired internal value. In particular if the internal value is the integer 2 you cannot pass "2" to options_for_select — you must pass 2. Be aware of values extracted from the params hash as they are all strings.

    +

    The second argument to options_for_select must be exactly equal to the desired internal value. In particular if the internal value is the integer 2 you cannot pass "2" to options_for_select — you must pass 2. Be aware of values extracted from the params hash as they are all strings.
    @@ -605,7 +615,7 @@ output: 
    ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got Fixnum(#1138750)
    -

    when you pass the params hash to Person.new or update_attributes. Another way of looking at this is that form helpers only edit attributes.

    +

    when you pass the params hash to Person.new or update_attributes. Another way of looking at this is that form helpers only edit attributes.

    @@ -647,7 +657,7 @@ output:

    1. -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. +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.

    2. @@ -675,9 +685,9 @@ Other helpers use the _tag suffix to indicate whether a helper is a barebones he 
      Date::civil(params[:start_date][:year].to_i, params[:start_date][:month].to_i, params[:start_date][:day].to_i)
    -

    The :prefix option controls where in the params hash the date components will be placed. Here it was set to start_date, if omitted it will default to date.

    +

    The :prefix option controls where in the params hash the date components will be placed. Here it was set to start_date, if omitted it will default to date.

    4.2. Model object helpers

    -

    select_date 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. +

    select_date 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

    @@ -690,7 +700,7 @@ The model object helpers for dates and times submit parameters with special name <select id="person_birth_date_2i" name="person[birth_date(2i)]"> ... </select> <select id="person_birth_date_3i" name="person[birth_date(3i)]"> ... </select>
    -

    which results in a params hash like

    +

    which results in a params hash like

    {:person => {'birth_date(1i)' => '2008', 'birth_date(2i)' => '11', 'birth_date(3i)' => '22'}}
    @@ -724,7 +734,7 @@ The model object helpers for dates and times submit parameters with special name

    Rails provides the usual pair of helpers: the barebones file_field_tag and the model oriented file_field. 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 params[:picture] and in the second case in params[:person][:picture].

    5.1. What gets uploaded

    -

    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 original_filename attribute containing the name the file had on the user’s computer and a content_type attribute containing the MIME type of the uploaded file. The following snippet saves the uploaded content in #{RAILS_ROOT}/public/uploads under the same name as the original file (assuming the form was the one in the previous example).

    +

    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 original_filename attribute containing the name the file had on the user’s computer and a content_type attribute containing the MIME type of the uploaded file. The following snippet saves the uploaded content in #{RAILS_ROOT}/public/uploads under the same name as the original file (assuming the form was the one in the previous example).

    7. Understanding Parameter Naming Conventions

    -

    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, params[:model] 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.

    +

    As you’ve seen in the previous sections, values from forms can be at the top level of the params hash or nested in another hash. For example in a standard create +action for a Person model, params[:model] 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.

    Fundamentally HTML forms don’t know about any sort of structured data, all they generate is name-value pairs. The arrays and hashes you see in your application are the result of some parameter naming conventions that Rails uses.

    @@ -804,12 +814,12 @@ action for a Person model, params[:model] would usually be a hash of al

    7.1. Basic structures

    -

    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

    +

    The two basic structures are arrays and hashes. Hashes mirror the syntax used for accessing the value in params. For example if a form contains

    <input id="person_name" name="person[name]" type="text" value="Henry"/>
    -

    the params hash will contain

    +

    the params hash will contain

    <input id="person_address_city" name="person[address][city]" type="text" value="New York"/>
    -

    will result in the params hash being

    +

    will result in the params hash being

    <input id="person_address_45_city" name="person[address][45][city]" size="30" type="text" /> </form>
    -

    This will result in a params hash that looks like

    +

    This will result in a params hash that looks like