From 177734836fc66fc9f1076dc99c6641c42348566e Mon Sep 17 00:00:00 2001 From: Mark Thomson Date: Thu, 8 Mar 2012 15:46:08 -0600 Subject: Small correction to the description of the role of the form builder. (endpoints are generated by form_for without reference to the form builder) --- actionpack/lib/action_view/helpers/form_helper.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 7492ef56c6..6de53bbb95 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -19,7 +19,7 @@ module ActionView # Forms for models are created with +form_for+. That method yields a form # builder that knows the model the form is about. The form builder is thus # able to generate default values for input fields that correspond to model - # attributes, and also convenient names, IDs, endpoints, etc. + # attributes, and also convenient names, and IDs, etc. # # Conventions in the generated field names allow controllers to receive form # data nicely structured in +params+ with no effort on your side. -- cgit v1.2.3 From 05801ffe2dca913796a1da2964e71ccef4d411e5 Mon Sep 17 00:00:00 2001 From: Mark Thomson Date: Thu, 8 Mar 2012 19:04:25 -0600 Subject: Additional preamble comments in form_helper.rb. --- actionpack/lib/action_view/helpers/form_helper.rb | 25 ++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 6de53bbb95..865914c1b7 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -16,17 +16,28 @@ module ActionView # Form helpers are designed to make working with resources much easier # compared to using vanilla HTML. # - # Forms for models are created with +form_for+. That method yields a form - # builder that knows the model the form is about. The form builder is thus - # able to generate default values for input fields that correspond to model - # attributes, and also convenient names, and IDs, etc. + # Typically, a form designed to create or update a resource reflects the + # identity of the resource in several ways: (i) the url that the form is + # sent to (the form element's +action+ attribute) should result in a request + # being routed to the appropriate controller action (with the appropriate :id + # parameter in the case of an existing resource), and (ii) input fields should + # be named in such a way that in the controller their values appear in the + # appropriate places within the +params+ hash. Also for an existing record, + # when the form is initially displayed, input fields corresponding to attributes + # of the resource should show the current values of those attributes. # - # Conventions in the generated field names allow controllers to receive form - # data nicely structured in +params+ with no effort on your side. + # In Rails, this is usually achieved by creating the form using +form_for+ and + # a number of related helper methods. +form_for+ generates an appropriate form + # tag and yields a form builder object that knows the model the form is about. + # Input fields are created by calling methods defined on the form builder, which + # means they are able to generate the appropriate names and default values + # corresponding to the model attributes, as well as convenient IDs, etc. + # Conventions in the generated field names allow controllers to receive form data + # nicely structured in +params+ with no effort on your side. # # For example, to create a new person you typically set up a new instance of # +Person+ in the PeopleController#new action, @person, and - # pass it to +form_for+: + # in the view template pass that object to +form_for+: # # <%= form_for @person do |f| %> # <%= f.label :first_name %>: -- cgit v1.2.3 From 2562404624bc7d314d05842f4e238aa145b5c78f Mon Sep 17 00:00:00 2001 From: Alexey Vakhov Date: Fri, 9 Mar 2012 19:28:38 +0400 Subject: Fix comment about layout folders lookup --- actionpack/lib/abstract_controller/layouts.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/abstract_controller/layouts.rb b/actionpack/lib/abstract_controller/layouts.rb index 92e93cbee7..b02ee5ead3 100644 --- a/actionpack/lib/abstract_controller/layouts.rb +++ b/actionpack/lib/abstract_controller/layouts.rb @@ -136,8 +136,8 @@ module AbstractController # layout "weblog_standard" # end # - # If no directory is specified for the template name, the template will by default be looked for in app/views/layouts/. - # Otherwise, it will be looked up relative to the template root. + # The template will be looked always in app/views/layouts/ folder. But you can point + # layouts folder direct also. layout "layouts/demo" is the same as layout "demo". # # Setting the layout to nil forces it to be looked up in the filesystem and fallbacks to the parent behavior if none exists. # Setting it to nil is useful to re-enable template lookup overriding a previous configuration set in the parent: -- cgit v1.2.3 From 23c4efbb5b8804bc029423ef620c1e38914e1565 Mon Sep 17 00:00:00 2001 From: Alexey Vakhov Date: Sat, 10 Mar 2012 09:45:13 +0400 Subject: Fix layout method doc formatting --- actionpack/lib/abstract_controller/layouts.rb | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/abstract_controller/layouts.rb b/actionpack/lib/abstract_controller/layouts.rb index b02ee5ead3..a82e3dc90a 100644 --- a/actionpack/lib/abstract_controller/layouts.rb +++ b/actionpack/lib/abstract_controller/layouts.rb @@ -238,8 +238,7 @@ module AbstractController # # If the specified layout is a: # String:: the String is the template name - # Symbol:: call the method specified by the symbol, which will return - # the template name + # Symbol:: call the method specified by the symbol, which will return the template name # false:: There is no layout # true:: raise an ArgumentError # -- cgit v1.2.3 From 69142aa4ddf9a833aea483ea4c8d0844c5b9ae08 Mon Sep 17 00:00:00 2001 From: Mark Thomson Date: Sat, 10 Mar 2012 01:51:13 -0600 Subject: Revised explanation of form_for usage --- actionpack/lib/action_view/helpers/form_helper.rb | 137 +++++++++++++--------- 1 file changed, 84 insertions(+), 53 deletions(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 865914c1b7..41173de2e7 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -120,29 +120,14 @@ module ActionView object.respond_to?(:to_model) ? object.to_model : object end - # Creates a form and a scope around a specific model object that is used - # as a base for questioning about values for the fields. + # Creates a form that allows the user to create or update the attributes + # of a specific model object. # - # Rails provides succinct resource-oriented form generation with +form_for+ - # like this: - # - # <%= form_for @offer do |f| %> - # <%= f.label :version, 'Version' %>: - # <%= f.text_field :version %>
- # <%= f.label :author, 'Author' %>: - # <%= f.text_field :author %>
- # <%= f.submit %> - # <% end %> - # - # There, +form_for+ is able to generate the rest of RESTful form - # parameters based on introspection on the record, but to understand what - # it does we need to dig first into the alternative generic usage it is - # based upon. - # - # === Generic form_for - # - # The generic way to call +form_for+ yields a form builder around a - # model: + # The method can be used in several slightly different ways, depending on + # how much you wish to rely on Rails to infer automatically from the model + # how the form should be constructed. For a generic model object, a form + # can be created by passing +form_for+ a string or symbol representing + # the object we are concerned with: # # <%= form_for :person do |f| %> # First name: <%= f.text_field :first_name %>
@@ -152,24 +137,38 @@ module ActionView # <%= f.submit %> # <% end %> # - # There, the argument is a symbol or string with the name of the - # object the form is about. - # - # The form builder acts as a regular form helper that somehow carries the - # model. Thus, the idea is that + # The variable +f+ yielded to the block is a FormBuilder object that + # incorporates the knowledge about the model object represented by + # :person passed to +form_for+. Methods defined on the FormBuilder + # are used to generate fields bound to this model. Thus, for example, # # <%= f.text_field :first_name %> # - # gets expanded to + # will get expanded to # # <%= text_field :person, :first_name %> + # which results in an html tag whose +name+ attribute is + # person[first_name]. This means that when the form is submitted, + # the value entered by the user will be available in the controller as + # params[:person][:first_name]. # - # The rightmost argument to +form_for+ is an - # optional hash of options: + # If :person also happens to be the name of an instance variable + # @person, the default value of the field shown when the form is + # initially displayed (e.g. in the situation where you are editing an + # existing record) will be the value of the corresponding attribute of + # @person. # - # * :url - The URL the form is submitted to. It takes the same - # fields you pass to +url_for+ or +link_to+. In particular you may pass - # here a named route directly as well. Defaults to the current action. + # The rightmost argument to +form_for+ is an + # optional hash of options - + # + # * :url - The URL the form is to be submitted to. This may be + # represented in the same way as values passed to +url_for+ or +link_to+. + # So for example you may use a named route directly. When the model is + # represented by a string or symbol, as in the example above, if the + # :url option is not specified, by default the form will be + # sent back to the current url (We will describe below an alternative + # resource-oriented usage of +form_for+ in which the URL does not need + # to be specified explicitly). # * :namespace - A namespace for your form to ensure uniqueness of # id attributes on form elements. The namespace attribute will be prefixed # with underscore on the generated HTML id. @@ -179,7 +178,7 @@ module ActionView # possible to use both the stand-alone FormHelper methods and methods # from FormTagHelper. For example: # - # <%= form_for @person do |f| %> + # <%= form_for :person do |f| %> # First name: <%= f.text_field :first_name %> # Last name : <%= f.text_field :last_name %> # Biography : <%= text_area :person, :biography %> @@ -191,26 +190,65 @@ module ActionView # are designed to work with an object as base, like # FormOptionHelper#collection_select and DateHelper#datetime_select. # - # === Resource-oriented style + # === #form_for with a model object + # + # In the examples above, the object to be created or edited was + # represented by a symbol passed to +form_for+, and we noted that + # a string can also be used equivalently. It is also possible, however, + # to pass a model object itself to +form_for+. For example, if @post + # is an existing record you wish to edit, you can create the form using + # + # <%= form_for @post do |f| %> + # ... + # <% end %> + # + # This behaves in almost the same way as outlined previously, with a + # couple of small exceptions. First, the prefix used to name the input + # elements within the form (hence the key that denotes them in the +params+ + # hash) is actually derived from the object's _class_, e.g. params[:post] + # if the object's class is +Post+. However, this can be overwritten using + # the :as option, e.g. - # - # As we said above, in addition to manually configuring the +form_for+ - # call, you can rely on automated resource identification, which will use - # the conventions and named routes of that approach. This is the - # preferred way to use +form_for+ nowadays. + # <%= form_for(@person, :as => :client) do |f| %> + # ... + # <% end %> # - # For example, if @post is an existing record you want to edit + # would result in params[:client]. + # + # Secondly, the field values shown when the form is initially displayed + # are taken from the attributes of the object passed to +form_for+. + # Furthermore, this is true regardless of whether the object is an instance + # variable. So, for example, if we had a _local_ variable +post+ + # representing an existing record, + # + # <%= form_for post do |f| %> + # ... + # <% end %> + # + # would produce a form with fields whose initial state reflect the current + # values of the attributes of +post+. + # + # === Resource-oriented style + # + # In the examples just shown, although not indicated explicitly, we still + # need to use the :url option in order to specify where the + # form is going to be sent. However, further simplification is possible + # if the record passed to +form_for+ is a _resource_, i.e. it corresponds + # to a set of RESTful routes, e.g. defined using the +resources+ method + # in config/routes.rb. In this case Rails will simply infer the + # appropriate URL from the record itself. For example, # # <%= form_for @post do |f| %> # ... # <% end %> # - # is equivalent to something like: + # is then equivalent to something like: # # <%= form_for @post, :as => :post, :url => post_path(@post), :method => :put, :html => { :class => "edit_post", :id => "edit_post_45" } do |f| %> # ... # <% end %> # - # And for new records + # And for a new record # # <%= form_for(Post.new) do |f| %> # ... @@ -222,7 +260,7 @@ module ActionView # ... # <% end %> # - # You can also overwrite the individual conventions, like this: + # However you can still overwrite individual conventions, such as: # # <%= form_for(@post, :url => super_posts_path) do |f| %> # ... @@ -234,13 +272,6 @@ module ActionView # ... # <% end %> # - # If you have an object that needs to be represented as a different - # parameter, like a Person that acts as a Client: - # - # <%= form_for(@person, :as => :client) do |f| %> - # ... - # <% end %> - # # For namespaced routes, like +admin_post_url+: # # <%= form_for([:admin, @post]) do |f| %> @@ -263,9 +294,9 @@ module ActionView # # :method => (:get|:post|:patch|:put|:delete) # - # in the options hash. If the verb is not GET or POST, which are natively supported by HTML forms, the - # form will be set to POST and a hidden input called _method will carry the intended verb for the server - # to interpret. + # in the options hash. If the verb is not GET or POST, which are natively + # supported by HTML forms, the form will be set to POST and a hidden input + # called _method will carry the intended verb for the server to interpret. # # === Unobtrusive JavaScript # -- cgit v1.2.3 From 52bbff4e898ab00265580b34a06241d7d2c1571f Mon Sep 17 00:00:00 2001 From: Mark Thomson Date: Sat, 10 Mar 2012 14:27:36 -0600 Subject: Added clarification to description of how initial form values are derived. --- actionpack/lib/action_view/helpers/form_helper.rb | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 41173de2e7..3dcef98352 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -152,7 +152,8 @@ module ActionView # the value entered by the user will be available in the controller as # params[:person][:first_name]. # - # If :person also happens to be the name of an instance variable + # For fields generated in this way using the FormBuilder, + # if :person also happens to be the name of an instance variable # @person, the default value of the field shown when the form is # initially displayed (e.g. in the situation where you are editing an # existing record) will be the value of the corresponding attribute of -- cgit v1.2.3 From 64cd57aba989b396aaa749ff9ac83d80e3e63bc7 Mon Sep 17 00:00:00 2001 From: Mark Thomson Date: Sun, 11 Mar 2012 03:15:38 -0500 Subject: Revised explanation of fields_for usage. Minor tweak to previous comments on form_for and form_helper.rb preamble --- actionpack/lib/action_view/helpers/form_helper.rb | 49 ++++++++++++++++++----- 1 file changed, 39 insertions(+), 10 deletions(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 3dcef98352..54e3032298 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -20,9 +20,9 @@ module ActionView # identity of the resource in several ways: (i) the url that the form is # sent to (the form element's +action+ attribute) should result in a request # being routed to the appropriate controller action (with the appropriate :id - # parameter in the case of an existing resource), and (ii) input fields should + # parameter in the case of an existing resource), (ii) input fields should # be named in such a way that in the controller their values appear in the - # appropriate places within the +params+ hash. Also for an existing record, + # appropriate places within the +params+ hash, and (iii) for an existing record, # when the form is initially displayed, input fields corresponding to attributes # of the resource should show the current values of those attributes. # @@ -217,8 +217,8 @@ module ActionView # would result in params[:client]. # # Secondly, the field values shown when the form is initially displayed - # are taken from the attributes of the object passed to +form_for+. - # Furthermore, this is true regardless of whether the object is an instance + # are taken from the attributes of the object passed to +form_for+, + # regardless of whether the object is an instance # variable. So, for example, if we had a _local_ variable +post+ # representing an existing record, # @@ -445,30 +445,59 @@ module ActionView # # === Generic Examples # + # Although the usage and purpose of +field_for+ is similar to +form_for+'s, + # its method signature is slightly different. Like +form_for+, it yields + # a FormBuilder object associated with a particular model object to a block, + # and within the block allows methods to be called on the builder to + # generate fields associated with the model object. Fields may reflect + # a model object in two ways - how they are named (hence how submitted + # values appear within the +params+ hash in the controller) and what + # default values are shown when the form the fields appear in is first + # displayed. In order for both of these features to be specified independently, + # both an object name (represented by either a symbol or string) and the + # object itself can be passed to the method separately - + # # <%= form_for @person do |person_form| %> # First name: <%= person_form.text_field :first_name %> # Last name : <%= person_form.text_field :last_name %> # - # <%= fields_for @person.permission do |permission_fields| %> + # <%= fields_for :permission, @person.permission do |permission_fields| %> # Admin? : <%= permission_fields.check_box :admin %> # <% end %> # # <%= f.submit %> # <% end %> # - # ...or if you have an object that needs to be represented as a different - # parameter, like a Client that acts as a Person: + # In this case, the checkbox field will be represented by an HTML +input+ + # tag with the +name+ attribute permission[admin], and the submitted + # value will appear in the controller as params[:permission][:admin]. + # If @person.permission is an existing record with an attribute + # +admin+, the initial state of the checkbox when first displayed will + # reflect the value of @person.permission.admin. + # + # Often this can be simplified by passing just the name of the model + # object to +fields_for+ - # - # <%= fields_for :person, @client do |permission_fields| %> + # <%= fields_for :permission do |permission_fields| %> # Admin?: <%= permission_fields.check_box :admin %> # <% end %> # - # ...or if you don't have an object, just a name of the parameter: + # ...in which case, if :permission also happens to be the name of an + # instance variable @permission, the initial state of the input + # field will reflect the value of that variable's attribute @permission.admin. # - # <%= fields_for :person do |permission_fields| %> + # Alternatively, you can pass just the model object itself (if the first + # argument isn't a string or symbol +fields_for+ will realize that the + # name has been omitted) - + # + # <%= fields_for @person.permission do |permission_fields| %> # Admin?: <%= permission_fields.check_box :admin %> # <% end %> # + # and +fields_for+ will derive the required name of the field from the + # _class_ of the model object, e.g. if @person.permission, is + # of class +Permission+, the field will still be named permission[admin]. + # # Note: This also works for the methods in FormOptionHelper and # DateHelper that are designed to work with an object as base, like # FormOptionHelper#collection_select and DateHelper#datetime_select. -- cgit v1.2.3 From 4cb71eaf463bb6a12edd1aaf222e9f1e3269bea7 Mon Sep 17 00:00:00 2001 From: Mark Thomson Date: Tue, 13 Mar 2012 02:36:59 -0500 Subject: Added documentation for the ActionController::MimeResponds::Collector class. --- .../lib/action_controller/metal/mime_responds.rb | 25 +++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_controller/metal/mime_responds.rb b/actionpack/lib/action_controller/metal/mime_responds.rb index 800752975c..f413a2f318 100644 --- a/actionpack/lib/action_controller/metal/mime_responds.rb +++ b/actionpack/lib/action_controller/metal/mime_responds.rb @@ -279,7 +279,30 @@ module ActionController #:nodoc: end end - class Collector #:nodoc: + # A container of responses available for requests with different mime-types + # sent to the current controller action. + # + # The public controller methods +respond_with+ and +respond_to+ may be called + # with a block that is used to define responses to different mime-types, e.g. + # for +respond_to+ : + # + # respond_to do |format| + # format.html + # format.xml { render :xml => @people.to_xml } + # end + # + # In this usage, the argument passed to the block (+format+ above) is an + # instance of the ActionController::MimeResponds::Collector class. This + # object serves as a container in which available responses can be stored by + # calling any of the dynamically generated, mime-type-specific methods such + # as +html+, +xml+ etc on the Collector. Each response is represented by a + # corresponding block if present. + # + # A subsequent call to #negotiate_format(request) will enable the Collector + # to determine which specific mime-type it should respond with for the current + # request, with this response then being accessible by calling #response. + # + class Collector include AbstractController::Collector attr_accessor :order, :format -- cgit v1.2.3