Module Dream_html.FormSource

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.

See the bottom of the page for complete examples.

• since 3.7.0.

Basic type decoders

In the following type decoders, the minimum and maximum values are all inclusive.

Forms and fields

Form decoders

  let* start_date = required unix_tm "start-date" in
  let+ end_date = required (unix_tm ~min:start_date) "end-date" in
  ...

Error keys

When errors are reported, the following keys are used instead of English strings. These keys can be used for localizing the error messages. The suggested default English translations are given below.

These keys are modelled after Play Framework.

Examples

Basic functionality

  type user =
    { name : string;
      age : int option
    }

  open Dream_html.Form

  let user_form =
    let+ name = required string "name"
    and+ age = optional (int ~min:16) "age" in
    (* Thanks, Australia! *)
    { name; age }

  let dream_form = ["age", "42"; "name", "Bob"]
  let user_result = validate user_form dream_form

Result: Ok { name = "Bob"; age = Some 42 }

Sad path:

  validate user_form ["age", "none"]

Result: Error [("age", "error.expected.int"); ("name", "error.required")]

Repeated values

  type plan =
    { id : string;
      features : string list
    }

  let plan_form =
    let+ id = required string "id"
    and+ features = list string "features" in
    { id; features } validate plan_form ["id", "foo"]

Result: Ok {id = "foo"; features = []}

  validate plan_form ["id", "foo"; "features", "f1"; "features", "f2"]

Result: Ok {id = "foo"; features = ["f1"; "f2"]}

Note that the names can be anything, eg "features[]" if you prefer.

Constrained field values

  let plan_form =
    let+ id =
      ensure "error.expected.nonempty" (( <> ) "") required string "id"
    and+ features = list string "features" in
    { id; features } validate plan_form ["id", ""]

Result: Error [("id", "error.expected.nonempty")]

Complex validation rules

Using chained validation rules where some fields depend on others:

  type req =
    { id : string;
      years : int option;
      months : int option;
      weeks : int option;
      days : int option
    }

  let req_form =
    let+ id = required string "id" (* Both id... *)
    and+ days, weeks, months, years =
      (* ...and period are required *)
      let* days = optional int "days" in
      let* weeks = optional int "weeks" in
      let* months = optional int "months" in
      let* years = optional int "years" in
      match days, weeks, months, years with
      | None, None, None, None -> error "years" "Please enter a period"
      (* Only one period component is required *)
      | _ -> ok (days, weeks, months, years)
    in
    { id; days; weeks; months; years } validate req []

Result: Error [("years", "Please enter a period"); ("id", "error.required")]

Multiple structured values

Suppose you have the following form data submitted:

  item-count: 2
  item[0].id: abc
  item[0].qty: 1
  item[1].id: def
  item[1].qty: 10
  item[1].discount: 25

And you want to decode it into the following types:

  type item =
    { id : string;
      qty : int;
      discount : int
    }

  type invoice =
    { item_count : int;
      items : item list
    }

First create the indexed invoice item decoder and invoice decoder:

  let item n =
    let nth name = "item[" ^ string_of_int n ^ "]." ^ name in
    let+ id = required string (nth "id")
    and+ qty = required int (nth "qty")
    and+ discount = required ~default:0 int (nth "discount") in
    { id; qty; discount }

  let invoice =
    let* item_count = required int "item-count" in
    let+ items = multiple item_count item in
    { item_count; items }

Try it:

  validate invoice
    [ "item[0].id", "abc";
      "item[0].qty", "1";
      "item[1].id", "def";
      "item[1].qty", "10";
      "item[1].discount", "25";
      "item-count", "2" ]

Result:

  Ok
    { item_count = 2;
      items =
        [ { id = "def"; qty = 10; discount = 25 };
          { id = "abc"; qty = 1; discount = 0 } ]
    }

Validation error:

  validate invoice
    [ "item[0].qty", "1";
      "item[1].id", "def";
      "item[1].discount", "25";
      "item-count", "2" ]
    Error
    [item [0].id, error.required; item [1].qty, error.required]