Parameters

URL-encoded parameters are the primary way browsers pass values to web applications. They are sent when a user submits a form, and are usually used for things like pagination.

Because Ring is a low level interface, it does not support parameters unless you apply the correct middleware:

(use 'ring.middleware.params)
(def app
  (wrap-params your-handler))

The wrap-params middleware provides support for URL-encoded parameters in the query string, or from the HTTP request body.

It does not provide support for file uploads, which is handled by the wrap-multipart-params middleware. See the section on File Uploads for more information about multipart forms.

The wrap-params function accepts an optional map of options. There's currently only one recognized key:

• :encoding - The character encoding of the parameters. Defaults to the request character encoding, or "UTF-8" if no request character encoding is set.

When applied to a handler, the parameter middleware adds three new keys to the request map:

• :query-params - A map of parameters from the query string
• :form-params - A map of parameters from submitted form data
• :params - A merged map of all parameters

For example, if you have a request that looks a little like this:

{:http-method :get
 :uri "/search"
 :query-string "q=clojure"}

Then the wrap-params middleware will modify the request into:

{:http-method :get
 :uri "/search"
 :query-string "q=clojure"
 :query-params {"q" "clojure"}
 :form-params {}
 :params {"q" "clojure"}}

Usually you'll only want to use the :params key, but the other keys are there in case you need to distinguish between a parameter passed via the query string, and one passed via a POSTed HTML form.

The parameters keys are strings, and the values are either strings, if there is only one value associated with the parameter name, or vectors, if there is more than one name/value pair with the same name.

For example, if you had a URL like:

http://example.com/demo?x=hello

Then your parameter map would look like:

{"x" => "hello"}

But if you have multiple parameters with the same name:

http://example.com/demo?x=hello&x=world

Then your parameter map would look like:

{"x" => ["hello", "world"]}