Services registered with register_new_service are available for all users. We call them public services.

Page generation may have side-effects:

let count = 
  let next =
    let c = ref 0 in
      (fun () -> c := !c + 1; !c)
  in
  register_new_service 
    ~url:["count"]
    ~get_params:unit
    (fun _ () () -> 
      return
        (html
         (head (title (pcdata "counter")) [])
         (body [p [pcdata (string_of_int (next ()))]])))

See this example here.

As usual in OCaml, you can forget labels when the application is total:

let hello = 
  register_new_service 
    ["dir";"hello"]  (* the url dir/hello *)
    unit
    (fun _ () () ->
      return
        (html
         (head (title (pcdata "Hello")) [])
         (body [h1 [pcdata "Hello"]])))

See this example here.

The last example shows how to define the default page for a directory. (Note that ["rep";""] is equivalent to ["rep";"index"], because some browsers do not behave well with empty links.)

let default = register_new_service ["rep";""] unit
  (fun _ () () -> 
    return
     (html
      (head (title (pcdata "")) [])
      (body [p [pcdata "default page. rep is redirected to rep/"]])))

See default.

Typed parameters

The parameter labelled get_params indicates the type of GET parameters for the page (that is, parameters present in the URL). unit means that the page does not take any GET parameter.

Functions implementing services take three parameters. The first one has type Eliom.server_params and corresponds to server informations (user-agent, ip, current-url, etc. - see later in that section for examples of use), the second one is for GET parameters (that is, parameters in the URL) and the third one for POST parameters (parameters in the body of the HTTP request).

Here is an example of a service with GET parameters:

let writeparams _ (i1, (i2, s1)) () =  
  return
   (html
    (head (title (pcdata "")) [])
    (body [p [pcdata "You sent: ";
              strong [pcdata (string_of_int i1)];
              pcdata ", ";
              strong [pcdata (string_of_int i2)];
              pcdata " and ";
              strong [pcdata s1]]]))

let coucou_params = register_new_service 
    ~url:["coucou"]
    ~get_params:(Eliom.int "i" ** (int "ii" ** string "s"))
    writeparams

Note that the URLs of coucou and coucou_params differ only by parameters. Url http://your_server/examples/coucou will run the first one,
http://your_server/examples/coucou?i=42&ii=17&s=krokodile will run the second one.
If i is not an integer, the server displays an error-message (try to change the value in the URL).
Here, int, string and are functions defined in the Eliom module.
Warning: The infix function ( ) is to be used to construct pairs (not tuples).

The following examples shows how to create a service with "suffix" service (taking the end of the URL as a parameter, as wikis do very often) and how to get server information:

let uasuffix = 
  register_new_service 
    ~url:["uasuffix"]
    ~get_params:(suffix (int "year" ** int "month"))
    (fun sp (year, month) () -> 
      return
       (html
        (head (title (pcdata "")) [])
        (body
           [p [pcdata "The suffix of the url is ";
               strong [pcdata ((string_of_int year)^"/"
                               ^(string_of_int month))];
               pcdata ", your user-agent is ";
               strong [pcdata (Eliom.get_user_agent sp)];
               pcdata ", your IP is ";
               strong [pcdata (Eliom.get_ip sp)]]])))

This service will answer to URLs like http://.../uasuffix/2000/11.

See uasuffix

Suffix parameters have names, because we can create forms towards these services. uasuffix/2000/11 is equivalent to uasuffix/?year=2000&month=11.

suffix_prod allows to take both a suffix and other parameters.
all_suffix allows to take the end of the suffix as string list.

let isuffix = 
  register_new_service 
    ~url:["isuffix"] 
    ~get_params:(suffix_prod (int "suff" ** all_suffix "endsuff") (int "i"))
    (fun sp ((suff, endsuff), i) () -> 
      return
       (html
        (head (title (pcdata "")) [])
        (body
           [p [pcdata "The suffix of the url is ";
               strong [pcdata (string_of_int suff)];
               pcdata " followed by ";
               strong [pcdata (string_of_url_path endsuff)];
               pcdata " and i is equal to ";
               strong [pcdata (string_of_int i)]]])))

See isuffix.

The following example shows how to use your own types:

type mysum = A | B
let mysum_of_string = function
  | "A" -> A
  | "B" -> B
  | _ -> raise (Failure "mysum_of_string")
let string_of_mysum = function
  | A -> "A"
  | B -> "B"

