package eliom

  1. Overview
  2. Docs
package eliom
Legend:
Library
Module
Module type
Parameter
Class
Class type

Creation and manipulation of Eliom services.

See the Eliom manual for a detailed introduction to the concept of <<a_manual chapter="server-services"|Eliom services>>.

See create for the main service creation function.x

include Eliom_service_sigs.S

Services

See Eliom_service.create (on the server) for how to create services.

include Eliom_service_sigs.TYPES
type get =
  1. | Get_method
type put =
  1. | Put_method
type post =
  1. | Post_method
type delete =
  1. | Delete_method
type co =
  1. | Co
type non_co =
  1. | Non_co
type ext =
  1. | Ext
type non_ext =
  1. | Non_ext
type http =
  1. | Http_ret
type 'a ocaml =
  1. | Ocaml of 'a
type non_ocaml =
  1. | Non_ocaml
type reg =
  1. | Reg
type non_reg =
  1. | Non_reg
type ('get, 'tipo, 'gn) params = ('get, 'tipo, 'gn) Eliom_parameter.params_type constraint 'tipo = [< `WithSuffix | `WithoutSuffix ]

Method specification

type ('m, _, _, _, _, _, _) meth =
  1. | Get : ('gp, 'tipo, 'gn) params -> (get, 'gp, 'gn, unit, unit, 'tipo, unit) meth
  2. | Post : ('gp, 'tipo, 'gn) params * ('pp, [ `WithoutSuffix ], 'pn) params -> (post, 'gp, 'gn, 'pp, 'pn, 'tipo, 'gp) meth
  3. | Put : ('gp, 'tipo, 'gn) params -> (put, 'gp, 'gn, Eliom_parameter.raw_post_data, Eliom_parameter.no_param_name, 'tipo, unit) meth
  4. | Delete : ('gp, 'tipo, 'gn) params -> (delete, 'gp, 'gn, Eliom_parameter.raw_post_data, Eliom_parameter.no_param_name, 'tipo, unit) meth

Method specification datatype

An Eliom service (see Eliom_service_sigs.S.t) can respond to one of the following HTTP methods:

  • GET (Get g)
  • POST (Post (g, p))
  • PUT (Put g)
  • DELETE (Delete g)

In all cases, the service parameters need to be provided (see Eliom_parameter_sigs.S). POST (Post (g, p)) services accept both GET (g) and POST (p) parameters. For the other methods, only GET (g) parameters apply.

The type parameters are used to impose various type constraints, and are not necessarily of interest to the programmer. Their technical meaning is as follows.

  • 0-th param : method
  • params 1-4 : GET and POST parameter types and names
  • param 5 : suffix parameters permitted or not
  • param 6 : non-unit only for the Post (g, p) case when g is not unit ; used to force unit GET parameters when needed
type 'm which_meth =
  1. | Get' : get which_meth
  2. | Post' : post which_meth
  3. | Put' : put which_meth
  4. | Delete' : delete which_meth

Like meth but without the parameters

Auxiliary types

type att
type non_att
type 'a attached_info =
  1. | Attached : att -> att attached_info
  2. | Nonattached : non_att -> non_att attached_info
type ('get, 'post, 'meth, 'attached, 'co, 'ext, 'reg, +'tipo, 'gn, 'pn, 'ret) t constraint 'tipo = [< `WithSuffix | `WithoutSuffix ]

Type of services

For a service ('get, 'post, 'meth, 'attached, 'co, 'ext, 'reg, 'tipo, 'gn, 'pn, 'ret) t:

  • 'get is the type of GET parameters expected by the service.
  • 'post is the type of POST parameters expected by the service.
  • 'meth the HTTP method
  • 'attached attached or non-attached
  • 'co co-service or regular service
  • 'ext external or internal
  • 'reg: possible to register a handler on this service
  • 'tipo the type parameter of subtype suff states the kind of parameters it uses: suffix or not.
  • 'gn is the type of GET parameters names. See Eliom_parameter.param_name and form generation functions (e. g. Eliom_content.Html.D.get_form ).
  • 'pn is the type of POST parameters names. See Eliom_parameter.param_name and form generation functions (e. g. Eliom_content.Html.D.post_form ).
  • 'ret is an information on what the service returns. See Eliom_registration.kind.
and result =
  1. | No_contents
  2. | Dom of Js_of_ocaml.Dom_html.element Js_of_ocaml.Js.t
  3. | Redirect : (unit, unit, get, _, _, _, _, [ `WithoutSuffix ], unit, unit, non_ocaml) t -> result
  4. | Reload_action of {
    1. hidden : bool;
    2. https : bool;
    }
type unit_service = (unit, unit, get, att, non_co, non_ext, non_reg, [ `WithoutSuffix ], unit, unit, non_ocaml) t
type (_, _, _) path_option =
  1. | Path : Eliom_lib.Url.path -> (att, non_co, _) path_option
  2. | No_path : (non_att, co, unit) path_option

Optional service path

Predefined services

Reload actions
val reload_action : (unit, unit, get, non_att, co, non_ext, non_reg, [ `WithoutSuffix ], unit, unit, non_ocaml) t

The service reload_action is 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 reload_action_https : (unit, unit, get, non_att, co, non_ext, non_reg, [ `WithoutSuffix ], unit, unit, non_ocaml) t

Like reload_action, but forces HTTPS

val reload_action_hidden : (unit, unit, get, non_att, co, non_ext, non_reg, [ `WithoutSuffix ], unit, unit, non_ocaml) t

Like reload_action, but keeps non-attached GET parameters.

val reload_action_https_hidden : (unit, unit, get, non_att, co, non_ext, non_reg, [ `WithoutSuffix ], unit, unit, non_ocaml) t

Like reload_action_hidden, but forces HTTPS

Static files

val static_dir : unit -> (string list, unit, get, att, non_co, non_ext, non_reg, [ `WithSuffix ], [ `One of string list ] Eliom_parameter.param_name, unit, non_ocaml) t

The predefined service static_dir allows one to create links to static files. This service takes the name of a static file as a parameter (a string list, slash separated). The actual directory in filesystem where static pages will be found must be set up in the configuration file with the staticmod extension.

val https_static_dir : unit -> (string list, unit, get, att, non_co, non_ext, non_reg, [ `WithSuffix ], [ `One of string list ] Eliom_parameter.param_name, unit, non_ocaml) t

Like static_dir, but forces HTTPS link

val static_dir_with_params : ?keep_nl_params:[ `All | `Persistent | `None ] -> get_params:('a, [ `WithoutSuffix ], 'an) Eliom_parameter.params_type -> unit -> (string list * 'a, unit, get, att, non_co, non_ext, non_reg, [ `WithSuffix ], [ `One of string list ] Eliom_parameter.param_name * 'an, unit, non_ocaml) t

Like static_dir, but allows one to put GET parameters

val https_static_dir_with_params : ?keep_nl_params:[ `All | `Persistent | `None ] -> get_params:('a, [ `WithoutSuffix ], 'an) Eliom_parameter.params_type -> unit -> (string list * 'a, unit, get, att, non_co, non_ext, non_reg, [ `WithSuffix ], [ `One of string list ] Eliom_parameter.param_name * 'an, unit, non_ocaml) t

Like static_dir_with_params, but forces HTTPS link

Miscellaneous

val preapply : service:('a, 'b, 'meth, att, 'co, 'ext, 'reg, _, 'e, 'f, 'return) t -> 'a -> (unit, 'b, 'meth, att, 'co, 'ext, non_reg, [ `WithoutSuffix ], unit, 'f, 'return) t

The function preapply ~service parameters creates a new service by preapplying service to the GET parameters. It is not possible to register a handler on an preapplied service; preapplied services may be used in links or as fallbacks.

val add_non_localized_get_parameters : params:('p, [ `WithoutSuffix ], 'pn) Eliom_parameter.non_localized_params -> service:('a, 'b, 'meth, 'attach, 'co, 'ext, 'reg, 'd, 'e, 'f, 'return) t -> ('a * 'p, 'b, 'meth, 'attach, 'co, 'ext, 'reg, 'd, 'e * 'pn, 'f, 'return) t

The function add_non_localized_get_parameters ~params ~service Adds non localized GET parameters params to service. See the Eliom manual for more information about <<a_manual chapter="server-params" fragment="nonlocalizedparameters"|non localized parameters>>.

val add_non_localized_post_parameters : params:('p, [ `WithoutSuffix ], 'pn) Eliom_parameter.non_localized_params -> service:('a, 'b, 'meth, 'attach, 'co, 'ext, 'g, 'd, 'e, 'f, 'return) t -> ('a, 'b * 'p, 'meth, 'attach, 'co, 'ext, 'g, 'd, 'e, 'f * 'pn, 'return) t

Like add_non_localized_get_parameters but with POST parameters.

val extern : ?keep_nl_params:[ `All | `Persistent | `None ] -> prefix:string -> path:Eliom_lib.Url.path -> meth:('m, 'gp, 'gn, 'pp, 'pn, 'tipo, _) meth -> unit -> ('gp, 'pp, 'm, att, non_co, ext, non_reg, 'tipo, 'gn, 'pn, non_ocaml) t

extern ~prefix ~path ~meth () creates an external service, i.e., a service implemented by a remote server (not necessarily running Ocsigen/Eliom).

val create : ?name:string -> ?csrf_safe:bool -> ?csrf_scope:[< Eliom_common.user_scope ] -> ?csrf_secure:bool -> ?max_use:int -> ?timeout:float -> ?https:bool -> ?keep_nl_params:[ `All | `Persistent | `None ] -> ?priority:int -> meth:('m, 'gp, 'gn, 'pp, 'pn, 'tipo, 'gp_) meth -> path:('att, 'co, 'gp_) path_option -> unit -> ('gp, 'pp, 'm, 'att, 'co, non_ext, reg, 'tipo, 'gn, 'pn, non_ocaml) t

Service definition

The function create ~id ~path () creates a service (Eliom_service_sigs.S.t) identified as per path and accepting parameters as per meth. See Eliom_service_sigs.S.path_option and Eliom_service_sigs.TYPES.meth for the respective arguments.

If path = Path p, the service appears on path p. Otherwise (No_path), the service doesn't have its own path. Rather, the service responds on any path as long as an internal automatically-generated parameter is provided.

In addition to ~path and ~meth, create accepts a series of optional arguments described below.

If ~https:true is provided, all links towards that service will use HTTPS. By default, links will keep the current protocol.

The optional argument ~priority allows one to change the priority order between services that share the same path. The default priority is 0. If you want the service to be tried before (resp. after) other services, put a higher (resp. lower) priority.

The remaining arguments are ignored for services identified by a path (constructor Path).

The optional ~timeout argument 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. The default is "no timeout". The optional ~max_use argument specifies that the service can be used only a fixed number of times. The default is "no limitation".

If the optional argument ~keep_nl_params:`Persistent (resp. ~keep_nl_params:`All) is given, all links towards that service will keep persistent (resp. all) non localized GET arguments of the current service. The default is `None. See the eliom manual for more information about <<a_manual chapter="server-params" fragment="nonlocalizedparameters"|non localized parameters>>.

The optional ~name argument provides a name for the service; otherwise, it will be anonymous (with an auto-generated internal name).

If the optional ~csrf_safe argument is true, we create a <<a_manual chapter="server-security" fragment="csrf"|"CSRF-safe" service>>. In that case the ~name argument is ignored. The default is false.

The ~csrf_scope and ~csrf_secure, if present, should respectively correspond to the ~scope and ~secure arguments that will be given to the associated register function. Otherwise the registration will fail with Eliom_service.Wrong_session_table_for_CSRF_safe_coservice. See Eliom_registration.Html.register, Eliom_registration.App.register or any other Eliom_registration.*.register functions for a description of these arguments.

Warning: create 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_service.register_eliom_module. Otherwise you will also get this exception.

val create_attached_get : ?name:string -> ?csrf_safe:bool -> ?csrf_scope:[< Eliom_common.user_scope ] -> ?csrf_secure:bool -> ?max_use:int -> ?timeout:float -> ?https:bool -> ?keep_nl_params:[ `All | `Persistent | `None ] -> fallback: (unit, unit, get, att, non_co, non_ext, _, [ `WithoutSuffix ], unit, unit, non_ocaml) t -> get_params:('gp, [ `WithoutSuffix ], 'gn) Eliom_parameter.params_type -> unit -> ('gp, unit, get, att, co, non_ext, reg, [ `WithoutSuffix ], 'gn, unit, non_ocaml) t

create_attached_get ~fallback ~get_params () attaches a new service on the path of fallback. The new service implements the GET method and accepts get_params, in addition to an automatically-generated parameter that is used to identify the service and does not need to be provided by the programmer. fallback remains available. For a description of the optional parameters see create.

val create_attached_post : ?name:string -> ?csrf_safe:bool -> ?csrf_scope:[< Eliom_common.user_scope ] -> ?csrf_secure:bool -> ?max_use:int -> ?timeout:float -> ?https:bool -> ?keep_nl_params:[ `All | `Persistent | `None ] -> fallback: ('gp, unit, get, att, non_co, non_ext, _, 'suff, 'gn, unit, non_ocaml) t -> post_params:('pp, [ `WithoutSuffix ], 'pn) Eliom_parameter.params_type -> unit -> ('gp, 'pp, post, att, co, non_ext, reg, 'suff, 'gn, 'pn, non_ocaml) t

create_attached_post ~fallback ~post_params () attaches a new service on the path of fallback. The new service implements the POST method and accepts the GET parameters of fallback, in addition to the POST parameters post_params. An automatically-generated parameter is used to identify the service and does not need to be provided by the programmer. fallback remains available. For a description of the optional parameters see create.

val attach : fallback:(unit, unit, get, att, _, non_ext, _, _, unit, unit, 'return1) t -> service: ('get, 'post, 'meth, non_att, co, non_ext, _, [< `WithoutSuffix ] as 'sf, 'gn, 'pn, 'return) t -> unit -> ('get, 'post, 'meth, att, co, non_ext, non_reg, 'sf, 'gn, 'pn, 'return) t

attach ~fallback ~service () attaches the preexisting pathless service service on the URL of fallback. This allows creating a link to a pathless service but with another URL than the current one. It is not possible to register something on the service returned by this function.

Static loading of Eliom modules

This functionality allows one to register initialization functions for Eliom modules which will be executed when the corresponding module is loaded in ocsigenserver.conf. If the module is loaded dynamically, you probably don't need this. But if the module is linked statically, some computations, like service registrations must be delayed.

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

The function register_eliom_module mod f is used to register the initialization function f to be executed when then module mod is loaded by Ocsigen server. The module mod could either be a dynamically loaded module or linked statically into the server: in each case, the f function will be invoked when the module is initialized in the configuration file using <eliommodule ...> ... </eliommodule>. If register_eliom_module is called twice with the same module name, the second initialization function will replace the previous one.

val unregister : ?scope:[< Eliom_common.scope ] -> ?secure:bool -> (_, _, _, _, _, non_ext, _, _, _, _, _) t -> unit

The function unregister service unregister the service handler previously associated to service with Eliom_registration.Html.register, Eliom_registration.App.register or any other Eliom_registration.*.register functions. See the documentation of those functions for a description of the ~scope and ~secure optional parameters.

val is_external : (_, _, _, _, _, _, _, _, _, _, _) t -> bool

Returns whether it is an external service or not.