Introduction
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 Ocsigen tutorial first, and especially this overview of all concepts or the 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, 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, 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.
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.