Writing a client/server Eliom application

The code of this tutorial has been tested against Eliom 6.0.

In this chapter, we will write a collaborative drawing application. It is a client/server web application displaying an area where users can draw using the mouse, and see what other users are drawing at the same time and in real-time.

This tutorial is a good starting point if you want a step-by-step introduction to Eliom programming.

The final eliom code is available for download. Tag eliom-5.0 has been tested against Eliom 5.0.


To get started, we recommend using Eliom's distillery, a program which creates scaffolds for Eliom projects. The following command creates a very simple project called graffiti in the directory graffiti:

$ eliom-distillery -name graffiti -template basic.ppx -target-directory graffiti

My first page

Our web application consists of a single page for now. Let's start by creating a very basic page. We define the service that will implement this page by the following declaration:

open Eliom_content.Html.D (* provides functions to create HTML nodes *)

let main_service =
    ~path:(Eliom_service.Path ["graff"])
    ~meth:(Eliom_service.Get Eliom_parameter.unit)
    (fun () () ->
           (head (title (pcdata "Page title")) [])
           (body [h1 [pcdata "Graffiti"]])))

If you're using eliom-distillery just replace the content of the eliom-file by the above lines and run

$ make test.byte

This will compile your application and run ocsigenserver on it. (Refer to the manual on how to compile your project "by hand".)

Your page is now available at URL http://localhost:8080/graff.

Execute parts of the program on the client

To create our first service, we used the function Eliom_registration.​Html.​create, as all we wanted to do was return HTML. But we actually want a service that corresponds to a full Eliom application with client and server parts. To do so, we need to create our own registration module by using the functor Eliom_registration.App:

module Graffiti_app =
  Eliom_registration.App (struct
      let application_name = "graffiti"
      let global_data_path = None

It is now possible to use Graffiti_app for registering our main service (now at URL /):

let main_service =
    ~path:(Eliom_servie.Path [""])
    ~meth:(Eliom_service.Get Eliom_parameter.unit)
    (fun () () ->
           (head (title (pcdata "Graffiti")) [])
           (body [h1 [pcdata "Graffiti"]]) ) )

We can now add some OCaml code to be executed by the browser. For this purpose, Eliom provides a syntax extension to distinguish between server and client code in the same file. We start by a very basic program, that will display a message to the user by calling the JavaScript function alert. Add the following lines to the program:

let%client _ = Eliom_lib.alert "Hello!"

After running again make test.byte, and visiting http://localhost:8080/, the browser will load the file graffiti.js, and open an alert-box.

Accessing server side variables on client side code

The client side process is not strictly separated from the server side. We can access some server variables from the client code. For instance:

let count = ref 0

let main_service =
    ~path:(Eliom_service.Path [""])
    ~meth:(Eliom_service.Get Eliom_parameter.unit)
    (fun () () ->
       let c = incr count; !count in
       ignore [%client
               (Printf.sprintf "You came %i times to this page" ~%c))
          : unit)
            (head (title (pcdata "Graffiti")) [])
            (body [h1 [pcdata "Graffiti"]])))

Here, we are increasing the reference count each time the page is accessed. When the page is loaded and the document is in-place, the client program initializes the value inside [%client ... ] , and thus triggers an alert window. More specifically, the variable c, in the scope of the client value on the server is made available to the client value using the syntax extension ~%c. In doing so, the server side value c is displayed in a message box on the client.

Collaborative drawing application

Drawing on a canvas

We now want to draw something on the page using an HTML canvas. The drawing primitive is defined in the client-side function called draw that just draws a line between two given points in a canvas.

To start our collaborative drawing application, we define another client-side function init_client , which just draws a single line for now.

Here is the (full) new version of the program:

  (* Modules opened in the shared-section are available in client-
     and server-code *)
  open Eliom_content.Html.D
  open Lwt
