The code of this tutorial has been tested against Eliom 4.
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 using Eliom is possible even if you don't need all the features (for example if you don't want HTML typing or client side features). Besides, this will make possible to extend your Web site in a full Web application if you want, later. 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 will answer for requests at URL http://.../aaa/bbb, by calling the following Ocaml function f:
f : (string * string) list -> unit -> string Lwt.t
f generates HTML as a string, taking as argument the list of URL parameters (GET parameters).
let f _ () = Lwt.return "<html><head><title>A</title></head><body>B</body></html>" let main_service = Eliom_registration.Html_text.register_service ~path:["aaa"; "bbb"] ~get_params:Eliom_parameter.any f
Eliom_paramer.any means that the service 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 -target-directory mysite
Put these lines in file mysite.eliom, 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 are created using the function Eliom_service.Http.register_post_service. To create a service with POST parameters, first you must create a service without POST parameters and then the service with POST parameters, with the first service as fallback. The fallback will be used if the user comes back later without POST parameters, for example because he put a bookmark on this URL.
let g getp postp = Lwt.return "..." let post_service = Eliom_registration.Html_text.register_post_service ~fallback:main_service ~post_params:Eliom_parameter.any g
Going further ¶
That's probably all you need for a basic Web site in OCaml.
Have a look at Eliom's API documentation to see other kinds of services, for example Eliom_registration.Redirection to create HTTP redirections.
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.
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.
Eliom also has other ways to identify services (rather than 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 possible for example to have the same feature on every page (for example a connection service).
Eliom also make possible to write client side code in OCaml and to program the communication between client and server.
See other tutorials for more details about all this.