This document is the Eliom manual, where you will find an explanation of all Eliom concepts. If you are looking for a more gentle introduction, have a look at the Ocsigen tutorial, which is a good starting point for beginners.

In the past few years, the web evolved from something quite static to a powerful platform, able to run dynamic programs. Recent browsers enable an entirely new kind of application, but most web developers still use the same old web frameworks that have not been adapted for this evolution.

We think that the new possibilities necessitate rethinking web programming techniques. The goal of Eliom (and other projects of the Ocsigen framework) is to propose a new way of writing traditional web sites and sophisticated client-server web applications. It simplifies the development of complex applications by:

  • providing high level expressive concepts that address the needs of web developers. This allows programming complex behaviour in very few lines of code.
  • helping the programmer to write safe and bug-free applications. To improve security, it takes charge of many security issues itself. To reduce the number of bugs, it uses the very powerful type system of the OCaml language to check many properties of the application at compile time: well-formedness of HTML pages, types of page parameters, absence of broken links, etc.

Eliom does not restrict the possibilities offered by web technology. In particular, the programmer can choose exactly the URL and parameter names she wants. Eliom also produces clean HTML code that can be parsed by search engines, even for client/server applications.

Eliom is not an entirely new language, but an extension of OCaml. An Eliom application can use any existing OCaml library.

Eliom web sites are written as OCaml modules (producing cma or cmxs files), that are loaded as plugins into the Ocsigen server.

Client/server applications

Eliom applications are applications distributed between a server and a browser. An instance of the application is running in a browser tab, and can communicate with the server. The entire application is written in OCaml, as a single program, with special syntax to distinguish between server-side and client-side code. Client-side code is compiled to JavaScript, using the Js_of_ocaml compiler, to be executed by the browser.

It is possible to refer on the client side to values defined in server-side code. Communication between the server and the client is handled by Eliom automatically. The use of the same language on both sides makes it very easy to exchange data.

It is possible to have a client side Eliom program and maintain the traditional web interaction (with URLs, links, forms, bookmarks, and the back button). When you click on a link, the client-side program does not stop! Thus:

  • You can keep a state on client side for the whole duration of the visit.
  • You can set bookmarks corresponding to some states of the client-side program.
  • Part of the page can persist after loading a new page.
  • If you are listening to music or watching a video, playback does not stop when you change page!

More information...


Pages are generated by services, which are a kind of functions that are called when the user clicks on a link, or sends data through a form in a web page. Services can be associated to URLs. Eliom's service identification mechanism (that is: the way Eliom chooses the service to be executed) is actually much more sophisticated. It is using many different criteria, like the URL, but also special parameters, the HTTP method used (GET or POST), parameter names, the session, etc.

Services usually return HTML pages, but you can also choose to return files, redirections, actions (that is: just perform a side effect on the server and redraw the current page), applications, etc.

There are even several ways to generate HTML. You can send HTML as raw text (as in most web programming frameworks). However, it is preferable to check at compile time that every page generated respects the recommendations of the W3C. For this we are using the TyXML library.

When defining a service, you must specify the names and types of the parameters it expects (through the URL or through the body of the HTTP request). Eliom automatically checks parameters and translates them to the right OCaml type (even for complex types like lists and sets). The OCaml compiler checks that the parameters you put in links have the right type (w.r.t. the service). It also checks that your forms correspond to the service to which they are associated. For example, if your form contains a radio button, the service must expect a boolean value.

Services can be created dynamically. For example, you can create new services that depend on previous interaction with the user (form data for example). This is equivalent to what is usually called continuation-based web programming. This enables for example implementing several-step forms very easily (like booking a plane ticket).

More information...

Sessions and server-side state

Eliom also has a very sophisticated session mechanism. Sessions are a common pattern in web programming, allowing some data (a state) to be stored on the server for each browser. This is used for example to recognize connected users, or to store a shopping basket. This is usually implemented by recording a session identifier in a browser cookie. With Eliom, session data is stored in Eliom references, which are a kind of reference whose value depends on the session (the session identifier sent in the cookie).

But you can choose other scope than "session" for Eliom references:

  • It is also possible to define references with scope "client process", which corresponds to a tab of your browser (if you are using client-side features). For example, if you are implementing a game, you can have several instances of the game in separate tabs. The score is stored on the server in an Eliom reference of scope "client process".
  • Eliom also provides the scope "session group". This allows for example grouping together all sessions belonging to the same user. For example, you can use this to share a shopping basket between several devices (e.g., the user's laptop and smartphone).
  • There is also a scope "request" that can be used to store data during the generation of a page.

More information...