Eliom

Reference manual

Version 1.2.0

Index

Lwt

Eliom

Main modules

Pages with Ocamlduce

XHTML pages typed with variants

Other pages

Eliom_predefmod

Creating new kinds of pages

Ocsigen

This is a preliminary version of the documentation. Help us to improve it by filling tickets. We are looking for native english speakers to proof read the documentation. Contact us!

3. More details on services and page generation

You now know all Eliom's main concepts. In that part, we'll give more details on some aspects that have been seen before:

The different types of output for services
Timeouts and error handling
Persistence of sessions
Advanced forms

Static parts

Fully static pages

The staticmod extension allows to associate to your site a static directory where you can put all the static (non generated) parts of your web-site (for examples images ans stylesheets). See the default config file ocsigen.conf to learn how to do that. A predefined service can be used to make links to static files. Get it using (static_dir sp). That service takes as string parameter the name of the file.
For example

Eliom.a
  (static_dir ~sp)
  sp
  [pcdata "download image"]
  "ocsigen8-100x30.png"

creates this link: download image

It is now also possible to handle static pages with Eliom, using Eliom_predefmod.Files (see later).

Other kinds of pages

Sending portions of pages

The Eliom_predefmod.Blocks module allows to register services that send portions of pages, of any type that may be contained directly in a <body> tag (blocks of xhtml DTD). It is useful to create AJAX pages (i.e. pages using the XMLHttpRequest Javascript object). Note that the service returns a list of blocks.


let divpage =
  Eliom_predefmod.Blocks.register_new_service
    ~path:["div"]
    ~get_params:unit
    (fun sp () () ->
      return
        [div [h2 [pcdata "Hallo"];
              p [pcdata "Blablablabla"] ]])

The Eliom_predefmod.SubXhtml module allows to create other modules for registering portions of pages of other types. For example, Eliom_predefmod.Blocks is defined by:


module Blocks = SubXhtml(struct
  type content = Xhtmltypes.body_content
end)

Redirections

The Eliom_predefmod.Redirection module allows to register HTTP redirections.
[New in 1.1.0. For 1.0.0, please see module Eliom_predefmod.Redirections.]
If a request is done towards such a service, the server asks the browser to retry with another URL.

Such services return a GET service without parameter at all. Example:


let redir1 = Eliom_predefmod.Redirection.register_new_service
    ~options:`Temporary
    ~path:["redir"]
    ~get_params:Eliom_parameters.unit
   (fun sp () () -> Lwt.return coucou)

If you want to give parameters to such services, use Eliom_services.preapply (see also later in the tutorial). Example:


let redir = Eliom_predefmod.Redirection.register_new_service
    ~options:`Temporary
    ~path:["redir"]
    ~get_params:(int "o")
   (fun sp o () ->
      Lwt.return
        (Eliom_services.preapply coucou_params (o,(22,"ee"))))

The options parameter may be either `Temporary or `Permanent.

Try it.

Note that the cost of a redirection is one more query and one more answer.

Sending files

You may want to register a service that will send files. To do that, use the Eliom_predefmod.Files module. Example:


let sendfile =
  Files.register_new_service
    ~path:["sendfile"]
    ~get_params:unit
    (fun _ () () -> return "filename")

Other example, with suffix URL:


let sendfile2 =
  Files.register_new_service
    ~path:["files"]
    ~get_params:(suffix (all_suffix "filename"))
    (fun _ s () -> return ("//path//"^(Ocsigen_extensions.string_of_url_path ~encode:false s)))

The extension Staticmod is another way to handle static files (see the default configuration file for more information).

Registering services that decide what they want to send

You may want to register a service that will send, for instance, sometimes an xhtml page, sometimes a file, sometimes something else. To do that, use the Eliom_predefmod.Any module, together with the send function of the module you want to use. Example:


