This is client API (go to server)

Module Eliom_client

module Eliom_client : sig..end

Call server side services and change the current page.


Mobile applications

val init_client_app : 
  app_name:string ->
  ?ssl:bool ->
  hostname:string ->
  ?port:int -> full_path:Eliom_lib.Url.path -> unit -> unit

Call this function if you want to be able to run your client side app before doing the first request, that is, when the client side app is not sent by the server. This may be the case for example if you are developing a mobile app. The parameters correspond to the base URL of the server side of your application.

Alternatively, and to make sure it is done early enough, define a JS variable called __eliom_server at the beginning of your html file, containing the full URL of your server.

val is_client_app : unit -> bool

Returns whether the application is sent by a server or started on client side. If called on server side, always returns false. Otherwise, it tests the presence of JS variables added automatically by Eliom when the page is sent by a server. Example:

if not (Eliom_client.is_client_app ())
 then Eliom_client.init_client_app ...

Calling services

val change_page : 
  ?absolute:bool ->
  ?absolute_path:bool ->
  ?https:bool ->
  service:('a, 'b, 'c, 'd, 'e, 'f, 'g,
   [< `WithSuffix | `WithoutSuffix ], 'h, 'i,
   Eliom_service.non_ocaml)
   Eliom_service.t ->
  ?hostname:string ->
  ?port:int ->
  ?fragment:string ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  ?nl_params:Eliom_parameter.nl_params_set ->
  ?keep_get_na_params:bool ->
  ?progress:(int -> int -> unit) ->
  ?upload_progress:(int -> int -> unit) ->
  ?override_mime_type:string -> 'a -> 'b -> unit Lwt.t

Call a server side service and change the current page. If the service belongs to the same application, the client side program is not stopped, and only the content (not the container) is reloaded.

