The code of this tutorial has been tested Eliom 3.
This tutorial is an overview of the main features of the Ocsigen framework. It explains how to program web sites and client-server web applications in OCaml using Eliom, Lwt, js_of_ocaml and other libraries of the Ocsigen project. Read it to understand the basics, then refer to each project's manual for more detail.
This programming guide assumes you know the OCaml language, and that you have a working installation of Ocsigen server, Eliom, Lwt, Js_of_ocaml, (and O'Closure for some examples). In particular, you need to have the interfaces (cmi) installed for all these packages (the -dev-packages in some distributions). The installation is described here.
If you need help, you can send a mail to email@example.com or chat with us on IRC in channel #ocsigen on freenode.net (e.g. by using their webchat)!
The first section of this introduction lists our main software projects. The second section is an overview of the tutorial. In the following chapters, we will show how to build step by step a small client/server web application.
Ocsigen software projects
Most projects are independent and can be used for non Eliom-releated applications, for example:
- the cooperative threading library Lwt,
- the TyXML library for generating typed XML,
- the database query library Macaque,
- the Ocsigen web server.
Ocsigen server is a full featured web server written in modular way. It implements most features of the HTTP protocol, and has a powerful extension mechanism that make easy to plug your own OCaml modules for generating pages. Many extensions are already written:
- to serve static files.
- to create reliable client/server web applications or web sites in OCaml using advanced high level concepts.
- allows for more options in the configuration file.
- allows to restrict the access to the sites from the config file (to request coming from a subnet, containing some headers, etc.).
- allows to restrict the access to the sites from the config file using Basic HTTP Authentication.
- serves CGI scripts. It may also be used to serve PHP through CGI.
- used to compress data before sending to the client.
- sets redirections towards other web sites from the configuration file.
- a reverse proxy for Ocsigen server. It allows to ask another server to handle the request.
- changes in incoming requests before sending them to other extensions.
- rewrites some parts of the output before sending it to the client.
- allows users to have their own configuration files.
- facilitates server to client communications.
Ocsigen server has a sophisticated configuration file mechanism allowing complex configurations of sites.
Eliom is an extension for Ocsigen server that allows the creation of reliable client/server web applications (or traditional dynamic websites) in OCaml. It implements many new concepts, and as a result, its approach to application development is very different from all other web programming tools.
Eliom enables the creation of complex web sites in very few lines of code, by providing high level programming primitives for many aspects of web programming: communication between the client and the server, implementation of complex web interaction, sessions, etc.
Eliom also improves the stability of your application by making extensive use of OCaml's static typing. The compiler checks many things for you, helping you to remove many bugs. For example, the validity of pages (e.g. well-formed HTML) is checked at compile time! Moreover, Eliom statically checks for example that your web site does not contain any broken links and that the parameters in a link or a form correspond to the service it leads to (and many other things).
A client/server application in one piece of code!
Note that client side features can be mixed with traditional web interaction (links, forms, bookmarks, back button ...)
Eliom helps you to make your web application secure by automatically addressing several common security issues (code injection, session fixation ...) and by providing features to implement very secure behaviours (avoiding for example "cross-site request forgery").
Lwt is a cooperative thread library for OCaml. It provides an alternative to the more usual preemptive threads approach for programming concurrent applications, that avoids most problems of concurrent data access and deadlocks. It is used by Ocsigen server and Eliom and has now become one of the standard ways to implement concurrent applications in OCaml. All your web sites must be written in Lwt-compatible way!
- The whole language, and most of the standard library are supported.
- The compiler is easy to install: it depends only on Findlib and Lwt.
- The generated code whic is independant of Eliom and the Ocsigen server. You can use it with any web server.
- You can use a standard installation of OCaml to compile your programs. In particular, you do not have to recompile a library to use it with Js_of_ocaml. You just have to link your program with a specific library to interface with the browser API.
Macaque is a library for safe and flexible database queries using comprehensions.
Overview of the tutorial
The goal of this tutorial is to give an overview of the features provided by the Ocsigen framework to build web applications. It will allow you to understand the philosophy of Eliom (the web programming framework in OCaml), and makes also a good starting point to understand other libraries of the Ocsigen project: Lwt, Macaque, etc.
Theses chapters do not aim at exhaustiveness but many references towards other chapters are made all along the text, so that you can dive into the details if you want to.
We assume the reader has a good knowledge of the Objective Caml
- Create new services
- Output valid HTML
- Send OCaml code to be executed on the client
- Catch mouse events
- Communicate with the server, in both directions
- Use the O'Closure widget library
- Create services with non-HTML output
The following chapter is devoted to server side programming. We will create a new web site with several pages and user connection. In this chapter, you will learn how to:
- Create a link towards another service
- Create forms
- Register session data or session services
- Create services performing actions (with no output)
- Dynamically register new services (continuation based web programming)
The last chapter is an overview of miscellaneous features. We will mix the application from the two previous chapters to produce a multi-user collaborative drawing application. In this chapter, you will learn how to:
- Integrate a typical web interaction (links, forms, …) with a client side program.
- Use Macaque for type-safe database interaction
- Add sounds or videos to your application
- Change pages without stopping the client side program
- Connect with external accounts (openID)
- Add an Atom feed
If you are not interested in client-side programming you can safely skip most of the first chapter (although we recommend you read at least the first section, which explains the basics). Conversely, if you are not interested in standard web interactions, with sessions links, and forms, you can skip the second chapter.
Keep in mind that one of the key feature of Eliom is that it allows one to mix commonplace web interactions (URLs, forms, links, bookmarks, back button) with dynamic client side features. In particular, the client-side program does not stop when the user clicks a link, sends a form, or presses the back button–yet the user still can save bookmarks on pages! This opens up a wide field of new possibilities, and should facilitate the emergence of new kinds of web applications.