Introduction

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
everyone.

Eliom is a framework for developing Web and mobile applications.
It can be used to implement either basic server-side Web sites,
or advanced client-server applications accessible through a Web browser.
From Eliom 6.0,
it is also possible to implement, with a single code base,
multi-platform applications that will run on a Web browser or
a mobile device (iOS, Android ...).

The goal of Eliom (and other projects of the Ocsigen framework)
is to propose a new programming style that
matches the needs of modern Web applications better
than the usual languages (most of which were designed years ago,
for a much more static Web).

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.

making it possible to write a client-server application as a single
program.

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. For example, the programmer can choose the exact 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!

Services

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.

Eliom services enable several ways of generating 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 checkbox, 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 multiple-step forms very easily (like booking a plane
ticket).

Sessions and server-side state

Eliom has a very advanced 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.