let mytype = 
  Eliom.Xhtml.register_new_service 
    ~url:["mytype"]
    ~get_params:
      (Eliom.user_type mysum_of_string string_of_mysum "valeur")
    (fun _ x () -> 
      let v = string_of_mysum x in 
      return
        (html
         (head (title (pcdata "")) [])
         (body [p [pcdata (v^" is valid. Now try with another value.")]])))

See mytype.

Untyped parameters

If you want a service that answers to request with any parameters, use the Eliom.any value. The service will get an association list of strings. Example:

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

Try any_serv.

let catch = register_new_service
    ~url:["catch"]
    ~get_params:(int "i")
    ~error_handler:(fun sp l -> 
      return
        (html
         (head (title (pcdata "")) [])
         (body [p [pcdata ("i is not an integer.")]])))
    (fun _ i () -> 
      let v = string_of_int i in 
      return
        (html
           (head (title (pcdata "")) [])
           (body [p [pcdata ("i is an integer: "^v)]])))

To create a link (<a>), use the function Eliom.Xhtml.a (or Eliomduce.Xhtml.a, etc), as in these examples:

let links = register_new_service ["rep";"links"] unit
 (fun sp () () -> 
   return
    (html
     (head (title (pcdata "Links")) [])
     (body 
       [p
        [Eliom.Xhtml.a coucou sp [pcdata "coucou"] (); br ();
         Eliom.Xhtml.a hello sp [pcdata "hello"] (); br ();
         Eliom.Xhtml.a default sp 
           [pcdata "default page of the dir"] (); br ();
         Eliom.Xhtml.a uasuffix sp 
           [pcdata "uasuffix"] (2007,06); br ();
         Eliom.Xhtml.a coucou_params sp 
           [pcdata "coucou_params"] (42,(22,"ciao")); br ();
         Eliom.Xhtml.a any_serv sp 
           [pcdata "any_serv"] [("sun","yellow");("sea","blue")]; br ();
         Eliom.Xhtml.a
           (new_external_service
              ~url:["http://fr.wikipedia.org";"wiki";""]
              ~get_params:(suffix (all_suffix "suff"))
              ~post_params:unit ()) 
           sp
           [pcdata "OCaml on wikipedia"]
           ["OCaml"]; br ();
         XHTML.M.a
           ~a:[a_href (uri_of_string "http://en.wikipedia.org/wiki/OCaml")]
           [pcdata "OCaml on wikipedia"]
       ]])))

See links.

If you open Eliom.Xhtml after XHTML.M, Eliom.Xhtml.a will mask XHTML.M.a. Thus you can avoid to write fully qualified values most of the time.

Eliom.Xhtml.a takes as first parameter the service you want to link to. Note that to create a (relative) link we need to know the current URL. That's why the function a takes sp as second parameter.

The third parameter is the text of the link. The last parameter is for GET parameters you want to put in the link. The type of this parameter and the name of GET parameters depend on the service you link to.

The link to Wikipedia shows how to define an external service (here it uses a suffix URL). For an external service without parameters, you can use the low level function XHTML.M.a, if you don't want to create an external service explicitely.

If you want to create (mutually or not) recursive pages, first create the service using Eliom.new_service, then register it in the table using (for example) Eliom.Xhtml.register:

let linkrec = Eliom.new_service ["linkrec"] unit ()

let _ = Eliom.Xhtml.register linkrec 
    (fun sp () () -> 
      return
       (html
        (head (title (pcdata "")) [])
        (body [p [a linkrec sp [pcdata "click"] ()]])))

See linkrec.

The server won't accept to start if there are unregistered services.

Forms towards services

The function Eliom.Xhtml.get_form allows to create a form that uses the GET method (parameters in the URL). It works like Eliom.Xhtml.a but takes as parameter a function that creates the form from parameters names.

let create_form = 
  (fun (number_name, (number2_name, string_name)) ->
    [p [pcdata "Write an int: ";
        Eliom.Xhtml.int_input ~input_type:`Text ~name:number_name ();
        pcdata "Write another int: ";
        Eliom.Xhtml.int_input ~input_type:`Text ~name:number2_name ();
        pcdata "Write a string: ";
        Eliom.Xhtml.string_input ~input_type:`Text ~name:string_name ();
        Eliom.Xhtml.string_input ~input_type:`Submit ~value:"Click" ()]])

