Today's example focuses on co-services. A co-service is basically a service that shares its URL with a "parent" service, but which may have different parameters. Co-services are often used together with sessions to personalise a given URL for one specific user.

Since co-services share the same URL, how does Eliom know which one is being invoked? That distinction is made via a special hidden parameter. However, it is nothing that you should be worried about, as it happens transparently to the developer.

The code below is a minimalistic illustration of the possible use for a co-service. I suggest that you use the "view source" functionality of your browser to observe the hidden parameter contained in the page.

(************************************************************************)
(* Coservice demonstration.                                             *)
(************************************************************************)

open XHTML.M


(************************************************************************)
(*  Declaration of the "foobar" service.  Note that we are not
    registering it yet, and therefore we do not provide the handler
    at this point.
*)

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


(************************************************************************)
(*  Declaration of the "foobar2" service, which is actually a
    coservice for "foobar".  Coservices share the same path as
    the main service, but may have different parameters.
*)

let foobar2_service = 
    Eliom_services.new_coservice
        ~fallback: foobar_service
        ~get_params: (Eliom_parameters.int "amount")
        ()


(************************************************************************)
(*  Handler for "foobar" service.  It displays the current value of
    the counter and provides links to reload itself or to invoke the
    coservice with different parameters.
*)

let counter = ref 0

let foobar_handler sp () () = 
    Lwt.return
        (html
        (head (title (pcdata "")) [])
        (body [p    [
                pcdata "counter is equal to ";
                pcdata (string_of_int !counter);
                br ();
                Eliom_predefmod.Xhtml.a foobar_service sp [pcdata "reload"] ();
                br ();
                Eliom_predefmod.Xhtml.a foobar2_service sp [pcdata "increment by 1"] 1;
                br ();
                Eliom_predefmod.Xhtml.a foobar2_service sp [pcdata "increment by 2"] 2;
                ]]))


(************************************************************************)
(*  Handler for the "foobar2" service (the coservice of "foobar").
    Note that this handler just increments the counter by the amount
    specified in the GET parameter and then invokes the handler of
    "foobar" to display the actual page.
*)

let foobar2_handler sp amount () =
    counter := !counter + amount;
    foobar_handler sp () ()


(************************************************************************)
(*  Registration of the services.
*)

let () =
    Eliom_predefmod.Xhtml.register foobar_service foobar_handler;
    Eliom_predefmod.Xhtml.register foobar2_service foobar2_handler