let send_any =
  Eliom_predefmod.Any.register_new_service
    ~path:["sendany"]
    ~get_params:(string "type")
   (fun sp s () ->
     if s = "valid"
     then
       Eliom_predefmod.Xhtml.send sp
         (html
            (head (title (pcdata "")) [])
            (body [p [pcdata
                        "This page has been statically typechecked.
                         If you change the parameter in the URL you will get an unchecked text page"]]))
     else
       Eliom_predefmod.HtmlText.send sp
         "<html><body><p>It is not a valid page. Put type=\"valid\" in the URL to get a typechecked page.</p></body></html>"
   )

See a valid page, and a non valid page.

You may also use Eliom_predefmod.Any to send cookies or to choose a different charset than the default (default charset is set in configuration file) for the page you send. To do that use the optional parameters ?cookies and ?charset of the send function.

Cookies

A simplest way to set your own cookies on the client is to use functions like Eliom_predefmod.Xhtml.Cookies.register instead of Eliom_predefmod.Xhtml.register. The function you register returns a pair containing the page (as usual) and a list of cookies, of type Eliom_services.cookie defined by:


type cookie =
  | Set of string list option * float option * string * string * bool
  | Unset of string list option * string

[New in 1.1.0] For version 1.0.0, the type cookie was slightly different (no secure cookies).

The string list option is a the path for which you want to set/unset the cookie (relative to the main directory of your site, defined in the configuration file). None means for all your site.

The float option is a the expiration date (Unix timestamp, in seconds since the epoch). None means that the cookie will expire when the browser will be closed.

If the bool is true and the protocol is https, the server will ask the browser to send the cookie only through secure connections.

You can access the cookies sent by the browser using Eliom_sessions.get_cookies sp.

Example:


let cookiename = "mycookie"

let cookies = new_service ["cookies"] unit ()

let _ = Cookies.register cookies
    (fun sp () () ->
      return
       ((html
         (head (title (pcdata "")) [])
         (body [p [pcdata (try
                             "cookie value: "^
                             (Ocsigen_http_frame.Cookievalues.find
                                cookiename (Eliom_sessions.get_cookies sp))
                           with _ -> "<cookie not set>");
                   br ();
                   a cookies sp [pcdata "send other cookie"] ()]])),
        [Eliom_services.Set (None, None,
                             cookiename,
                             string_of_int (Random.int 100),
                             false)]))

Try it.

Persistence of sessions

Tables of sessions (for data or services) are kept in memory, and thus will disappear if you close the server process. To solve this problem, Ocsigen allows to reload the modules of your configuration file without shutting down the server. Another solution provided by Eliom is to save session data on hard disk.

Updating sites without shutting down the server

To reload the modules of the configuration file without stoping the server, 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 <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.

Note that coservices 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.).

Persistent data

Eliom allows to use more persistent data, using the module Ocsipersist. (Ocsipersist is needed in eliom.cma, thus you need to dynlink it in the configuration file before Eliom). There are currently two implementations of Ocsipersist: ocsipersist-dbm.cma (uses the DBM database) and ocsipersist-sqlite.cma (uses the SQLite database, and depends on sqlite3.cma).

These modules allow to:

Create persistent references (still present after restarting the server),
Create persistent association tables,
Set persistent session data (using set_persistent_data, see below).

Note that persistent data are serialized on hard disk using OCaml's Marshal module:

It is not possible to serialize closures or services (as we are using dynamic linking).
If you ever change the type of serialised data, don't forget to delete the database file! Or if you really want to keep it, and you know what you are doing, you can use the sqlite client to manually update the table or a program to create a new sqlite or dbm table for the new type.

Suppose for example that you use get/set_persistent_data (see below) to store a (int, string) tuple with the user's login credentials. At this point you stop the server, and change the code such that get/set_persistent_data now to store a (int, string, string). Now recompile and restart the server. If by any chance a client with an old cookie reconnects, you get a segfault on the server, because of the type change in the data stored in the DB backend ...

Persistent references

Ocsipersist allows to create persistent references. Here is an example of page with a persistent counter:


let mystore = Ocsipersist.open_store "eliomexamplestore2"

let count2 =
  let next =
    let cthr = Ocsipersist.make_persistent mystore "countpage" 0 in
    let mutex = Lwt_mutex.create () in
    (fun () ->
      cthr >>=
      (fun c ->
        Lwt_mutex.lock mutex >>= fun () ->
        Ocsipersist.get c >>=
        (fun oldc ->
          let newc = oldc + 1 in
          Ocsipersist.set c newc >>=
          (fun () ->
            Lwt_mutex.unlock mutex;
            return newc))))
  in
  register_new_service
    ~path:["count2"]
    ~get_params:unit
    (fun _ () () ->
      next () >>=
      (fun n ->
        return
         (html
          (head (title (pcdata "counter")) [])
          (body [p [pcdata (string_of_int n)]]))))

See this example here.

Persistent tables

Ocsipersist also allows to create very basic persistent tables. Use them if you don't need complex requests on your tables. Otherwise use a database such as PostgreSQL or MySQL. Here are the interface you can use:


type 'value table

val open_table : string -> 'value table

val find : 'value table -> string -> 'value Lwt.t

val add : 'value table -> string -> 'value -> unit Lwt.t

val remove : 'value table -> string -> unit Lwt.t

As you can see, all these function are cooperative.

Persistent session data

Eliom also implements persistent session tables. You can use them instead of memory tables if you don't need to register closures.

The following example is a new version of our site with users, with persistent connections. (login_box, disconnect_box and disconnect_action are the same as before).


(************************************************************)
(************ Connection of users, version 4 ****************)
(**************** (persistent sessions) *********************)
(************************************************************)


let my_persistent_table =
  create_persistent_table "eliom_example_table"

(* -------------------------------------------------------- *)
(* We create one main service and two (POST) actions        *)
(* (for connection and disconnection)                       *)

let persist_session_example =
  Eliom_services.new_service
    ~path:["persist"]
    ~get_params:unit
    ()

let persist_session_connect_action =
  Eliom_services.new_post_coservice'
    ~name:"connect4"
    ~post_params:(string "login")
    ()

(* disconnect_action, login_box and disconnect_box have been
   defined in the section about actions *)

(* ----------------------------------------------------------- *)
(* Handler for "persist_session_example" service (main page):  *)

let persist_session_example_handler sp () () =
  Eliom_sessions.get_persistent_session_data 
    ~table:my_persistent_table ~sp () >>= fun sessdat ->
  return
    (html
       (head (title (pcdata "")) [])
       (body
          (match sessdat with
          | Eliom_sessions.Data name ->
              [p [pcdata ("Hello "^name); br ()];
              disconnect_box sp "Close session"]
          | Eliom_sessions.Data_session_expired ->
              [login_box sp true persist_session_connect_action;
               p [em [pcdata "The only user is 'toto'."]]]
          | Eliom_sessions.No_data ->
              [login_box sp false persist_session_connect_action;
               p [em [pcdata "The only user is 'toto'."]]]
          )))


(* ----------------------------------------------------------- *)
(* Handler for persist_session_connect_action (user logs in):  *)

let persist_session_connect_action_handler sp () login =
  Eliom_sessions.close_session  ~sp () >>= fun () ->
  if login = "toto" (* Check user and password :-) *)
  then begin
    Eliom_sessions.set_persistent_session_data  ~table:my_persistent_table ~sp login >>= fun () ->
    return []
  end
  else return [Bad_user]


(* -------------------------------------------------------- *)
(* Registration of main services:                           *)

let () =
  Eliom_predefmod.Xhtml.register
    ~service:persist_session_example
    persist_session_example_handler;
  Eliom_predefmod.Actions.register
    ~service:persist_session_connect_action
    persist_session_connect_action_handler

See this example here.

As it is not possible to serialize closures, there is no persistent session service table. Be very carefull if you use both persistent session data tables and service session tables, as your session may become inconsistent (use the session service table only for volatile services, like coservices with timeouts).

[New in 0.99.5 - EXPERIMENTAL] Session groups

The idea is complementary to that of the "session name". While the optional session_name parameter allows for a single session to have multiple buckets of data associated with it, a session_group parameter (also optional) allow multiple sessions to be referenced together. For most uses, the session group is the user name. It allows to implement features like "close all sessions" for one user (even those opened on other browsers), or to limit the number of sessions one user may open at the same time.

Session groups have been suggested by Dario Teixeira and introduced in Eliom 0.99.5. Dario explains: Consider the following scenario: a user logs in from home using a "Remember me on this computer" feature, which sets a (almost) no-expiration cookie on his browser and session timeouts of infinity on the server. The user goes on vacation, and while logging from a cyber-café, she also sets the "Remember me" option. Back home she realises her mistake, and wishes to do a "global logout", ie, closing all existing sessions associated with her user name.


(************************************************************)
(************ Connection of users, version 5 ****************)
(************************************************************)


(* -------------------------------------------------------- *)
(* We create one main service and two (POST) actions        *)
(* (for connection and disconnection)                       *)

let connect_example5 =
  Eliom_services.new_service
    ~path:["groups"]
    ~get_params:Eliom_parameters.unit
    ()

let connect_action =
  Eliom_services.new_post_coservice'
    ~name:"connect5"
    ~post_params:(Eliom_parameters.string "login")
    ()

(* As the handler is very simple, we register it now: *)
let disconnect_action =
  Eliom_predefmod.Actions.register_new_post_coservice'
    ~name:"disconnect5"
    ~post_params:Eliom_parameters.unit
    (fun sp () () ->
      Eliom_sessions.close_session  ~sp () >>= fun () ->
      Lwt.return [])


(* -------------------------------------------------------- *)
(* login ang logout boxes:                                  *)

let disconnect_box sp s =
  Eliom_predefmod.Xhtml.post_form disconnect_action sp
    (fun _ -> [p [Eliom_predefmod.Xhtml.string_input
                    ~input_type:`Submit ~value:s ()]]) ()

let login_box sp =
  Eliom_predefmod.Xhtml.post_form connect_action sp
    (fun loginname ->
      [p
         (let l = [pcdata "login: ";
                   Eliom_predefmod.Xhtml.string_input
                     ~input_type:`Text ~name:loginname ()]
         in l)
     ])
    ()


(* -------------------------------------------------------- *)
(* Handler for the "connect_example5" service (main page):    *)

let connect_example5_handler sp () () =
  let sessdat = Eliom_sessions.get_volatile_data_session_group  ~sp () in
  return
    (html
       (head (title (pcdata "")) [])
       (body
          (match sessdat with
          | Eliom_sessions.Data name ->
              [p [pcdata ("Hello "^name); br ()];
              disconnect_box sp "Close session"]
          | Eliom_sessions.Data_session_expired
          | Eliom_sessions.No_data -> [login_box sp]
          )))


(* -------------------------------------------------------- *)
(* Handler for connect_action (user logs in):               *)

let connect_action_handler sp () login =
  Eliom_sessions.close_session  ~sp () >>= fun () ->
  Eliom_sessions.set_volatile_data_session_group ~set_max:(Some 10)  ~sp login;
  return []


(* -------------------------------------------------------- *)
(* Registration of main services:                           *)

let () =
  Eliom_predefmod.Xhtml.register ~service:connect_example5 connect_example5_handler;
  Eliom_predefmod.Actions.register ~service:connect_action connect_action_handler

As we will see later, there are three kinds of sessions (services, volatile data and persistent data). It is highly recommended to set a group for each of them!

Other concepts

Pre-applied services

Services or coservices with GET parameters can be preapplied to obtain a service without parameters. Example:


let preappl = Eliom_services.preapply coucou_params (3,(4,"cinq"))

It is not possible to register something on a preapplied service, but you can use them in links or as fallbacks for coservices.

Void action [New in 1.1.0]

Eliom_services.void_action: is a special non-attached action, with special behaviour: it has no parameter at all, even non-attached parameters. Use it if you want to make a link to the current page without non-attached parameters. It is almost equivalent to a POST non-attached coservice without POST parameters, on which you register an action that does nothing, but you can use it with <a> links, not only forms. Example:


Eliom_duce.Xhtml.a
  ~service:Eliom_services.void_action
  ~sp
  {{ "cancel" }}
  ()

Giving information to fallbacks

Fallbacks have access to some information about what succeeded before they were called. Get this information using Eliom_sessions.get_exn sp; That function returns a list of exceptions. That list contains Eliom_common.Eliom_Link_too_old if the coservice was not found, and Eliom_common.Eliom_Service_session_expired if the "service session" has expired.

It is also possible to tell actions to send information to the page generated after them. Just place exceptions in the list returned by the action. These exceptions will also be accessible with Eliom_sessions.get_exn. Here is the new version of the example of session with actions: by:


(************************************************************)
(************ Connection of users, version 6 ****************)
(************************************************************)

(* -------------------------------------------------------- *)
(* We create one main service and two (POST) actions        *)
(* (for connection and disconnection)                       *)

let connect_example6 =
  Eliom_services.new_service
    ~path:["action2"]
    ~get_params:unit
    ()

let connect_action =
  Eliom_services.new_post_coservice'
    ~name:"connect6"
    ~post_params:(string "login")
    ()

(* new disconnect action and box:                           *)

let disconnect_action =
  Eliom_predefmod.Actions.register_new_post_coservice'
    ~name:"disconnect6"
    ~post_params:Eliom_parameters.unit
    (fun sp () () ->
      Eliom_sessions.close_session  ~sp () >>= fun () ->
      return [])

let disconnect_box sp s =
  Eliom_predefmod.Xhtml.post_form disconnect_action sp
    (fun _ -> [p [Eliom_predefmod.Xhtml.string_input
                    ~input_type:`Submit ~value:s ()]]) ()


exception Bad_user

(* -------------------------------------------------------- *)
(* new login box:                                           *)

let login_box sp session_expired action =
  Eliom_predefmod.Xhtml.post_form action sp
    (fun loginname ->
      let l =
        [pcdata "login: ";
         string_input ~input_type:`Text ~name:loginname ()]
      in
      let exnlist = Eliom_sessions.get_exn sp in
      (* If exnlist is not empty, something went wrong
         during an action. We write an error message: *)
      [p (if List.mem Bad_user exnlist
      then (pcdata "Wrong user")::(br ())::l
      else
        if session_expired
        then (pcdata "Session expired")::(br ())::l
        else l)
     ])
    ()

(* -------------------------------------------------------- *)
(* Handler for the "connect_example6" service (main page):   *)

let connect_example6_handler sp () () =
  let group =
    Eliom_sessions.get_volatile_data_session_group  ~sp ()
  in
  return
    (html
       (head (title (pcdata "")) [])
       (body
          (match group with
          | Eliom_sessions.Data name ->
              [p [pcdata ("Hello "^name); br ()];
              disconnect_box sp "Close session"]
          | Eliom_sessions.Data_session_expired ->
              [login_box sp true connect_action;
               p [em [pcdata "The only user is 'toto'."]]]
          | Eliom_sessions.No_data ->
              [login_box sp false connect_action;
               p [em [pcdata "The only user is 'toto'."]]]
          )))

(* -------------------------------------------------------- *)
(* New handler for connect_action (user logs in):           *)

let connect_action_handler sp () login =
  Eliom_sessions.close_session  ~sp () >>= fun () ->
  if login = "toto" (* Check user and password :-) *)
  then begin
    Eliom_sessions.set_volatile_data_session_group ~set_max:(Some 10)  ~sp login;
    return []
  end
  else return [Bad_user]

(* -------------------------------------------------------- *)
(* Registration of main services:                           *)

let () =
  Eliom_predefmod.Xhtml.register ~service:connect_example6 connect_example6_handler;
  Eliom_predefmod.Actions.register ~service:connect_action connect_action_handler

See this example here.

If the actions raises an exception (with Lwt.fail), the server will send an error 500 (like for any other service). Think about catching the exceptions and put them in the list if they correspond to usual cases you want to handle while generating the page after the action.

Disposable coservices

It is possible to set a limit to the number of uses of (attached or non-attached) coservices. Just give the maximum number of uses with the optional ?max_use parameter while creating your coservices. Example


let disposable = new_service ["disposable"] unit ()

let _ = register disposable
    (fun sp () () ->
      let disp_coservice =
        new_coservice ~max_use:2 ~fallback:disposable ~get_params:unit ()
      in
      register_for_session sp disp_coservice
        (fun sp () () ->
          return
            (html
              (head (title (pcdata "")) [])
              (body [p [pcdata "I am a disposable coservice";
                        br ();
                        a disp_coservice sp [pcdata "Try me once again"] ()]]))
        );
      return
        (html
          (head (title (pcdata "")) [])
          (body [p [(if List.mem
                          Eliom_common.Eliom_Link_too_old
                          (Eliom_sessions.get_exn sp)
                    then pcdata "Your link was outdated. I am the fallback. I just created a new disposable coservice. You can use it only twice."
                    else
                    pcdata "I just created a disposable coservice. You can use it only twice.");
                    br ();
                    a disp_coservice sp [pcdata "Try it!"] ()]])))

Try it.

Timeout for sessions

The default timeout for sessions in one hour. Sessions will be automatically closed after that amount of time of inactivity from the user. You can change that value for your whole site during initialisation using:


Eliom_sessions.set_global_volatile_timeout (Some 7200.)

Here 7200 seconds. None means no timeout.

You can change that value for your whole site after initialisation using:


Eliom_sessions.set_global_volatile_timeout ~sp (Some 7200.)

You can change that value for one user only using:


Eliom_sessions.set_volatile_session_timeout ~sp (Some 7200.)

Note that there is also a possibility to change the default value for Eliom in the configuration file like this:


    <extension module="//path_to///eliom.cma">
      <timeout value="7200"/>
    </extension>

means no timeout.

Warning: that default may be overriden by each site using Eliom_sessions.set_global_volatile_timeout or Eliom_sessions.set_default_volatile_timeout. If you want your user to be able to set the default in the configuration file for your site (between <site> and </site>), you must parse the configuration (Eliom_sessions.get_config () function, see below).

Timeout for coservices

It is also possible to put timeouts on coservices using the optional parameter ?timeout of functions new_coservice, new_coservice', etc. Note that session coservices cannot survive after the end of the session. Use this if you don't want your coservice to be available during all the session duration. For example if your coservice is here to show the results of a search, you probably want it to be available only for a short time. The following example shows a coservice with timeout registered in the session table.


let timeout = new_service ["timeout"] unit ()

let _ =
  let page sp () () =
    let timeoutcoserv =
      register_new_coservice_for_session
        ~sp ~fallback:timeout ~get_params:unit ~timeout:5.
        (fun _ _ _ ->
           return
             (html
               (head (title (pcdata "Coservices with timeouts")) [])
               (body [p
                 [pcdata "I am a coservice with timeout."; br ();
                  pcdata "Try to reload the page!"; br ();
                  pcdata "I will disappear after 5 seconds of inactivity." ];
                 ])))
    in
    return
      (html
        (head (title (pcdata "Coservices with timeouts")) [])
        (body [p
          [pcdata "I just created a coservice with 5 seconds timeout."; br ();
           a timeoutcoserv sp [pcdata "Try it"] (); ];
          ]))
  in
  register timeout page

See this example here.

Registering coservices in public table during session

If you want to register coservices in the public table during a session, (that is, after the initialisation phase of your module), you must add the optional sp parameter to the register function. Remember that using register without sp is possible only during initialisation!

We recommend to put a timeout on such coservices, otherwise, they will be available until the end of the server process, and it will not be possible to re-create them when the server is relaunched.

The following example is a translation of the previous one using the public table:


let publiccoduringsess = new_service ["publiccoduringsess"] unit ()

let _ =
  let page sp () () =
    let timeoutcoserv =
      register_new_coservice
        ~sp ~fallback:publiccoduringsess ~get_params:unit ~timeout:5.
        (fun _ _ _ ->
           return
             (html
               (head (title (pcdata "Coservices with timeouts")) [])
               (body [p
                 [pcdata "I am a public coservice with timeout."; br ();
                  pcdata "I will disappear after 5 seconds of inactivity." ];
                 ])))
    in
    return
      (html
        (head (title (pcdata "Public coservices with timeouts")) [])
        (body [p
          [pcdata "I just created a public coservice with 5 seconds timeout."; br ();
           a timeoutcoserv sp [pcdata "Try it"] (); ];
          ]))
  in
  register publiccoduringsess page

See this example here.

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_services.set_exn_handler. Here is the handler used by this tutorial:


let _ = Eliom_services.set_exn_handler
   (fun sp e -> match e with
    | Eliom_common.Eliom_404 ->
        Eliom_predefmod.Xhtml.send ~code:404 ~sp
          (html
             (head (title (pcdata "")) [])
             (body [h1 [pcdata "Eliom tutorial"];
                    p [pcdata "Page not found"]]))
    | Eliom_common.Eliom_Wrong_parameter ->
        Eliom_predefmod.Xhtml.send ~sp
          (html
             (head (title (pcdata "")) [])
             (body [h1 [pcdata "Eliom tutorial"];
                    p [pcdata "Wrong parameters"]]))
    | e -> fail e)

Giving configuration options to your sites

You can add your own options in the configuration file for your Web site. For example:


    <eliom module="//path_to///yourmodule.cmo">
      <youroptions> ...
    </eliom>

Use Eliom_sessions.get_config () during the initialization of your module to get the data between <eliom> and </eliom>. Warning: parsing these data is very basic for now. That feature will be improved in the future.

More about sessions

By default, Eliom is using three cookies :

One for session services,
one for volatile session data,
one for persistent session data.

They correspond to three different sessions (opened only if needed). Eliom_sessions.close_session closes all three sessions, but you may want to desynchronize the three sessions by using Eliom_sessions.close_persistent_session (persistent session), Eliom_sessions.close_service_session (session services), or Eliom_sessions.close_data_session (volatile data session). There is also Eliom_sessions.close_volatile_session for both volatile data session and session services. The module Eliom_sessions also contains functions for setting timeouts or expiration dates for cookies for each kind of session.

If you need more sessions (for example several different data sessions) for the same site, you can give a name to your sessions by giving the optional parameter ?session_name to functions like Eliom_sessions.close_data_session, register_for_session, or Eliom_sessions.get_volatile_session_data. Note that this tutorial has been implemented using this feature, even if it has been hidden for the sake of simplicity. That's how the different examples of sessions in this tutorial are independant.

Secure services [New in 1.1.0]

You may want to impose HTTPS for some of your services. To do that, use the optional parameter https:true while creating your service.

It is also possible to require http or https while creating a link or a form (using the optional parameter https:true). But it is never possible to make an http link towards an https service, even if you request it.

Warning: if the protocol needs to be changed (from http to https or vice versa), Eliom will generate absolute URLs. The host name and port numbers are guessed from the IP and the configuration by default, but it is recommended to specify them in the configuration file. For example:

Secure sessions [New in 1.1.0]

For security reasons, Eliom does not use the same cookies in https and http. Secure sessions are using secure cookies (i.e. Ocsigen will ask the browsers to send the cookie only if the protocol is secure). Thus it is not possible to access secure session if the user is using http. If the user is using https, Eliom will save data and services in secure session. But it is possible to access unsecure session data and to register unsecure session services using the optional parameter secure:false when calling functions like Eliom_sessions.set_volatile_session_data, Eliom_sessions.get_persistent_session_data, Eliom_predefmod.Xhtml.register_for_session, etc.

Advanced forms and parameters

This section shows more advanced use of page parameters and corresponding forms.

Parsing parameters using regular expressions

Eliom_parameters.regexp allows to parse page parameters using (Perl-compatible) regular expressions. We use the module Netstring_pcre, from OCamlnet. See the documentation about OCamlnet for more information. The following example shows a service that accepts only parameters values enclosed between [ and ]:


let r = Netstring_pcre.regexp "\\\\[(.*)\\\\]"

let regexp =
  Eliom_predefmod.Xhtml.register_new_service
    ~path:["regexp"]
    ~get_params:(regexp r "$1" "myparam")
    (fun _ g () ->
      return
        (html
           (head (title (pcdata "")) [])
           (body [p [pcdata g]])))

Try it.

Boolean checkboxes

Page may take parameter of type bool. A possible use of this type is in a form with boolean checkboxes, as in the example below:


(* Form with bool checkbox: *)
let bool_params = register_new_service
    ~path:["bool"]
    ~get_params:(bool "case")
  (fun _ case () ->
    return
    << <html>
         <head><title></title></head>
         <body>
         <p>
           $pcdata (if case then "checked" else "not checked")$
         </p>
         </body>
       </html> >>)

let create_form_bool casename =
    <:xmllist< <p>check? $bool_checkbox ~name:casename ()$ <br/>
      $string_input ~input_type:`Submit ~value:"Click" ()$</p> >>

let form_bool = register_new_service ["formbool"] unit
  (fun sp () () ->
     let f = get_form bool_params sp create_form_bool in
     return
     << <html>
          <head><title></title></head>
          <body> $f$ </body>
        </html> >>)

Try it.

Important warning: As you can see, browsers do not send any value for unchecked boxes! An unchecked box is equivalent to no parameter at all! Thus it is not possible to distinguish between a service taking a boolean and a service taking no parameter at all (if they share the same URL). In Eliom services are tried in order of registration! The first matching service will answer.

Other types similar to bool:

Eliom_parameters.opt (page taking an optional parameter),
Eliom_parameters.sum (either a parameter or another).

See the interface here.

Type set

Page may take several parameters of the same name. It is useful when you want to create a form with a variable number of fields. To do that with Eliom, use the type Eliom_parameters.set. For example set int "val" means that the page will take zero, one or several parameters of name "val", all of type int. The function you register will receive the parameters in a list. Example:



let set = register_new_service
    ~path:["set"]
    ~get_params:(set string "s")
  (fun _ l () ->
    let ll =
      List.map
        (fun s -> << <strong>$str:s$ </strong> >>) l
    in
    return
    << <html>
         <head><title></title></head>
         <body>
         <p>
           You sent:
           $list:ll$
         </p>
         </body>
       </html> >>)

These parameters may come from several kinds of widgets in forms. Here is an example of a form with several checkboxes, all sharing the same name, but with different values:



(* form to set *)
let setform = register_new_service
    ~path:["setform"]
    ~get_params:unit
    (fun sp () () ->
      return
        (html
           (head (title (pcdata "")) [])
           (body [h1 [pcdata "Set Form"];
                  get_form set sp
                    (fun n ->
                      [p [pcdata "Form to set: ";
                          string_checkbox ~name:n ~value:"box1" ();
                          string_checkbox
                            ~name:n ~value:"box2" ~checked:true ();
                          string_checkbox ~name:n ~value:"box3" ();
                          string_checkbox ~name:n ~value:"box4" ();
                          string_input ~input_type:`Submit ~value:"Click" ()]])
                ])))

