{0 Introduction}

{e This document is the Eliom manual, where you will find an
detailed explanation of all Eliom concepts.
If you want to learn how to program with Ocsigen, please read
the {{:https://ocsigen.org/tuto/}Ocsigen tutorial} first,
and especially {{:https://ocsigen.org/tuto/basics.html}this overview of all concepts}
or the {{:https://ocsigen.org/tuto/basics-server.html}server-side programming guide}.}

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,
{b multi-platform applications} that will run on a {b Web browser} or
a {b 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, using a multi-tier extension of OCaml.
- 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.

{1 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
{e 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!

{{!page-"clientserver-applications"}More information...}

{1 Services}

Pages are generated by {e 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
{e 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
{e continuation-based Web programming}. This enables for example
implementing multiple-step forms very easily (like booking a plane
ticket).

{{!page-"server-services"}More information...}

{1 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 {e 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 {e scope} than "session" for Eliom
references:
- It is also possible to define references with scope {e "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 {e "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 {e "request"} that can be used to store data
  during the generation of a page.

{{!page-"server-state"}More information...}
