actionview 6.1.4.1 → 7.0.0.rc2

data/lib/action_view/helpers/form_helper.rb

@@ -2,7 +2,7 @@
 
 require "cgi"
 require "action_view/helpers/date_helper"
-require "action_view/helpers/tag_helper"
+require "action_view/helpers/url_helper"
 require "action_view/helpers/form_tag_helper"
 require "action_view/helpers/active_model_helper"
 require "action_view/model_naming"
@@ -11,11 +11,10 @@ require "active_support/core_ext/module/attribute_accessors"
 require "active_support/core_ext/hash/slice"
 require "active_support/core_ext/string/output_safety"
 require "active_support/core_ext/string/inflections"
-require "active_support/core_ext/symbol/starts_ends_with"
 
 module ActionView
   # = Action View Form Helpers
-  module Helpers #:nodoc:
+  module Helpers # :nodoc:
     # Form helpers are designed to make working with resources much easier
     # compared to using vanilla HTML.
     #
@@ -283,6 +282,12 @@ module ActionView
       #     ...
       #   <% end %>
       #
+      # You can omit the <tt>action</tt> attribute by passing <tt>url: false</tt>:
+      #
+      #   <%= form_for(@post, url: false) do |f| %>
+      #     ...
+      #   <% end %>
+      #
       # You can also set the answer format, like this:
       #
       #   <%= form_for(@post, format: :json) do |f| %>
@@ -427,50 +432,45 @@ module ActionView
       #   <% end %>
       def form_for(record, options = {}, &block)
         raise ArgumentError, "Missing block" unless block_given?
-        html_options = options[:html] ||= {}
 
         case record
         when String, Symbol
+          model       = nil
           object_name = record
-          object      = nil
         else
-          object      = record.is_a?(Array) ? record.last : record
+          model       = record
+          object      = _object_for_form_builder(record)
           raise ArgumentError, "First argument in form cannot contain nil or be empty" unless object
           object_name = options[:as] || model_name_from_record_or_class(object).param_key
-          apply_form_for_options!(record, object, options)
+          apply_form_for_options!(object, options)
         end
 
-        html_options[:data]   = options.delete(:data)   if options.has_key?(:data)
-        html_options[:remote] = options.delete(:remote) if options.has_key?(:remote)
-        html_options[:method] = options.delete(:method) if options.has_key?(:method)
-        html_options[:enforce_utf8] = options.delete(:enforce_utf8) if options.has_key?(:enforce_utf8)
-        html_options[:authenticity_token] = options.delete(:authenticity_token)
+        remote = options.delete(:remote)
+
+        if remote && !embed_authenticity_token_in_remote_forms && options[:authenticity_token].blank?
+          options[:authenticity_token] = false
+        end
 
-        builder = instantiate_builder(object_name, object, options)
-        output  = capture(builder, &block)
-        html_options[:multipart] ||= builder.multipart?
+        options[:model]                               = model
+        options[:scope]                               = object_name
+        options[:local]                               = !remote
+        options[:skip_default_ids]                    = false
+        options[:allow_method_names_outside_object]   = options.fetch(:allow_method_names_outside_object, false)
 
-        html_options = html_options_for_form(options[:url] || {}, html_options)
-        form_tag_with_body(html_options, output)
+        form_with(**options, &block)
       end
 
-      def apply_form_for_options!(record, object, options) #:nodoc:
+      def apply_form_for_options!(object, options) # :nodoc:
         object = convert_to_model(object)
 
         as = options[:as]
         namespace = options[:namespace]
-        action, method = object.respond_to?(:persisted?) && object.persisted? ? [:edit, :patch] : [:new, :post]
+        action = object.respond_to?(:persisted?) && object.persisted? ? :edit : :new
+        options[:html] ||= {}
         options[:html].reverse_merge!(
           class:  as ? "#{action}_#{as}" : dom_class(object, action),
           id:     (as ? [namespace, action, as] : [namespace, dom_id(object, action)]).compact.join("_").presence,
-          method: method
         )
-
-        options[:url] ||= if options.key?(:format)
-          polymorphic_path(record, format: options.delete(:format))
-        else
-          polymorphic_path(record, {})
-        end
       end
       private :apply_form_for_options!
 
@@ -485,7 +485,16 @@ module ActionView
       #     <%= form.text_field :title %>
       #   <% end %>
       #   # =>
