Typed, extensible HTML form decoder with error reporting for form field validation failures. Powerful chained decoding functionality–the validation of one field can depend on the values of other decoded fields.

Type-safe wrapper for Dream.form. Similarly to that, you can match on the result:

  type new_user = { name : string; email : string }
  let new_user =
    let open Dream_html.Form in
    let+ name = required string "name"
    and+ email = required string "email" in
    { name; email }

  (* POST /users *)
  let post_users req =
    match%lwt Dream_html.form new_user req with
    | `Ok { name; email } -> (* ... *)
    | `Invalid errors -> Dream.json ~code:422 ( (* ...render errors... *) )
    | _ -> Dream.empty `Bad_Request

• since 3.8.0

Type-safe wrapper for Dream.all_queries. Can be used to decode the query parameters into a typed value.

• since 3.8.0

redirect ?status ?code ?headers ?flash req href is the same as Dream.redirect but instead of taking a string location to redirect to, it takes an attribute (you'll usually want to use href). The reason for taking an attribute is that we can construct correct route paths in attributes without having to hard-code the entire path. Eg,

  let%path order = "/orders/%s"
  ...
  let order_id = ... in
  Dream_html.redirect req (path_attr href order order_id)

• parameter flash

  convenience to add a flash message under the key flash. Internally just calls Dream.add_flash_message.

• since 3.11.0

Type-safe wrapper for Dream.send.

• since 3.2.0.

Type-safe wrapper for Dream.set_body. Sets the body to the given node and sets the Content-Type header to text/html.

Type-safe wrapper for Dream.write.

Convenience to add a CSRF token generated by Dream into your form. Type-safe equivalent of Dream.csrf_tag.

  form
    [action "/foo"]
    [csrf_tag req; input [name "bar"]; input [type_ "submit"]]

if_none_match req ~key refresh checks the If-None-Match header of req to see if it contains an ETag derived from the key. If so, it responds with 304 Not Modified and an empty body. Otherwise, it re-fetches the resource corresponding to key using refresh (), and sets the ETag in the response header.

• parameter key

  (eg a timestamp) together with the strength of its validator, is used to derive an ETag. If `None, the server does not know about the resource and responds with a 404 Not Found.

• since 3.11.0

if_match req ~key save checks if the If-Match header of req matches the ETag derived from the key. If so, it calls save () and returns the response. Otherwise, it responds with an error 412 Precondition Failed.

• parameter key

  (eg a timestamp) together with the strength of its validator, is used to derive an ETag. If `None, the server does not know about the resource and thus allows it to be updated with save ().

• since 3.11.0

A path that can be used for routing and can also be printed as an attribute value.

• since 3.9.0

Wrapper for a Dream route that represents the ability to parse path parameters and pass them to the handler function with the correct types.

• since 3.9.0

path request_fmt attr_fmt is a router path. The dream-html.ppx provides a more convenient way.

Without PPX: let order = path "/orders/%s" "/orders/%s"

With PPX: let%path order = "/orders/%s"

Refer to the PPX documentation for instructions on using it.

⚠️ Due to the way Dream's router works, all parameter captures happen between / characters and the end of the path (or the ? character, whichever comes first). Eg, /foo/%s/bar/%d is valid, but /foo/%s.%s (note the dot character) is not a valid capture.

⚠️ If a route is matched but the data type does not match, a 400 Bad Request response will be returned. The following type conversion specs are supported:

%s capture a string and pass it to the handler

%*s capture the rest of the path and pass the captured length and string to the handler

%c capture a char

%d or %i capture an int

%x capture a hexadecimal int

%X capture an uppercase hexadecimal int

%o capture an octal int

%ld capture an int32

%Ld capture an int64

%f capture a float

%B capture a bool

⚠️ We are actually using Dream's built-in router, not our own, and Dream's router doesn't distinguish between parameter types. So, to Dream both /%s and /%d are the same path. It will route the request to whichever happens to be first in the route list, and that one will succeed or fail depending on its type and the request target.

• since 3.9.0

path_attr attr path is an HTML attribute with the path parameters filled in from the given values. Eg,

  let%path order = "/orders/%s"

  open Dream_html
  open HTML

  a [path_attr href order "yzxyzc"] [txt "My Order"]

Renders: <a href="/orders/yzxyzc">My Order</a>

Use this instead of hard-coding your route URLs throughout your app, to make it easy to refactor routes with minimal effort.

• since 3.9.0

pp_path is a pretty-printer for path values. For a path like path "/foo" "/foo", it will print out /foo.

• since 3.9.0

Type-safe wrappers for Dream.get and so on. Using the PPX, eg:

  let%path order = "/orders/%s"

  let get_order = get order (fun request order_id ->
    ...
    a [path_attr href order order_id] [txt "Your order"]
    ...
  )

• since 3.9.0

• since 3.9.0

• since 3.9.0

• since 3.9.0

• since 3.9.0

• since 3.9.0

• since 3.9.0

• since 3.9.0

• since 3.9.0

• since 3.9.0

use middlewares routes is a route that is composed of all the given routes with the middlewares attached to them.

• since 3.9.0

static_asset path is a route that handles serving the static file at the path. Importantly, it sets an immutable cache header which remains valid for a year.

⚠️ Be sure that the resource has a unique identifier because it will be cached immutably. The dreamwork CLI tool automates this for you. See Dreamwork.

• since 3.9.2

Live reload script injection and handling. Adapted from Dream.livereload middleware. This version is not a middleware so it's not as plug-and-play as that, but on the other hand it's much simpler to implement because it uses type-safe dream-html nodes rather than parsing and printing raw HTML. See below for the 3-step process to use it.