Compiling and configuring Eliom modules

This chapter explains how to set Eliom's options in the Ocsigen server configuration file, and how to define options for your Eliom modules. See the Ocsigen server documentation for more information about the server's configuration.

Note, however, that Eliom's distillery provides templates to get started at once with Eliom!

Using Eliom modules with Ocsigen server

Configuration file

To run an Ocsigen server with an Eliom module example.cmo, add the following lines to the Ocsigen configuration file (/etc/ocsigen/ocsigen.conf most of the times):

<extension findlib-package="eliom.server"/>
<host>
  <site path="examples">
    <eliommodule module="~///path_to///example.cmo" />
    <eliom />
  </site>
</host>

The block surrounded by the <site> tag creates a sub-site on your host, in directory examples. The <site> tag is optional if you want to register your services at the root of the server path tree.

The <eliom> tag defines an Eliom module to be loaded (dynamically while starting Ocsigen server) for this subsite.

Running Ocsigen server

Run Ocsigen server, by typing the command

ocsigenserver

or, if your configuration file is not in the default location:

ocsigenserver -c //<your configuration file>//

You should see the page corresponding to service "coucou" in site examples/ at url
http://your_server/examples/coucou.

Several Eliom modules for one site

If your site consists of several modules, you can load them consecutively from the configuration file using several eliommodule-tags. Note that there can be only one <eliom> tag for each <site> (or <host>), however.

Using findlib with Eliom modules

If your module has a findlib META file, it is also possible (and recommended!) to do:

<host>
  <site path="examples">
    <eliommodule findlib-package="//package-name//" />
    <eliom />
  </site>
</host>

Updating sites without shutting down the server

Ocsigen server has a feature that allows the configuration to be reloaded without shutting down the server (see section * *). This can be used to reload Eliom modules without closing volatile sessions. To do that use /etc/init.d/ocsigen reload for most of the distributions, or do it manually using:

echo reload > /var/run/ocsigen_command

Only modules loaded inside <host>, <site> or <library> will be reloaded. Module loaded using <extension> will not.

Have a look at the logs to see if all went well during the reload. If something went wrong, old services may still be reachable.

Warning:

  • Services created with the old modules or URLs that have not been masked by new ones will still reachable after the update!
  • During the reload, some information of the configuration file will not be re-read (for example port numbers, user and group, etc.).

Interacting with Ocsigen server from Eliom programs

Defining an exception handler for the whole site

When an exception is raised during the generation of a page, or when the page has not been found or has wrong parameters, an HTTP error 500 or 404 is sent to the client. You may want to catch these exceptions to print your own error page. Do this using Eliom_service.​set_exn_handler. Here is the handler used by the tutorial:

let _ = Eliom_service.set_exn_handler
   (fun e -> match e with
    | Eliom_common.Eliom_404 ->
        Eliom_registration.Html.send ~code:404
          (html
             (head (title (pcdata "")) [])
             (body [h1 [pcdata "Eliom tutorial"];
                    p [pcdata "Page not found"]])