Skip to content
This repository
Browse code

Rearrange the date and form builder sections

  • Loading branch information...
commit 2e1cd2e1fdeb13367d29847252c9400ceae7ca90 1 parent e94dfb2
Frederick Cheung fcheung authored

Showing 1 changed file with 27 additions and 26 deletions. Show diff stats Hide diff stats

  1. +27 26 railties/doc/guides/source/form_helpers.txt
53 railties/doc/guides/source/form_helpers.txt
@@ -456,7 +456,8 @@ There is also `time_zone_options_for_select` helper for a more manual (therefore
456 456 Rails _used_ to have a `country_select` helper for choosing countries but this has been extracted to the http://github.com/rails/country_select/tree/master[country_select plugin]. 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)
457 457
458 458 Date and time select boxes
459   -~~~~~~~~~~~~~~~~~~~~~~~~~~
  459 +--------------------------
  460 +
460 461 The date and time helpers differ from all the other form helpers in two important respects:
461 462
462 463 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.
@@ -465,7 +466,7 @@ The date and time helpers differ from all the other form helpers in two importan
465 466 Both of these families of helpers will create a series of select boxes for the different components (year, month, day etc...).
466 467
467 468 Barebones helpers
468   -^^^^^^^^^^^^^^^^^
  469 +~~~~~~~~~~~~~~~~~
469 470 The `select_*` 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
470 471
471 472 -----------
@@ -484,7 +485,7 @@ Date::civil(params[:start_date][:year].to_i, params[:start_date][:month].to_i, p
484 485 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`
485 486
486 487 Model object helpers
487   -^^^^^^^^^^^^^^^^^^^^
  488 +~~~~~~~~~~~~~~~~~~~~
488 489 `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.
489 490 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
490 491 ---------------
@@ -505,35 +506,13 @@ which results in a params hash like
505 506 When this is passed to `Person.new`, Active Record spots that these parameters should all be used to construct the `birth_date` attribute and uses the suffixed information to determine in which order it should pass these parameters to functions such as `Date::civil`.
506 507
507 508 Common options
508   -^^^^^^^^^^^^^^
  509 +~~~~~~~~~~~~~~
509 510 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 `:start_year` and `:end_year` options override this. For an exhaustive list of the available options, refer to the http://api.rubyonrails.org/classes/ActionView/Helpers/DateHelper.html[API documentation].
510 511
511 512 As a rule of thumb you should be using `date_select` when working with model objects and `select_date` in others cases, such as a search for which filters results by date.
512 513
513 514 NOTE: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
514 515
515   -Scoping out form controls with `fields_for`
516   --------------------------------------------
517   -
518   -`fields_for` creates a form builder in exactly the same way as `form_for` but doesn't create the actual `<form>` tags. It creates a scope around a specific model object like `form_for`, 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:
519   --------------
520   -<% form_for @person do |person_form| %>
521   - <%= person_form.text_field :name %>
522   - <% fields_for @person.contact_detail do |contact_details_form| %>
523   - <%= contact_details_form.text_field :phone_number %>
524   - <% end %>
525   -<% end %>
526   --------------
527   -
528   -which produces the following output:
529   -
530   --------------
531   -<form action="/people/1" class="edit_person" id="edit_person_1" method="post">
532   - <input id="person_name" name="person[name]" size="30" type="text" />
533   - <input id="contact_detail_phone_number" name="contact_detail[phone_number]" size="30" type="text" />
534   -</form>
535   --------------
536   -
537 516 Form builders
538 517 -------------
539 518
@@ -566,6 +545,28 @@ The form builder used also determines what happens when you do
566 545 ------
567 546 If `f` is an instance of FormBuilder then this will render the 'form' partial, setting the partial's object to the form builder. If the form builder is of class LabellingFormBuilder then the 'labelling_form' partial would be rendered instead.
568 547
  548 +Scoping out form controls with `fields_for`
  549 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  550 +
  551 +`fields_for` creates a form builder in exactly the same way as `form_for` but doesn't create the actual `<form>` tags. It creates a scope around a specific model object like `form_for`, 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:
  552 +-------------
  553 +<% form_for @person do |person_form| %>
  554 + <%= person_form.text_field :name %>
  555 + <% fields_for @person.contact_detail do |contact_details_form| %>
  556 + <%= contact_details_form.text_field :phone_number %>
  557 + <% end %>
  558 +<% end %>
  559 +-------------
  560 +
  561 +which produces the following output:
  562 +
  563 +-------------
  564 +<form action="/people/1" class="edit_person" id="edit_person_1" method="post">
  565 + <input id="person_name" name="person[name]" size="30" type="text" />
  566 + <input id="contact_detail_phone_number" name="contact_detail[phone_number]" size="30" type="text" />
  567 +</form>
  568 +-------------
  569 +
569 570
570 571 Parameter Names
571 572 ---------------

0 comments on commit 2e1cd2e

Please sign in to comment.
Something went wrong with that request. Please try again.