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.

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クラスの抽出 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.

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.