Client-side services

Starting with Eliom 6.0, services can have client-side handlers. Registering client-side handlers for services allows us to perform most of the operations (e.g., building the user interface) locally, and only call the server for operations that are by necessity non-local (e.g., retrieving database data).

Client-side service implementation is required for building mobile applications with Eliom, but can also be used to change page faster within a Web application. In this manual chapter, we focus on the client-side service mechanics and do not go into the details of setting up a complete mobile application. The complete setup needed is discussed in the mobile applications chapter of this manual.

Service creation and registering

As described in the chapter on server-side services, services are first created via Eliom.Service.create and similar functions, and subsequently registered.

The first step (creation) can only happen on the server; allowing the opposite would permit "creating" on the client services that are not actually provided by the server. To allow client-side service manipulation, services can be injected, as demonstrated by the following example:

let%server s =
  Eliom.Service.create
    ~meth:(Eliom.Service.Get Eliom.Parameter.unit)
    ~path:(Eliom.Service.Path ["content"])
    ()

let%client s = ~%s

The above style makes the service available under the same identifier (here s) on both sides. Subsequently, the service can be registered on both sides with the same Eliom.Registration APIs. For example:

let%shared () =
  Eliom.Registration.Html.register s
    (fun () () ->
       Lwt.return
         (Eliom.Tools.F.html
            ~title:"hybrid"
            Html.F.(body [
              h1 [txt "Salut !"];
            ])))

The types of the handlers are compatible between the two sides. For instance, Eliom.Registration.Html expects a function that produces a Html_types.html Eliom.Content.Html.D.elt Lwt.t, for Eliom.Registration.Action we must return unit Lwt.t, and so on. The behavior of all services is compatible to the extent possible, e.g., actions perform a reload after performing their side effect.

For application services, the Eliom.Registration.App functor needs to be called just like on the server. The signatures are compatible between the two sides, and therefore the functor invocation can happen in a shared section.

A service registered as above can be called via links (e.g., Eliom.Content.Html.D.a) and forms just like a standard server-only service. Eliom detects the existence of a client-side implementation and calls that instead of performing a request to the server. If no client-side implementation exists, a standard server request is performed, which may cause problems in the context of mobile applications.

Service routing

Service routing is the operation of choosing a service based on a URL and a collection of POST parameters. This is clearly a key operation on the server, allowing Eliom to respond on different paths. Routing has also become available on the client via the function Eliom.Client.change_page_uri. This function can be used for example in order to open a link inside a mobile application without launching the Web browser.