From b00e6a984df51a2f891c2a4c819ac2ab08359eed Mon Sep 17 00:00:00 2001 From: David Heinemeier Hansson Date: Sat, 23 Jun 2007 17:49:18 +0000 Subject: Massive documentation update for all helpers (closes #8223, #8177, #8175, #8108, #7977, #7972, #7971, #7969) [jeremymcanally] git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7106 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- .../lib/action_view/helpers/form_tag_helper.rb | 299 +++++++++++++++++---- 1 file changed, 251 insertions(+), 48 deletions(-) (limited to 'actionpack/lib/action_view/helpers/form_tag_helper.rb') diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb index cf8fb74f59..bf82fa234a 100644 --- a/actionpack/lib/action_view/helpers/form_tag_helper.rb +++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb @@ -3,33 +3,36 @@ require 'action_view/helpers/tag_helper' module ActionView module Helpers - # Provides a number of methods for creating form tags that doesn't rely on conventions with an object assigned to the template like - # FormHelper does. With the FormTagHelper, you provide the names and values yourself. + # Provides a number of methods for creating form tags that doesn't rely on an ActiveRecord object assigned to the template like + # FormHelper does. Instead, you provide the names and values manually. # - # NOTE: The html options disabled, readonly, and multiple can all be treated as booleans. So specifying :disabled => true - # will give disabled="disabled". + # NOTE: The HTML options disabled, readonly, and multiple can all be treated as booleans. So specifying + # :disabled => true will give disabled="disabled". module FormTagHelper # Starts a form tag that points the action to an url configured with url_for_options just like # ActionController::Base#url_for. The method for the form defaults to POST. # - # Examples: - # * form_tag('/posts') =>
- # * form_tag('/posts/1', :method => :put) => - # * form_tag('/upload', :multipart => true) => - # - # ERb example: - # <% form_tag '/posts' do -%> - #
<%= submit_tag 'Save' %>
- # <% end -%> - # - # Will output: - #
- # - # Options: + # ==== Options # * :multipart - If set to true, the enctype is set to "multipart/form-data". # * :method - The method to use when submitting the form, usually either "get" or "post". # If "put", "delete", or another verb is used, a hidden input with name _method # is added to simulate the verb over post. + # * A list of parameters to feed to the URL the form will be posted to. + # + # ==== Examples + # form_tag('/posts') + # # =>
+ # + # form_tag('/posts/1', :method => :put) + # # => + # + # form_tag('/upload', :multipart => true) + # # => + # + # <% form_tag '/posts' do -%> + #
<%= submit_tag 'Save' %>
+ # <% end -%> + # # =>
def form_tag(url_for_options = {}, options = {}, *parameters_for_url, &block) html_options = html_options_for_form(url_for_options, options, *parameters_for_url) if block_given? @@ -39,45 +42,101 @@ module ActionView end end - # Creates a dropdown selection box, or if the :multiple option is set to true, a multiple # choice selection box. # # Helpers::FormOptions can be used to create common select boxes such as countries, time zones, or - # associated records. + # associated records. option_tags is a string containing the option tags for the select box. + # + # ==== Options + # * :multiple - If set to true the selection will allow multiple choices. + # * :disabled - If set to true, the user will not be able to use this input. + # * Any other key creates standard HTML attributes for the tag. # - # option_tags is a string containing the option tags for the select box: - # # Outputs + # ==== Examples # select_tag "people", "" + # # => # - # Options: - # * :multiple - If set to true the selection will allow multiple choices. + # select_tag "count", "" + # # => + # + # select_tag "colors", "", :multiple => true + # # => + # + # select_tag "locations", "" + # # => + # + # select_tag "access", "", :multiple => true, :class => 'form_input' + # # => + # + # select_tag "destination", "", :disabled => true + # # => def select_tag(name, option_tags = nil, options = {}) content_tag :select, option_tags, { "name" => name, "id" => name }.update(options.stringify_keys) end - # Creates a standard text field. + # Creates a standard text field; use these text fields to input smaller chunks of text like a username + # or a search query. # - # Options: + # ==== Options # * :disabled - If set to true, the user will not be able to use this input. # * :size - The number of visible characters that will fit in the input. # * :maxlength - The maximum number of characters that the browser will allow the user to enter. + # * Any other key creates standard HTML attributes for the tag. # - # A hash of standard HTML options for the tag. + # ==== Examples + # text_field_tag 'name' + # # => + # + # text_field_tag 'query', 'Enter your search query here' + # # => + # + # text_field_tag 'request', nil, :class => 'special_input' + # # => + # + # text_field_tag 'address', '', :size => 75 + # # => + # + # text_field_tag 'zip', nil, :maxlength => 5 + # # => + # + # text_field_tag 'payment_amount', '$0.00', :disabled => true + # # => + # + # text_field_tag 'ip', '0.0.0.0', :maxlength => 15, :size => 20, :class => "ip-input" + # # => def text_field_tag(name, value = nil, options = {}) tag :input, { "type" => "text", "name" => name, "id" => name, "value" => value }.update(options.stringify_keys) end - # Creates a hidden field. + # Creates a hidden form input field used to transmit data that would be lost due to HTTP's statelessness or + # data that should be hidden from the user. + # + # ==== Options + # * Creates standard HTML attributes for the tag. + # + # ==== Examples + # hidden_field_tag 'tags_list' + # # => # - # Takes the same options as text_field_tag + # hidden_field_tag 'token', 'VUBJKB23UIVI1UU1VOBVI@' + # # => + # + # hidden_field_tag 'collected_input', '', :onchange => "alert('Input collected!')" + # # => def hidden_field_tag(name, value = nil, options = {}) text_field_tag(name, value, options.stringify_keys.update("type" => "hidden")) end - # Creates a file upload field. + # Creates a file upload field. If you are using file uploads then you will also need + # to set the multipart option for the form tag: # - # If you are using file uploads then you will also need to set the multipart option for the form: # <%= form_tag { :action => "post" }, { :multipart => true } %> # <%= file_field_tag "file" %> # <%= submit_tag %> @@ -85,23 +144,93 @@ module ActionView # # The specified URL will then be passed a File object containing the selected file, or if the field # was left blank, a StringIO object. + # + # ==== Options + # * Creates standard HTML attributes for the tag. + # * :disabled - If set to true, the user will not be able to use this input. + # + # ==== Examples + # file_field_tag 'attachment' + # # => + # + # file_field_tag 'avatar', :class => 'profile-input' + # # => + # + # file_field_tag 'picture', :disabled => true + # # => + # + # file_field_tag 'resume', :value => '~/resume.doc' + # # => + # + # file_field_tag 'user_pic', :accept => 'image/png,image/gif,image/jpeg' + # # => + # + # file_field_tag 'file', :accept => 'text/html', :class => 'upload', :value => 'index.html' + # # => def file_field_tag(name, options = {}) text_field_tag(name, nil, options.update("type" => "file")) end - # Creates a password field. + # Creates a password field, a masked text field that will hide the users input behind a mask character. # - # Takes the same options as text_field_tag + # ==== Options + # * :disabled - If set to true, the user will not be able to use this input. + # * :size - The number of visible characters that will fit in the input. + # * :maxlength - The maximum number of characters that the browser will allow the user to enter. + # * Any other key creates standard HTML attributes for the tag. + # + # ==== Examples + # password_field_tag 'pass' + # # => + # + # password_field_tag 'secret', 'Your secret here' + # # => + # + # password_field_tag 'masked', nil, :class => 'masked_input_field' + # # => + # + # password_field_tag 'token', '', :size => 15 + # # => + # + # password_field_tag 'key', nil, :maxlength => 16 + # # => + # + # password_field_tag 'confirm_pass', nil, :disabled => true + # # => + # + # password_field_tag 'pin', '1234', :maxlength => 4, :size => 6, :class => "pin-input" + # # => def password_field_tag(name = "password", value = nil, options = {}) text_field_tag(name, value, options.update("type" => "password")) end - # Creates a text input area. + # Creates a text input area; use a textarea for longer text inputs such as blog posts or descriptions. + # + # ==== Options + # * :size - A string specifying the dimensions of the textarea using dimensions (e.g., "25x10"). + # * :rows - Specify the number of rows in the textarea + # * :cols - Specify the number of columns in the textarea + # * :disabled - If set to true, the user will not be able to use this input. + # * Any other key creates standard HTML attributes for the tag. + # + # ==== Examples + # text_area_tag 'post' + # # => + # + # text_area_tag 'bio', @user.bio + # # => # - # Options: - # * :size - A string specifying the dimensions of the textarea. - # # Outputs - # <%= text_area_tag "body", nil, :size => "25x10" %> + # text_area_tag 'body', nil, :rows => 10, :cols => 25 + # # => + # + # text_area_tag 'body', nil, :size => "25x10" + # # => + # + # text_area_tag 'description', "Description goes here.", :disabled => true + # # => + # + # text_area_tag 'comment', nil, :class => 'comment_input' + # # => def text_area_tag(name, content = nil, options = {}) options.stringify_keys! @@ -112,14 +241,52 @@ module ActionView content_tag :textarea, content, { "name" => name, "id" => name }.update(options.stringify_keys) end - # Creates a check box. + # Creates a check box form input tag. + # + # ==== Options + # * :disabled - If set to true, the user will not be able to use this input. + # * Any other key creates standard HTML options for the tag. + # + # ==== Examples + # check_box_tag 'accept' + # # => + # + # check_box_tag 'rock', 'rock music' + # # => + # + # check_box_tag 'receive_email', 'yes', true + # # => + # + # check_box_tag 'tos', 'yes', false, :class => 'accept_tos' + # # => + # + # check_box_tag 'eula', 'accepted', false, :disabled => true + # # => def check_box_tag(name, value = "1", checked = false, options = {}) html_options = { "type" => "checkbox", "name" => name, "id" => name, "value" => value }.update(options.stringify_keys) html_options["checked"] = "checked" if checked tag :input, html_options end - # Creates a radio button. + # Creates a radio button; use groups of radio buttons named the same to allow users to + # select from a group of options. + # + # ==== Options + # * :disabled - If set to true, the user will not be able to use this input. + # * Any other key creates standard HTML options for the tag. + # + # ==== Examples + # radio_button_tag 'gender', 'male' + # # => + # + # radio_button_tag 'receive_updates', 'no', true + # # => + # + # radio_button_tag 'time_slot', "3:00 p.m.", false, :disabled => true + # # => + # + # radio_button_tag 'color', "green", true, :class => "color_input" + # # => def radio_button_tag(name, value, checked = false, options = {}) pretty_tag_value = value.to_s.gsub(/\s/, "_").gsub(/(?!-)\W/, "").downcase pretty_name = name.gsub(/\[/, "_").gsub(/\]/, "") @@ -128,14 +295,33 @@ module ActionView tag :input, html_options end - # Creates a submit button with the text value as the caption. If options contains a pair with the key of :disable_with, - # then the value will be used to rename a disabled version of the submit button. - # - # Options: - # * :disable_with - When specified the button will be disabled when clicked and the value will be replaced with the - # the string provided. - # # Outputs - # <%= submit_tag 'Send', :disable_with => 'Saving...' %> + # Creates a submit button with the text value as the caption. + # + # ==== Options + # * :disabled - If set to true, the user will not be able to use this input. + # * :disable_with - Value of this parameter will be used as the value for a disabled version + # of the submit button when the form is submitted. + # * Any other key creates standard HTML options for the tag. + # + # ==== Examples + # submit_tag + # # => + # + # submit_tag "Edit this article" + # # => + # + # submit_tag "Save edits", :disabled => true + # # => + # + # submit_tag "Complete sale", :disable_with => "Please wait..." + # # => + # + # submit_tag nil, :class => "form_submit" + # # => + # + # submit_tag "Edit", :disable_width => "Editing...", :class => 'edit-button' + # # => def submit_tag(value = "Save changes", options = {}) options.stringify_keys! @@ -157,6 +343,23 @@ module ActionView # Displays an image which when clicked will submit the form. # # source is passed to AssetTagHelper#image_path + # + # ==== Options + # * :disabled - If set to true, the user will not be able to use this input. + # * Any other key creates standard HTML options for the tag. + # + # ==== Examples + # image_submit_tag("login.png") + # # => + # + # image_submit_tag("purchase.png"), :disabled => true + # # => + # + # image_submit_tag("search.png"), :class => 'search-button' + # # => + # + # image_submit_tag("agree.png"), :disabled => true, :class => "agree-disagree-button" + # # => def image_submit_tag(source, options = {}) tag :input, { "type" => "image", "src" => image_path(source) }.update(options.stringify_keys) end -- cgit v1.2.3