vendor/rails/actionpack/lib/action_view/helpers/form_tag_helper.rb

   1 require 'cgi'
   2 require 'action_view/helpers/tag_helper'
   3
   4 module ActionView
   5   module Helpers
   6     # Provides a number of methods for creating form tags that doesn't rely on an Active Record object assigned to the template like
   7     # FormHelper does. Instead, you provide the names and values manually.
   8     #
   9     # NOTE: The HTML options <tt>disabled</tt>, <tt>readonly</tt>, and <tt>multiple</tt> can all be treated as booleans. So specifying
  10     # <tt>:disabled => true</tt> will give <tt>disabled="disabled"</tt>.
  11     module FormTagHelper
  12       # Starts a form tag that points the action to an url configured with <tt>url_for_options</tt> just like
  13       # ActionController::Base#url_for. The method for the form defaults to POST.
  14       #
  15       # ==== Options
  16       # * <tt>:multipart</tt> - If set to true, the enctype is set to "multipart/form-data".
  17       # * <tt>:method</tt> - The method to use when submitting the form, usually either "get" or "post".
  18       #   If "put", "delete", or another verb is used, a hidden input with name <tt>_method</tt>
  19       #   is added to simulate the verb over post.
  20       # * A list of parameters to feed to the URL the form will be posted to.
  21       #
  22       # ==== Examples
  23       #   form_tag('/posts')
  24       #   # => <form action="/posts" method="post">
  25       #
  26       #   form_tag('/posts/1', :method => :put)
  27       #   # => <form action="/posts/1" method="put">
  28       #
  29       #   form_tag('/upload', :multipart => true)
  30       #   # => <form action="/upload" method="post" enctype="multipart/form-data">
  31       #
  32       #   <% form_tag '/posts' do -%>
  33       #     <div><%= submit_tag 'Save' %></div>
  34       #   <% end -%>
  35       #   # => <form action="/posts" method="post"><div><input type="submit" name="submit" value="Save" /></div></form>
  36       def form_tag(url_for_options = {}, options = {}, *parameters_for_url, &block)
  37         html_options = html_options_for_form(url_for_options, options, *parameters_for_url)
  38         if block_given?
  39           form_tag_in_block(html_options, &block)
  40         else
  41           form_tag_html(html_options)
  42         end
  43       end
  44
  45       # Creates a dropdown selection box, or if the <tt>:multiple</tt> option is set to true, a multiple
  46       # choice selection box.
  47       #
  48       # Helpers::FormOptions can be used to create common select boxes such as countries, time zones, or
  49       # associated records. <tt>option_tags</tt> is a string containing the option tags for the select box.
  50       #
  51       # ==== Options
  52       # * <tt>:multiple</tt> - If set to true the selection will allow multiple choices.
  53       # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
  54       # * Any other key creates standard HTML attributes for the tag.
  55       #
  56       # ==== Examples
  57       #   select_tag "people", "<option>David</option>"
  58       #   # => <select id="people" name="people"><option>David</option></select>
  59       #
  60       #   select_tag "count", "<option>1</option><option>2</option><option>3</option><option>4</option>"
  61       #   # => <select id="count" name="count"><option>1</option><option>2</option>
  62       #   #    <option>3</option><option>4</option></select>
  63       #
  64       #   select_tag "colors", "<option>Red</option><option>Green</option><option>Blue</option>", :multiple => true
  65       #   # => <select id="colors" multiple="multiple" name="colors[]"><option>Red</option>
  66       #   #    <option>Green</option><option>Blue</option></select>
  67       #
  68       #   select_tag "locations", "<option>Home</option><option selected="selected">Work</option><option>Out</option>"
  69       #   # => <select id="locations" name="locations"><option>Home</option><option selected='selected'>Work</option>
  70       #   #    <option>Out</option></select>
  71       #
  72       #   select_tag "access", "<option>Read</option><option>Write</option>", :multiple => true, :class => 'form_input'
  73       #   # => <select class="form_input" id="access" multiple="multiple" name="access[]"><option>Read</option>
  74       #   #    <option>Write</option></select>
  75       #
  76       #   select_tag "destination", "<option>NYC</option><option>Paris</option><option>Rome</option>", :disabled => true
  77       #   # => <select disabled="disabled" id="destination" name="destination"><option>NYC</option>
  78       #   #    <option>Paris</option><option>Rome</option></select>
  79       def select_tag(name, option_tags = nil, options = {})
  80         html_name = (options[:multiple] == true && !name.to_s.ends_with?("[]")) ? "#{name}[]" : name
  81         content_tag :select, option_tags, { "name" => html_name, "id" => sanitize_to_id(name) }.update(options.stringify_keys)
  82       end
  83
  84       # Creates a standard text field; use these text fields to input smaller chunks of text like a username
  85       # or a search query.
  86       #
  87       # ==== Options
  88       # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
  89       # * <tt>:size</tt> - The number of visible characters that will fit in the input.
  90       # * <tt>:maxlength</tt> - The maximum number of characters that the browser will allow the user to enter.
  91       # * Any other key creates standard HTML attributes for the tag.
  92       #
  93       # ==== Examples
  94       #   text_field_tag 'name'
  95       #   # => <input id="name" name="name" type="text" />
  96       #
  97       #   text_field_tag 'query', 'Enter your search query here'
  98       #   # => <input id="query" name="query" type="text" value="Enter your search query here" />
  99       #
 100       #   text_field_tag 'request', nil, :class => 'special_input'
 101       #   # => <input class="special_input" id="request" name="request" type="text" />
 102       #
 103       #   text_field_tag 'address', '', :size => 75
 104       #   # => <input id="address" name="address" size="75" type="text" value="" />
 105       #
 106       #   text_field_tag 'zip', nil, :maxlength => 5
 107       #   # => <input id="zip" maxlength="5" name="zip" type="text" />
 108       #
 109       #   text_field_tag 'payment_amount', '$0.00', :disabled => true
 110       #   # => <input disabled="disabled" id="payment_amount" name="payment_amount" type="text" value="$0.00" />
 111       #
 112       #   text_field_tag 'ip', '0.0.0.0', :maxlength => 15, :size => 20, :class => "ip-input"
 113       #   # => <input class="ip-input" id="ip" maxlength="15" name="ip" size="20" type="text" value="0.0.0.0" />
 114       def text_field_tag(name, value = nil, options = {})
 115         tag :input, { "type" => "text", "name" => name, "id" => sanitize_to_id(name), "value" => value }.update(options.stringify_keys)
 116       end
 117
 118       # Creates a label field
 119       #
 120       # ==== Options
 121       # * Creates standard HTML attributes for the tag.
 122       #
 123       # ==== Examples
 124       #   label_tag 'name'
 125       #   # => <label for="name">Name</label>
 126       #
 127       #   label_tag 'name', 'Your name'
 128       #   # => <label for="name">Your Name</label>
 129       #
 130       #   label_tag 'name', nil, :class => 'small_label'
 131       #   # => <label for="name" class="small_label">Name</label>
 132       def label_tag(name, text = nil, options = {})
 133         content_tag :label, text || name.to_s.humanize, { "for" => sanitize_to_id(name) }.update(options.stringify_keys)
 134       end
 135
 136       # Creates a hidden form input field used to transmit data that would be lost due to HTTP's statelessness or
 137       # data that should be hidden from the user.
 138       #
 139       # ==== Options
 140       # * Creates standard HTML attributes for the tag.
 141       #
 142       # ==== Examples
 143       #   hidden_field_tag 'tags_list'
 144       #   # => <input id="tags_list" name="tags_list" type="hidden" />
 145       #
 146       #   hidden_field_tag 'token', 'VUBJKB23UIVI1UU1VOBVI@'
 147       #   # => <input id="token" name="token" type="hidden" value="VUBJKB23UIVI1UU1VOBVI@" />
 148       #
 149       #   hidden_field_tag 'collected_input', '', :onchange => "alert('Input collected!')"
 150       #   # => <input id="collected_input" name="collected_input" onchange="alert('Input collected!')"
 151       #   #    type="hidden" value="" />
 152       def hidden_field_tag(name, value = nil, options = {})
 153         text_field_tag(name, value, options.stringify_keys.update("type" => "hidden"))
 154       end
 155
 156       # Creates a file upload field.  If you are using file uploads then you will also need
 157       # to set the multipart option for the form tag:
 158       #
 159       #   <% form_tag '/upload', :multipart => true do %>
 160       #     <label for="file">File to Upload</label> <%= file_field_tag "file" %>
 161       #     <%= submit_tag %>
 162       #   <% end %>
 163       #
 164       # The specified URL will then be passed a File object containing the selected file, or if the field
 165       # was left blank, a StringIO object.
 166       #
 167       # ==== Options
 168       # * Creates standard HTML attributes for the tag.
 169       # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
 170       #
 171       # ==== Examples
 172       #   file_field_tag 'attachment'
 173       #   # => <input id="attachment" name="attachment" type="file" />
 174       #
 175       #   file_field_tag 'avatar', :class => 'profile-input'
 176       #   # => <input class="profile-input" id="avatar" name="avatar" type="file" />
 177       #
 178       #   file_field_tag 'picture', :disabled => true
 179       #   # => <input disabled="disabled" id="picture" name="picture" type="file" />
 180       #
 181       #   file_field_tag 'resume', :value => '~/resume.doc'
 182       #   # => <input id="resume" name="resume" type="file" value="~/resume.doc" />
 183       #
 184       #   file_field_tag 'user_pic', :accept => 'image/png,image/gif,image/jpeg'
 185       #   # => <input accept="image/png,image/gif,image/jpeg" id="user_pic" name="user_pic" type="file" />
 186       #
 187       #   file_field_tag 'file', :accept => 'text/html', :class => 'upload', :value => 'index.html'
 188       #   # => <input accept="text/html" class="upload" id="file" name="file" type="file" value="index.html" />
 189       def file_field_tag(name, options = {})
 190         text_field_tag(name, nil, options.update("type" => "file"))
 191       end
 192
 193       # Creates a password field, a masked text field that will hide the users input behind a mask character.
 194       #
 195       # ==== Options
 196       # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
 197       # * <tt>:size</tt> - The number of visible characters that will fit in the input.
 198       # * <tt>:maxlength</tt> - The maximum number of characters that the browser will allow the user to enter.
 199       # * Any other key creates standard HTML attributes for the tag.
 200       #
 201       # ==== Examples
 202       #   password_field_tag 'pass'
 203       #   # => <input id="pass" name="pass" type="password" />
 204       #
 205       #   password_field_tag 'secret', 'Your secret here'
 206       #   # => <input id="secret" name="secret" type="password" value="Your secret here" />
 207       #
 208       #   password_field_tag 'masked', nil, :class => 'masked_input_field'
 209       #   # => <input class="masked_input_field" id="masked" name="masked" type="password" />
 210       #
 211       #   password_field_tag 'token', '', :size => 15
 212       #   # => <input id="token" name="token" size="15" type="password" value="" />
 213       #
 214       #   password_field_tag 'key', nil, :maxlength => 16
 215       #   # => <input id="key" maxlength="16" name="key" type="password" />
 216       #
 217       #   password_field_tag 'confirm_pass', nil, :disabled => true
 218       #   # => <input disabled="disabled" id="confirm_pass" name="confirm_pass" type="password" />
 219       #
 220       #   password_field_tag 'pin', '1234', :maxlength => 4, :size => 6, :class => "pin-input"
 221       #   # => <input class="pin-input" id="pin" maxlength="4" name="pin" size="6" type="password" value="1234" />
 222       def password_field_tag(name = "password", value = nil, options = {})
 223         text_field_tag(name, value, options.update("type" => "password"))
 224       end
 225
 226       # Creates a text input area; use a textarea for longer text inputs such as blog posts or descriptions.
 227       #
 228       # ==== Options
 229       # * <tt>:size</tt> - A string specifying the dimensions (columns by rows) of the textarea (e.g., "25x10").
 230       # * <tt>:rows</tt> - Specify the number of rows in the textarea
 231       # * <tt>:cols</tt> - Specify the number of columns in the textarea
 232       # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
 233       # * Any other key creates standard HTML attributes for the tag.
 234       #
 235       # ==== Examples
 236       #   text_area_tag 'post'
 237       #   # => <textarea id="post" name="post"></textarea>
 238       #
 239       #   text_area_tag 'bio', @user.bio
 240       #   # => <textarea id="bio" name="bio">This is my biography.</textarea>
 241       #
 242       #   text_area_tag 'body', nil, :rows => 10, :cols => 25
 243       #   # => <textarea cols="25" id="body" name="body" rows="10"></textarea>
 244       #
 245       #   text_area_tag 'body', nil, :size => "25x10"
 246       #   # => <textarea name="body" id="body" cols="25" rows="10"></textarea>
 247       #
 248       #   text_area_tag 'description', "Description goes here.", :disabled => true
 249       #   # => <textarea disabled="disabled" id="description" name="description">Description goes here.</textarea>
 250       #
 251       #   text_area_tag 'comment', nil, :class => 'comment_input'
 252       #   # => <textarea class="comment_input" id="comment" name="comment"></textarea>
 253       def text_area_tag(name, content = nil, options = {})
 254         options.stringify_keys!
 255
 256         if size = options.delete("size")
 257           options["cols"], options["rows"] = size.split("x") if size.respond_to?(:split)
 258         end
 259
 260         content_tag :textarea, content, { "name" => name, "id" => name }.update(options.stringify_keys)
 261       end
 262
 263       # Creates a check box form input tag.
 264       #
 265       # ==== Options
 266       # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
 267       # * Any other key creates standard HTML options for the tag.
 268       #
 269       # ==== Examples
 270       #   check_box_tag 'accept'
 271       #   # => <input id="accept" name="accept" type="checkbox" value="1" />
 272       #
 273       #   check_box_tag 'rock', 'rock music'
 274       #   # => <input id="rock" name="rock" type="checkbox" value="rock music" />
 275       #
 276       #   check_box_tag 'receive_email', 'yes', true
 277       #   # => <input checked="checked" id="receive_email" name="receive_email" type="checkbox" value="yes" />
 278       #
 279       #   check_box_tag 'tos', 'yes', false, :class => 'accept_tos'
 280       #   # => <input class="accept_tos" id="tos" name="tos" type="checkbox" value="yes" />
 281       #
 282       #   check_box_tag 'eula', 'accepted', false, :disabled => true
 283       #   # => <input disabled="disabled" id="eula" name="eula" type="checkbox" value="accepted" />
 284       def check_box_tag(name, value = "1", checked = false, options = {})
 285         html_options = { "type" => "checkbox", "name" => name, "id" => sanitize_to_id(name), "value" => value }.update(options.stringify_keys)
 286         html_options["checked"] = "checked" if checked
 287         tag :input, html_options
 288       end
 289
 290       # Creates a radio button; use groups of radio buttons named the same to allow users to
 291       # select from a group of options.
 292       #
 293       # ==== Options
 294       # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
 295       # * Any other key creates standard HTML options for the tag.
 296       #
 297       # ==== Examples
 298       #   radio_button_tag 'gender', 'male'
 299       #   # => <input id="gender_male" name="gender" type="radio" value="male" />
 300       #
 301       #   radio_button_tag 'receive_updates', 'no', true
 302       #   # => <input checked="checked" id="receive_updates_no" name="receive_updates" type="radio" value="no" />
 303       #
 304       #   radio_button_tag 'time_slot', "3:00 p.m.", false, :disabled => true
 305       #   # => <input disabled="disabled" id="time_slot_300_pm" name="time_slot" type="radio" value="3:00 p.m." />
 306       #
 307       #   radio_button_tag 'color', "green", true, :class => "color_input"
 308       #   # => <input checked="checked" class="color_input" id="color_green" name="color" type="radio" value="green" />
 309       def radio_button_tag(name, value, checked = false, options = {})
 310         pretty_tag_value = value.to_s.gsub(/\s/, "_").gsub(/(?!-)\W/, "").downcase
 311         pretty_name = name.to_s.gsub(/\[/, "_").gsub(/\]/, "")
 312         html_options = { "type" => "radio", "name" => name, "id" => "#{pretty_name}_#{pretty_tag_value}", "value" => value }.update(options.stringify_keys)
 313         html_options["checked"] = "checked" if checked
 314         tag :input, html_options
 315       end
 316
 317       # Creates a submit button with the text <tt>value</tt> as the caption.
 318       #
 319       # ==== Options
 320       # * <tt>:confirm => 'question?'</tt> - This will add a JavaScript confirm
 321       #   prompt with the question specified. If the user accepts, the form is
 322       #   processed normally, otherwise no action is taken.
 323       # * <tt>:disabled</tt> - If true, the user will not be able to use this input.
 324       # * <tt>:disable_with</tt> - Value of this parameter will be used as the value for a disabled version
 325       #   of the submit button when the form is submitted.
 326       # * Any other key creates standard HTML options for the tag.
 327       #
 328       # ==== Examples
 329       #   submit_tag
 330       #   # => <input name="commit" type="submit" value="Save changes" />
 331       #
 332       #   submit_tag "Edit this article"
 333       #   # => <input name="commit" type="submit" value="Edit this article" />
 334       #
 335       #   submit_tag "Save edits", :disabled => true
 336       #   # => <input disabled="disabled" name="commit" type="submit" value="Save edits" />
 337       #
 338       #   submit_tag "Complete sale", :disable_with => "Please wait..."
 339       #   # => <input name="commit" onclick="this.disabled=true;this.value='Please wait...';this.form.submit();"
 340       #   #    type="submit" value="Complete sale" />
 341       #
 342       #   submit_tag nil, :class => "form_submit"
 343       #   # => <input class="form_submit" name="commit" type="submit" />
 344       #
 345       #   submit_tag "Edit", :disable_with => "Editing...", :class => "edit-button"
 346       #   # => <input class="edit-button" onclick="this.disabled=true;this.value='Editing...';this.form.submit();"
 347       #   #    name="commit" type="submit" value="Edit" />
 348       def submit_tag(value = "Save changes", options = {})
 349         options.stringify_keys!
 350
 351         if disable_with = options.delete("disable_with")
 352           disable_with = "this.value='#{disable_with}'"
 353           disable_with << ";#{options.delete('onclick')}" if options['onclick']
 354
 355           options["onclick"]  = "if (window.hiddenCommit) { window.hiddenCommit.setAttribute('value', this.value); }"
 356           options["onclick"] << "else { hiddenCommit = this.cloneNode(false);hiddenCommit.setAttribute('type', 'hidden');this.form.appendChild(hiddenCommit); }"
 357           options["onclick"] << "this.setAttribute('originalValue', this.value);this.disabled = true;#{disable_with};"
 358           options["onclick"] << "result = (this.form.onsubmit ? (this.form.onsubmit() ? this.form.submit() : false) : this.form.submit());"
 359           options["onclick"] << "if (result == false) { this.value = this.getAttribute('originalValue');this.disabled = false; }return result;"
 360         end
 361
 362         if confirm = options.delete("confirm")
 363           options["onclick"] ||= ''
 364           options["onclick"] << "return #{confirm_javascript_function(confirm)};"
 365         end
 366
 367         tag :input, { "type" => "submit", "name" => "commit", "value" => value }.update(options.stringify_keys)
 368       end
 369
 370       # Displays an image which when clicked will submit the form.
 371       #
 372       # <tt>source</tt> is passed to AssetTagHelper#image_path
 373       #
 374       # ==== Options
 375       # * <tt>:confirm => 'question?'</tt> - This will add a JavaScript confirm
 376       #   prompt with the question specified. If the user accepts, the form is
 377       #   processed normally, otherwise no action is taken.
 378       # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
 379       # * Any other key creates standard HTML options for the tag.
 380       #
 381       # ==== Examples
 382       #   image_submit_tag("login.png")
 383       #   # => <input src="/images/login.png" type="image" />
 384       #
 385       #   image_submit_tag("purchase.png", :disabled => true)
 386       #   # => <input disabled="disabled" src="/images/purchase.png" type="image" />
 387       #
 388       #   image_submit_tag("search.png", :class => 'search-button')
 389       #   # => <input class="search-button" src="/images/search.png" type="image" />
 390       #
 391       #   image_submit_tag("agree.png", :disabled => true, :class => "agree-disagree-button")
 392       #   # => <input class="agree-disagree-button" disabled="disabled" src="/images/agree.png" type="image" />
 393       def image_submit_tag(source, options = {})
 394         options.stringify_keys!
 395
 396         if confirm = options.delete("confirm")
 397           options["onclick"] ||= ''
 398           options["onclick"] += "return #{confirm_javascript_function(confirm)};"
 399         end
 400
 401         tag :input, { "type" => "image", "src" => path_to_image(source) }.update(options.stringify_keys)
 402       end
 403
 404       # Creates a field set for grouping HTML form elements.
 405       #
 406       # <tt>legend</tt> will become the fieldset's title (optional as per W3C).
 407       # <tt>options</tt> accept the same values as tag.
 408       #
 409       # === Examples
 410       #   <% field_set_tag do %>
 411       #     <p><%= text_field_tag 'name' %></p>
 412       #   <% end %>
 413       #   # => <fieldset><p><input id="name" name="name" type="text" /></p></fieldset>
 414       #
 415       #   <% field_set_tag 'Your details' do %>
 416       #     <p><%= text_field_tag 'name' %></p>
 417       #   <% end %>
 418       #   # => <fieldset><legend>Your details</legend><p><input id="name" name="name" type="text" /></p></fieldset>
 419       #
 420       #   <% field_set_tag nil, :class => 'format' do %>
 421       #     <p><%= text_field_tag 'name' %></p>
 422       #   <% end %>
 423       #   # => <fieldset class="format"><p><input id="name" name="name" type="text" /></p></fieldset>
 424       def field_set_tag(legend = nil, options = nil, &block)
 425         content = capture(&block)
 426         concat(tag(:fieldset, options, true))
 427         concat(content_tag(:legend, legend)) unless legend.blank?
 428         concat(content)
 429         concat("</fieldset>")
 430       end
 431
 432       private
 433         def html_options_for_form(url_for_options, options, *parameters_for_url)
 434           returning options.stringify_keys do |html_options|
 435             html_options["enctype"] = "multipart/form-data" if html_options.delete("multipart")
 436             html_options["action"]  = url_for(url_for_options, *parameters_for_url)
 437           end
 438         end
 439
 440         def extra_tags_for_form(html_options)
 441           case method = html_options.delete("method").to_s
 442             when /^get$/i # must be case-insentive, but can't use downcase as might be nil
 443               html_options["method"] = "get"
 444               ''
 445             when /^post$/i, "", nil
 446               html_options["method"] = "post"
 447               protect_against_forgery? ? content_tag(:div, token_tag, :style => 'margin:0;padding:0') : ''
 448             else
 449               html_options["method"] = "post"
 450               content_tag(:div, tag(:input, :type => "hidden", :name => "_method", :value => method) + token_tag, :style => 'margin:0;padding:0')
 451           end
 452         end
 453
 454         def form_tag_html(html_options)
 455           extra_tags = extra_tags_for_form(html_options)
 456           tag(:form, html_options, true) + extra_tags
 457         end
 458
 459         def form_tag_in_block(html_options, &block)
 460           content = capture(&block)
 461           concat(form_tag_html(html_options))
 462           concat(content)
 463           concat("</form>")
 464         end
 465
 466         def token_tag
 467           unless protect_against_forgery?
 468             ''
 469           else
 470             tag(:input, :type => "hidden", :name => request_forgery_protection_token.to_s, :value => form_authenticity_token)
 471           end
 472         end
 473
 474         # see http://www.w3.org/TR/html4/types.html#type-name
 475         def sanitize_to_id(name)
 476           name.to_s.gsub(']','').gsub(/[^-a-zA-Z0-9:.]/, "_")
 477         end
 478
 479     end
 480   end
 481 end