vendor/rails/railties/doc/guides/source/actioncontroller_basics/params.txt

   1 == Parameters ==
   2
   3 You will probably want to access data sent in by the user or other parameters in your controller actions. There are two kinds of parameters possible in a web application. The first are parameters that are sent as part of the URL, called query string parameters. The query string is everything after "?" in the URL. The second type of parameter is usually referred to as POST data. This information usually comes from a HTML form which has been filled in by the user. It's called POST data because it can only be sent as part of an HTTP POST request. Rails does not make any distinction between query string parameters and POST parameters, and both are available in the `params` hash in your controller:
   4
   5 [source, ruby]
   6 -------------------------------------
   7 class ClientsController < ActionController::Base
   8
   9   # This action uses query string parameters because it gets run by a HTTP
  10   # GET request, but this does not make any difference to the way in which
  11   # the parameters are accessed. The URL for this action would look like this
  12   # in order to list activated clients: /clients?status=activated
  13   def index
  14     if params[:status] = "activated"
  15       @clients = Client.activated
  16     else
  17       @clients = Client.unativated
  18     end
  19   end
  20
  21   # This action uses POST parameters. They are most likely coming from an HTML
  22   # form which the user has submitted. The URL for this RESTful request will
  23   # be "/clients", and the data will be sent as part of the request body.
  24   def create
  25     @client = Client.new(params[:client])
  26     if @client.save
  27       redirect_to @client
  28     else
  29       # This line overrides the default rendering behavior, which would have been
  30       # to render the "create" view.
  31       render :action => "new"
  32     end
  33   end
  34
  35 end
  36 -------------------------------------
  37
  38 === Hash and Array Parameters ===
  39
  40 The params hash is not limited to one-dimensional keys and values. It can contain arrays and (nested) hashes. To send an array of values, append "[]" to the key name:
  41
  42 -------------------------------------
  43 GET /clients?ids[]=1&ids[]=2&ids[]=3
  44 -------------------------------------
  45
  46 NOTE: The actual URL in this example will be encoded as "/clients?ids%5b%5d=1&ids%5b%5d=2&ids%5b%5b=3" as [ and ] are not allowed in URLs. Most of the time you don't have to worry about this because the browser will take care of it for you, and Rails will decode it back when it receives it, but if you ever find yourself having to send those requests to the server manually you have to keep this in mind.
  47
  48 The value of `params[:ids]` will now be `["1", "2", "3"]`. Note that parameter values are always strings; Rails makes no attempt to guess or cast the type.
  49
  50 To send a hash you include the key name inside the brackets:
  51
  52 -------------------------------------
  53 <form action="/clients" method="post">
  54   <input type="text" name="client[name]" value="Acme" />
  55   <input type="text" name="client[phone]" value="12345" />
  56   <input type="text" name="client[address][postcode]" value="12345" />
  57   <input type="text" name="client[address][city]" value="Carrot City" />
  58 </form>
  59 -------------------------------------
  60
  61 The value of `params[:client]` when this form is submitted  will be `{"name" => "Acme", "phone" => "12345", "address" => {"postcode" => "12345", "city" => "Carrot City"}}`. Note the nested hash in `params[:client][:address]`.
  62
  63 Note that the params hash is actually an instance of HashWithIndifferentAccess from Active Support which is a subclass of Hash which lets you use symbols and strings interchangeably as keys.
  64
  65 === Routing Parameters ===
  66
  67 The `params` hash will always contain the `:controller` and `:action` keys, but you should use the methods `controller_name` and `action_name` instead to access these values. Any other parameters defined by the routing, such as `:id` will also be available. As an example, consider a listing of clients where the list can show either active or inactive clients. We can add a route which captures the `:status` parameter in a "pretty" URL:
  68
  69 [source, ruby]
  70 ------------------------------------
  71 # ...
  72 map.connect "/clients/:status", :controller => "clients", :action => "index", :foo => "bar"
  73 # ...
  74 ------------------------------------
  75
  76 In this case, when a user opens the URL `/clients/active`, `params[:status]` will be set to "active". When this route is used, `params[:foo]` will also be set to "bar" just like it was passed in the query string in the same way `params[:action]` will contain "index".
  77
  78 === `default_url_options` ===
  79
  80 You can set global default parameters that will be used when generating URLs with `default_url_options`. To do this, define a method with that name in your controller:
  81
  82 ------------------------------------
  83 class ApplicationController < ActionController::Base
  84
  85   #The options parameter is the hash passed in to +url_for+
  86   def default_url_options(options)
  87     {:locale => I18n.locale}
  88   end
  89
  90 end
  91 ------------------------------------
  92
  93 These options will be used as a starting-point when generating, so it's possible they'll be overridden by +url_for+. Because this method is defined in the controller, you can define it on ApplicationController so it would be used for all URL generation, or you could define it on only one controller for all URLs generated there.