Introduction

This document is the Eliom manual, where you will find an explanation of each concepts provided by Eliom. If you are looking for a more didactic introduction, have a look at the tutorial of the Ocsigen project 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 very dynamic programs. Recent browsers make possible a very new kind of applications, but most Web developers still use the same old Web frameworks that are not adapted to this evolution.

We think these new possibilities deserve to rethink Web programming techniques. The goal of Eliom (and other projects of the Ocsigen framework) is to propose a new way to write traditional Web sites or sophisticated client/server Web applications. It simplifies the development of complex applications by:

providing high level expressive concepts
that fit very well the needs of Web developers. This allows to program complex behaviour in very few lines of code.
helping the programmer to write safe and bug free applications.
To improve security, it takes in charge itself many security issues. To reduce the number of bugs, it uses the very powerful typing 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 the technology. In particular, the programmer can choose exactly the URL and parameter names he wants. Eliom also produces clean HTML code that can be parsed by search engines (even for client/server applications).

Eliom is not a language but is using the OCaml language. This makes possible to use any existing library you want.

Eliom Web sites are written as OCaml modules (cma or cmxs), that will be loaded as a plugin into the Ocsigen server.

Services

Pages are generated by services, which are some kind of functions that are called when you click on a link or send 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), parameters 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 server side and redraw current page), applications, etc.

There are even several ways to generate HTML. You can send it as raw text (as in most Web programming frameworks). But we prefer to check at compile time that every page generated will respect the recommendation of the W3C. For this we are using the TyXML module (or, if you prefer, the OCamlDuce compiler, but this is not compatible with client/server Eliom applications).

When defining a service, you must specify the names and types of the parameters it expects (in the URL or in the body of the HTTP request). Eliom will automatically check parameters and translate them to the right OCaml type (even for complex types like list or 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 makes possible for example to implement several step forms very easily (like booking a plane ticket).

More information...

Sessions and server side state

Eliom also have a very sophisticated session mechanism. Sessions are a common pattern in Web programming allowing to store some data (a state) on server side 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 are stored in Eliom references, which are some 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 several tabs. The score is stored on server side in an Eliom references with scope "client process".
  • Eliom also provide a scope "session group". This allows to group together for example all sessions belonging to the same user. Use this for example if you want to share the shopping basket between several devices (like my laptop and my smartphone...).
  • There is also a scope "request" to store data during the generation of a page.

More information...

Client/server applications

Eliom applications are applications distributed between a server and a browser. An instance of the application is running in a tab of the browser and can communicate with the server. The full application is written in OCaml, as a single program, with a 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 use on client side values defined in server side code. Communication between the server and the client is taking in charge by Eliom automatically. The use of the same language on both sides makes very easy to exchange data.

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

  • You can keep a state on client side during all the duration of the visit on the Website.
  • 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 music or watching a video, it does not stop when you change page!

More information...