-      #   <form action="/posts" method="post" data-remote="true">
+      #   <form action="/posts" method="post">
+      #     <input type="text" name="title">
+      #   </form>
+      #
+      #   # With an intentionally empty URL:
+      #   <%= form_with url: false do |form| %>
+      #     <%= form.text_field :title %>
+      #   <% end %>
+      #   # =>
+      #   <form method="post" data-remote="true">
       #     <input type="text" name="title">
       #   </form>
       #
@@ -494,7 +503,7 @@ module ActionView
       #     <%= form.text_field :title %>
       #   <% end %>
       #   # =>
-      #   <form action="/posts" method="post" data-remote="true">
+      #   <form action="/posts" method="post">
       #     <input type="text" name="post[title]">
       #   </form>
       #
@@ -503,7 +512,7 @@ module ActionView
       #     <%= form.text_field :title %>
       #   <% end %>
       #   # =>
-      #   <form action="/posts" method="post" data-remote="true">
+      #   <form action="/posts" method="post">
       #     <input type="text" name="post[title]">
       #   </form>
       #
@@ -512,7 +521,7 @@ module ActionView
       #     <%= form.text_field :title %>
       #   <% end %>
       #   # =>
-      #   <form action="/posts/1" method="post" data-remote="true">
+      #   <form action="/posts/1" method="post">
       #     <input type="hidden" name="_method" value="patch">
       #     <input type="text" name="post[title]" value="<the title of the post>">
       #   </form>
@@ -523,7 +532,7 @@ module ActionView
       #     <%= form.text_field :but_in_forms_they_can %>
       #   <% end %>
       #   # =>
-      #   <form action="/cats" method="post" data-remote="true">
+      #   <form action="/cats" method="post">
       #     <input type="text" name="cat[cats_dont_have_gills]">
       #     <input type="text" name="cat[but_in_forms_they_can]">
       #   </form>
@@ -604,10 +613,16 @@ module ActionView
       #   This is helpful when fragment-caching the form. Remote forms
       #   get the authenticity token from the <tt>meta</tt> tag, so embedding is
       #   unnecessary unless you support browsers without JavaScript.
-      # * <tt>:local</tt> - By default form submits via typical HTTP requests.
-      #   Enable remote and unobtrusive XHRs submits with <tt>local: false</tt>.
-      #   Remote forms may be enabled by default by setting
-      #   <tt>config.action_view.form_with_generates_remote_forms = true</tt>.
+      # * <tt>:local</tt> - Whether to use standard HTTP form submission.
+      #   When set to <tt>true</tt>, the form is submitted via standard HTTP.
+      #   When set to <tt>false</tt>, the form is submitted as a "remote form", which
+      #   is handled by Rails UJS as an XHR. When unspecified, the behavior is derived
+      #   from <tt>config.action_view.form_with_generates_remote_forms</tt> where the
+      #   config's value is actually the inverse of what <tt>local</tt>'s value would be.
+      #   As of Rails 6.1, that configuration option defaults to <tt>false</tt>
+      #   (which has the equivalent effect of passing <tt>local: true</tt>).
+      #   In previous versions of Rails, that configuration option defaults to
+      #   <tt>true</tt> (the equivalent of passing <tt>local: false</tt>).
       # * <tt>:skip_enforcing_utf8</tt> - If set to true, a hidden input with name
       #   utf8 is not output.
       # * <tt>:builder</tt> - Override the object used to build the form.
@@ -735,13 +750,14 @@ module ActionView
       #     form_with(**options.merge(builder: LabellingFormBuilder), &block)
       #   end
       def form_with(model: nil, scope: nil, url: nil, format: nil, **options, &block)
-        options[:allow_method_names_outside_object] = true
-        options[:skip_default_ids] = !form_with_generates_ids
+        options = { allow_method_names_outside_object: true, skip_default_ids: !form_with_generates_ids }.merge!(options)
 
         if model
-          url ||= polymorphic_path(model, format: format)
+          if url != false
+            url ||= polymorphic_path(model, format: format)
+          end
 
-          model   = model.last if model.is_a?(Array)
+          model   = _object_for_form_builder(model)
           scope ||= model_name_from_record_or_class(model).param_key
         end
 
@@ -1000,8 +1016,9 @@ module ActionView
       # hidden field is not needed and you can pass <tt>include_id: false</tt>
       # to prevent fields_for from rendering it automatically.
       def fields_for(record_name, record_object = nil, options = {}, &block)
