package ocaml-vdom

  1. Overview
  2. Docs

Virtual DOM

A "Virtual application" (or "Elm-like" application) is described by two types:

  • model: the current state of the UI,
  • msg ("messages"): possible state transitions;

and by the following values:

  • init: the initial state of the application, plus some initial commands to be spawned;
  • view: a function mapping the current state to a "virtual" DOM tree (vdom);
  • update: a function that processes messages to update the current state, and potentially spawns some commands.

Commands represents (typically) asynchronous operations, such as querying a server, or waiting for some timer.

Messages can be generated either by a VDOM tree (to encapsulate DOM events) or by commands (to notify their outcome).

Commands

module Cmd : sig ... end

Custom elements

module Custom : sig ... end

Properties and event handlers

type mouse_event = {
  1. x : int;
  2. y : int;
  3. page_x : float;
  4. page_y : float;
  5. buttons : int;
  6. alt_key : bool;
  7. ctrl_key : bool;
  8. shift_key : bool;
}
type key_event = {
  1. which : int;
  2. alt_key : bool;
  3. ctrl_key : bool;
  4. shift_key : bool;
}
type 'msg event_handler =
  1. | MouseDown of mouse_event -> 'msg
  2. | Click of mouse_event -> 'msg
  3. | DblClick of mouse_event -> 'msg
  4. | Focus of 'msg
  5. | Blur of 'msg
  6. | Input of string -> 'msg
  7. | Change of string -> 'msg
  8. | ChangeIndex of int -> 'msg
  9. | ChangeChecked of bool -> 'msg
  10. | MouseMove of mouse_event -> 'msg
  11. | KeyDown of key_event -> 'msg
  12. | KeyDownCancel of key_event -> 'msg option
  13. | ContextMenu of mouse_event -> 'msg
  14. | CustomEvent of Custom.event -> 'msg option
type prop_val =
  1. | String of string
  2. | Int of int
  3. | Float of float
  4. | Bool of bool
type 'msg attribute =
  1. | Property of string * prop_val
  2. | Style of string * string
  3. | Handler of 'msg event_handler
  4. | Attribute of string * string

Event handlers