module Graffiti_app =
  Eliom_registration.App (
      let application_name = "graffiti"
      let global_data_path = None
let%shared width  = 700
let%shared height = 400
let%client draw ctx ((r, g, b), size, (x1, y1), (x2, y2)) =
  let color = CSS.Color.string_of_t (CSS.Color.rgb r g b) in
  ctx##.strokeStyle := (Js.string color);
  ctx##.lineWidth := float size;
  ctx##(moveTo (float x1) (float y1));
  ctx##(lineTo (float x2) (float y2));
let canvas_elt =
  canvas ~a:[a_width width; a_height height]
    [pcdata "your browser doesn't support canvas"]

let page () =
     (head (title (pcdata "Graffiti")) [])
     (body [h1 [pcdata "Graffiti"];
let%client init_client () =
  let canvas = Eliom_content.Html.To_dom.of_canvas ~%canvas_elt in
  let ctx = canvas##(getContext (Dom_html._2d_)) in
  ctx##.lineCap := Js.string "round";
  draw ctx ((0, 0, 0), 12, (10, 10), (200, 100))
let main_service =
    ~path:(Eliom_service.Path [""])
    ~meth:(Eliom_service.Get Eliom_parameter.unit)
    (fun () () ->
       (* Cf. section "Client side side-effects on the server" *)
       let _ = [%client (init_client () : unit) ] in
       Lwt.return (page ()))

Single user drawing application

We now want to catch mouse events to draw lines with the mouse like with the brush tools of any classical drawing application. One solution would be to mimic typical JavaScript code in OCaml; for example by using the function Dom_events.​listen that is the Js_of_ocaml's equivalent of addEventListener. However, this solution is at least as verbose as the JavaScript equivalent, hence not satisfactory. Js_of_ocaml's library provides a much easier way to do that with the help of Lwt.

Replace the init_client of the previous example by the following piece of code, then compile and draw!

let%client init_client () =

  let canvas = Eliom_content.Html.To_dom.of_canvas ~%canvas_elt in
  let ctx = canvas##(getContext (Dom_html._2d_)) in
  ctx##.lineCap := Js.string "round";

  let x = ref 0 and y = ref 0 in

  let set_coord ev =
    let x0, y0 = Dom_html.elementClientPosition canvas in
    x := ev##.clientX - x0; y := ev##.clientY - y0

  let compute_line ev =
    let oldx = !x and oldy = !y in
    set_coord ev;
    ((0, 0, 0), 5, (oldx, oldy), (!x, !y))

  let line ev = draw ctx (compute_line ev); Lwt.return () in

  Lwt.async (fun () ->
    let open Lwt_js_events in
    mousedowns canvas
      (fun ev _ ->
         set_coord ev; line ev >>= fun () ->
             [mousemoves Dom_html.document (fun x _ -> line x);
	      mouseup Dom_html.document >>= line]))

We use two references x and y to record the last mouse position. The function set_coord updates those references from mouse event data. The function compute_line computes the coordinates of a line from the initial (old) coordinates to the new coordinates–the event data sent as a parameter.

The last four lines of code implement the event-handling loop. They can be read as follows: for each mousedown event on the canvas, do set_coord, then line (this will draw a dot), then behave as the first of the two following lines that terminates:

  • For each mousemove event on the document, call line (never terminates)
  • If there is a mouseup event on the document, call line.

Collaborative drawing application

In order to see what other users are drawing, we now want to do the following:

  • Send the coordinates to the server when the user draw a line, then
  • Dispatch the coordinates to all connected users.

We first declare a type, shared by the server and the client, describing the color (as RGB values) and coordinates of drawn lines.

  type messages =
    ((int * int * int) * int * (int * int) * (int * int))
    [@@deriving json]

We annotate the type declaration with [@@deriving json] to allow type-safe deserialization of this type. Eliom forces you to use this in order to avoid server crashes if a client sends corrupted data. This is defined using a JSON plugin for ppx_deriving, which you need to install. You need to do that for each type of data sent by the client to the server. This annotation can only be added on types containing exclusively basic types, or other types annotated with [@@deriving json].

Then we create an Eliom bus to broadcast drawing events to all client with the function Eliom_bus.​create. This function take as parameter the type of values carried by the bus.

let bus = Eliom_bus.create [%derive.json: messages]

To write draw commands into the bus, we just replace the function line in init_client by:

let line ev =
  let v = compute_line ev in
  let _ = Eliom_bus.write ~%bus v in
  draw ctx v;
  Lwt.return () in

Finally, to interpret the draw orders read on the bus, we add the following line at the end of function init_client:

Lwt.async (fun () -> Lwt_stream.iter (draw ctx) (Eliom_bus.stream ~%bus))

Now you can try the program using two browser windows to see that the lines are drawn on both windows.

Color and size of the brush

In this section, we add a color picker and slider to choose the size of the brush. For the colorpicker we used a widget available in Ocsigen-widgets.

To install Ocsigen widgets, do:

opam pin add ocsigen-widgets https://github.com/ocsigen/ocsigen-widgets.git
opam install ocsigen-widgets

In Makefile.options, created by Eliom's distillery, add ocsigen-widgets.client to the CLIENT_PACKAGES:

CLIENT_PACKAGES := ... ocsigen-widgets.client

To create the widget, we add the following code in the init_client immediately after canvas configuration:

(* Color of the brush *)
let colorpicker = Ow_color_picker.create ~width:150 () in
Ow_color_picker.append_at (Dom_html.document##.body) colorpicker;
Ow_color_picker.init_handler colorpicker;

We subsequently add a simple HTML slider to change the size of the brush. Near the canvas_elt definition, simply add the following code:

let slider =
      Html.D.a_id "slider";
      Html.D.a_input_min (`Number 1);
      Html.D.a_input_max (`Number 80)

Form.int is a typing information telling that this input takes an integer value. This kind of input can only be associated to services taking an integer as parameter.

We then add the slider to the page body, as follows:

let page () =
    (head (title (pcdata "Graffiti")) [])