-        builder = instantiate_builder(record_name, record_object, options)
-        capture(builder, &block)
+        options = { model: record_object, allow_method_names_outside_object: false, skip_default_ids: false }.merge!(options)
+
+        fields(record_name, **options, &block)
       end
 
       # Scopes input fields with either an explicit scope or model.
@@ -1050,10 +1067,10 @@ module ActionView
       # to work with an object as a base, like
       # FormOptionsHelper#collection_select and DateHelper#datetime_select.
       def fields(scope = nil, model: nil, **options, &block)
-        options[:allow_method_names_outside_object] = true
-        options[:skip_default_ids] = !form_with_generates_ids
+        options = { allow_method_names_outside_object: true, skip_default_ids: !form_with_generates_ids }.merge!(options)
 
         if model
+          model   = _object_for_form_builder(model)
           scope ||= model_name_from_record_or_class(model).param_key
         end
 
@@ -1215,7 +1232,7 @@ module ActionView
       #   file_field(:attachment, :file, class: 'file_input')
       #   # => <input type="file" id="attachment_file" name="attachment[file]" class="file_input" />
       def file_field(object_name, method, options = {})
-        Tags::FileField.new(object_name, method, self, convert_direct_upload_option_to_url(options.dup)).render
+        Tags::FileField.new(object_name, method, self, convert_direct_upload_option_to_url(method, options.dup)).render
       end
 
       # Returns a textarea opening and closing tag set tailored for accessing a specified attribute (identified by +method+)
@@ -1252,6 +1269,12 @@ module ActionView
       # Additional options on the input tag can be passed as a hash with +options+. The +checked_value+ defaults to 1
       # while the default +unchecked_value+ is set to 0 which is convenient for boolean values.
       #
+      # ==== Options
+      #
+      # * Any standard HTML attributes for the tag can be passed in, for example +:class+.
+      # * <tt>:checked</tt> - +true+ or +false+ forces the state of the checkbox to be checked or not.
+      # * <tt>:include_hidden</tt> - If set to false, the auxiliary hidden field described below will not be generated.
+      #
       # ==== Gotcha
       #
       # The HTML specification says unchecked check boxes are not successful, and
@@ -1265,7 +1288,7 @@ module ActionView
       # wouldn't update the flag.
       #
       # To prevent this the helper generates an auxiliary hidden field before
-      # the very check box. The hidden field has the same name and its
+      # every check box. The hidden field has the same name and its
       # attributes mimic an unchecked check box.
       #
       # This way, the client either sends only the hidden field (representing
@@ -1289,6 +1312,8 @@ module ActionView
       # In that case it is preferable to either use +check_box_tag+ or to use
       # hashes instead of arrays.
       #
+      # ==== Examples
+      #
       #   # Let's say that @post.validated? is 1:
       #   check_box("post", "validated")
       #   # => <input name="post[validated]" type="hidden" value="0" />
@@ -1403,8 +1428,9 @@ module ActionView
       # Returns a text_field of type "time".
       #
       # The default value is generated by trying to call +strftime+ with "%T.%L"
-      # on the object's value. It is still possible to override that
-      # by passing the "value" option.
+      # on the object's value. If you pass <tt>include_seconds: false</tt>, it will be
+      # formatted by trying to call +strftime+ with "%H:%M" on the object's value.
+      # It is also possible to override this by passing the "value" option.
       #
       # === Options
       # * Accepts same options as time_field_tag
@@ -1425,6 +1451,12 @@ module ActionView
       #   time_field("task", "started_at", min: "01:00:00")
       #   # => <input id="task_started_at" name="task[started_at]" type="time" min="01:00:00.000" />
       #
+      # By default, provided times will be formatted including seconds. You can render just the hour
+      # and minute by passing <tt>include_seconds: false</tt>. Some browsers will render a simpler UI
+      # if you exclude seconds in the timestamp format.
+      #
+      #   time_field("task", "started_at", value: Time.now, include_seconds: false)
+      #   # => <input id="task_started_at" name="task[started_at]" type="time" value="01:00" />
       def time_field(object_name, method, options = {})
         Tags::TimeField.new(object_name, method, self, options).render
       end
@@ -1528,34 +1560,24 @@ module ActionView
         Tags::RangeField.new(object_name, method, self, options).render
       end
 
