This is server API (go to client)

Warning: Reason support is experimental. We are looking for beta-tester and contributors.

Module Eliom_services

module Eliom_services : sig..end

Types, creation and manipulation of Eliom services.


exception Wrong_session_table_for_CSRF_safe_coservice
type suff = [ `WithSuffix | `WithoutSuffix ]

Types of services


type servcoserv = [ `Coservice | `Service ]
type getpost = [ `Get | `Post ]
type attached_service_kind = [ `External | `Internal of servcoserv ]
type internal = [ `Internal of servcoserv ]
type registrable = [ `Registrable | `Unregistrable ]
type (+'a, +'b) a_s

You can call register function only on registrable services

type +'a na_s
type service_kind = 
  [ `Attached of
   (attached_service_kind, getpost)
   a_s
  | `Nonattached of getpost na_s ]
type internal_service_kind = 
  [ `Attached of
   (internal, getpost)
   a_s
  | `Nonattached of getpost na_s ]
type get_service_kind = 
  [ `Attached of
   (attached_service_kind, [ `Get ])
   a_s
  | `Nonattached of [ `Get ] na_s ]
type post_service_kind = 
  [ `Attached of
   (attached_service_kind, [ `Post ])
   a_s
  | `Nonattached of [ `Post ] na_s ]
type attached = 
  [ `Attached of
   (attached_service_kind, getpost)
   a_s ]
type nonattached = [ `Nonattached of getpost na_s ]
type ('a, 'b, +'c, +'d, +'e, +'f, +'g, +'h) service
val get_get_or_post : 
  ('a, 'b,
   [< `Attached of
   (attached_service_kind,
   [< getpost ])
   a_s
   | `Nonattached of [< getpost ] na_s ],
   'c, 'd, 'e, 'f, 'g)
  service -> getpost

Type of services.* 'get is the type of GET parameters

  • 'post is the type of POST parameters
  • 'kind is a subtype of Eliom_services.​service_kind (attached or non-attached service, internal or external, GET only or with POST parameters)
  • 'tipo is a phantom type stating the kind of parameters it uses (suffix or not)
  • 'getnames is the type of GET parameters names
  • 'postnames is the type of POST parameters names
  • 'registrable is a phantom type, subtype of Eliom_services.​registrable, telling if it is possible to register a handler on this service.
  • 'return is an information on what the service returns


val register_eliom_module : string -> (unit -> unit) -> unit

Registration of named modules


This functionality allows to register module initialization functions for Eliom modules which will be executed when the corresponding module is initialized in ocsigen.conf.


This function is used to specify the initialization function for Eliom modules linked dynamic or statically into the server. register_eliom_module name f registers the initialization function f for module name. The f function will be invoked when the module is initialized in the configuration file using <eliom name="name"> ... </eliom>, which is equivalent to <eliom module="name.cmo"> ... </eliom> with the exception that it does not load the module using Dynlink.

Definitions of services


Warning: These functions must be called when the site information is available, that is, either during a request or during the initialisation phase of the site. Otherwise, it will raise the exception Eliom_common.​Eliom_site_information_not_available. If you are using static linking, you must delay the call to this function until the configuration file is read, using Eliom_services.​register_eliom_module. Otherwise you will also get this exception.

val service : 
  ?https:bool ->
  path:Eliom_pervasives.Url.path ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  ?priority:int ->
  get_params:('a, [< suff ] as 'b, 'c)
   Eliom_parameters.params_type ->
  unit ->
  ('a, unit,
   [> `Attached of
   ([> `Internal of [> `Service ] ], [> `Get ]) a_s ],
   'b, 'c, unit, [> `Registrable ], 'd)
  service

Main services


val external_service : 
  prefix:string ->
  path:Eliom_pervasives.Url.path ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  get_params:('a, [< suff ] as 'b, 'c)
   Eliom_parameters.params_type ->
  unit ->
  ('a, unit,
   [> `Attached of ([> `External ], [> `Get ]) a_s ], 'b,
   'c, unit, [> `Unregistrable ], 'd)
  service

service ~path ~get_params () creates a Eliom_services.​service associated to the path path, taking the GET parameters get_params.

If ~https is true, all links towards that service will use https.

The default priority is 0. If you want the service to be tried before (resp after) the other ones at the same path, put a higher (resp. lower) priority.

val external_post_service : 
  prefix:string ->
  path:Eliom_pervasives.Url.path ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  get_params:('a, [< suff ] as 'b, 'c)
   Eliom_parameters.params_type ->
  post_params:('d, [ `WithoutSuffix ], 'e) Eliom_parameters.params_type ->
  unit ->
  ('a, 'd,
   [> `Attached of ([> `External ], [> `Post ]) a_s ],
   'b, 'c, 'e, [> `Unregistrable ], 'f)
  service

Creates a service for an external web site, that will use GET method. This allows to creates links or forms towards other Web sites using Eliom's syntax.

The parameter labelled ~path is the URL path, and each element of the list will be URL-encoded.

The parameter labelled ~prefix contains all what you want to put before the path. It usually starts with "http://" plus the name of the server. The whole URL is constructed from the prefix, the path and parameters. The prefix is not encoded. An empty prefix can be used to make a link to another site of the same server.

val post_service : 
  ?https:bool ->
  fallback:('a, unit,
   [ `Attached of
   ([ `Internal of [ `Coservice | `Service ] ], [ `Get ])
   a_s ],
   [< suff ] as 'b, 'c, unit, [< `Registrable ],
   'd)
   service ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  ?priority:int ->
  post_params:('e, [ `WithoutSuffix ], 'f) Eliom_parameters.params_type ->
  unit ->
  ('a, 'e,
   [> `Attached of
   ([> `Internal of [ `Coservice | `Service ] ], [> `Post ])
   a_s ],
   'b, 'c, 'f, [> `Registrable ], 'g)
  service

Same, with POST method.


Creates a service that takes POST parameters. fallback is a service without POST parameters. You can't create an service with POST parameters if the same service does not exist without POST parameters. Thus, the user cannot put a bookmark on a page that does not exist.

val coservice : 
  ?name:string ->
  ?csrf_safe:bool ->
  ?csrf_scope:[< Eliom_common.user_scope > `Session ] ->
  ?csrf_secure:bool ->
  ?max_use:int ->
  ?timeout:float ->
  ?https:bool ->
  fallback:(unit, unit,
   [ `Attached of
   ([ `Internal of [ `Service ] ], [ `Get ])
   a_s ],
   [ `WithoutSuffix ], unit, unit,
   [< registrable ], 'a)
   service ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  get_params:('b, [ `WithoutSuffix ], 'c) Eliom_parameters.params_type ->
  unit ->
  ('b, unit,
   [> `Attached of
   ([> `Internal of [> `Coservice ] ], [> `Get ])
   a_s ],
   [ `WithoutSuffix ], 'c, unit, [> `Registrable ], 'd)
  service

Attached coservices


val post_coservice : 
  ?name:string ->
  ?csrf_safe:bool ->
  ?csrf_scope:[< Eliom_common.user_scope > `Session ] ->
  ?csrf_secure:bool ->
  ?max_use:int ->
  ?timeout:float ->
  ?https:bool ->
  fallback:('a, unit,
   [ `Attached of
   ([ `Internal of [< `Coservice | `Service ] ], [ `Get ])
   a_s ],
   [< suff ] as 'b, 'c, unit, [< `Registrable ],
   'd)
   service ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  post_params:('e, [ `WithoutSuffix ], 'f) Eliom_parameters.params_type ->
  unit ->
  ('a, 'e,
   [> `Attached of
   ([> `Internal of [> `Coservice ] ], [> `Post ])
   a_s ],
   'b, 'c, 'f, [> `Registrable ], 'g)
  service

Creates an attached coservice. A coservice is another version of an already existing main service, where you can register another handler. The two versions are automatically distinguished using an extra parameter added automatically by Eliom. It allows to have several links towards the same page, that will behave differently, or to create services dedicated to one user. Coservices can be named if the ?name optional parameter is present or anonymous (in that case, a coservice number will be generated).

See the programmer's manual for more informations.

The ~timeout parameter specifies a timeout (in seconds) after which the coservice will disappear. This amount of time is computed from the creation or from the last call to the service. Default: no timeout.

The ~max_use parameter specifies that the service can be used only a fixed number of times. Default: no limitation.

If ~csrf_safe is true, it will create a "CSRF-safe" service (the default is false). (In that case ~name is ignored). It means that the registration of the service will not actually take place when register is called, but delayed and performed each time a form is created. This allows to protect against CSRF attacks, and should be use with a short timeout (and max_use). (And you should probably use POST coservices in that case). In that case, you can register the CSRF safe service either in the global service table or in the session service table. But the actual registration, that will occure when creating a link or a form, will always take place in a session service table. This table is specified by the ~csrf_scope and ~csrf_secure parameters (that correspond to ~scope and ~secure for the delayed registration); it is the default session table if they are absent. Parameters ?scope and ?secure of register must have the same values as the one declared while creating the CSRF safe coservice, otherwise the registration will fail with .


Creates a coservice with POST parameters

val coservice' : 
  ?name:string ->
  ?csrf_safe:bool ->
  ?csrf_scope:[< Eliom_common.user_scope > `Session ] ->
  ?csrf_secure:bool ->
  ?max_use:int ->
  ?timeout:float ->
  ?https:bool ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  get_params:('a, [ `WithoutSuffix ], 'b) Eliom_parameters.params_type ->
  unit ->
  ('a, unit, [> `Nonattached of [> `Get ] na_s ],
   [ `WithoutSuffix ], 'b, unit, [> `Registrable ], 'c)
  service

Non attached coservices


val post_coservice' : 
  ?name:string ->
  ?csrf_safe:bool ->
  ?csrf_scope:[< Eliom_common.user_scope > `Session ] ->
  ?csrf_secure:bool ->
  ?max_use:int ->
  ?timeout:float ->
  ?https:bool ->
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  ?keep_get_na_params:bool ->
  post_params:('a, [ `WithoutSuffix ], 'b) Eliom_parameters.params_type ->
  unit ->
  (unit, 'a, [> `Nonattached of [> `Post ] na_s ],
   [ `WithoutSuffix ], unit, 'b, [> `Registrable ], 'c)
  service

Creates a non-attached coservice, that is, services that do not correspond to a path in the URL. They are identified only by a parameter, whatever be the path. Links towards such services will not change the URL, just add extra parameters. Non-attached coservices can be named if the ?name optional parameter is present or anonymous (in that case, a coservice number will be generated). See the programmer's manual for more informations.


Creates a non attached coservice with POST parameters. If the optional parameter ~keep_get_na_params is false, GET non-attached parameters won't be kept in the URL (if any) when you create a POST form to this coservice. Default is true.

Predefined services


val static_dir : 
  unit ->
  (string list, unit,
   [> `Attached of
   ([> `Internal of [> `Service ] ], [> `Get ]) a_s ],
   [ `WithSuffix ], [ `One of string list ] Eliom_parameters.param_name,
   unit, [> `Unregistrable ], 'a)
  service

Static files


val https_static_dir : 
  unit ->
  (string list, unit,
   [> `Attached of
   ([> `Internal of [> `Service ] ], [> `Get ]) a_s ],
   [ `WithSuffix ], [ `One of string list ] Eliom_parameters.param_name,
   unit, [> `Unregistrable ], 'a)
  service

A predefined service that correponds to the directory where static pages are (if the staticmod extension is used). This directory is chosen in the configuration file. This service takes the name of the static file as a parameter (a string list, slash separated).

val static_dir_with_params : 
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  get_params:('a, [ `WithoutSuffix ], 'b) Eliom_parameters.params_type ->
  unit ->
  (string list * 'a, unit,
   [> `Attached of
   ([> `Internal of [> `Service ] ], [> `Get ]) a_s ],
   [ `WithSuffix ],
   [ `One of string list ] Eliom_parameters.param_name * 'b, unit,
   [> `Unregistrable ], 'c)
  service

The same, but forcing https

val https_static_dir_with_params : 
  ?keep_nl_params:[ `All | `None | `Persistent ] ->
  get_params:('a, [ `WithoutSuffix ], 'b) Eliom_parameters.params_type ->
  unit ->
  (string list * 'a, unit,
   [> `Attached of
   ([> `Internal of [> `Service ] ], [> `Get ]) a_s ],
   [ `WithSuffix ],
   [ `One of string list ] Eliom_parameters.param_name * 'b, unit,
   [> `Unregistrable ], 'c)
  service

Like static_dir, but allows to put GET parameters


The same, but forcing https

val void_coservice' : 
  (unit, unit, [> `Nonattached of 'a na_s ],
   [ `WithoutSuffix ], unit, unit, [> `Unregistrable ], 'b)
  service

Void non-attached coservices


val https_void_coservice' : 
  (unit, unit, [> `Nonattached of 'a na_s ],
   [ `WithoutSuffix ], unit, unit, [> `Unregistrable ], 'b)
  service

A predefined 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 service without POST parameters, on which you register an action that does nothing, but you can use it with <a> links, not only forms. It does not keep non attached GET parameters.

val void_hidden_coservice' : 
  (unit, unit, [> `Nonattached of 'a na_s ],
   [ `WithoutSuffix ], unit, unit, [> `Unregistrable ], 'b)
  service

The same, but forcing https.

val https_void_hidden_coservice' : 
  (unit, unit, [> `Nonattached of 'a na_s ],
   [ `WithoutSuffix ], unit, unit, [> `Unregistrable ], 'b)
  service

Same as void_coservice' but keeps non attached GET parameters.


The same, but forcing https.

val preapply : 
  service:('a, 'b, [> `Attached of ('d, 'e) a_s ] as 'c,
   [< suff ], 'f, 'g, 'h, 'i)
   service ->
  'a ->
  (unit, 'b, 'c, [ `WithoutSuffix ], unit, 'g, [> `Unregistrable ], 'i)
  service

Miscellaneous


val add_non_localized_get_parameters : 
  params:('a, [ `WithoutSuffix ], 'b)
   Eliom_parameters.non_localized_params ->
  service:('c, 'd, 'e, 'f, 'g, 'h, 'i, 'j) service ->
  ('c * 'a, 'd, 'e, 'f, 'g * 'b, 'h, 'i, 'j) service

creates a new service by preapplying a service to GET parameters. It is not possible to register a handler on an preapplied service. Preapplied services may be used in links or as fallbacks for coservices

val add_non_localized_post_parameters : 
  params:('a, [ `WithoutSuffix ], 'b)
   Eliom_parameters.non_localized_params ->
  service:('c, 'd, 'e, 'f, 'g, 'h, 'i, 'j) service ->
  ('c, 'd * 'a, 'e, 'f, 'g, 'h * 'b, 'i, 'j) service

Adds non localized GET parameters to a service

val unregister : 
  ?scope:[< Eliom_common.scope ] ->
  ?secure:bool ->
  ('a, 'b,
   [< `Attached of
   ([> `Internal of 'c ], [< `Get | `Post ]) a_s
   | `Nonattached of 'd na_s ],
   'e, 'f, 'g, 'h, 'i)
  service -> unit

Adds non localized POST parameters to a service


Unregister a service (by default from the public table)

Eliom application services


val onload : Eliom_pervasives.XML.event -> unit

This function will register a function that will be executed on client side once the Eliom_appl page is loaded. Use it with Eliom's syntax extension for client side code. For example: set_onload ~sp {{ ... }}

val onunload : Eliom_pervasives.XML.event -> unit

This function will register a function that will be executed on client side when leaving current Eliom_appl page.