let form = register_new_service ["form"] unit
  (fun sp () () -> 
     let f = Eliom.Xhtml.get_form coucou_params sp create_form in 
     return
       (html
         (head (title (pcdata "")) [])
         (body [f])))

See the function form in action.

Note that if you want to use typed parameters, you cannot use functions like XHTML.M.input to create your forms. Indeed, parameter names are typed to force them be used properly. In our example, number_name has type int param_name and must be used with int_input (or other widgets), whereas string_name has type string param_name and must be used with string_input (or other widgets). All functions for creating form widgets are detailed here.

For untyped forms, you may use functions from XHTML.M (or OCamlDuce's syntax, or whatever syntax you are using) or functions whose name is prefixed by "any_". Here is a form linking to our (untyped) service any_serv.

let any_form = register_new_service 
    ~url:["anyform"]
    ~get_params:unit
    (fun sp () () ->
      return
        (html
           (head (title (pcdata "")) [])
           (body 
              [h1 [pcdata "Any Form"];
               Eliom.Xhtml.get_form any_serv sp 
                 (fun () ->
                   [p [pcdata "Form to any_serv: ";
                       Eliom.Xhtml.any_input ~input_type:`Text ~name:"plop" ();
                       Eliom.Xhtml.any_input ~input_type:`Text ~name:"plip" ();
                       Eliom.Xhtml.any_input ~input_type:`Text ~name:"plap" ();
                       Eliom.Xhtml.string_input ~input_type:`Submit ~value:"Click" ()]])
                ])))

Try this form.

POST parameters

By default parameters of a Web page are in the URL (GET parameters). A web page may also expect parameters POST parameters (that is, parameters that are not in the URL but in the body of the HTTP request). Use this if you don't want the user to be able to bookmark the URL with parameters, for example if you want to post some data that will change the state of the server (paiement, database changes, etc). When designing a Web site, think carefully about the choice between GET or POST method for each service!

When you register a service with POST parameters, you must register before a service (fallback) without these parameters (for example that will answer if the page is reloaded without the hidden parameters, or if it is bookmarked).

let no_post_param_service = 
  register_new_service 
    ~url:["post"]
    ~get_params:unit
    (fun _ () () -> 
      return
        (html
         (head (title (pcdata "")) [])
         (body [h1 [pcdata 
                      "Version of the page without POST parameters"]])))
    
let my_service_with_post_params = 
  register_new_post_service
    ~fallback:no_post_param_service
    ~post_params:(string "value")
    (fun _ () value -> 
      return
        (html
         (head (title (pcdata "")) [])
         (body [h1 [pcdata value]])))

Services may take both GET and POST parameters:

let get_no_post_param_service = 
  register_new_service 
    ~url:["post2"]
    ~get_params:(int "i")
    (fun _ i () -> 
      return
        (html
         (head (title (pcdata "")) [])
         (body [p [pcdata "No POST parameter, i:";
                   em [pcdata (string_of_int i)]]])))

let my_service_with_get_and_post = register_new_post_service 
  ~fallback:get_no_post_param_service
  ~post_params:(string "value")
  (fun _ i value -> 
    return
      (html
         (head (title (pcdata "")) [])
         (body [p [pcdata "Value: ";
                   em [pcdata value];
                   pcdata ", i: ";
                   em [pcdata (string_of_int i)]]])))

POST forms

To create a POST form, use the Eliom.Xhtml.post_form function. It is similar to Eliom.Xhtml.get_form with an additional parameter for the GET parameters you want to put in the URL (if any). Here form2 is a page containing a form to the service post (using XHTML.M's functions) and form3 (defined using the syntax extension) contains a form to post2, with a GET parameter. form4 is a form to an external page.

let form2 = register_new_service ["form2"] unit
  (fun sp () () -> 
     let f =
       (Eliom.Xhtml.post_form my_service_with_post_params sp
          (fun chaine -> 
            [p [pcdata "Write a string: ";
                string_input ~input_type:`Text ~name:chaine ()]]) ()) in
     return
       (html
         (head (title (pcdata "form")) [])
         (body [f])))

let form3 = register_new_service ["form3"] unit
  (fun sp () () ->
     let f  = 
       (Eliom.Xhtml.post_form my_service_with_get_and_post sp
          (fun chaine -> 
            <:xmllist< <p> Write a string: 
                    $string_input ~input_type:`Text ~name:chaine ()$ </p> >>)
          222) in 
     return
       << <html>
            <head><title></title></head>
            <body>$f$</body></html> >>)

let form4 = register_new_service ["form4"] unit
  (fun sp () () ->
     let f  = 
       (Eliom.Xhtml.post_form
          (new_external_service 
             ~url:["http://www.petizomverts.com"]
             ~get_params:(int "i")
             ~post_params:(string "chaine") ()) sp
          (fun chaine -> 
            <:xmllist< <p> Write a string: 
                     $string_input ~input_type:`Text ~name:chaine ()$ </p> >>)
          222) in 
     return
       (html
        (head (title (pcdata "form")) [])
        (body [f])))

See the urls: post without parameter, post2 without POST parameter, form2, form3, form4.

Remember that a Web site written with Eliom is an OCaml application. This application must be able to handle several requests at the same time, if one of the requests takes time. To make this possible, Ocsigen is using cooperative threads, implemented in monadic style by Jérôme Vouillon (Lwt module), which make them really easy to use.

With respect to preemptive threads, cooperative threads are not using a scheduler to distribute processor time between threads. Instead of this, each thread must tell the others that he wants to let them work. If a thread does not cooperate, the others will be blocked.

Advantages

• It is much lighter
• No need of mutex and no risk of deadlock!
• The use of many (small) threads make implementation very easy (for example, for user interfaces, no need to implement another event loop, make a thread for each widget!)

Drawbacks

• Threads must cooperate ... Otherwise the whole program will hang.As it does not cooperate, the following page will stop the server for 5 seconds. No one will be able to do a request during this delay:

let looong =
  register_new_service
    ~url:["looong"]
    ~get_params:unit
    (fun sp () () ->
      Unix.sleep 5;
      return
        (html
          (head (title (pcdata "")) [])
          (body [h1 [pcdata "Ok now, you can read the page."]])))

To solve this problem, use a cooperative version of sleep:

let looong = 
  register_new_service 
    ~url:["looong"]
    ~get_params:unit
    (fun sp () () -> 
      Lwt_unix.sleep 5.0 >>= fun () ->
      return
        (html
          (head (title (pcdata "")) [])
          (body [h1 [pcdata 
                   "Ok now, you can read the page."]])))

<p class="importantwarning"> The binary operator >>= used to bind the result of a non blocking computation to another. In other words, it means: "if the left handside takes time, do not block here, continue to the next instruction, but remember to come back here and give the result to the following function once you get it".

In other words, it is used to specify a sequence of computations that depend one from another. It is a kind of let binding. e1 >>= (fun r -> return e2) will try to evaluate e1, and once e1 is evaluated, it will give the result to the function given as second parameter. If the left handside (e1) takes time (for example because it is waiting for a read on a socket), the whole computation will be saved in a table and the program will continue to the next instruction that does not depend on e1. The computation will resume at a future cooperation point, if it is ready to continue. Instead of e1 >>= (fun r -> return e2), you can write bind e1 (fun r -> return e2).

See looong.

Lwt.bind, (or >>=) has type
'a Lwt.t -> ('a -> 'b Lwt.t) -> 'b Lwt.t

Lwt.return has type
'a -> 'a Lwt.t

'a Lwt.t is the type of threads returning a result of type 'a. All cooperative functions must return this type.

Cooperation points are inserted when you call cooperative functions such as Lwt_unix.read or Lwt_unix.write. You can add other cooperation points by calling Lwt_unix.yield (). The thread will suspend itself, Lwt will wake up the oldest waiting thread, and this thread will resume as soon as possible.

Exceptions

To raise an exception e inside a Lwt thread, use fail e and be carefull about functions that may raise exceptions.

You must be careful when catching exception with Lwt. If you use the try ... with construct for an expression of type 'a Lwt.t, it may not work (as the computation may happen later).

Remember the following: if e has type 'a Lwt.t (where 'a is any type), do not write:

try
  e
with
  ...

but write:

catch
  (fun () -> e)
  (function ... | exn -> fail exn)

What if my function is not implemented in cooperative way?

If my function is thread-safe (for preemptive threads)

Ocsigen implements a way to make a non cooperative computation be executed automatically by a another preemptive thread (for example a database request using a non-cooperative database library, such as postgresql-ocaml or pgocaml). To do this, use the detach function. For example:

let looong2 = 
  register_new_service 
    ~url:["looong2"]
    ~get_params:unit
    (fun sp () () -> 
      Preemptive.detach Unix.sleep 5 >>= fun () ->
      return
        (html
          (head (title (pcdata "")) [])
          (body [h1 [pcdata 
                   "Ok now, you can read the page."]])))

See looong2.

A pool of preemptive threads is waiting for such "detached functions". You can specify the number of threads in the pool in the configuration file.

Warning: Detached functions must be thread-safe! Be careful to concurrent access to data. Be sure to use mutexes for your own functions, and use only thread-safe libraries.<!– For example <code></code> (version ) is NOT thread-safe, <code></code> (version ) is thread-safe. –> The libraries from Ocsigen are NOT thread-safe for now. Let us know if you really need them to be thread-safe.

If my function is not thread-safe (for preemptive threads)

If you want to use a function that takes time to execute but it not written in thread-safe way (for example some functions of OCaml's Str module), consider rewriting it in cooperative manner, or delegate the work to another process.

Examples

A thread that prints "hello" every 10 seconds

Just add the following lines to your program:

let rec f () = 
  print_endline "hello";
  Lwt_unix.sleep 10. >>= f
in f ();
      

More advanced use: Create a thread waiting for an event

Lwt.wait () creates a thread that waits forever. You can wake it up using Lwt.wakeup.

(* Create the event *)
let w = wait () in

(* Bind a thread on this event *)
(w >>= (fun v -> return (print_endline v));
...

(* Trigger the event *)
wakeup w "HELLO");
(* All threads waiting for w are awoken, and w's value is "HELLO". *)
      

Eliom provides a way to save session data on server side and restore it at each request. This data is available during the whole duration of the session. To save session data, create a table using Eliom.create_table and save and get data from this table using Eliom.set_session_data and Eliom.get_session_data. The following example shows a site with authentification. The name of the user is asked in the login form and saved in a table to be displayed on the page instead of the login form while the user is connected. Note that the session is opened automatically when needed.

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


(* "my_table" will be the structure used to store
   the session data (namely the login name): *)

let my_table = Eliom.create_table ()


(* -------------------------------------------------------- *)
(* Create services, but do not register them yet:           *)

let session_data_example =
  Eliom.new_service
    ~url:["sessdata"]
    ~get_params:Eliom.unit
    ()

let session_data_example_with_post_params =
  Eliom.new_post_service
    ~fallback:session_data_example
    ~post_params:(Eliom.string "login")
    ()

let session_data_example_close =
  Eliom.new_service
    ~url:["close"]
    ~get_params:Eliom.unit
    ()



(* -------------------------------------------------------- *)
(* Handler for the "session_data_example" service:          *)

let session_data_example_handler sp _ _  =
  let sessdat = Eliom.get_session_data my_table sp in
  return
    (html
       (head (title (pcdata "")) [])
       (body 
          [
           match sessdat with
           | Some name -> 
               p [pcdata ("Hello "^name); 
                  br (); 
                  Eliom.Xhtml.a 
                    session_data_example_close
                    sp [pcdata "close session"] ()]
           | None -> 
               Eliom.Xhtml.post_form 
                 session_data_example_with_post_params
                 sp
                 (fun login -> 
                   [p [pcdata "login: ";
                       Eliom.Xhtml.string_input
                         ~input_type:`Text ~name:login ()]]) ()
         ]))

(* -------------------------------------------------------- *)
(* Handler for the "session_data_example_with_post_params"  *)
(* service with POST params:                                *)

let session_data_example_with_post_params_handler sp _ login =
  Eliom.close_session ~sp >>= fun () ->
  Eliom.set_session_data my_table sp login;
  return
    (html
       (head (title (pcdata "")) [])
       (body 
          [p [pcdata ("Welcome " ^ login ^ ". You are now connected."); 
              br ();
              Eliom.Xhtml.a session_data_example sp [pcdata "Try again"] ()
            ]]))



(* -------------------------------------------------------- *)
(* Handler for the "session_data_example_close" service:    *)

let session_data_example_close_handler sp () () =
  let sessdat = Eliom.get_session_data my_table sp in
  Eliom.close_session ~sp >>= fun () -> 
  return
    (html
       (head (title (pcdata "Disconnect")) [])
       (body [
        (match sessdat with
        | None   -> p [pcdata "You were not connected."]
        | Some _ -> p [pcdata "You have been disconnected."]);
        p [Eliom.Xhtml.a session_data_example sp [pcdata "Retry"] () ]]))


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

let () =
  Eliom.Xhtml.register 
    session_data_example_close session_data_example_close_handler;
  Eliom.Xhtml.register 
    session_data_example session_data_example_handler;
  Eliom.Xhtml.register 
    session_data_example_with_post_params
    session_data_example_with_post_params_handler

See this example here.

To close a session, use the function close_session. Session data will disappear when the session is closed (explicitely or by timeout). Warning: if your session data contains opened file descriptors, they won't be closed by OCaml's garbage collector. Close it yourself! (for example using Gc.finalise).

We will see in the following of this tutorial how to improve this example to solve the following problems:

• The use of a main service for disconnection is not a good idea for ergonomics. You probably want to go to the same page with the login form. We will do this with a coservice.
• If you want the same login form on several pages, it is tedious work to create a coservice with POST parameters for each page. We will se how to solve this using actions and non-attached coservices.
• Session data are kept in memory and will be lost if you switch off the server, which is bad if you want long duration sessions. You can solve this problem by using persistent tables.

Eliom allows to replace a public service by a service valid only for one user. Use this to personalise main services for one user (or to create new coservices available only to one user, see later). To create a "session service", register the service in a "session service table" (valid only for one client) instead of the public table. To do that, use register_for_session.

Users are recognized automatically using a cookie. Use this for example if you want two versions of each page, one public, one for connected users.
To close a session, use close_session. Both the session service table and the session data table for that user will disappear when the sesison is closed.

Note that register_for_session and close_session take sp as parameter (because sp contains the session table).

The following example shows how to reimplement the previous one (session_data_example), without using Eliom.set_session_data. Note that this version is less efficient than the other if your site has lots of pages, because it requires to register all the new services each time a user logs in. But in other cases, that feature is really usefull, for example with coservices (see later).

We first define the main page, with a login form:

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

(* -------------------------------------------------------- *)
(* Create services, but do not register them yet:           *)

let session_services_example = 
  Eliom.new_service
    ~url:["sessionservices"] 
    ~get_params:Eliom.unit 
    ()

let session_services_example_with_post_params = 
  Eliom.new_post_service 
    ~fallback:session_services_example
    ~post_params:(Eliom.string "login")
    ()

let session_services_example_close = 
  Eliom.new_service
    ~url:["close2"]
    ~get_params:Eliom.unit
    ()


(* ------------------------------------------------------------- *)
(* Handler for the "session_services_example" service:           *)
(* It displays the main page of our site, with a login form.     *)

let session_services_example_handler sp () () = 
  let f = 
    Eliom.Xhtml.post_form 
      session_services_example_with_post_params 
      sp
      (fun login -> 
        [p [pcdata "login: ";
            string_input ~input_type:`Text ~name:login ()]]) () 
  in 
  return
    (html
       (head (title (pcdata "")) [])
       (body [f]))


(* ------------------------------------------------------------- *)
(* Handler for the "session_services_example_close" service:     *)

let session_services_example_close_handler sp () () =
  Eliom.close_session ~sp >>= fun () ->
  return
    (html
       (head (title (pcdata "Disconnect")) [])
       (body [p [pcdata "You have been disconnected. ";
                 a session_services_example
                   sp [pcdata "Retry"] ()
               ]]))

When the page is called with login parameters, it runs the function launch_session that replaces some services already defined by new ones:

(* ------------------------------------------------------------- *)
(* Handler for the "session_services_example_with_post_params"   *)
(* service:                                                      *)

let launch_session sp () login =

  (* New handler for the main page: *)
  let new_main_page sp () () = 
    return
      (html
       (head (title (pcdata "")) [])
       (body [p [pcdata "Welcome ";
                 pcdata login; 
                 pcdata "!"; br ();
                 a coucou sp [pcdata "coucou"] (); br ();
                 a hello sp [pcdata "hello"] (); br ();
                 a links sp [pcdata "links"] (); br ();
                 a session_services_example_close
                   sp [pcdata "close session"] ()]]))
  in

  (* If a session was opened, we close it first! *)
  Eliom.close_session ~sp >>= fun () ->

  (* Now we register new versions of main services in the
     session service table: *)
  Eliom.Xhtml.register_for_session 
    ~sp
    ~service:session_services_example
    (* service is any public service already registered,
       here the main page of our site *)
    new_main_page;
  
  Eliom.Xhtml.register_for_session 
    ~sp
    ~service:coucou
    (fun _ () () -> 
      return
        (html
         (head (title (pcdata "")) [])
         (body [p [pcdata "Coucou ";
                   pcdata login;
                   pcdata "!"]])));

  Eliom.Xhtml.register_for_session 
    ~sp
    ~service:hello
    (fun _ () () -> 
      return
        (html
         (head (title (pcdata "")) [])
         (body [p [pcdata "Ciao ";
                   pcdata login;
                   pcdata "!"]])));

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

let () = 
  Eliom.Xhtml.register
    ~service:session_services_example
    session_services_example_handler;
  Eliom.Xhtml.register
    ~service:session_services_example_close
    session_services_example_close_handler;
  Eliom.Xhtml.register
    ~service:session_services_example_with_post_params
    launch_session

See the result.

Warning: As in the previous example, to implement such connection and disconnection forms, you get more flexibility by using actions instead of xhtml services (see below for the same example with actions).

Services registered in session tables are called session or private services. Services registered in the public table are called public.

A coservice is a service that uses the same URL as a main service, but generates another page. They are distinguished from main services only by a special parameter, called state parameter. Coservices may use GET or POST parameters.

Most of the time, GET coservices are created dynamically with respect to previous interaction with the user and are registered in the session table. They allow to give a precise semantics to the "back" button of the browser (be sure that you will go back in the past) or bookmarks, or duplication of the browser's window. (See the calc example below).

Use POST coservices if you want to particularize a link or form, but not the URL it points to. More precisely, POST coservices are mainly used in two situations:

• For the same purpose as GET coservices (new services corresponding to precise points of the interaction with the user) but when you don't want this service to be bookmarkable.
• To create a button that leads to a service after having performed a side-effect. For example a disconnection button that leads to the main page of the side, but with the side effect of disconnecting the user.

To create a coservice, use new_coservice and new_post_coservice. Like register_new_post_service, they take a public service as parameter (labelled fallback) to be used as fallback when the user comes back without the state parameter (for example if it was a POST coservice and/or the coservice has expired).

The following example shows the difference between GET coservices (bookmarkable) and POST coservices:

(************************************************************)
(************** Coservices. Basic examples ******************)
(************************************************************)

(* -------------------------------------------------------- *)
(* We create one main service and two coservices:           *)

let coservices_example = 
  Eliom.new_service
    ~url:["coserv"] 
    ~get_params:Eliom.unit
    ()

let coservices_example_post = 
  Eliom.new_post_coservice 
    ~fallback:coservices_example 
    ~post_params:Eliom.unit
    ()

let coservices_example_get = 
  Eliom.new_coservice
    ~fallback:coservices_example
    ~get_params:Eliom.unit
    ()


(* -------------------------------------------------------- *)
(* The three of them display the same page,                 *)
(* but the coservices change the counter.                   *)

let _ = 
  let c = ref 0 in
  let page sp () () = 
    let l3 = Eliom.Xhtml.post_form coservices_example_post sp 
        (fun _ -> [p [Eliom.Xhtml.string_input 
                        ~input_type:`Submit
                        ~value:"incr i (post)" ()]]) () 
    in
    let l4 = Eliom.Xhtml.get_form coservices_example_get sp 
        (fun _ -> [p [Eliom.Xhtml.string_input
                        ~input_type:`Submit
                        ~value:"incr i (get)" ()]]) 
    in 
    return
      (html
       (head (title (pcdata "")) [])
       (body [p [pcdata "i is equal to ";
                 pcdata (string_of_int !c); br ();
                 a coservices_example sp [pcdata "reload"] (); br ();
                 a coservices_example_get sp [pcdata "incr i"] ()];
              l3;
              l4]))
  in
  Eliom.Xhtml.register coservices_example page;
  let f sp () () = c := !c + 1; page sp () () in
  Eliom.Xhtml.register coservices_example_post f;
  Eliom.Xhtml.register coservices_example_get f

Try coserv.

Note that if the coservice does not exist (for example it has expired), the fallback is called.

In this example, coservices do not take any parameters (but the state parameter), but you can create coservices with parameters. Note that the fallback of a GET coservice cannot take parameters. Actually as coservices parameters have special names, it is possible to use a "pre-applied" service as fallback (see later).

Exercise: Rewrite the example of Web site with connection (session_data_example, with session data) using a POST coservice without parameter to make the disconnection link go back to the main page of the site instead of a "disconnection" page. It is better for ergonomics, but it would be even better to stay on the same page ... How to do that with POST coservices? A much better solution will be seen in the section about actions and non-attached coservices.

Non-attached coservices

Non-attached coservices are services that are not attached to an URL. When you point a link or a form towards such a service, the URL does not change. The name of the service is sent as a special parameter.

As for attached coservices, there are GET and POST versions. To create them, use Eliom.new_coservice' or Eliom.new_post_coservice'. POST non-attached coservices are really usefull if you want a link or form to be present on every page but you don't want the URL to change. Very often, POST coservices are used with actions (see more details and an example in the section about actions below).

You can register coservices in session tables to create dynamically new services dedicated to an user. Here is an example of pages that add two integers. Once the first number is sent by the user, a coservice is created and registered in the session table. This service takes the second number as parameter and displays the result of the sum with the first one. Try to duplicate the pages and/or to use the back button of your navigator to verify that it has the expected behaviour.

(************************************************************)
(*************** calc: sum of two integers ******************)
(************************************************************)

(* -------------------------------------------------------- *)
(* We create two main services on the same URL,             *)
(* one with a GET integer parameter:                        *)

let calc = 
  new_service
    ~url:["calc"]
    ~get_params:unit
    ()

let calc_i = 
  new_service 
    ~url:["calc"]
    ~get_params:(int "i")
    ()


(* -------------------------------------------------------- *)
(* The handler for the service without parameter.           *)
(* It displays a form where you can write an integer value: *)

let calc_handler sp () () =   
  let create_form intname = 
    [p [pcdata "Write a number: ";
        Eliom.Xhtml.int_input ~input_type:`Text ~name:intname ();
        br ();
        Eliom.Xhtml.string_input ~input_type:`Submit ~value:"Send" ()]]
  in
  let f = Eliom.Xhtml.get_form calc_i sp create_form in
  return
    (html 
       (head (title (pcdata "")) [])
       (body [f]))

(* -------------------------------------------------------- *)
(* The handler for the service with parameter.              *)
(* It creates dynamically and registers a new coservice     *)
(* with one GET integer parameter.                          *)
(* This new coservice depends on the first value (i)        *)
(* entered by the user.                                     *)

let calc_i_handler sp i () = 
  let create_form is = 
    (fun entier ->
       [p [pcdata (is^" + ");
           int_input ~input_type:`Text ~name:entier ();
           br ();
           string_input ~input_type:`Submit ~value:"Sum" ()]])
  in
  let is = string_of_int i in
  let calc_result = 
    register_new_coservice_for_session
      ~sp
      ~fallback:calc
      ~get_params:(int "j")
      (fun sp j () -> 
        let js = string_of_int j in
        let ijs = string_of_int (i+j) in 
        return
          (html
             (head (title (pcdata "")) [])
             (body
                [p [pcdata (is^" + "^js^" = "^ijs)]])))
  in
  let f = get_form calc_result sp (create_form is) in 
  return
    (html
       (head (title (pcdata "")) [])
       (body [f]))


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

let () =
  Eliom.Xhtml.register calc   calc_handler;
  Eliom.Xhtml.register calc_i calc_i_handler

See the result.

Actions are services that do not generate any page. Use them to perform an effect on the server (connection/disconnection of a user, adding something in a shopping basket, delete a message in a forum, etc.). The page you link to is redisplayed after the action. For ex, when you have the same form (or link) on several pages (for ex a connection form), instead of making a version with post params of all these pages, you can use only one action, registered on a non-attached coservice. To register actions, just use the module Actions instead of Eliom.Xhtml (or Eliomduce.Xhtml, etc.). For example Actions.register, Actions.register_new_service, Actions.register_for_session.

Here we rewrite the example session_data_example using actions and non-attached coservices (note the POST coservice for disconnection, much better than the previous solution that was using another URL).

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


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

let action_example = 
  Eliom.new_service
    ~url:["action"] 
    ~get_params:Eliom.unit
    ()

let connect_action = 
  Eliom.new_post_coservice'
    ~post_params:(Eliom.string "login")
    ()
    
(* As the handler is very simple, we register it now: *)
let disconnect_action = 
  Actions.register_new_post_coservice'
    ~post_params:Eliom.unit 
    (fun sp () () -> 
      Eliom.close_session ~sp >>= fun () -> 
      return [])


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

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

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