+      def _object_for_form_builder(object) # :nodoc:
+        object.is_a?(Array) ? object.last : object
+      end
+
       private
         def html_options_for_form_with(url_for_options = nil, model = nil, html: {}, local: !form_with_generates_remote_forms,
           skip_enforcing_utf8: nil, **options)
-          html_options = options.slice(:id, :class, :multipart, :method, :data).merge(html)
+          html_options = options.slice(:id, :class, :multipart, :method, :data, :authenticity_token).merge!(html)
+          html_options[:remote] = html.delete(:remote) || !local
           html_options[:method] ||= :patch if model.respond_to?(:persisted?) && model.persisted?
-          html_options[:enforce_utf8] = !skip_enforcing_utf8 unless skip_enforcing_utf8.nil?
-
-          html_options[:enctype] = "multipart/form-data" if html_options.delete(:multipart)
-
-          # The following URL is unescaped, this is just a hash of options, and it is the
-          # responsibility of the caller to escape all the values.
-          html_options[:action] = url_for(url_for_options || {})
-          html_options[:"accept-charset"] = "UTF-8"
-          html_options[:"data-remote"] = true unless local
-
-          html_options[:authenticity_token] = options.delete(:authenticity_token)
-
-          if !local && html_options[:authenticity_token].blank?
-            html_options[:authenticity_token] = embed_authenticity_token_in_remote_forms
-          end
-
-          if html_options[:authenticity_token] == true
-            # Include the default authenticity_token, which is only generated when it's set to nil,
-            # but we needed the true value to override the default of no authenticity_token on data-remote.
-            html_options[:authenticity_token] = nil
+          if skip_enforcing_utf8.nil?
+            if options.key?(:enforce_utf8)
+              html_options[:enforce_utf8] = options[:enforce_utf8]
+            end
+          else
+            html_options[:enforce_utf8] = !skip_enforcing_utf8
           end
-
-          html_options.stringify_keys!
+          html_options_for_form(url_for_options.nil? ? {} : url_for_options, html_options)
         end
 
         def instantiate_builder(record_name, record_object, options)
@@ -1685,6 +1707,69 @@ module ActionView
         @index = options[:index] || options[:child_index]
       end
 
+      # Generate an HTML <tt>id</tt> attribute value.
+      #
+      # return the <tt><form></tt> element's <tt>id</tt> attribute.
+      #
+      #   <%= form_for @post do |f| %>
+      #     <%# ... %>
+      #
+      #     <% content_for :sticky_footer do %>
+      #       <%= form.button(form: f.id) %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # In the example above, the <tt>:sticky_footer</tt> content area will
+      # exist outside of the <tt><form></tt> element. By declaring the
+      # <tt>form</tt> HTML attribute, we hint to the browser that the generated
+      # <tt><button></tt> element should be treated as the <tt><form></tt>
+      # element's submit button, regardless of where it exists in the DOM.
+      def id
+        options.dig(:html, :id)
+      end
+
+      # Generate an HTML <tt>id</tt> attribute value for the given field
+      #
+      # Return the value generated by the <tt>FormBuilder</tt> for the given
+      # attribute name.
+      #
+      #   <%= form_for @post do |f| %>
+      #     <%= f.label :title %>
+      #     <%= f.text_field :title, aria: { describedby: f.field_id(:title, :error) } %>
+      #     <%= tag.span("is blank", id: f.field_id(:title, :error) %>
+      #   <% end %>
+      #
+      # In the example above, the <tt><input type="text"></tt> element built by
+      # the call to <tt>FormBuilder#text_field</tt> declares an
+      # <tt>aria-describedby</tt> attribute referencing the <tt><span></tt>
+      # element, sharing a common <tt>id</tt> root (<tt>post_title</tt>, in this
+      # case).
+      def field_id(method, *suffixes, index: @index)
+        @template.field_id(@object_name, method, *suffixes, index: index)
+      end
+
+      # Generate an HTML <tt>name</tt> attribute value for the given name and
+      # field combination
+      #
+      # Return the value generated by the <tt>FormBuilder</tt> for the given
+      # attribute name.
+      #
+      #   <%= form_for @post do |f| %>
+      #     <%= f.text_field :title, name: f.field_name(:title, :subtitle) %>
+      #     <%# => <input type="text" name="post[title][subtitle]">
+      #   <% end %>
+      #
+      #   <%= form_for @post do |f| %>
+      #     <%= f.field_tag :tag, name: f.field_name(:tag, multiple: true) %>
+      #     <%# => <input type="text" name="post[tag][]">
+      #   <% end %>
+      #
+      def field_name(method, *methods, multiple: false, index: @index)
+        object_name = @options.fetch(:as) { @object_name }
+
+        @template.field_name(object_name, method, *methods, index: index, multiple: multiple)
+      end
+
       ##
       # :method: text_field
       #