Try it.

Once again, note that there is no difference between an empty set or no parameter at all. If you register a service without parameters and a service with a set of parameters on the same URL, the firstly registered service that matches will answer.

Select

Here is an example of a select box.


let select_example_result = register_new_service
    ~path:["select"]
    ~get_params:(string "s")
    (fun sp g () ->
      return
        (html
           (head (title (pcdata "")) [])
           (body [p [pcdata "You selected: ";
                     strong [pcdata g]]])))

let create_select_form =
  (fun select_name ->
    [p [pcdata "Select something: ";
        Eliom_predefmod.Xhtml.string_select ~name:select_name
          (Eliom_predefmod.Xhtml.Option ([] (* attributes *),
                                        "Bob" (* value *),
                                        None (* Content, if different from value *),
                                        false (* not selected *))) (* first line *)
          [Eliom_predefmod.Xhtml.Option ([], "Marc", None, false);
          (Eliom_predefmod.Xhtml.Optgroup
          ([],
           "Girls",
           ([], "Karin", None, false),
           [([a_disabled `Disabled], "Juliette", None, false);
            ([], "Alice", None, true);
            ([], "Germaine", Some (pcdata "Bob's mother"), false)]))]
          ;
        Eliom_predefmod.Xhtml.string_input ~input_type:`Submit ~value:"Send" ()]])

let select_example = register_new_service ["select"] unit
  (fun sp () () ->
     let f =
       Eliom_predefmod.Xhtml.get_form
         select_example_result sp create_select_form
     in
     return
       (html
         (head (title (pcdata "")) [])
         (body [f])))

Try it.

To do "multiple" select boxes, use functions like Eliom_predefmod.Xhtml.string_multiple_select. As you can see in the type, the service must be declared with parameters of type set.

Clickable images

Here is an example of clickable image. You receive the coordinates the user clicked on.


let coord = register_new_service
    ~path:["coord"]
    ~get_params:(coordinates "coord")
  (fun _ c () ->
    return
  << <html>
       <head><title></title></head>
       <body>
       <p>
         You clicked on coordinates:
         ($str:(string_of_int c.abscissa)$, $str:(string_of_int c.ordinate)$)
       </p>
       </body>
     </html> >>)

(* form to image *)
let imageform = register_new_service
    ~path:["imageform"]
    ~get_params:unit
    (fun sp () () ->
      return
        (html
           (head (title (pcdata "")) [])
           (body [h1 [pcdata "Image Form"];
                  get_form coord sp
                    (fun n ->
                      [p [image_input
                            ~src:(make_uri ~service:(static_dir sp) ~sp ["ocsigen5.png"])
                            ~name:n
                            ()]])
                ])))

Try it.

You may also send a value with the coordinates:


let coord2 = register_new_service
    ~path:["coord2"]
    ~get_params:(int_coordinates "coord")
  (fun _ (i, c) () ->
    return
  << <html>
       <head><title></title></head>
       <body>
       <p>
         You clicked on coordinates:
         ($str:(string_of_int c.abscissa)$, $str:(string_of_int c.ordinate)$)
       </p>
       </body>
     </html> >>)

(* form to image *)
let imageform2 = register_new_service
    ~path:["imageform2"]
    ~get_params:unit
    (fun sp () () ->
      return
        (html
           (head (title (pcdata "")) [])
           (body [h1 [pcdata "Image Form"];
                  get_form coord2 sp
                    (fun n ->
                      [p [int_image_input
                            ~src:(make_uri ~service:(static_dir sp) ~sp ["ocsigen5.png"])
                            ~name:n
                            ~value:3
                            ()]])
                ])))

Try it.

Type list

Another way (than Eliom_parameters.set) to do variable length forms is to use indexed lists (using Eliom_parameters.list). The use of that feature is a bit more complex than set and still experimental. Here is an example of service taking an indexed list as parameter:



(* lists *)
let coucou_list = register_new_service
    ~path:["coucou"]
    ~get_params:(list "a" (string "str"))
  (fun _ l () ->
    let ll =
      List.map (fun s -> << <strong>$str:s$</strong> >>) l in
    return
      << <html>
           <head><title></title></head>
           <body>
           <p>
             You sent:
             $list:ll$
           </p>
           </body>
         </html> >>)

Here is an example of link towards this service: coucou?a.str[0]=toto&a.str[1]=titi.

Warning: As for sets or bools, if a request has no parameter, it will be considered as the empty list. Services are tried in order of registration.

As you see, the names of each list element is built from the name of the list, the name of the list element, and an index. To spare you creating yourself these names, Eliom provides you an iterator to create them.




(* Form with list: *)
let create_listform f =
  (* Here, f.it is an iterator like List.map,
     but it must be applied to a function taking 2 arguments
     (unlike 1 in map), the first one being the name of the parameter,
     and the second one the element of list.
     The last parameter of f.it is the code that must be appended at the
     end of the list created
   *)
  f.it (fun stringname v ->
    <:xmllist< <p>Write the value for $str:v$:
      $string_input ~input_type:`Text ~name:stringname ()$ </p> >>)
    ["one";"two";"three";"four"]
    <:xmllist< <p>$string_input ~input_type:`Submit ~value:"Click" ()$</p> >>

let listform = register_new_service ["listform"] unit
  (fun sp () () ->
     let f = get_form coucou_list sp create_listform in
     return
      << <html>
           <head><title></title></head>
           <body> $f$ </body>
         </html> >>)

Try it.

Important warning: As we have seen in the section about boolean (or optional) parameters, it is not possible to distinguish between a boolean with value "false", and no parameter at all. This causes problems if you create a list of boolean or optional values, as it is not possible to know the length of the list. In that case, Eliom always takes the shortest possible list.

Forms and suffixes

Service with "suffix" URLs have an equivalent version with usual parameters, allowing to create forms towards such services. Example:


(* Form for service with suffix: *)
let create_suffixform ((suff, endsuff),i) =
    <:xmllist< <p>Write the suffix:
      $int_input ~input_type:`Text ~name:suff ()$ <br/>
      Write a string: $user_type_input
         ~input_type:`Text ~name:endsuff 
         (Ocsigen_extensions.string_of_url_path ~encode:false)$ <br/>
      Write an int: $int_input ~input_type:`Text ~name:i ()$ <br/>
      $string_input ~input_type:`Submit ~value:"Click" ()$</p> >>

let suffixform = register_new_service ["suffixform"] unit
  (fun sp () () ->
     let f = get_form isuffix sp create_suffixform in
     return
      << <html>
           <head><title></title></head>
           <body> $f$ </body>
         </html> >>)

Try it.

Uploading files

The Eliom_parameters.file parameter type allows to send files in your request. The service gets something of type Ocsigen_extensions.file_info. You can extract information using this using these functions (from Eliom_sessions):


val get_tmp_filename : Ocsigen_extensions.file_info -> string
val get_filesize : Ocsigen_extensions.file_info -> int64
val get_original_filename : Ocsigen_extensions.file_info -> string

Eliom_sessions.get_tmp_filename allows to know the actual name of the uploaded file on the hard disk. Eliom_sessions.get_original_filename gives the original filename.

To make possible the upload of files, you must configure a directory for uploaded files in Ocsigen's configuration file. For example:


  <uploaddir>/tmp</uploaddir>

Files are kept in this directory only during the request. Then they are automatically cancelled. Thus your services must copy them somewhere else themselves if they want to keep them. In the following example, we create a new hard link to the file to keep it (the destination must be on the same partition of the disk).


let upload = new_service
    ~path:["upload"]
    ~get_params:unit
    ()

let upload2 = register_new_post_service
   ~fallback:upload
   ~post_params:(file "file")
    (fun _ () file ->
      let to_display =
        let newname = "/tmp/thefile" in
        (try
          Unix.unlink newname;
        with _ -> ());
        Unix.link (Eliom_sessions.get_tmp_filename file) newname;
        let fd_in = open_in newname in
        try
          let line = input_line fd_in in close_in fd_in; line (*end*)
        with End_of_file -> close_in fd_in; "vide"
      in
      return
        (html
           (head (title (pcdata "Upload")) [])
           (body [h1 [pcdata to_display]])))


let uploadform = register upload
    (fun sp () () ->
      let f =
        (post_form upload2 sp
           (fun file ->
             [p [file_input ~name:file ();
                 br ();
                 string_input ~input_type:`Submit ~value:"Send" ()
               ]]) ()) in
      return
        (html
           (head (title (pcdata "form")) [])
           (body [f])))

Try it (warning: uploading on ocsigen.org is forbidden).

Predefined constructs

Images, CSS, Javascript

To include an image, simply use the function XHTML.M.img:

img ~alt:"Ocsigen"
    ~src:(Eliom_predefmod.Xhtml.make_uri ~service:senddoc ~sp ["ocsigen1024.jpg"])
    ()

The function Eliom_predefmod.Xhtml.make_uri creates the relative URL string from current URL (in sp) (see above) to the URL of the image in the static directory configured in the configuration file.

To simplify the creation of <link> tags for CSS or <script> tags for Javascript, use the following functions:

css_link ~uri:(make_uri ~service:(static_dir sp) ~sp ["style.css"]) ()

js_script ~uri:(make_uri ~service:(static_dir sp) ~sp ["funs.js"]) ()

Basic menus

To make a menu on your web page, you can use the function Eliom_tools.menu. First, define your menu like this:

let mymenu current sp =
  Eliom_tools.menu ~classe:["menuprincipal"]
    (home, <:xmllist< Home >>)
    [
     (infos, <:xmllist< More info >>);
     (tutorial, <:xmllist< Documentation >>)
   ] current sp

Here, home, infos, and tutorial are your three pages (generated for example by Eliom_services.new_service).

Then mymenu service:home sp will generate the following code:

<ul class="menu menuprincipal"> <li class="current first">Home </li> <li><a href="infos">More info</a> </li> <li class="last"><a href="tutorial">Documentation</a> </li> </ul>

Personalise it in your CSS style-sheet.

Eliom_tools.menu takes a list of services without GET parameters. If you want one of the link to contains GET parameters, pre-apply the service.

How to make a menu entry with GET parameters?

Preapply your service.

Hierarchical menus


(* Hierarchical menu *)
open Eliom_tools_common
open Eliom_tools

let hier1 = new_service ~path:["hier1"] ~get_params:unit ()
let hier2 = new_service ~path:["hier2"] ~get_params:unit ()
let hier3 = new_service ~path:["hier3"] ~get_params:unit ()
let hier4 = new_service ~path:["hier4"] ~get_params:unit ()
let hier5 = new_service ~path:["hier5"] ~get_params:unit ()
let hier6 = new_service ~path:["hier6"] ~get_params:unit ()
let hier7 = new_service ~path:["hier7"] ~get_params:unit ()
let hier8 = new_service ~path:["hier8"] ~get_params:unit ()
let hier9 = new_service ~path:["hier9"] ~get_params:unit ()
let hier10 = new_service ~path:["hier10"] ~get_params:unit ()

let mymenu =
  (
   (Main_page hier1),

   [([pcdata "page 1"], Site_tree (Main_page hier1, []));

    ([pcdata "page 2"], Site_tree (Main_page hier2, []));

    ([pcdata "submenu 4"],
     Site_tree
       (Default_page hier4,
         [([pcdata "submenu 3"],
          Site_tree
             (Not_clickable,
              [([pcdata "page 3"], Site_tree (Main_page hier3, []));
               ([pcdata "page 4"], Site_tree (Main_page hier4, []));
               ([pcdata "page 5"], Site_tree (Main_page hier5, []))]
             )
          );

          ([pcdata "page 6"], Site_tree (Main_page hier6, []))]
       )
    );

    ([pcdata "page 7"],
     Site_tree (Main_page hier7, []));

    ([pcdata "disabled"], Disabled);

    ([pcdata "submenu 8"],
     Site_tree
       (Main_page hier8,
        [([pcdata "page 9"], Site_tree (Main_page hier9, []));
         ([pcdata "page 10"], Site_tree (Main_page hier10, []))]
       )
    )
  ]
  )

let f i s sp () () =
  return
    (html
       (head (title (pcdata ""))
          ((style ~contenttype:"text/css"
             [cdata_style
 "a {color: red;}\n
  li.eliomtools_current > a {color: blue;}\n
  .breadthmenu li {\n
    display: inline;\n
    padding: 0px 1em;\n
    margin: 0px;\n
    border-right: solid 1px black;}\n
  .breadthmenu li.eliomtools_last {border: none;}\n
                "])::
                structure_links mymenu ~service:s ~sp)
             )
       (body [h1 [pcdata ("Page "^string_of_int i)];
              h2 [pcdata "Depth first, whole tree:"];
              div
                (hierarchical_menu_depth_first
                   ~whole_tree:true mymenu ~service:s ~sp);
              h2 [pcdata "Depth first, only current submenu:"];
              div (hierarchical_menu_depth_first mymenu ~service:s ~sp);
              h2 [pcdata "Breadth first:"];
              div
                (hierarchical_menu_breadth_first
                   ~classe:["breadthmenu"] mymenu ~service:s ~sp )]))


let _ =
  register hier1 (f 1 hier1);
  register hier2 (f 2 hier2);
  register hier3 (f 3 hier3);
  register hier4 (f 4 hier4);
  register hier5 (f 5 hier5);
  register hier6 (f 6 hier6);
  register hier7 (f 7 hier7);
  register hier8 (f 8 hier8);
  register hier9 (f 9 hier9);
  register hier10 (f 10 hier10)

Miscellaneous

Several Ocaml modules for one site

If your site consists of several modules, you can load them consecutively from the configuration file using <eliommodule> (same syntax as <eliom>, the difference being that <eliommodule> does not generate any page). In that case, only the position of the <eliom> tag will be taken into account for generating the page using Eliom. Note that there can be only one <eliom> tag for each <site> (or <host>).

Advanced use: create an extension for the server that access Eliom's data

If you want an Ocsigen extension with access to Eliom's data (for example if you want an extension that will register some services), you can use the function Eliom_extensions.register_eliom_extension to register the function that will generate the Ocsigen_extensions.answer from sp.

Static linking of Eliom modules

From version 1.2, it is possible to link extensions and Eliom modules statically (See here). Obviously, for Eliom modules, configuration retrieval, but also service creation and registration, must be delayed until the configuration file is read. To create a statically linkable Eliom module, use the function Eliom_services.register_eliom_module. It takes as parameters the name of the module and the initialization function, that will be called when the module is initialized in the configuration file. That function will register services (and possibly call Eliom_sessions.get_config if the module has configuration options).

To initialize the module from the configuration file, use the syntax:

which is equivalent to:

with the exception that it does not load the module using Dynlink, but calls the initialization function. (Also works with <eliom> tag).

Examples

Writing a forum

As an example, we will now write a small forum. Our forum has a main page, summarising all the messages and a page for each message. All the functions to access the database and print the result are left to the reader. We only want to show the structure of the site. Suppose you have written a function news_headers_list_box that writes the beginning of messages, and message_box that write a full message.


(* All the services: *)

let main_page = new_service ~path:[""]
    ~get_params:unit ()

let news_page = new_service ["msg"] (int "num") ()

(* Construction of pages *)

let home sp () () =
  page sp
    [h1 [pcdata "Mon site"];
     news_headers_list_box
       sp anonymoususer news_page]

let print_news_page sp i () =
  page sp
    [h1 [pcdata "Info"];
     message_box i anonymoususer]

(* Services registration *)

let _ = register
  ~service:main_page
  home

let _ = register
  ~service:news_page
  print_news_page

Now the same example with a login box on each page. We now have two versions of each page: connected and not connected. We need two actions (for connection and disconnection). Suppose we have the functions login_box, connected_box, and connect.

(* All the services: *)

let main_page = new_service ~path:[""] ~get_params:unit ()

let news_page = new_service ["msg"] (int "num") ()

let connect_action =
  new_post_coservice'
    ~post_params:(string "login" ** string "password")

(* Construction of pages *)

let home sp () () =
   match get_volatile_session_data ~table:my_table ~sp () with
   | Eliom_sessions.Data_session_expired
   | Eliom_sessions.No_data ->
     page sp
       [h1 [pcdata "My site"];
        login_box sp connect_action;
        news_headers_list_box sp anonymoususer news_page]
   | Eliom_sessions.Data user ->
      page sp
        [h1 [pcdata "Mon site"];
         text_box "Bonjour !";
         connected_box sp user disconnect_action;
         news_headers_list_box sp user news_page]

let print_news_page sp i () =
   match get_volatile_session_data ~table:my_table ~sp () with
   | Eliom_sessions.Data_session_expired
   | Eliom_sessions.No_data ->
      page sp
        [h1 [pcdata "Info"];
         login_box sp connect_action;
         message_box i anonymoususer]
   | Eliom_sessions.Data user ->
      page sp
        [h1 [pcdata "Info"];
         connected_box sp user disconnect_action;
         message_box i user]

(* Services registration *)

let _ = register
  ~service:main_page
  home

let _ = register
  ~service:news_page
  print_news_page

let launch_session sp user =
  set_volatile_session_data my_table sp user

let _ = Eliom_predefmod.Actions.register
  ~action:connect_action
    (fun h (login, password) ->
      launch_session sp (connect login password); return [])

Miniwiki

Ocsigen's source code contains an example of Wiki written with Eliom by Janne Hellsten. It is called Miniwiki.

Ocsigen

This page has been generated by Ocsimore. If you are a member of the Ocsigen team, you can log in to modify the pages.