package bonsai

  1. Overview
  2. Docs
package bonsai
Legend:
Library
Module
Module type
Parameter
Class
Class type
module View : sig ... end
module Form_view := View
type 'a t
val return : 'a -> 'a t

return produces a bonsai form that will always produce the same value. set and normalize will do nothing to the form provided by this.

val return_settable : (module Bonsai_web.Bonsai.Model with type t = 'a) -> 'a -> 'a t Bonsai_web.Computation.t

return_settable is identical to return, but set and normalize will update the value of the form.

val return_error : Core.Error.t -> _ t

return_error produces a form that always fails validation.

val map_error : 'a t -> f:(Core.Error.t -> Core.Error.t) -> 'a t
val value : 'a t -> 'a Core.Or_error.t
val value_or_default : 'a t -> default:'a -> 'a
val is_valid : _ t -> bool

is_valid returns true if value would return Ok.

val view : _ t -> Form_view.t
val map_view : 'a t -> f:(Form_view.t -> Form_view.t) -> 'a t
module Submit : sig ... end
val view_as_vdom : ?theme:Bonsai_web.View.Theme.t -> ?on_submit:'a Submit.t -> ?editable:Form_view.editable -> 'a t -> Bonsai_web.Vdom.Node.t

view_as_vdom produces the vdom representation of the form.

editable defaults to `Yes_always, which should be used when form input can't be disabled. `Currently_yes allows editing, but generates less diff when toggled with `Currently_no. When editable is `Currently_no, the view is wrapped in a fieldset that disables all of the inputs in the form.

Regardless of the value of editable, scheduling the Form.set effect will still change the values in the form.

Known bugs: While setting editable to `Currently_no prevents modification of most browser-builtin input elements, some custom form elements like the drag-and-drop, multiselect, and removing items using the pills in typeahead-multi for don't currently respect this and can be modified anyway. Work is underway to fix these.

val set : 'a t -> 'a -> unit Ui_effect.t

set fills the form with the provided value, setting the contents of form-elements if possible

val normalize : _ t -> unit Ui_effect.t

normalize sets the contents of a form to its current value. This only impacts values that have a "normalized" form. For example, a float-producing textbox being normalized might go from displaying "1.000" to "1."

val both : 'a t -> 'b t -> ('a * 'b) t

Combines two forms into another one that produces both values from the inputs in tupled form.

val all : 'a t list -> 'a list t

Combines a list of forms into another that produces all values from the inputs in list form.

val all_map : ('k, 'a t, 'cmp) Core.Map.t -> ('k, 'a, 'cmp) Core.Map.t t

Combines a map of forms into another that produces all values from the inputs in map form.

val project : 'a t -> parse_exn:('a -> 'b) -> unparse:('b -> 'a) -> 'b t

project is the powerhouse of the library; Using this function, you can change the type produced. Think of it like map.

  • parse_exn is a function that converts "forwards". As its name implies, you're free (and encouraged to) throw exceptions when the type conversion would fail.
  • unparse goes in the opposite direction. This one must not throw.

Example:

let _ : int Form.t =
  project
    (a: string Form.t)
    ~parse_exn:Int.of_string
    ~unparse:Int.to_string
val project' : 'a t -> parse:('a -> 'b Core.Or_error.t) -> unparse:('b -> 'a) -> 'b t

The same as project except that the parse function is Or_error returning.

val validate : 'a t -> f:('a -> unit Core.Or_error.t) -> 'a t

validate can provide additional validation of a value, but unlike project or project', it doesn't change the type of the resulting form

val label : string -> 'a t -> 'a t

Adds a label to the form.

val label' : Bonsai_web.Vdom.Node.t -> 'a t -> 'a t

Same as label, but it lets you use an arbitrary vdom node instead of just a string.

val tooltip : string -> 'a t -> 'a t

Adds a tooltip to the form.

val tooltip' : Bonsai_web.Vdom.Node.t -> 'a t -> 'a t

Same as tooltip, but it lets you use an arbitrary vdom node instead of just a string.

val optional : 'a t -> is_some:('a -> bool) -> none:'a -> 'a option t

optional takes a 'a t and produces a 'a option t when given a "some detector" and a token "none" value. is_some none must be false.

Example:

let _ : string option t =
  optional
    (a: string t)
    ~is_some:(Fn.non String.is_empty)
    ~none:""
val optional' : 'a t -> parse:('a -> 'b option Core.Or_error.t) -> unparse:('b -> 'a) -> none:'a -> 'b option t

An alternative "optional form" construction function; optional' gives you the ability to produce the full set of parse options:

  • Ok (Some b)
  • Ok None
  • Error error] while also converting to another type ('a -> 'b option) at the same time.
val fallback_to : 'a t -> value:'a -> 'a t

fallback_to modifies the given form so that Ok default is used as the form's value when it is in an Error state.

module Record_builder : sig ... end

Record_builder is the primary way to compose form values using this library.

module Dynamic : sig ... end

Unlike the rest of the API which operates on values of type Form.t value values, they operate on Form.t Value.t, and typically return Computation.t.

module Expert : sig ... end
module Private : sig ... end
module Elements : sig ... end
module Typed : sig ... end

The functions in this module can be hard to understand Please look at the examples in lib/bonsai/examples/forms/typed.ml

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct