Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Added documentation to the FormBuilder class #10122

Merged
merged 1 commit into from

4 participants

@wangjohn

This should help clarify issue #10115. The documentation attempts to explain what the FormBuilder class does.

I've also changed the field_helpers attribute to an explicit list of methods. The reason I did this was because the old way of defining the field_helpers called FormHelper.instance_methods and subtracted away some methods. It is hard to figure out what methods these are without running the code, so I think that this change so make things more readable and understandable. Thoughts?

@wangjohn wangjohn Added documentation to the FormBuilder class, should help
clarify issue #10115. Also made the field_helpers an explicit list of
methods.
fb24f41
@egilburg

+1

@egilburg egilburg commented on the diff
actionpack/lib/action_view/helpers/form_helper.rb
@@ -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 %>
@egilburg
egilburg added a note

You use person_form var name here, yet |f| in line 1195. Could they be made consistent?

@wangjohn
wangjohn added a note

Ah, sorry this diff isn't very clear. The above is for the documentation for the fields_for method. Here's what it looked like before:

      #   <%= 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 <%= f.submit %> to correct an error.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@egilburg egilburg commented on the diff
actionpack/lib/action_view/helpers/form_helper.rb
((51 lines not shown))
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]
@egilburg
egilburg added a note

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.

@wangjohn
wangjohn added a note

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@senny
Owner
@rafaelfranca rafaelfranca merged commit 436d918 into rails:master
@wangjohn wangjohn deleted the wangjohn:adding_documentation_to_form_builder branch
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Apr 7, 2013
  1. @wangjohn

    Added documentation to the FormBuilder class, should help

    wangjohn authored
    clarify issue #10115. Also made the field_helpers an explicit list of
    methods.
This page is out of date. Refresh to see the latest.
Showing with 55 additions and 2 deletions.
  1. +55 −2 actionpack/lib/action_view/helpers/form_helper.rb
View
57 actionpack/lib/action_view/helpers/form_helper.rb
@@ -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]
@egilburg
egilburg added a note

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.

@wangjohn
wangjohn added a note

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ 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 %>
@egilburg
egilburg added a note

You use person_form var name here, yet |f| in line 1195. Could they be made consistent?

@wangjohn
wangjohn added a note

Ah, sorry this diff isn't very clear. The above is for the documentation for the fields_for method. Here's what it looked like before:

      #   <%= 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 <%= f.submit %> to correct an error.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
# <% end %>
#
# In this case, the checkbox field will be represented by an HTML +input+
Something went wrong with that request. Please try again.