val onmousedown : (mouse_event -> 'msg) -> 'msg attribute
val onclick : (mouse_event -> 'msg) -> 'msg attribute
val ondblclick : (mouse_event -> 'msg) -> 'msg attribute
val oncontextmenu : (mouse_event -> 'msg) -> 'msg attribute
val onfocus : 'msg -> 'msg attribute
val onblur : 'msg -> 'msg attribute
val oninput : (string -> 'msg) -> 'msg attribute

Pass the value property of the event target.

val onchange_checked : (bool -> 'msg) -> 'msg attribute

Pass the checked property of the event targer.

val onchange : (string -> 'msg) -> 'msg attribute

Pass the value property of the event target.

val onchange_index : (int -> 'msg) -> 'msg attribute

Pass the selected_index property of the event target.

val onmousemove : (mouse_event -> 'msg) -> 'msg attribute
val onkeydown : (key_event -> 'msg) -> 'msg attribute
val onkeydown_cancel : (key_event -> 'msg option) -> 'msg attribute
val oncustomevent : (Custom.event -> 'msg option) -> 'msg attribute

Generic DOM properties

Generic DOM properties correspond to actual properties on DOM objects. The name of these properties is usually the same as the corresponding HTML attribute, but not always (e.g. "class" attribute, but "className" property).

val str_prop : string -> string -> 'msg attribute
val int_prop : string -> int -> 'msg attribute
val bool_prop : string -> bool -> 'msg attribute
val float_prop : string -> float -> 'msg attribute
val style : string -> string -> 'msg attribute

A sub-field of the "style" DOM property.

val attr : string -> string -> 'mg attribute
val int_attr : string -> int -> 'msg attribute
val float_attr : string -> float -> 'msg attribute

Common DOM properties

val class_ : string -> 'msg attribute
val type_ : string -> 'msg attribute
val type_button : 'msg attribute
val value : string -> 'msg attribute
val disabled : bool -> 'msg attribute
val add_class : string -> 'msg attribute list -> 'msg attribute list

Pseudo-attributes

Pseudo-attributes are interpreted in a special way by the infrastructure.

val scroll_to_show : 'msg attribute

When this pseudo-attribute is first applied to an element, its parent is automatically scrolled (vertically) to show the element.

val autofocus : 'msg attribute

When this pseudo-attribute is first applied to an element, the element gets focused.

val relative_dropdown : int -> 'msg attribute

When this pseudo-attribute is first applied to an element, the element is moved to a fixed position below its parents.

val autofocus_counter : int -> 'msg attribute

When this pseudo-attribute is first applied to an element, or applied with a different counter as the previous time, the element gets focused.

Events

type event = {
  1. ev : 'msg. 'msg event_handler -> 'msg option;
}
val blur_event : event
val input_event : string -> event
val checked_event : bool -> event
val change_event : string -> event
val change_index_event : int -> event
val custom_event : Custom.event -> event

VDOM

type +'msg vdom =
  1. | Text of {
    1. key : string;
    2. txt : string;
    }
  2. | Element of {
    1. key : string;
    2. ns : string;
    3. tag : string;
    4. attributes : 'msg attribute list;
    5. children : 'msg vdom list;
    }
  3. | Map : {
    1. key : string;
    2. f : 'submsg -> 'msg;
    3. child : 'submsg vdom;
    } -> 'msg vdom
  4. | Memo : {
    1. key : string;
    2. f : 'a -> 'msg vdom;
    3. arg : 'a;
    } -> 'msg vdom
  5. | Custom of {
    1. key : string;
    2. elt : Custom.t;
    3. attributes : 'msg attribute list;
    }

Generic VDOM constructors

type ('msg, 'res) elt_gen = ?key:string -> ?a:'msg attribute list -> 'res
val elt : ?ns:string -> string -> ('msg, 'msg vdom list -> 'msg vdom) elt_gen

A generic element.

val svg_elt : string -> ('msg, 'msg vdom list -> 'msg vdom) elt_gen

A generic element in the SVG namespace.

val text : ?key:string -> string -> 'msg vdom

A text node.

val map_attr : ('msg attribute list -> 'msg attribute list) -> 'msg vdom -> 'msg vdom

Map attributes of a vdom element

val map : ?key:string -> ('a -> 'b) -> 'a vdom -> 'b vdom

Wrap all messages generated by a VDOM tree with the provided function.

val memo : ?key:string -> ('a -> 'msg vdom) -> 'a -> 'msg vdom

Apply the function to generate a VDOM tree only if the function or its argument have changed (physically) from the previous synchronization.

Note that physical equality is used both for the function and its argument. In particular, this is unlikely to behave as expected if the function is defined inline (as an abstraction) or obtained by a (partial) function application. Instead, the functional argument should be a simple reference to a globally defined function.

TODO: n-ary versions.

val custom : ?key:string -> ?a:'msg attribute list -> Custom.t -> 'msg vdom

A custom kind of node. Usually not used directly.

Common elements

val div : ('msg, 'msg vdom list -> 'msg vdom) elt_gen
val input : ('msg, 'msg vdom list -> 'msg vdom) elt_gen
val txt_span : ('msg, string -> 'msg vdom) elt_gen

Virtual Application

val return : ?c:'msg Cmd.t list -> 'model -> 'model * 'msg Cmd.t
type ('model, 'msg) app = {
  1. init : 'model * 'msg Cmd.t;
  2. update : 'model -> 'msg -> 'model * 'msg Cmd.t;
  3. view : 'model -> 'msg vdom;
}
val app : init:('model * 'msg Cmd.t) -> update:('model -> 'msg -> 'model * 'msg Cmd.t) -> view:('model -> 'msg vdom) -> unit -> ('model, 'msg) app
val simple_app : init:'model -> update:('model -> 'msg -> 'model) -> view:('model -> 'msg vdom) -> unit -> ('model, 'msg) app

A simple app does not trigger commands.