The code of this tutorial has been tested against Eliom 4.
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 firstname.lastname@example.org or chat with us on IRC in channel #ocsigen on freenode.net (e.g. by using their webchat)!
The first section is an overview of the tutorial. The second section of this introduction lists our main software projects.
Overview of the tutorial
The tutorial is divided into several parts, mostly independant.
- If you want a wide overview about Ocsigen, for beginners, in french
- Look at this video, by Vincent Balat
- If you are an OCaml developer who want to write a Web site by generating page using OCaml functions
- Read tutorial Basic web site
- If you want to write a client-server Web application
- Read tutorial Client-server application
It describes step by step how to write a client/server collaborative drawing application. You will learn, from the very beginning, how to:
- 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
- If you want a quick introduction to client-server Web programming with Eliom
- Read tutorial Eliom apps basics: writing client server widgets
It shows on an example the client-server syntax, and is a good starting point for understanding Eliom's client-server features.
- If you want to write a more traditional Web site, with pages, forms, and sessions:
- Read tutorial Service based Web programming
This tutorial is devoted to server side programming. It shows how to create a new Web site with several pages and user connection. 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)
- If you want to learn more details about Ocsigen
- Read tutorial Miscellaneous features
We will mix the client-server drawing application with the session mechanism and user management 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 want to have quickly a full application with user management (registration, activation emails, authentication)
- Have a look at Eliom base app.
Eliom base app is a library and a template for Eliom distillery that contains a working Eliom application with user and right management.
You will also find some other tutorials in the menu on the left.
We also have a list of Quick HOWTOs.
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.
- If you want a more complete manual
- Read the manual of each project, and/or the API documentation.
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,
- Ocsigen Server, a full-featured 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 Web sites) 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.