formFields

Signature

def formFields(field: <FieldDef[T]>): Directive1[T]
def formFields(fields: <FieldDef[T_i]>*): Directive[T_0 :: ... T_i ... :: HNil]
def formFields(fields: <FieldDef[T_0]> :: ... <FieldDef[T_i]> ... :: HNil): Directive[T_0 :: ... T_i ... :: HNil]

The signature shown is simplified and written in pseudo-syntax, the real signature uses magnets. [1] The type <FieldDef> doesn’t really exist but consists of the syntactic variants as shown in the description and the examples.

[1] See The Magnet Pattern for an explanation of magnet-based overloading.

Description

Extracts fields from requests generated by HTML forms (independently of HttpMethod used).

Form fields can be either extracted as a String or can be converted to another type. The parameter name can be supplied either as a String or as a Symbol. Form field extraction can be modified to mark a field as required, optional, or repeated, or to filter requests where a form field has a certain value:

"color"

extract value of field “color” as String

"color".?

extract optional value of field “color” as Option[String]

"color" ? "red"

extract optional value of field “color” as String with default value "red"

"color" ! "blue"

require value of field “color” to be "blue" and extract nothing

"amount".as[Int]

extract value of field “amount” as Int, you need a matching implicit Unmarshaller in scope for that to work (see also Unmarshalling)

"amount".as(unmarshaller)

extract value of field “amount” with an explicit Unmarshaller

"distance".*

extract multiple occurrences of field “distance” as Iterable[String]

"distance".as[Int].*

extract multiple occurrences of field “distance” as Iterable[Int], you need a matching implicit Unmarshaller in scope for that to work (see also Unmarshalling)

"distance".as(unmarshaller).*

extract multiple occurrences of field “distance” with an explicit Unmarshaller

You can use Case Class Extraction to group several extracted values together into a case-class instance.

Requests missing a required field or field value will be rejected with an appropriate rejection.

There’s also a singular version, formField.

Query parameters can be handled in a similar way, see parameters.

Unmarshalling

Data POSTed from HTML forms is either of type application/x-www-form-urlencoded or of type multipart/form-data. The value of an url-encoded field is a String while the value of a multipart/form-data-encoded field is a “body part” containing an entity. This means that different kind of unmarshallers are needed depending on what the Content-Type of the request is:

• A application/x-www-form-urlencoded encoded field needs an implicit Unmarshaller[Option[String], T]
• A multipart/form-data encoded field needs an implicit FromStrictFormFieldUnmarshaller[T]

For common data-types, these implicits are predefined so that you usually don’t need to care. For custom data-types it should usually suffice to create a FromStringUnmarshaller[T] if the value will be encoded as a String. This should be valid for all values generated by HTML forms apart from file uploads.

Details

It should only be necessary to read and understand this paragraph if you have very special needs and need to process arbitrary forms, especially ones not generated by HTML forms.

The formFields directive contains this logic to find and decide how to deserialize a POSTed form field:

• It tries to find implicits of both types at the definition site if possible or otherwise at least one of both. If none is available compilation will fail with an “implicit not found” error.
• Depending on the Content-Type of the incoming request it first tries the matching (see above) one if available.
• If only a Unmarshaller[Option[String], T] is available when a request of type multipart/form-data is received, this unmarshaller will be tried to deserialize the body part for a field if the entity is of type text/plain or unspecified.
• If only a FromStrictFormFieldUnmarshaller[T] is available when a request of type application/x-www-form-urlencoded is received, this unmarshaller will be tried to deserialize the field value by packing the field value into a body part with an entity of type text/plain. Deserializing will only succeed if the unmarshaller accepts entities of type text/plain.

If you need to handle encoded fields of a multipart/form-data-encoded request for a custom type, you therefore need to provide a FromStrictFormFieldUnmarshaller[T].

Example

val route =
  formFields('color, 'age.as[Int]) { (color, age) =>
    complete(s"The color is '$color' and the age ten years ago was ${age - 10}")
  }

// tests:
Post("/", FormData("color" -> "blue", "age" -> "68")) ~> route ~> check {
  responseAs[String] shouldEqual "The color is 'blue' and the age ten years ago was 58"
}

Get("/") ~> Route.seal(route) ~> check {
  status shouldEqual StatusCodes.BadRequest
  responseAs[String] shouldEqual "Request is missing required form field 'color'"
}

For more examples about the way how fields can specified see the examples for the parameters directive.