The code of this tutorial has been tested against Eliom 6.0.
In this tutorial, we will show how to use the Ocsigen framework (mainly Eliom) to write a lightweight Web site by generating pages using OCaml functions. The goal is to show that, even though Eliom makes it possible to write complete client-server Web and mobile apps, you can still use Eliom even if you don't need all these features (for example if you don't want HTML type checking or client-side features). Besides, this will allow you to extend your Web site in a full Web application if you need, later on. This tutorial is also a good overview of the basics of Eliom.
A service generating a page ¶
The following code shows how to create a service that answers for requests at URL http://.../aaa/bbb, by invoking an Ocaml function f of type:
f : (string * string) list -> unit -> string Lwt.t
Function f generates HTML as a string, taking as argument the list of URL parameters (GET parameters).
let f _ () = Lwt.return "<html><head><title>Hello world</title></head><body>Welcome</body></html>" let main_service = (* create the service and register it at once *) Eliom_registration.Html_text.create ~path:(Eliom_service.Path ["aaa"; "bbb"]) ~meth:(Eliom_service.Get Eliom_parameter.any) f
Eliom_service.Get Eliom_parameter.any means that the service uses the GET method and takes any GET parameter.
We recommend to use the program eliom-distillery to generate a template for your application (a Makefile and a default configuration file for Ocsigen Server).
$ eliom-distillery -name mysite -template basic.ppx -target-directory mysite
Modify file mysite.eliom to include the piece of code above, instead of the default one. Then compile and run the server by doing:
$ make test.byte
Your page is now available at URL http://localhost:8080/aaa/bbb.
If you dont want to use the Makefile provided by eliom-distillery, just replace mysite.eliom by a file mysite.ml, compile and run with
$ ocamlfind ocamlc -package eliom.server -thread -c mysite.ml $ ocsigenserver -c mysite.conf
where mysite.conf is adapted from local/etc/mysite/mysite-test.conf by replacing mysite.cma by your cmo.
POST service ¶
Services using the POST HTTP method can be created and registered using the function Eliom_registration.Html.create.
let g getp postp = Lwt.return ("t = " ^ (string_of_int postp)) let post_service = Eliom_registration.Html_text.create ~path:(Eliom_service.Path [""]) ~meth:(Eliom_service.Post (Eliom_parameter.any,Eliom_parameter.int "t")) g
What if the user comes back later without POST parameters, for example because he put a bookmark on this URL? This may produce an error, to prevent this from happening we can create a service without POST parameters using the same URL as the first one, which will be used whenever the POST parameters are not provided.
let g' getp postp = Lwt.return "..." let get_service = Eliom_registration.Html_text.create ~path:(Eliom_service.Path [""]) ~meth:(Eliom_service.Get Eliom_parameter.any) g'
Going further ¶
That is probably all you need for a very basic Web site in OCaml.
Instead of generating HTML in OCaml strings, we highly recommend to use typed HTML. It is very easy to use, once you have learned the basics, and helps a lot to efficiently write modular and valid HTML. To do this, use module Eliom_registration.Html instead of Eliom_registration.Html_text. See this tutorial for more information, a comprehensive documentation here, and a more advanced manual here.
Have a look at Eliom's API documentation to see other kinds of services, for example Eliom_registration.Redirection to create HTTP redirections.
Eliom also has a way to typecheck forms and GET or POST parameters. By giving a description of the parameters your service expects, Eliom will check their presence automatically, and convert them for you to OCaml types. See this tutorial and this manual page.
Eliom also has other ways to identify services (besides just the PATH in the URL). For example Eliom can identify a service just by a parameter (whatever the path is). This is called non-attached coservices and this makes it possible for instance to have the same feature on every page (for example a connection service). See this tutorial and this manual page.
Another interesting feature of Eliom is its session model, that uses a very simple interface to record session data server-side. It is even possible to choose the scope of this data: either a browser, or a tab, or even a group of browsers (belonging for instance to a same user). See this section and the beginning of this manual page.
We suggest to continue your reading by one of these tutorials:
- A quick start tutorial for client-server Eliom applications (for the people already familiar with OCaml, Lwt, etc.)
- A step by step tutorial for client-server Eliom applications
- A tutorial on server side dynamic Web site