val call_ocaml_service : 
  ?absolute:bool ->
  ?absolute_path:bool ->
  ?https:bool ->
  service:('a, 'b, 'c, 'd, 'e, 'f, 'g,
   [< `WithSuffix | `WithoutSuffix ], 'h, 'i,
   'return Eliom_service.ocaml)
   Eliom_service.t ->
  ?hostname:string ->
  ?port:int ->
  ?fragment:string ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  ?nl_params:Eliom_parameter.nl_params_set ->
  ?keep_get_na_params:bool ->
  ?progress:(int -> int -> unit) ->
  ?upload_progress:(int -> int -> unit) ->
  ?override_mime_type:string -> 'a -> 'b -> 'return Lwt.t

Call a server side service that return an OCaml value.

If the service raises an exception, the call to the call_ocaml_service raises an exception Exception_on_server whose argument describes the server-side exception. (NB that we cannot send the original exception as-it, because OCaml permits the marshalling of exceptions ...)

val exit_to : 
  ?absolute:bool ->
  ?absolute_path:bool ->
  ?https:bool ->
  service:('a, 'b, 'c, 'd, 'e, 'f, 'g,
   [< `WithSuffix | `WithoutSuffix ], 'h, 'i,
   Eliom_service.non_ocaml)
   Eliom_service.t ->
  ?hostname:string ->
  ?port:int ->
  ?fragment:string ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  ?nl_params:Eliom_parameter.nl_params_set ->
  ?keep_get_na_params:bool -> 'a -> 'b -> unit

Stop current program and load a new page. Note that for string arguments, sole line feed or sole carriage return characters are substituted by the string "\r\n".

val window_open : 
  window_name:Js.js_string Js.t ->
  ?window_features:Js.js_string Js.t ->
  ?absolute:bool ->
  ?absolute_path:bool ->
  ?https:bool ->
  service:('a, unit, Eliom_service.get, 'b, 'c, 'd, 'e,
   [< `WithSuffix | `WithoutSuffix ], 'f, unit, 'g)
   Eliom_service.t ->
  ?hostname:string ->
  ?port:int ->
  ?fragment:string ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  ?nl_params:Eliom_parameter.nl_params_set ->
  ?keep_get_na_params:bool -> 'a -> Dom_html.window Js.t

Loads an Eliom service in a window (cf. Javascript's window.open).

val change_url : 
  ?absolute:bool ->
  ?absolute_path:bool ->
  ?https:bool ->
  service:('get, unit, Eliom_service.get, 'a, 'b, 'c, 'd,
   [< `WithSuffix | `WithoutSuffix ], 'e, unit, 'f)
   Eliom_service.t ->
  ?hostname:string ->
  ?port:int ->
  ?fragment:string ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  ?nl_params:Eliom_parameter.nl_params_set -> 'get -> unit

Changes the URL, without doing a request. It takes a GET (co-)service as parameter and its parameters.

val call_service : 
  ?absolute:bool ->
  ?absolute_path:bool ->
  ?https:bool ->
  service:('a, 'b, 'c, 'd, 'e, 'f, 'g,
   [< `WithSuffix | `WithoutSuffix ], 'h, 'i, 'j)
   Eliom_service.t ->
  ?hostname:string ->
  ?port:int ->
  ?fragment:string ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  ?nl_params:Eliom_parameter.nl_params_set ->
  ?keep_get_na_params:bool ->
  ?progress:(int -> int -> unit) ->
  ?upload_progress:(int -> int -> unit) ->
  ?override_mime_type:string -> 'a -> 'b -> string Lwt.t

(low level) Call a server side service and return the content of the resulting HTTP frame as a string.

Misc

val onload : (unit -> unit) -> unit

Registers some code to be executed after loading the client application, or after changing the page the next time.

It complements as a toplevel expression in the client module with the side effect from client values while creating the response of a service: While the latter are executed each time the service has been called; the former is executed only once; but each at a time where the document is in place:

{shared{ open Eliom_lib }}
    {client{
      let () = alert "Once only during initialization of the client, i.e. before the document is available."
      let () =
        Eliom_client.onload
          (fun () -> alert "Once only when the document is put in place.")
    }}
    {server{
      let _ = My_app.register_service ~path ~get_params
        (fun () () ->
           ignore {unit{
             alert "Each time this service is called and the sent document is put in place."
           }};
           Lwt.return html
    }}
val onunload : (unit -> string option) -> unit

onunload f registers f as a handler to be called before changing the page the next time. If f returns Some s, then we ask the user to confirm quitting. We try to use s in the confirmation pop-up. None means no confirmation needed.

The callback f is sometimes trigerred by internal service calls, and sometimes by the browser onbeforeunload event. In the onbeforeunload case, the confirmation pop-up is managed by the browser. For Firefox, the string s returned by f is ignored: https://bugzilla.mozilla.org/show_bug.cgi?id=641509

onunload can be used to register multiple callbacks. If the user decides to stay, we call any remaining callbacks, but these cannot ask for further confirmation.

val wait_load_end : unit -> unit Lwt.t

Wait for the initialization phase to terminate

val get_application_name : unit -> string

Returns the name of currently running Eliom application, defined while applying Eliom_registration.App functor.

RPC / Server functions

See the manual .

type ('a, 'b) server_function = 'a -> 'b Lwt.t

A ('a, 'b) server_function provides transparently access to a server side function which has been created by Error a_api: invalid contents .

See also the opaque server side representation .

The handling of exception on the server corresponds to that of <<a_api subproject="client"|val Eliom_client.call_ocaml_service>>.

val server_function : 
  ?scope:[< Eliom_common.scope ] ->
  ?options:unit ->
  ?charset:string ->
  ?code:int ->
  ?content_type:string ->
  ?headers:Http_headers.t ->
  ?secure_session:bool ->
  name:string ->
  ?csrf_safe:bool ->
  ?csrf_scope:[< Eliom_common.user_scope ] ->
  ?csrf_secure:bool ->
  ?max_use:int ->
  ?timeout:float ->
  ?https:bool ->
  ?error_handler:((string * exn) list -> 'b Lwt.t) ->
  'a Deriving_Json.t -> unit -> ('a, 'b) server_function

server_function argument_type f creates a value of type Eliom_client.​server_function . This allows to call f from the client. The first argument argument_type is an instance of Deriving_Json for the type of the argument. It is used to safely encode and decode the argument sent to the server.

The optional parameters correspond directly to the optional parameters of Eliom_registration.​Ocaml.​register_service .

See also the manual .

Defining server functions in shared or client sections is possible only if you give them a name.