Rails form helpers ================== Forms in web applications are an essential interface for user input. However, form markup can quickly become tedious to write and maintain because of form control naming and their numerous attributes. Rails deals away with these complexities by providing view helpers for generating form markup. However, since they have different use-cases, developers are required to know all the differences between similar helper methods before putting them to use. In this guide you will: * Create search forms and similar kind of generic forms not representing any specific model in your application * Make model-centric forms for creation and editing of specific database records * Generate select boxes from multiple types of data * Understand the date and time helpers Rails provides * Learn what makes a file upload form different * Find out where to look for complex forms NOTE: This guide is not intended to be a complete documentation of available form helpers and their arguments. Please visit http://api.rubyonrails.org/[the Rails API documentation] for a complete reference. Dealing With Basic Forms ------------------------ The most basic form helper is `form_tag`. ---------------------------------------------------------------------------- <% form_tag do %> Form contents <% end %> ---------------------------------------------------------------------------- When called without arguments like this, it creates a form element that has the current page as its action and "post" as its method (some line breaks added for readability): .Sample output from `form_tag` ----------------------------------------------------------------------------
---------------------------------------------------------------------------- If you carefully observe this output, you can see that the helper generated something you didn't specify: a `div` element with a hidden input inside. This is a security feature of Rails called *cross-site request forgery protection* and form helpers generate it for every form whose action is not "get" (provided that this security feature is enabled). You can read more about this in the link:./security.html#_cross_site_reference_forgery_csrf[Ruby On Rails Security Guide]. NOTE: Throughout this guide, this `div` with the hidden input will be stripped away to have clearer code samples. A Generic search form ~~~~~~~~~~~~~~~~~~~~~ Probably the most minimal form often seen on the web is a search form with a single text input for search terms. This form consists of: 1. a form element with "GET" method, 2. a label for the input, 3. a text input element, and 4. a submit element. IMPORTANT: Always use "GET" as the method for search forms. This allows users are able to bookmark a specific search and get back to it, more generally Rails encourages you to use the right HTTP verb for an action. To create this form you will use `form_tag`, `label_tag`, `text_field_tag` and `submit_tag`, respectively. .A basic search form ---------------------------------------------------------------------------- <% form_tag(search_path, :method => "get") do %> <%= label_tag(:q, "Search for:") %> <%= text_field_tag(:q) %> <%= submit_tag("Search") %> <% end %> ---------------------------------------------------------------------------- [TIP] ============================================================================ `search_path` can be a named route specified in "routes.rb": ---------------------------------------------------------------------------- map.search "search", :controller => "search" ---------------------------------------------------------------------------- ============================================================================ The above view code will result in the following markup: .Search form HTML ---------------------------------------------------------------------------- ---------------------------------------------------------------------------- Besides `text_field_tag` and `submit_tag`, there is a similar helper for _every_ form control in HTML. TIP: For every form input, an ID attribute is generated from its name ("q" in the example). These IDs can be very useful for CSS styling or manipulation of form controls with JavaScript. Multiple hashes in form helper calls ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By now you've seen that the `form_tag` helper accepts 2 arguments: the path for the action and an options hash. This hash specifies the method of form submission and HTML options such as the form element's class. As with the `link_to` helper, the path argument doesn't have to be given a string. It can be a hash of URL parameters that Rails' routing mechanism will turn into a valid URL. Still, you cannot simply write this: .A bad way to pass multiple hashes as method arguments ---------------------------------------------------------------------------- form_tag(:controller => "people", :action => "search", :method => "get", :class => "nifty_form") # =>