@@ -2171,7 +2256,7 @@ module ActionView
             return fields_for_with_nested_attributes(record_name, record_object, fields_options, block)
           end
         else
-          record_object = record_name.is_a?(Array) ? record_name.last : record_name
+          record_object = @template._object_for_form_builder(record_name)
           record_name   = model_name_from_record_or_class(record_object).param_key
         end
 
@@ -2281,6 +2366,12 @@ module ActionView
       # Additional options on the input tag can be passed as a hash with +options+. The +checked_value+ defaults to 1
       # while the default +unchecked_value+ is set to 0 which is convenient for boolean values.
       #
+      # ==== Options
+      #
+      # * Any standard HTML attributes for the tag can be passed in, for example +:class+.
+      # * <tt>:checked</tt> - +true+ or +false+ forces the state of the checkbox to be checked or not.
+      # * <tt>:include_hidden</tt> - If set to false, the auxiliary hidden field described below will not be generated.
+      #
       # ==== Gotcha
       #
       # The HTML specification says unchecked check boxes are not successful, and
@@ -2294,7 +2385,7 @@ module ActionView
       # wouldn't update the flag.
       #
       # To prevent this the helper generates an auxiliary hidden field before
-      # the very check box. The hidden field has the same name and its
+      # every check box. The hidden field has the same name and its
       # attributes mimic an unchecked check box.
       #
       # This way, the client either sends only the hidden field (representing
@@ -2318,6 +2409,8 @@ module ActionView
       # In that case it is preferable to either use +check_box_tag+ or to use
       # hashes instead of arrays.
       #
+      # ==== Examples
+      #
       #   # Let's say that @post.validated? is 1:
       #   check_box("validated")
       #   # => <input name="post[validated]" type="hidden" value="0" />
@@ -2386,7 +2479,7 @@ module ActionView
       # hash with +options+. These options will be tagged onto the HTML as an HTML element attribute as in the example
       # shown.
       #
-      # Using this method inside a +form_for+ block will set the enclosing form's encoding to <tt>multipart/form-data</tt>.
+      # Using this method inside a +form_with+ block will set the enclosing form's encoding to <tt>multipart/form-data</tt>.
       #
       # ==== Options
       # * Creates standard HTML attributes for the tag.
@@ -2483,6 +2576,9 @@ module ActionView
       #   button("Create post")
       #   # => <button name='button' type='submit'>Create post</button>
       #
+      #   button(:draft, value: true)
+      #   # => <button name="post[draft]" value="true" type="submit">Create post</button>
+      #
       #   button do
       #     content_tag(:strong, 'Ask me!')
       #   end
@@ -2497,14 +2593,31 @@ module ActionView
       #   #      <strong>Create post</strong>
       #   #    </button>
       #
+      #   button(:draft, value: true) do
+      #     content_tag(:strong, "Save as draft")
+      #   end
+      #   # =>  <button name="post[draft]" value="true" type="submit">
+      #   #       <strong>Save as draft</strong>
+      #   #     </button>
+      #
       def button(value = nil, options = {}, &block)
-        value, options = nil, value if value.is_a?(Hash)
+        case value
+        when Hash
+          value, options = nil, value
+        when Symbol
+          value, options[:name] = nil, field_name(value)
+        end
         value ||= submit_default_value
 
         if block_given?
           value = @template.capture { yield(value) }
         end
 
+        formmethod = options[:formmethod]
+        if formmethod.present? && !/post|get/i.match?(formmethod) && !options.key?(:name) && !options.key?(:value)
+          options.merge! formmethod: :post, name: "_method", value: formmethod
+        end
+
         @template.button_tag(value, options)
       end
 
@@ -2565,7 +2678,9 @@ module ActionView
               else
                 options[:child_index] = nested_child_index(name)
               end
-              output << fields_for_nested_model("#{name}[#{options[:child_index]}]", child, options, block)
+              if content = fields_for_nested_model("#{name}[#{options[:child_index]}]", child, options, block)
+                output << content
+              end
             end
             output
           elsif association