=doc #17938 fix references to "Deserializer" in docs

This commit is contained in:
Konrad Malawski 2015-10-14 11:20:40 +02:00
parent da7e043372
commit 6ac2a2433c

View file

@ -35,17 +35,17 @@ as required, optional, or repeated, or to filter requests where a form field has
``"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 ``Deserializer`` in scope for that to work
extract value of field "amount" as ``Int``, you need a matching implicit ``Unmarshaller`` in scope for that to work
(see also :ref:`http-unmarshalling-scala`)
``"amount".as(deserializer)``
extract value of field "amount" with an explicit ``Deserializer``
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 ``Deserializer`` in scope for that to work
extract multiple occurrences of field "distance" as ``Iterable[Int]``, you need a matching implicit ``Unmarshaller`` in scope for that to work
(see also :ref:`http-unmarshalling-scala`)
``"distance".as(deserializer).*``
extract multiple occurrences of field "distance" with an explicit ``Deserializer``
extract multiple occurrences of field "distance" with an explicit ``Unmarshaller``
You can use :ref:`Case Class Extraction` to group several extracted values together into a case-class
instance.
@ -60,14 +60,14 @@ 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 deserializers are needed depending
``multipart/form-data``-encoded field is a "body part" containing an entity. This means that different kind of unmarshallerss are needed depending
on what the Content-Type of the request is:
- A ``application/x-www-form-urlencoded`` encoded field needs an implicit ``Deserializer[Option[String], T]``
- A ``multipart/form-data`` encoded field needs an implicit ``Deserializer[Option[BodyPart], T]``
- 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 ``Deserializer[String, T]`` if the value will be encoded as a ``String``.
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
@ -81,16 +81,16 @@ The ``formFields`` directive contains this logic to find and decide how to deser
- 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 ``Deserializer[Option[String], T]`` is available when a request of type ``multipart/form-data`` is
received, this deserializer will be tried to deserialize the body part for a field if the entity is of type
- 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 ``Deserializer[Option[BodyPart], T]`` is available when a request of type
``application/x-www-form-urlencoded`` is received, this deserializer will be tried to deserialize the field value by
- 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 deserializer accepts entities of type ``text/plain``.
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 ``Deserializer[Option[BodyPart], T]``.
to provide a ``FromStrictFormFieldUnmarshaller[T]``.
.. _HTML forms: http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4