New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Added documentation to the FormBuilder class #10122
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -1152,12 +1152,65 @@ def default_form_builder | |
end | ||
end | ||
|
||
# A +FormBuilder+ object is associated with a particular model object and | ||
# allows you to generate fields associated with the model object. The | ||
# +FormBuilder+ object is yielded when using +form_for+ or +fields_for+. | ||
# For example: | ||
# | ||
# <%= form_for @person do |person_form| %> | ||
# Name: <%= person_form.text_field :name %> | ||
# Admin: <%= person_form.check_box :admin %> | ||
# <% end %> | ||
# | ||
# In the above block, the a +FormBuilder+ object is yielded as the | ||
# +person_form+ variable. This allows you to generate the +text_field+ | ||
# and +check_box+ fields by specifying their eponymous methods, which | ||
# modify the underlying template and associates the +@person+ model object | ||
# with the form. | ||
# | ||
# The +FormBuilder+ object can be thought of as serving as a proxy for the | ||
# methods in the +FormHelper+ module. This class, however, allows you to | ||
# call methods with the model object you are building the form for. | ||
# | ||
# You can create your own custom FormBuilder templates by subclasses this | ||
# class. For example: | ||
# | ||
# class MyFormBuilder < ActionView::Helpers::FormBuilder | ||
# def div_radio_button(method, tag_value, options = {}) | ||
# @template.content_tag(:div, | ||
# @template.radio_button( | ||
# @object_name, method, tag_value, objectify_options(options) | ||
# ) | ||
# ) | ||
# end | ||
# | ||
# The above code creates a new method +div_radio_button+ which wraps a div | ||
# around the a new radio button. Note that when options are passed in, you | ||
# must called +objectify_options+ in order for the model object to get | ||
# correctly passed to the method. If +objectify_options+ is not called, | ||
# then the newly created helper will not be linked back to the model. | ||
# | ||
# The +div_radio_button+ code from above can now be used as follows: | ||
# | ||
# <%= form_for @person, :builder => MyFormBuilder do |f| %> | ||
# I am a child: <%= f.div_radio_button(:admin, "child") %> | ||
# I am an adult: <%= f.div_radio_button(:admin, "adult") %> | ||
# <% end -%> | ||
# | ||
# The standard set of helper methods for form building are located in the | ||
# +field_helpers+ class attribute. | ||
class FormBuilder | ||
include ModelNaming | ||
|
||
# The methods which wrap a form helper call. | ||
class_attribute :field_helpers | ||
self.field_helpers = FormHelper.instance_methods - [:form_for, :convert_to_model, :model_name_from_record_or_class] | ||
self.field_helpers = [:fields_for, :label, :text_field, :password_field, | ||
:hidden_field, :file_field, :text_area, :check_box, | ||
:radio_button, :color_field, :search_field, | ||
:telephone_field, :phone_field, :date_field, | ||
:time_field, :datetime_field, :datetime_local_field, | ||
:month_field, :week_field, :url_field, :email_field, | ||
:number_field, :range_field] | ||
|
||
attr_accessor :object_name, :object, :options | ||
|
||
|
@@ -1239,7 +1292,7 @@ def #{selector}(method, options = {}) # def text_field(method, options = {}) | |
# Admin? : <%= permission_fields.check_box :admin %> | ||
# <% end %> | ||
# | ||
# <%= f.submit %> | ||
# <%= person_form.submit %> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You use person_form var name here, yet |f| in line 1195. Could they be made consistent? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ah, sorry this diff isn't very clear. The above is for the documentation for the # <%= form_for @person do |person_form| %>
# First name: <%= person_form.text_field :first_name %>
# Last name : <%= person_form.text_field :last_name %>
#
# <%= fields_for :permission, @person.permission do |permission_fields| %>
# Admin? : <%= permission_fields.check_box :admin %>
# <% end %>
#
# <%= f.submit %>
# <% end %> I'm just changing the |
||
# <% end %> | ||
# | ||
# In this case, the checkbox field will be represented by an HTML +input+ | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this just for clarity? It could be extra maintenance if they have to be changed in both places every time another field is added/removed.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, this is just for clarity. I was wondering about thoughts on this. Obviously, this method requires extra maintenance, but it might be worth the added clarity because (at least in my opinion), it makes it clearer what fields are being passed when the helper method wrappers are defined https://github.com/rails/rails/blob/master/actionpack/lib/action_view/helpers/form_helper.rb#L1206-1216.