package dream-html

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

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"]]

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.