github/rails
1
1
Fork 0
mirror of https://github.com/github/rails.git synced 2026-04-26 03:00:59 -04:00
Code Issues Packages Projects Releases Wiki Activity

move the fields_for/form builder section higher up

Browse Source
This commit is contained in:
Frederick Cheung
2009-01-01 10:39:22 +00:00
parent 2ea0c3d61b
commit ebfa76e3ac
1 changed files with 55 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
railties/doc/guides/source/form_helpers.txt
View File

@@ -512,6 +512,61 @@ As a rule of thumb you should be using `date_select` when working with model obj
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
Scoping out form controls with `fields_for`
-------------------------------------------
`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:
-------------
<% 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 %>
-------------
which produces the following output:
-------------
<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>
-------------
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 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
----------
<% form_for @person do |f| %>
<%= text_field_with_label f, :first_name %>
<% end %>
----------
can be replaced with
----------
<% form_for @person, :builder => LabellingFormBuilder do |f| %>
<%= f.text_field :first_name %>
<% end %>
----------
by defining a LabellingFormBuilder class similar to the following:
-------
class LabellingFormBuilder < FormBuilder
def text_field attribute, options={}
label(attribute) + text_field(attribute, options)
end
end
-------
If you reuse this frequently you could define a `labeled_form_for` helper that automatically applies the `:builder => LabellingFormBuilder` option.
The form builder used also determines what happens when you do
------
<%= render :partial => f %>
------
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.
Parameter Names
---------------
[[parameter_names]]
@@ -581,59 +636,6 @@ File upload form
:multipart - If set to true, the enctype is set to "multipart/form-data".
Scoping out form controls with `fields_for`
-------------------------------------------
`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:
-------------
<% 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 %>
-------------
which produces the following output:
-------------
<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>
-------------
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 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
----------
<% form_for @person do |f| %>
<%= text_field_with_label f, :first_name %>
<% end %>
----------
can be replaced with
----------
<% form_for @person, :builder => LabellingFormBuilder do |f| %>
<%= f.text_field :first_name %>
<% end %>
----------
by defining a LabellingFormBuilder class similar to the following:
-------
class LabellingFormBuilder < FormBuilder
def text_field attribute, options={}
label(attribute) + text_field(attribute, options)
end
end
-------
If you reuse this frequently you could define a `labeled_form_for` helper that automatically applies the `:builder => LabellingFormBuilder` option.
The form builder used also determines what happens when you do
------
<%= render :partial => f %>
------
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.
* `form_for` within a namespace